s402 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-04-11
+
+This release closes the facilitator causal-binding hole identified in the April 2026 scale-fragility review, and establishes s402 as a pure chain-agnostic protocol repo (no Sui code anywhere). Chain-specific implementations now live in downstream adapter repos — the canonical Sui reference is `@sweefi/sui` in the SweeFi monorepo.
+
+### Added
+
+- **`verifySettlement` — client-side causal-binding check (S8 Facilitator Accountability).** New optional method on `s402ClientScheme`. For all client-signed schemes (`exact`, `stream`, `escrow`, `unlock` TX1), this is a **local, offline comparison**: derive the expected transaction digest from the signed BCS bytes and compare to `SettleResponse.txDigest`. No RPC call required. Closes the causal-binding hole where a malicious facilitator could substitute an unrelated-but-real transaction digest — that digest would correspond to different signed bytes the client never produced, and the check would reject it. Interface-only in this release; concrete implementations land in `@sweefi/sui` per ADR-002. See `typescript/src/scheme.ts` and `INVARIANTS.md` § S8 for the full contract and copy-paste implementation template.
+- **`s402SettlementVerification` type** — return shape for `verifySettlement`: `{ verified, expectedDigest, actualDigest, reason? }`.
+- **`DIGEST_MISMATCH` error code** — `retryable: false`, with a `suggestedAction` warning callers NOT to retry on mismatch. Retrying is dangerous: the signed bytes may have already landed on-chain under the *expected* digest (the facilitator may simply be lying about what it broadcast), and a fresh retry would double-pay. The correct failure mode is to mark the payment as non-settled and stop trusting the facilitator. See `typescript/src/errors.ts`.
+- **S8. Facilitator Accountability** — first-class safety invariant alongside S1–S7. Full statement, formal proof for the `exact` scheme on Sui (by blake2b-256 collision resistance), per-scheme scope table, and a copy-paste implementation template for downstream Sui adapters now live in `INVARIANTS.md` § S8. The Allium behavioral spec is at `spec/allium/s8-facilitator-accountability.allium`.
+- **ADR-001 — Protocol Boundaries.** Documents four decisions from the scale-fragility council: (1) facilitator trust boundary sealed by client-side digest verification, (2) receipt cardinality is a non-guarantee at the protocol layer, (3) scheme cap at five with burden-of-proof for any new scheme, (4) extension hygiene rules. See `docs/adr/001-protocol-boundaries.md`.
+- **ADR-002 — s402 is a pure protocol repo.** Decides that this repo contains NO chain-specific code at any path — not in `typescript/src/`, not in a sibling package, not anywhere. All Sui-specific implementation moves to SweeFi. Corollary: the S7 chain-agnostic boundary is now enforced repo-wide, not just inside `src/`. See `docs/adr/002-s402-is-pure-protocol.md`.
+
+### Removed
+
+- **`mcp-server/` directory deleted.** The Sui-specific MCP server that previously shipped in this repo has been relocated to `@sweefi/mcp` (canonical implementation in the SweeFi repo) per ADR-002. **This does not affect the npm `s402` package** — `mcp-server` was a separate consumer of this package, not part of it. Users who were installing from the repo directly should migrate to `npx @sweefi/mcp`; a forthcoming `npm deprecate s402-mcp` will redirect the legacy standalone package to the new name.
+
+### Changed
+
+- **S7 scope strengthened to repo-level.** `INVARIANTS.md` § S7 scope note now reads: "chain-specific code lives in downstream implementation repos (e.g. `@sweefi/sui` for the Sui implementation) which consume this package from npm and add chain validation on top. Per ADR-002, the s402 repo itself contains NO chain-specific imports at the repo level — the protocol-pure boundary is enforced repo-wide, not just inside `src/`."
+- **`INVARIANTS.md` Sui references rewritten as downstream pointers.** Prior revisions of the S8 proof block referenced a reference implementation at `mcp-server/src/sui-exact.ts`. That path no longer exists; the proof block now points at `sweefi/packages/sui/src/s402/exact/client.ts` as the canonical Sui adapter per ADR-002.
+- **Demo API distribution surfaces** (`demo-api/public/index.html` served at `demo.s402-protocol.org`, and `demo-api/src/server.ts`) now reference `@sweefi/mcp` with the correct `SUI_PRIVATE_KEY` / `SUI_NETWORK` environment variables, matching SweeFi's documented `mcpServers` config shape. Outside the npm package scope but noted here for consumers browsing the monorepo.
+
+### Compatibility
+
+- **TypeScript type compatibility**: `verifySettlement` is optional on `s402ClientScheme`, and `DIGEST_MISMATCH` is a purely additive enum member. Existing adapter implementations compile unchanged against `^0.3.0`.
+- **Wire format**: unchanged from v0.2.3. The 132 conformance test vectors in `test/conformance/vectors/` still pass byte-for-byte against v0.3.0.
+- **Minor-bump rationale**: the 0.2.3 → 0.3.0 jump reflects the semantic significance of adding a new safety invariant (S8) and the repo-level architectural decisions (ADR-001/002), not a breaking wire-format change. Under semver 0.x, minor bumps are treated as breaking by `^0.x.y` ranges — consumers should expect to opt-in explicitly.
+
 ## [0.2.1] - 2026-03-02
 
 ### Added
@@ -129,6 +158,7 @@ _Version bump for npm publish after license change._
 - Property-based fuzz testing via fast-check
 - 207 tests, zero runtime dependencies
 
+[0.3.0]: https://github.com/s402-protocol/core/compare/v0.2.3...v0.3.0
 [0.2.1]: https://github.com/s402-protocol/core/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/s402-protocol/core/compare/v0.1.8...v0.2.0
 [0.1.8]: https://github.com/s402-protocol/core/compare/v0.1.7...v0.1.8

package/README.md

