feat: forward trusted payment metadata upstream + onPaymentSettled host callback (0.2.1)

[j4ys0n]

Why

missionsquad-api now does per-run x402 revenue accounting (source/priceUsd on usage metrics), but payer-address and settlement-tx reconciliation was impossible: the proxy settles in its own layer and nothing payment-related reached the upstream. This PR gives hosts a trusted, spoof-proof channel for that data.

What

1. Trusted x-x402-* upstream request headers (gated by forwardPaymentMetadata, default true):

Header	Value	http / http-stream-direct	http-stream relay
x-x402-payment-id	SDK-generated UUID (correlates with the settlement event)	✓	✓
x-x402-resource-id	resource id, encodeURIComponent-encoded	✓	✓
x-x402-scheme / -network / -amount / -asset / -pay-to	from the verified accepted payment requirements	✓	✓
x-x402-payer / x-x402-transaction	facilitator settle result	— (settlement follows the upstream request by design)	✓ (carried in the HMAC-signed lease token)

2. onPaymentSettled config callback — fires after every successful settlement (all kinds) with { paymentId, resourceId, kind, transaction, network, payer?, requirements, settledAt }. Fire-and-forget: a throwing/rejecting callback never affects the paid request. In-process hosts (missionsquad-api) join it to the request via x-x402-payment-id.

Security invariants

• All nine names are registered as internal payment headers: client-supplied values are stripped unconditionally — even when a resource's forwardRequestHeaders explicitly lists them (integration-tested). An upstream can trust any x-x402-* value it sees.
• Metadata derives only from paymentPayload.accepted (the requirements the core verified) — never from the client-controlled scheme payload (getPayer-style reads).
• Payer identity comes only from the facilitator's settle response, never from verify-time client data.
• Settle ordering is untouched: http/direct still settle only after the upstream accepts (status < 400); settle-failure still aborts the direct-stream upstream.
• Header values pass a printable-ASCII guard (skip, never throw, mid-proxy); resource ids are URI-encoded.

Compatibility

• Additive: upstreams that ignore unknown headers see no change; forwardPaymentMetadata: false restores byte-identical upstream requests.
• Lease tokens minted before 0.2.1 relay without metadata headers (graceful absence, tested).
• settlePayment now returns the full settle result internally (was boolean); no public API removed. Version → 0.2.1.

Tests

232 passing (13 new): per-kind header matrices + settlement-event correlation, spoofing attempt via allow-listed names, upstream→settle ordering preserved, legacy-lease relay, throwing callback isolation, forwardPaymentMetadata: false, header-guard/encoding units, config validation. yarn typecheck + yarn build clean.

Follow-up (separate repo, after publish)

missionsquad-api: pass onPaymentSettled to persist payer/tx against the usage row via x-x402-payment-id.

🤖 Generated with Claude Code

[j4ys0n]

Adversarial self-review — 1 HIGH fixed (commit 2560ef2)

Ran an adversarial pass against this diff; one finding was material and verified against @x402/core's actual source before fixing.

[HIGH] Forwarded metadata trusted the client echo, not the server requirement. toPaymentMetadata / toLeasePaymentInfo / the onPaymentSettled requirements all read payment.paymentPayload.accepted — the client-submitted object. @x402/core's findMatchingRequirements (server/index.js:846-863) only deep-equals that against the server requirement for x402Version 2; for v1 it matches on scheme+network only, so a payer could submit accepted={amount:"0", asset:…, payTo:…} and those forged values would populate the "trusted" x-x402-amount/-asset/-pay-to headers and the settlement event. (The charge itself was never at risk — core settles against the server matchingRequirements, which is exactly the object the verified result exposes as payment.paymentRequirements, server/index.js:1103-1138.) Fix: source all forwarded metadata from payment.paymentRequirements — version-independent and always the server's own object. Regression test forges a v1 payload with tampered amount/asset/payTo and asserts the server values win in both the headers and the event.

[LOW] encodeURIComponent(resourceId) could throw mid-proxy on a lone-surrogate id (operator-controlled, but validation only requires a non-empty string, and custom stores may skip validation). Now guarded — an un-encodable id skips the x-x402-resource-id header instead of 500-ing the request. Unit-tested.

[LOW] Test gaps closed: the v1 anti-spoof test above, the encode-throw/round-trip units, and a websocket-lease onPaymentSettled test (kind:"websocket").

Other verdicts held SOLID: strip-set completeness (all nine names internal, client copies dropped even when a resource allowlists them), builder ordering, HMAC lease integrity + pre-0.2.1-token graceful degradation, settle ordering unchanged, callback isolation. 236 tests green; typecheck + build clean.