valiron-payment-interceptor

在支付执行之前，使用对手方代理的 @valiron/sdk 信任决策拦截并授权传出的机器对机器支付（x402 或类似）。在实施支付中间件、钱包支出防护、策略引擎、基于信任的允许/拒绝/限制决策、失败打开/失败关闭行为以及可审计的交易风险控制时使用。

## 概述（中文）

在支付执行之前，使用对手方代理的 @valiron/sdk 信任决策拦截并授权传出的机器对机器支付（x402 或类似）。在实施支付中间件、钱包支出防护、策略引擎、基于信任的允许/拒绝/限制决策、失败打开/失败关闭行为以及可审计的交易风险控制时使用。

## 原文

# Valiron Payment Interceptor

Add a trust gate in front of outgoing agent payments.

## Runtime requirements

Declare and validate runtime prerequisites before enabling the interceptor:

- Node.js runtime compatible with your app and `@valiron/sdk`.
- Installed dependencies:
  - `@valiron/sdk`
  - Your payment rail package(s) (x402 or equivalent) used by the host app.
- Configuration/credentials (via secret manager or env vars):
  - `VALIRON_API_KEY` (optional today; reserved for authenticated deployments)
  - `VALIRON_BASE_URL` (if using non-default endpoint)
  - `VALIRON_TIMEOUT_MS` (optional, with safe default)
- Policy/config inputs:
  - Decision policy JSON (route-to-action matrix)
  - Spend limit defaults and per-route overrides

Fail startup (or fail closed for payment endpoints) when required policy/config inputs are missing. If your deployment enforces SDK auth, treat `VALIRON_API_KEY` as required.

## Workflow

1. Extract counterparty identity from the payment request.
   - Prefer `counterpartyAgentId`.
   - Support wallet fallback with `getWalletProfile(wallet)`.
2. Evaluate trust with Valiron.
   - Fast path: `checkAgent(agentId)`.
   - Full path: `getAgentProfile(agentId)` when you need reasons/signals, pricing, or audit details.
3. Apply deterministic decision policy from `references/decision-policy.md`.
4. Enforce spend controls from `references/spend-controls.md`.
5. If allowed, continue to payment initiation (x402 challenge creation or equivalent flow).
6. If blocked/restricted, return explicit denial/degrade reason.
7. Log outcome using `references/audit-events.md`.

## Decision model

Map route decisions to payment actions:

- `prod`: allow payment under normal limits.
- `prod_throttled`: allow with reduced caps/rate limits.
- `sandbox`: allow only test/sandbox payment rail (or deny prod transfer).
- `sandbox_only`: deny outgoing payment.

Never authorize payment using free-form model output alone.

## x402-specific sequencing

For x402-protected purchases or settlement-like flows:

1. Trust-check counterparty identity.
2. Evaluate route + spend policy.
3. If denied, abort before creating payment commitment.
4. If allowed, generate/send x402 payment payload.
5. Record authorization decision + amount + result.

## Outage and fallback

Use endpoint-class fallback from `references/fallback-modes.md`:

- High-risk payment actions: `fail-closed`.
- Low-risk/test actions: optional `fail-open-guarded` with strict caps.

Keep fallback mode explicit and versioned.

## Use bundled resources

- Runtime + credential checklist: `references/runtime-requirements.md`
- Decision matrix: `references/decision-policy.md`
- Spend/risk controls: `references/spend-controls.md`
- Fallback guidance: `references/fallback-modes.md`
- Audit schema: `references/audit-events.md`
- Error handling: `references/error-handling.md`
- Interceptor template: `assets/payment-interceptor.ts`
- Policy validator: `scripts/validate-payment-policy.mjs`