feat: body-matched resources + http-stream-direct kind + facilitator sync hardening (0.2.0)

[j4ys0n]

Why

missionsquad-api needs x402 in front of its existing OpenAI-compatible endpoint (POST /v1/chat/completions) with per-agent pricing selected by the model body field (owner/agent-slug), using the standard single-request 402-retry flow — no derivative endpoints, no lease dance. Design doc: msq/docs/x402-per-agent-payment-config-design.md (v2).

Two capabilities were missing, plus hardening that becomes critical once resource definitions come from user-writable data:

What

1. Body-matched resources (match)

• New optional X402Resource.match: { bodyField, equals } — many resources may share one publicPath, discriminated by a parsed-JSON body field (e.g. model). Each carries its own pricing (amount/network/payTo).
• Payment routes register under synthetic per-resource keys (/__x402/match/<id>); context.path uses the same key during payment processing, while the 402 challenge advertises the real request URL (adapter.getUrl() fallback) and discovery URLs are built from the real publicPath.
• Requests matching no discriminator fall through to the host app, so unknown models keep existing behavior (e.g. 401/404 from the host's own routes). Body-matched resources take precedence over unmatched ones on the same path.
• Duplicate (method, path, bodyField, equals) claims → invalid at refresh and rejected by InMemoryX402ResourceStore.
• Allowed on http and http-stream-direct kinds only (payment happens where the body is present); requires a JSON body parser before the middleware.

2. http-stream-direct kind

• Single-request paid streaming: verify → settle → pipe unbuffered (reuses proxyStreamingHttpRequest, including client-disconnect abort propagation). No lease endpoint/token/use-store.
• Content-agnostic pipe: serves OpenAI stream:true SSE and stream:false JSON through one resource.
• Settlement completes before the upstream call (pay-for-access; documented in README security notes).

3. Facilitator sync hardening

• initPromise no longer floats unhandled: a detached rejection guard prevents unhandled-rejection crashes; the awaited path still observes failures.
• RouteConfigurationError from @x402/core (missing_facilitator/missing_scheme) now prunes only the offending resources to the invalid list (visible in diagnostics) and retries the sync — one bad network config no longer poisons the whole paid surface, and previously the rejected promise was never cleared, so every paid request 500'd until a manual refresh.
• Other sync failures (facilitator unreachable): requests fail 503 FACILITATOR_SYNC_ERROR (retryable), surface as diagnostics().facilitatorSyncError, and the sync retries on the next payment request; the error clears on success.
• Refresh race (matched resource, route missing from swapped generation): 503 RESOURCE_ROUTE_SYNC_ERROR instead of a hung request.
• Protected-request hooks that grant access now serve without settlement on all kinds (previously: hung request).

API surface

New exports: X402ResourceMatch, FacilitatorSyncError, ResourceRouteSyncError; X402ProxyDiagnostics.facilitatorSyncError?; X402LoadedResource.match?. Existing kinds/flows unchanged. Version → 0.2.0.

Tests

• tests/integration/shared-path-model-match.integration.test.ts — per-model 402 pricing on a shared path, real (non-synthetic) challenge URL, settle-before-upstream ordering, service-token injection, SSE + buffered relays, unknown-model/missing-body fallthrough, duplicate-claim rejection (runtime + store).
• tests/integration/facilitator-sync-hardening.integration.test.ts — unsupported-network pruning with continued service, 503 + diagnostics + recovery when the facilitator is down, no unhandled rejection from a failed background sync.
• Validator unit cases for match/kind combinations and the no-lease rule for http-stream-direct.

yarn typecheck ✅ · yarn build ✅ · yarn test ✅ 23 files / 214 tests

🤖 Generated with Claude Code

[j4ys0n]

Adversarial self-review — 4 findings, all fixed in 33954cc

Ran an adversarial review of this diff against @x402/core's actual matching internals before handing off. Findings (each verified in @x402/core dist/cjs/server/index.js source, not assumed):

1. CRITICAL — synthetic match keys broke for path-hostile resource ids. @x402/core decodes incoming paths (normalizePath → decodeURIComponent, slash collapsing) but compiles route keys literally as case-insensitive patterns where * → .*? and [x] → param. Deriving the key from encodeURIComponent(resource.id) therefore failed to match its own route for any id containing /, %, space, etc. (→ no-payment-required), and ids with */case variants could cross-match other resources' routes → wrong price/payTo. Fixed: the synthetic segment is now a sha256 lowercase-hex digest of the id — immune to every transform. E2E-covered with id OpenAI/GPT 4* [x] 100%.

2. CRITICAL — the granted outcome was fail-open. no-payment-required can only arise from a route-matching miss or an onProtectedRequest grant hook — and this SDK never registers such hooks. Combined with finding 1, a hostile id would have been served without payment. Fixed: after the route key is confirmed present, no-payment-required fails closed with 503 RESOURCE_ROUTE_SYNC_ERROR. (The PR description's original mention of "hooks that grant access now serve without settlement" is superseded by this — there is no grant path.)

3. MAJOR — http-stream-direct settled before contacting the upstream, charging payers for upstream outages/5xx. Fixed to mirror handleHttp's settle-on-success rule: connect → status < 400 → settle → relay. Upstream errors are never charged; a settlement failure after connect aborts the upstream run; PAYMENT-RESPONSE still precedes all body bytes. New openStreamingUpstream() split in httpProxy makes this possible without duplicating the relay/backpressure/disconnect logic.

4. MINOR — concurrent first-sync prune race could 503 a second in-flight request and transiently poison diagnostics while recovery was already underway; generation swaps mid-await could also return without syncing. Fixed: followers re-evaluate/follow the fresh sync; bounded by an iteration cap.

Also from review nits: match now requires a body-carrying method (POST/PUT/PATCH) — a GET match resource was silently dead config.

Suite: 23 files / 219 tests passing; typecheck + build clean. New regression tests: hostile-id e2e (402 → pay → stream, never free), upstream-500 and upstream-unreachable → relayed error with no settlement, settle-failure → 402 + upstream aborted, corrected settle-ordering assertion (upstream before settle).

🤖 Generated with Claude Code