@@ -3,9 +3,9 @@
 [![CI](https://github.com/s402-protocol/core/actions/workflows/ci.yml/badge.svg)](https://github.com/s402-protocol/core/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/s402.svg)](https://www.npmjs.com/package/s402)
 
-**Sui-native HTTP 402 protocol.** Atomic settlement via Sui's Programmable Transaction Blocks (PTBs). Includes an optional compat layer (`s402/compat`) for normalizing x402 input.
+**Chain-agnostic HTTP 402 protocol.** Five payment schemes for AI agent commerce. Wire-compatible with x402. Zero runtime dependencies. Includes an optional compat layer (`s402/compat`) for normalizing x402 input.
 
-s402 is the Sui-native implementation of HTTP 402 (Payment Required) — an open protocol that lets AI agents pay for API calls in a single HTTP request with no per-call on-chain transaction. Unlike Coinbase's x402 on Base (EVM L2), s402 uses Sui's Programmable Transaction Blocks to reduce 1,000 payments to just 2 on-chain transactions via the Prepaid scheme, cutting per-call effective gas from $0.007 to $0.000014 and making micropayments economically viable for AI agents for the first time.
+s402 is a chain-agnostic HTTP 402 wire format — types, HTTP encoding, scheme registry, and error handling for five payment schemes. The protocol layer contains no chain-specific logic (see [S7 invariant](./AGENTS.md)). The reference implementation on Sui uses Programmable Transaction Blocks to reduce 1,000 payments to just 2 on-chain transactions via the Prepaid scheme, cutting per-call effective gas from $0.007 to $0.000014 and making micropayments economically viable for AI agents for the first time.
 
 ```bash
 npm install s402

package/dist/compat.mjs

@@ -15,6 +15,7 @@ function fromX402Requirements(x402) {
 	if (x402.facilitatorUrl !== void 0) try {
 		const url = new URL(x402.facilitatorUrl);
 		if (url.protocol !== "https:" && url.protocol !== "http:") throw new s402Error("INVALID_PAYLOAD", `facilitatorUrl must use https:// or http://, got "${url.protocol}"`);
+		if (url.username || url.password) throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl must not contain embedded credentials (user:password@)");
 	} catch (e) {
 		if (e instanceof s402Error) throw e;
 		throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl is not a valid URL");

package/dist/errors.d.mts

@@ -23,6 +23,7 @@ declare const s402ErrorCode: {
   readonly REQUIREMENTS_EXPIRED: "REQUIREMENTS_EXPIRED";
   readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
   readonly SETTLEMENT_FAILED: "SETTLEMENT_FAILED";
+  readonly DIGEST_MISMATCH: "DIGEST_MISMATCH";
 };
 type s402ErrorCodeType = (typeof s402ErrorCode)[keyof typeof s402ErrorCode];
 interface s402ErrorInfo {
@@ -34,7 +35,7 @@ interface s402ErrorInfo {
 /**
  * Create a typed s402 error with recovery hints.
  *
- * @param code - One of the 15 s402 error codes (e.g. 'SETTLEMENT_FAILED')
+ * @param code - One of the 16 s402 error codes (e.g. 'SETTLEMENT_FAILED')
  * @param message - Optional human-readable message (defaults to the code)
  * @returns Error info object with code, message, retryable flag, and suggestedAction
  *

package/dist/errors.mjs

@@ -22,7 +22,8 @@ const s402ErrorCode = {
 	SIGNATURE_INVALID: "SIGNATURE_INVALID",
 	REQUIREMENTS_EXPIRED: "REQUIREMENTS_EXPIRED",
 	VERIFICATION_FAILED: "VERIFICATION_FAILED",
-	SETTLEMENT_FAILED: "SETTLEMENT_FAILED"
+	SETTLEMENT_FAILED: "SETTLEMENT_FAILED",
+	DIGEST_MISMATCH: "DIGEST_MISMATCH"
 };
 /** Error recovery hints for each error code */
 const ERROR_HINTS = {
@@ -68,7 +69,7 @@ const ERROR_HINTS = {
 	},
 	NETWORK_MISMATCH: {
 		retryable: false,
-		suggestedAction: "Ensure client and server are on the same Sui network"
+		suggestedAction: "Ensure client and server are on the same network"
 	},
 	SIGNATURE_INVALID: {
 		retryable: false,
@@ -85,12 +86,16 @@ const ERROR_HINTS = {
 	SETTLEMENT_FAILED: {
 		retryable: true,
 		suggestedAction: "Transient RPC failure during settlement — retry in a few seconds"
+	},
+	DIGEST_MISMATCH: {
+		retryable: false,
+		suggestedAction: "Facilitator returned a transaction digest that does not match the signed payload. Do NOT retry — treat payment as non-settled and investigate the facilitator."
 	}
 };
 /**
 * Create a typed s402 error with recovery hints.
 *
-* @param code - One of the 15 s402 error codes (e.g. 'SETTLEMENT_FAILED')
+* @param code - One of the 16 s402 error codes (e.g. 'SETTLEMENT_FAILED')
 * @param message - Optional human-readable message (defaults to the code)
 * @returns Error info object with code, message, retryable flag, and suggestedAction
 *

package/dist/http.mjs

@@ -109,8 +109,8 @@ const S402_SUB_OBJECT_KEYS = {
 	]),
 	unlock: new Set([
 		"encryptionId",
-		"walrusBlobId",
-		"encryptionPackageId"
+		"encryptedContentId",
+		"encryptionServiceId"
 	]),
 	prepaid: new Set([
 		"ratePerCall",
@@ -156,6 +156,7 @@ function pickRequirementsFields(obj) {
 * ```
 */
 function decodePaymentRequired(header) {
+	if (typeof header !== "string") throw new s402Error("INVALID_PAYLOAD", `payment-required header must be a string, got ${typeof header}`);
 	if (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `payment-required header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
 	try {
@@ -228,6 +229,7 @@ function pickPayloadFields(obj) {
 * ```
 */
 function decodePaymentPayload(header) {
+	if (typeof header !== "string") throw new s402Error("INVALID_PAYLOAD", `x-payment header must be a string, got ${typeof header}`);
 	if (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `x-payment header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
 	try {
@@ -261,6 +263,7 @@ function pickSettleResponseFields(obj) {
 }
 /** Decode settlement response from the `payment-response` header */
 function decodeSettleResponse(header) {
+	if (typeof header !== "string") throw new s402Error("INVALID_PAYLOAD", `payment-response header must be a string, got ${typeof header}`);
 	if (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `payment-response header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
 	try {
@@ -370,8 +373,8 @@ function validateUnlockShape(value) {
 	assertPlainObject(value, "unlock");
 	const obj = value;
 	assertString(obj, "encryptionId", "unlock");
-	assertString(obj, "walrusBlobId", "unlock");
-	assertString(obj, "encryptionPackageId", "unlock");
+	assertString(obj, "encryptedContentId", "unlock");
+	assertString(obj, "encryptionServiceId", "unlock");
 }
 /**
 * Validate prepaid sub-object.
@@ -417,7 +420,7 @@ function validateRequirementsShape(obj) {
 	if (typeof record.network !== "string") missing.push("network (string)");
 	if (typeof record.asset !== "string") missing.push("asset (string)");
 	if (typeof record.amount !== "string") missing.push("amount (string)");
-	else if (!isValidU64Amount(record.amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${record.amount}": must be a non-negative integer string within u64 range`);
+	else if (!isValidAmount(record.amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${record.amount}": must be a non-negative integer string`);
 	if (typeof record.payTo !== "string") missing.push("payTo (string)");
 	else if (record.payTo.length === 0) throw new s402Error("INVALID_PAYLOAD", "payTo must be a non-empty string");
 	if (missing.length > 0) throw new s402Error("INVALID_PAYLOAD", `Malformed payment requirements: missing ${missing.join(", ")}`);
@@ -443,6 +446,7 @@ function validateRequirementsShape(obj) {
 		try {
 			const url = new URL(record.facilitatorUrl);
 			if (url.protocol !== "https:" && url.protocol !== "http:") throw new s402Error("INVALID_PAYLOAD", `facilitatorUrl must use https:// or http://, got "${url.protocol}"`);
+			if (url.username || url.password) throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl must not contain embedded credentials (user:password@)");
 		} catch (e) {
 			if (e instanceof s402Error) throw e;
 			throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl is not a valid URL");
@@ -495,6 +499,7 @@ function encodeRequirementsBody(requirements) {
 }
 /** Decode payment requirements from JSON string (from response body) */
 function decodeRequirementsBody(body) {
+	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 requirements body must be a string, got ${typeof body}`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -510,6 +515,7 @@ function encodePayloadBody(payload) {
 }
 /** Decode payment payload from JSON string (from request body) */
 function decodePayloadBody(body) {
+	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 payload body must be a string, got ${typeof body}`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -525,6 +531,7 @@ function encodeSettleBody(response) {
 }
 /** Decode settlement response from JSON string (from response body) */
 function decodeSettleBody(body) {
+	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 settle body must be a string, got ${typeof body}`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);

package/dist/index.d.mts

@@ -1,101 +1,9 @@
 import { createS402Error, s402Error, s402ErrorCode, s402ErrorCodeType, s402ErrorInfo } from "./errors.mjs";
 import { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PaymentSession, s402PrepaidExtra, s402PrepaidPayload, s402RegistryQuery, s402Scheme, s402ServiceEntry, s402SettleResponse, s402SettlementMode, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402VerifyResponse } from "./types.mjs";
 import { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
+import { a as s402ServerScheme, i as s402RouteConfig, n as s402DirectScheme, o as s402SettlementVerification, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-D7qqwo3Q.mjs";
 import { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader, s402Receipt, s402ReceiptSigner, s402ReceiptVerifier } from "./receipts.mjs";
 
-//#region src/scheme.d.ts
-/** Implemented by each scheme on the client side */
-interface s402ClientScheme {
-  /** Which scheme this implements */
-  readonly scheme: s402Scheme;
-  /** Create a signed payment payload from server requirements */
-  createPayment(requirements: s402PaymentRequirements): Promise<s402PaymentPayload>;
-}
-/** Implemented by each scheme on the server side */
-interface s402ServerScheme {
-  readonly scheme: s402Scheme;
-  /** Build payment requirements from route config */
-  buildRequirements(config: s402RouteConfig): s402PaymentRequirements;
-}
-/**
- * Implemented by each scheme in the facilitator.
- *
- * Critical: each scheme has its OWN verify logic.
- * - Exact: signature recovery + dry-run simulation + balance check
- * - Stream: stream creation PTB validation + deposit check
- * - Escrow: escrow creation PTB validation + arbiter/deadline check
- * - Unlock: escrow validation (key release is separate PTB)
- */
-interface s402FacilitatorScheme {
-  readonly scheme: s402Scheme;
-  /** Verify a payment payload without broadcasting */
-  verify(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402VerifyResponse>;
-  /** Verify and broadcast the transaction */
-  settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
-}
-/**
- * For self-sovereign agents that hold their own keys.
- * Builds, signs, and broadcasts in one step — no facilitator needed.
- *
- * MUST call waitForTransaction() before returning success.
- * Without finality confirmation, server could grant access for a
- * transaction that gets reverted.
- */
-interface s402DirectScheme {
-  readonly scheme: s402Scheme;
-  /** Build, sign, broadcast, and wait for finality */
-  settleDirectly(requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
-}
-/** Per-route payment configuration for the server middleware */
-interface s402RouteConfig {
-  /** Which payment scheme(s) to accept. Always includes "exact" for x402 compat. */
-  schemes: s402Scheme[];
-  /** Amount in base units, same as wire format (e.g., "1000000") */
-  price: string;
-  /** Network identifier (e.g., "sui:mainnet", "solana:mainnet-beta") */
-  network: string;
-  /** Recipient address (chain-specific format, validated by chain adapter) */
-  payTo: string;
-  /** Asset/coin type identifier (chain-specific, e.g., Sui Move type or Solana mint address) */
-  asset: string;
-  /** Facilitator URL (optional for direct settlement) */
-  facilitatorUrl?: string;
-  /** Settlement mode preference */
-  settlementMode?: s402SettlementMode;
-  /** AP2 mandate requirements */
-  mandate?: {
-    required: boolean;
-    minPerTx?: string;
-  };
-  /** Protocol fee in basis points */
-  protocolFeeBps?: number;
-  /** Require on-chain receipt */
-  receiptRequired?: boolean;
-  stream?: {
-    ratePerSecond: string;
-    budgetCap: string;
-    minDeposit: string;
-  };
-  escrow?: {
-    seller: string;
-    arbiter?: string;
-    deadlineMs: string;
-  };
-  unlock?: {
-    encryptionId: string;
-    walrusBlobId: string;
-    encryptionPackageId: string;
-  };
-  prepaid?: {
-    ratePerCall: string;
-    maxCalls?: string;
-    minDeposit: string;
-    withdrawalDelayMs: string; /** Provider Ed25519 pubkey (hex). Enables v0.2 signed receipt mode. @since v0.2 */
-    providerPubkey?: string; /** Dispute window in ms. Required when providerPubkey is set. @since v0.2 */
-    disputeWindowMs?: string;
-  };
-}
-//#endregion
 //#region src/client.d.ts
 declare class s402Client {
   private schemes;
@@ -277,4 +185,4 @@ declare class s402ResourceServer {
   process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
 }
 //#endregion
-export { S402_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatReceiptHeader, isValidAmount, isValidU64Amount, parseReceiptHeader, s402Client, type s402ClientScheme, type s402DirectScheme, type s402Discovery, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, s402Facilitator, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402Receipt, type s402ReceiptSigner, type s402ReceiptVerifier, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatReceiptHeader, isValidAmount, isValidU64Amount, parseReceiptHeader, s402Client, type s402ClientScheme, type s402DirectScheme, type s402Discovery, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, s402Facilitator, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402Receipt, type s402ReceiptSigner, type s402ReceiptVerifier, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402SettlementVerification, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };

package/dist/scheme-D7qqwo3Q.d.mts

@@ -0,0 +1,136 @@
+import { s402PaymentPayload, s402PaymentRequirements, s402Scheme, s402SettleResponse, s402SettlementMode, s402VerifyResponse } from "./types.mjs";
+
+//#region src/scheme.d.ts
+/**
+ * Result of client-side settlement verification.
+ *
+ * See `s402ClientScheme.verifySettlement` — this is the outcome of the
+ * client independently checking that the facilitator's returned digest
+ * is causally bound to the signed payload the client actually sent.
+ */
+interface s402SettlementVerification {
+  /** True iff the facilitator's digest matches the one derived from the signed payload bytes. */
+  verified: boolean;
+  /** The digest the client computed locally from its own signed bytes. */
+  expectedDigest: string;
+  /** The digest the facilitator returned (copied from SettleResponse). */
+  actualDigest: string | null;
+  /**
+   * Human-readable reason when `verified` is false. Present only on mismatch,
+   * unknown-digest, or when the scheme cannot verify the settlement locally.
+   */
+  reason?: string;
+}
+/** Implemented by each scheme on the client side */
+interface s402ClientScheme {
+  /** Which scheme this implements */
+  readonly scheme: s402Scheme;
+  /** Create a signed payment payload from server requirements */
+  createPayment(requirements: s402PaymentRequirements): Promise<s402PaymentPayload>;
+  /**
+   * Verify that the facilitator's `SettleResponse` is causally bound to the
+   * signed payload the client actually sent.
+   *
+   * For schemes where the client signs the full transaction before sending
+   * (exact, stream, escrow, unlock-TX1), this is a **local, offline check**:
+   * derive the expected tx digest from the signed bytes and compare it to the
+   * digest the facilitator returned. No RPC call required. This closes the
+   * causal-binding hole identified in the April 2026 scale-fragility review
+   * (see `knowledge/scale-fragility-council-v03.md`): a malicious facilitator
+   * cannot substitute an unrelated-but-real tx digest, because that other
+   * digest would correspond to different signed bytes the client never
+   * produced.
+   *
+   * Optional for backward-compatibility. Schemes that cannot verify locally
+   * (e.g. unlock-TX2, which is facilitator-constructed) should return
+   * `{ verified: false, reason: 'scheme does not support local verification' }`
+   * and rely on other attestation mechanisms.
+   */
+  verifySettlement?(payload: s402PaymentPayload, settleResponse: s402SettleResponse): s402SettlementVerification;
+}
+/** Implemented by each scheme on the server side */
+interface s402ServerScheme {
+  readonly scheme: s402Scheme;
+  /** Build payment requirements from route config */
+  buildRequirements(config: s402RouteConfig): s402PaymentRequirements;
+}
+/**
+ * Implemented by each scheme in the facilitator.
+ *
+ * Critical: each scheme has its OWN verify logic.
+ * - Exact: signature recovery + dry-run simulation + balance check
+ * - Stream: stream creation PTB validation + deposit check
+ * - Escrow: escrow creation PTB validation + arbiter/deadline check
+ * - Unlock: escrow validation (key release is separate PTB)
+ */
+interface s402FacilitatorScheme {
+  readonly scheme: s402Scheme;
+  /** Verify a payment payload without broadcasting */
+  verify(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402VerifyResponse>;
+  /** Verify and broadcast the transaction */
+  settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+}
+/**
+ * For self-sovereign agents that hold their own keys.
+ * Builds, signs, and broadcasts in one step — no facilitator needed.
+ *
+ * MUST call waitForTransaction() before returning success.
+ * Without finality confirmation, server could grant access for a
+ * transaction that gets reverted.
+ */
+interface s402DirectScheme {
+  readonly scheme: s402Scheme;
+  /** Build, sign, broadcast, and wait for finality */
+  settleDirectly(requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+}
+/** Per-route payment configuration for the server middleware */
+interface s402RouteConfig {
+  /** Which payment scheme(s) to accept. Always includes "exact" for x402 compat. */
+  schemes: s402Scheme[];
+  /** Amount in base units, same as wire format (e.g., "1000000") */
+  price: string;
+  /** Network identifier (e.g., "sui:mainnet", "solana:mainnet-beta") */
+  network: string;
+  /** Recipient address (chain-specific format, validated by chain adapter) */
+  payTo: string;
+  /** Asset/coin type identifier (chain-specific, e.g., Sui Move type or Solana mint address) */
+  asset: string;
+  /** Facilitator URL (optional for direct settlement) */
+  facilitatorUrl?: string;
+  /** Settlement mode preference */
+  settlementMode?: s402SettlementMode;
+  /** AP2 mandate requirements */
+  mandate?: {
+    required: boolean;
+    minPerTx?: string;
+  };
+  /** Protocol fee in basis points */
+  protocolFeeBps?: number;
+  /** Require on-chain receipt */
+  receiptRequired?: boolean;
+  stream?: {
+    ratePerSecond: string;
+    budgetCap: string;
+    minDeposit: string;
+  };
+  escrow?: {
+    seller: string;
+    arbiter?: string;
+    deadlineMs: string;
+  };
+  unlock?: {
+    encryptionId: string;
+    encryptedContentId: string;
+    encryptionServiceId: string;
+  };
+  prepaid?: {
+    ratePerCall: string;
+    maxCalls?: string;
+    minDeposit: string;
+    withdrawalDelayMs: string; /** Provider Ed25519 pubkey (hex). Enables v0.2 signed receipt mode. @since v0.2 */
+    providerPubkey?: string; /** Dispute window in ms. Required when providerPubkey is set. @since v0.2 */
+    disputeWindowMs?: string;
+  };
+}
+//#endregion
+export { s402ServerScheme as a, s402RouteConfig as i, s402DirectScheme as n, s402SettlementVerification as o, s402FacilitatorScheme as r, s402ClientScheme as t };

package/dist/test-utils.d.mts

@@ -0,0 +1,74 @@
+import { s402PaymentPayload, s402PaymentRequirements, s402SettleResponse, s402VerifyResponse } from "./types.mjs";
+import { a as s402ServerScheme, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-D7qqwo3Q.mjs";
+
+//#region src/test-utils.d.ts
+/**
+ * Create a mock client scheme for the `exact` payment type.
+ *
+ * Produces payloads with deterministic transaction/signature strings
+ * derived from the requirements (amount + payTo). Useful for testing
+ * the client→server→facilitator flow without real keys.
+ *
+ * @example
+ * ```ts
+ * const client = new s402Client();
+ * client.register('sui:testnet', mockExactClientScheme());
+ *
+ * const payload = await client.createPayment(requirements);
+ * // payload.payload.transaction === 'mock-pay-1000000-to-0xabc...'
+ * ```
+ */
+declare function mockExactClientScheme(): s402ClientScheme;
+/**
+ * Create a mock facilitator scheme for the `exact` payment type.
+ *
+ * Verifies that the payload's transaction string matches the expected
+ * format from `mockExactClientScheme()`. Settle always succeeds with
+ * a deterministic digest.
+ *
+ * Pair this with `mockExactClientScheme()` for end-to-end testing.
+ *
+ * @param options.txDigest - Custom transaction digest (default: 'mock-tx-digest')
+ * @param options.finalityMs - Custom finality time (default: 400)
+ * @param options.verifyFn - Override the verify function for custom behavior
+ * @param options.settleFn - Override the settle function for custom behavior
+ *
+ * @example
+ * ```ts
+ * const facilitator = new s402Facilitator();
+ * facilitator.register('sui:testnet', mockExactFacilitatorScheme());
+ *
+ * const result = await facilitator.process(payload, requirements);
+ * // result.success === true
+ * // result.txDigest === 'mock-tx-digest'
+ * ```
+ */
+declare function mockExactFacilitatorScheme(options?: {
+  txDigest?: string;
+  finalityMs?: number;
+  verifyFn?: (payload: s402PaymentPayload, requirements: s402PaymentRequirements) => Promise<s402VerifyResponse>;
+  settleFn?: (payload: s402PaymentPayload, requirements: s402PaymentRequirements) => Promise<s402SettleResponse>;
+}): s402FacilitatorScheme;
+/**
+ * Create a mock server scheme for the `exact` payment type.
+ *
+ * Builds payment requirements from a route config. Useful for testing
+ * server middleware without chain-specific adapters.
+ *
+ * @example
+ * ```ts
+ * const server = new s402ResourceServer();
+ * server.register('sui:testnet', mockExactServerScheme());
+ *
+ * const requirements = server.buildRequirements({
+ *   schemes: ['exact'],
+ *   price: '1000000',
+ *   network: 'sui:testnet',
+ *   payTo: '0xabc...',
+ *   asset: 'SUI',
+ * });
+ * ```
+ */
+declare function mockExactServerScheme(): s402ServerScheme;
+//#endregion
+export { mockExactClientScheme, mockExactFacilitatorScheme, mockExactServerScheme };

package/dist/test-utils.mjs

@@ -0,0 +1,132 @@
+import { S402_VERSION } from "./types.mjs";
+
+//#region src/test-utils.ts
+/**
+* Create a mock client scheme for the `exact` payment type.
+*
+* Produces payloads with deterministic transaction/signature strings
+* derived from the requirements (amount + payTo). Useful for testing
+* the client→server→facilitator flow without real keys.
+*
+* @example
+* ```ts
+* const client = new s402Client();
+* client.register('sui:testnet', mockExactClientScheme());
+*
+* const payload = await client.createPayment(requirements);
+* // payload.payload.transaction === 'mock-pay-1000000-to-0xabc...'
+* ```
+*/
+function mockExactClientScheme() {
+	return {
+		scheme: "exact",
+		async createPayment(requirements) {
+			return {
+				s402Version: S402_VERSION,
+				scheme: "exact",
+				payload: {
+					transaction: `mock-pay-${requirements.amount}-to-${requirements.payTo}`,
+					signature: "mock-signature"
+				}
+			};
+		}
+	};
+}
+/**
+* Create a mock facilitator scheme for the `exact` payment type.
+*
+* Verifies that the payload's transaction string matches the expected
+* format from `mockExactClientScheme()`. Settle always succeeds with
+* a deterministic digest.
+*
+* Pair this with `mockExactClientScheme()` for end-to-end testing.
+*
+* @param options.txDigest - Custom transaction digest (default: 'mock-tx-digest')
+* @param options.finalityMs - Custom finality time (default: 400)
+* @param options.verifyFn - Override the verify function for custom behavior
+* @param options.settleFn - Override the settle function for custom behavior
+*
+* @example
+* ```ts
+* const facilitator = new s402Facilitator();
+* facilitator.register('sui:testnet', mockExactFacilitatorScheme());
+*
+* const result = await facilitator.process(payload, requirements);
+* // result.success === true
+* // result.txDigest === 'mock-tx-digest'
+* ```
+*/
+function mockExactFacilitatorScheme(options) {
+	const txDigest = options?.txDigest ?? "mock-tx-digest";
+	const finalityMs = options?.finalityMs ?? 400;
+	return {
+		scheme: "exact",
+		async verify(payload, requirements) {
+			if (options?.verifyFn) return options.verifyFn(payload, requirements);
+			if (payload.scheme !== "exact") return {
+				valid: false,
+				invalidReason: `Expected exact scheme, got ${payload.scheme}`
+			};
+			const exact = payload;
+			const expectedTx = `mock-pay-${requirements.amount}-to-${requirements.payTo}`;
+			if (exact.payload.transaction !== expectedTx) return {
+				valid: false,
+				invalidReason: "Transaction does not match expected mock format"
+			};
+			return {
+				valid: true,
+				payerAddress: "0xmock-payer"
+			};
+		},
+		async settle(payload, requirements) {
+			if (options?.settleFn) return options.settleFn(payload, requirements);
+			return {
+				success: true,
+				txDigest,
+				finalityMs
+			};
+		}
+	};
+}
+/**
+* Create a mock server scheme for the `exact` payment type.
+*
+* Builds payment requirements from a route config. Useful for testing
+* server middleware without chain-specific adapters.
+*
+* @example
+* ```ts
+* const server = new s402ResourceServer();
+* server.register('sui:testnet', mockExactServerScheme());
+*
+* const requirements = server.buildRequirements({
+*   schemes: ['exact'],
+*   price: '1000000',
+*   network: 'sui:testnet',
+*   payTo: '0xabc...',
+*   asset: 'SUI',
+* });
+* ```
+*/
+function mockExactServerScheme() {
+	return {
+		scheme: "exact",
+		buildRequirements(config) {
+			return {
+				s402Version: S402_VERSION,
+				accepts: [...new Set([...config.schemes, "exact"])],
+				network: config.network,
+				asset: config.asset,
+				amount: config.price,
+				payTo: config.payTo,
+				facilitatorUrl: config.facilitatorUrl,
+				protocolFeeBps: config.protocolFeeBps,
+				receiptRequired: config.receiptRequired,
+				settlementMode: config.settlementMode
+			};
+		}
+	};
+}
+
+//#endregion
+export { mockExactClientScheme, mockExactFacilitatorScheme, mockExactServerScheme };

package/dist/types.d.mts

@@ -24,7 +24,15 @@ interface s402PaymentRequirements {
   amount: string;
   /** Recipient address */
   payTo: string;
-  /** Facilitator URL (optional for direct settlement) */
+  /**
+   * Facilitator URL (optional for direct settlement).
+   *
+   * Validated at the wire layer for protocol (`https:` or `http:` only) and
+   * embedded credentials (rejected). Consumers that fetch this URL MUST apply
+   * their own hostname/IP restrictions to prevent SSRF (block RFC 1918 private
+   * addresses, link-local 169.254.x.x, loopback, cloud metadata endpoints).
+   * DNS-based SSRF cannot be caught at URL parse time.
+   */
   facilitatorUrl?: string;
   /** AP2 mandate requirements (if agent spending authorization is needed) */
   mandate?: s402MandateRequirements;
@@ -99,10 +107,10 @@ interface s402EscrowExtra {
 interface s402UnlockExtra {
   /** Encryption ID for key servers */
   encryptionId: string;
-  /** Walrus blob ID containing the encrypted content */
-  walrusBlobId: string;
-  /** Encryption package ID on Sui */
-  encryptionPackageId: string;
+  /** Content identifier for the encrypted blob (e.g., Walrus blob ID, IPFS CID) */
+  encryptedContentId: string;
+  /** Identifier for the encryption service or module (e.g., Sui package ID, EVM contract address) */
+  encryptionServiceId: string;
 }
 /**
  * Prepaid-specific requirements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s402",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for five payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "Apache-2.0",
@@ -88,24 +88,30 @@
         "default": "./dist/receipts.mjs"
       },
       "default": "./dist/receipts.mjs"
+    },
+    "./test-utils": {
+      "import": {
+        "types": "./dist/test-utils.d.mts",
+        "default": "./dist/test-utils.mjs"
+      },
+      "default": "./dist/test-utils.mjs"
     }
   },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "fast-check": "^4.5.3",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.7.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^3.0.5"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build && npm run typecheck && npm run test",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^3.2.4",
-    "fast-check": "^4.5.3",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.7.0",
-    "vitepress": "^1.6.4",
-    "vitest": "^3.0.5"
   }
-}
+}

package/test/conformance/vectors/requirements-decode.json

@@ -62,7 +62,7 @@
   {
     "description": "Decode unlock scheme",
     "input": {
-      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVubG9jayJdLCJuZXR3b3JrIjoic3VpOm1haW5uZXQiLCJhc3NldCI6IjB4Mjo6c3VpOjpTVUkiLCJhbW91bnQiOiIxMDAwMDAwIiwicGF5VG8iOiIweGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTAiLCJ1bmxvY2siOnsiZW5jcnlwdGlvbklkIjoiZW5jLWFiYy0xMjMiLCJ3YWxydXNCbG9iSWQiOiJibG9iLXh5ei03ODkiLCJlbmNyeXB0aW9uUGFja2FnZUlkIjoiMHhwa2cxMjM0NTY3ODkwIn19"
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVubG9jayJdLCJuZXR3b3JrIjoic3VpOm1haW5uZXQiLCJhc3NldCI6IjB4Mjo6c3VpOjpTVUkiLCJhbW91bnQiOiIxMDAwMDAwIiwicGF5VG8iOiIweGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTAiLCJ1bmxvY2siOnsiZW5jcnlwdGlvbklkIjoiZW5jLWFiYy0xMjMiLCJlbmNyeXB0ZWRDb250ZW50SWQiOiJibG9iLXh5ei03ODkiLCJlbmNyeXB0aW9uU2VydmljZUlkIjoiMHhwa2cxMjM0NTY3ODkwIn19"
     },
     "expected": {
       "s402Version": "1",
@@ -75,8 +75,8 @@
       "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
       "unlock": {
         "encryptionId": "enc-abc-123",
-        "walrusBlobId": "blob-xyz-789",
-        "encryptionPackageId": "0xpkg1234567890"
+        "encryptedContentId": "blob-xyz-789",
+        "encryptionServiceId": "0xpkg1234567890"
       }
     },
     "shouldReject": false

package/test/conformance/vectors/requirements-encode.json

@@ -72,12 +72,12 @@
       "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
       "unlock": {
         "encryptionId": "enc-abc-123",
-        "walrusBlobId": "blob-xyz-789",
-        "encryptionPackageId": "0xpkg1234567890"
+        "encryptedContentId": "blob-xyz-789",
+        "encryptionServiceId": "0xpkg1234567890"
       }
     },
     "expected": {
-      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVubG9jayJdLCJuZXR3b3JrIjoic3VpOm1haW5uZXQiLCJhc3NldCI6IjB4Mjo6c3VpOjpTVUkiLCJhbW91bnQiOiIxMDAwMDAwIiwicGF5VG8iOiIweGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTAiLCJ1bmxvY2siOnsiZW5jcnlwdGlvbklkIjoiZW5jLWFiYy0xMjMiLCJ3YWxydXNCbG9iSWQiOiJibG9iLXh5ei03ODkiLCJlbmNyeXB0aW9uUGFja2FnZUlkIjoiMHhwa2cxMjM0NTY3ODkwIn19"
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVubG9jayJdLCJuZXR3b3JrIjoic3VpOm1haW5uZXQiLCJhc3NldCI6IjB4Mjo6c3VpOjpTVUkiLCJhbW91bnQiOiIxMDAwMDAwIiwicGF5VG8iOiIweGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTAiLCJ1bmxvY2siOnsiZW5jcnlwdGlvbklkIjoiZW5jLWFiYy0xMjMiLCJlbmNyeXB0ZWRDb250ZW50SWQiOiJibG9iLXh5ei03ODkiLCJlbmNyeXB0aW9uU2VydmljZUlkIjoiMHhwa2cxMjM0NTY3ODkwIn19"
     },
     "shouldReject": false
   },

package/test/conformance/vectors/validation-reject.json

@@ -175,14 +175,6 @@
     "shouldReject": true,
     "expectedErrorCode": "INVALID_PAYLOAD"
   },
-  {
-    "description": "Rejects amount exceeding u64 max",
-    "input": {
-      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbImV4YWN0Il0sIm5ldHdvcmsiOiJzdWk6bWFpbm5ldCIsImFzc2V0IjoiU1VJIiwiYW1vdW50IjoiMTg0NDY3NDQwNzM3MDk1NTE2MTYiLCJwYXlUbyI6IjB4YWJjIn0="
-    },
-    "shouldReject": true,
-    "expectedErrorCode": "INVALID_PAYLOAD"
-  },
   {
     "description": "Rejects invalid base64 header",
     "input": {

package/test/conformance/README.md

@@ -1,172 +0,0 @@
-# s402 Conformance Test Vectors
-
-Machine-readable test vectors that define s402-compliant behavior. Use these to verify any s402 implementation — TypeScript, Go, Python, Rust, etc.
-
-## Getting the Vectors
-
-The vectors ship with the `s402` npm package:
-
-```bash
-npm pack s402
-tar xzf s402-*.tgz
-ls package/test/conformance/vectors/
-```
-
-Or clone the repo directly:
-
-```bash
-git clone https://github.com/s402-protocol/core.git
-ls core/test/conformance/vectors/
-```
-
-## Vector Format
-
-Each JSON file contains an array of test cases:
-
-```json
-[
-  {
-    "description": "Human-readable test name",
-    "input": { ... },
-    "expected": { ... },
-    "shouldReject": false
-  }
-]
-```
-
-### Accept vectors (`shouldReject: false`)
-
-The implementation MUST produce `expected` when given `input`.
-
-### Reject vectors (`shouldReject: true`)
-
-The implementation MUST reject the input with an error. The `expectedErrorCode` field indicates which error:
-
-```json
-{
-  "description": "Rejects negative amount",
-  "input": { "header": "base64-encoded-malformed-json" },
-  "shouldReject": true,
-  "expectedErrorCode": "INVALID_PAYLOAD"
-}
-```
-
-## Vector Files
-
-| File | Tests | Description |
-|------|-------|-------------|
-| `requirements-encode.json` | Encode | `s402PaymentRequirements` object → base64 header string |
-| `requirements-decode.json` | Decode | base64 header string → `s402PaymentRequirements` object |
-| `payload-encode.json` | Encode | `s402PaymentPayload` object → base64 header string |
-| `payload-decode.json` | Decode | base64 header string → `s402PaymentPayload` object |
-| `settle-encode.json` | Encode | `s402SettleResponse` object → base64 header string |
-| `settle-decode.json` | Decode | base64 header string → `s402SettleResponse` object |
-| `body-transport.json` | Both | Requirements/payload/settle via JSON body (no base64) |
-| `compat-normalize.json` | Normalize | x402 V1/V2 input → normalized s402 output |
-| `receipt-format.json` | Format | Receipt fields → `X-S402-Receipt` header string |
-| `receipt-parse.json` | Parse | `X-S402-Receipt` header string → parsed receipt fields |
-| `validation-reject.json` | Reject | Malformed inputs that MUST be rejected |
-| `roundtrip.json` | Roundtrip | encode → decode → re-encode = identical output |
-
-## Encoding Scheme
-
-s402 uses **Unicode-safe base64** for HTTP header transport:
-
-1. JSON-serialize the object: `JSON.stringify(obj)`
-2. UTF-8 encode the string: `TextEncoder.encode(json)`
-3. Base64 encode the bytes: `btoa(bytes.map(b => String.fromCharCode(b)).join(''))`
-
-For ASCII-only content (the common case), this produces the same output as plain `btoa(json)`.
-
-Body transport uses raw JSON (no base64).
-
-## Receipt Header Format
-
-The `X-S402-Receipt` header uses colon-separated fields:
-
-```
-v2:base64(signature):callNumber:timestampMs:base64(responseHash)
-```
-
-- `v2` — version prefix (always "v2" for signed receipts)
-- `signature` — 64-byte Ed25519 signature, base64-encoded
-- `callNumber` — sequential call number (1-indexed, bigint string)
-- `timestampMs` — Unix timestamp in milliseconds (bigint string)
-- `responseHash` — response body hash (typically SHA-256, 32 bytes), base64-encoded
-
-In the vector JSON files, `signature` and `responseHash` are represented as arrays of byte values (0-255) since JSON has no binary type.
-
-## Implementing in Another Language
-
-1. Load the JSON vector files
-2. For each vector where `shouldReject` is `false`:
-   - Feed `input` to your encode/decode function
-   - Compare the result to `expected`
-3. For each vector where `shouldReject` is `true`:
-   - Feed `input` to your decode function
-   - Verify it throws/returns an error with the matching error code
-4. For roundtrip vectors:
-   - Verify `expected.identical` is `true`
-   - Verify `expected.firstEncode === expected.reEncode`
-
-### Key stripping on decode
-
-All three decode functions (`decodePaymentRequired`, `decodePaymentPayload`, `decodeSettleResponse`) MUST strip unknown top-level keys. Only known fields should survive the decode. This is a defense-in-depth measure at the HTTP trust boundary.
-
-**Requirements known top-level keys:** `s402Version`, `accepts`, `network`, `asset`, `amount`, `payTo`, `facilitatorUrl`, `mandate`, `protocolFeeBps`, `protocolFeeAddress`, `receiptRequired`, `settlementMode`, `expiresAt`, `stream`, `escrow`, `unlock`, `prepaid`, `extensions`.
-
-**Requirements sub-object known keys** (also stripped of unknowns):
-- `mandate`: `required`, `minPerTx`, `coinType`
-- `stream`: `ratePerSecond`, `budgetCap`, `minDeposit`, `streamSetupUrl`
-- `escrow`: `seller`, `arbiter`, `deadlineMs`
-- `unlock`: `encryptionId`, `walrusBlobId`, `encryptionPackageId`
-- `prepaid`: `ratePerCall`, `maxCalls`, `minDeposit`, `withdrawalDelayMs`, `providerPubkey`, `disputeWindowMs`
-
-**Payload known top-level keys:** `s402Version`, `scheme`, `payload`.
-
-**Payload inner keys** (per scheme):
-- `exact`, `stream`, `escrow`: `transaction`, `signature`
-- `unlock`: `transaction`, `signature`, `encryptionId`
-- `prepaid`: `transaction`, `signature`, `ratePerCall`, `maxCalls`
-
-**Settle response known keys:** `success`, `txDigest`, `receiptId`, `finalityMs`, `streamId`, `escrowId`, `balanceId`, `error`, `errorCode`.
-
-### JSON key ordering
-
-s402 vectors use JavaScript's `JSON.stringify()` key ordering (insertion order). Cross-language implementations MUST serialize keys in the same order as the vector files to produce identical base64 output. If your language's JSON serializer uses alphabetical ordering by default, you'll need ordered serialization (e.g., Go's `json.Marshal` on a struct with ordered fields, Python's `json.dumps` with `sort_keys=False`).
-
-Note: **decode also reorders keys**. The decode functions iterate their allowlist in the order listed above, not the input order. If the input JSON has keys in a different order, the decoded output follows the allowlist order. This affects roundtrip tests — the re-encoded output uses the allowlist order, which may differ from the original input order.
-
-### Header size limits
-
-Implementations SHOULD enforce a maximum header size of **64 KiB** (`MAX_HEADER_BYTES = 65536`). Headers exceeding this limit indicate abuse or misconfiguration and SHOULD be rejected before base64 decoding.
-
-### Rejection vector dispatch
-
-Rejection vectors are dispatched in this precedence order:
-
-1. If `expectedErrorCode` is `"RECEIPT_PARSE_ERROR"` → test `parseReceiptHeader`. Note: receipts throw a plain `Error`, not an `s402Error`, since receipts are a separate subsystem.
-2. If `input.decodeAs` is `"payload"` → test `decodePaymentPayload`
-3. If `input.decodeAs` is `"compat"` → test `normalizeRequirements` with the raw JSON (not base64)
-4. Otherwise → test `decodePaymentRequired` (the default)
-
-### Error codes
-
-Rejection vectors use `expectedErrorCode` values from the s402 error code enum:
-
-- `INVALID_PAYLOAD` — malformed or invalid input
-- `RECEIPT_PARSE_ERROR` — malformed receipt header (vector convention for receipt-specific parsing errors)
-
-## Regenerating Vectors
-
-If you modify the s402 encoding logic, regenerate vectors:
-
-```bash
-npx tsx test/conformance/generate-vectors.ts
-```
-
-Then run the conformance tests to verify:
-
-```bash
-pnpm run test
-```