s402 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 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, s402SettlementOverrides, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402UptoExtra, s402UptoPayload, 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-m-uk4zyH.mjs";
+import { MAX_BODY_BYTES, 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-M-z-UV0c.mjs";
 import { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader, s402Receipt, s402ReceiptSigner, s402ReceiptVerifier } from "./receipts.mjs";
 
 //#region src/client.d.ts
@@ -32,7 +32,7 @@ declare class s402Client {
    * `accepts` array that we have a registered implementation for.
    *
    * Accepts typed s402PaymentRequirements only. For x402 input, normalize
-   * first via `normalizeRequirements()` from 's402/compat'.
+   * first via `normalizeRequirements()` from 's402/compat/x402'.
    *
    * @param requirements - Server's payment requirements (from a 402 response)
    * @returns Payment payload ready to send in the `x-payment` header
@@ -199,12 +199,50 @@ interface s402ProcessOptions {
    * @default false
    */
   skipVerify?: boolean;
+  /**
+   * Caller-supplied idempotency key (e.g., from an `Idempotency-Key` HTTP
+   * header). When present, this string becomes the dedup cache key instead of
+   * the auto-computed payload fingerprint.
+   *
+   * Semantics (Stripe-compatible):
+   * - Same key + same payload → returns the cached original result (retry dedup)
+   * - Same key while first call is in flight → awaits the in-flight promise (concurrent dedup)
+   * - Key collisions across distinct payloads are the caller's responsibility
+   *
+   * Omit this field to fall back to payload-based dedup (JSON fingerprint).
+   */
+  idempotencyKey?: string;
+}
+/**
+ * Constructor options for `s402Facilitator`.
+ */
+interface s402FacilitatorOptions {
+  /**
+   * How long a completed result stays in the retry-dedup cache, in milliseconds.
+   * A retry arriving within this window returns the cached original result
+   * instead of re-executing. Tune based on your client's retry budget.
+   *
+   * @default 300_000 (5 minutes)
+   */
+  dedupTtlMs?: number;
+  /**
+   * Maximum entries retained in the retry-dedup cache. When the cache exceeds
+   * this size, the oldest entry (by insertion order) is evicted. Bound memory
+   * under high request volume; higher values retain more retry history.
+   *
+   * @default 10_000
+   */
+  dedupMaxEntries?: number;
 }
 declare class s402Facilitator {
   private schemes;
   private inFlight;
+  private completed;
+  private dedupTtlMs;
+  private dedupMaxEntries;
   private extensionRegistry;
   private extensionErrorHandler?;
+  constructor(options?: s402FacilitatorOptions);
   /**
    * Register a scheme-specific facilitator for a network.
    */
@@ -263,6 +301,9 @@ declare class s402Facilitator {
    * ```
    */
   process(payload: s402PaymentPayload, requirements: s402PaymentRequirements, options?: s402ProcessOptions): Promise<s402SettleResponse>;
+  private executeProcess;
+  private getCached;
+  private cacheResult;
   /**
    * Check if a scheme is supported for a network.
    */
@@ -303,9 +344,9 @@ declare class s402ResourceServer {
    * const requirements = server.buildRequirements({
    *   schemes: ['exact'],
    *   price: '1000000',
-   *   network: 'sui:mainnet',
-   *   payTo: '0xYOUR_ADDRESS',
-   *   asset: '0x2::sui::SUI',
+   *   network: 'your-chain:mainnet',
+   *   payTo: 'YOUR_ADDRESS',
+   *   asset: 'NATIVE_TOKEN',
    * });
    * res.status(402).setHeader('payment-required', encodePaymentRequired(requirements));
    * ```
@@ -342,4 +383,258 @@ 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, getExtensionData, isValidAmount, isValidU64Amount, parseReceiptHeader, runExtensionHooks, s402Client, type s402ClientExtension, type s402ClientScheme, type s402DirectScheme, type s402Discovery, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, type s402Extension, type s402ExtensionErrorHandler, s402ExtensionRegistry, s402Facilitator, type s402FacilitatorExtension, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402ProcessOptions, type s402Receipt, type s402ReceiptSigner, type s402ReceiptVerifier, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerExtension, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402SettlementOverrides, type s402SettlementVerification, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402UptoExtra, type s402UptoPayload, type s402VerifyResponse, setExtensionData, validateRequirementsShape };
+//#region src/envelope.d.ts
+/** Content type for the settlement envelope wire format. */
+declare const S402_ENVELOPE_CONTENT_TYPE: "application/vnd.s402.envelope+json";
+/** SRI-compatible digest algorithm identifiers. See ADR-007. */
+type s402DigestAlg = 'sha256' | 'sha384' | 'sha512' | 'blake3';
+/** Signature algorithm identifiers. See ADR-007. */
+type s402SigAlg = 'ed25519' | 'ed25519ph' | 'secp256k1' | 'ml-dsa-44';
+/** Algorithm identifiers carried in every envelope for crypto-agility. */
+interface s402Algs {
+  digest: s402DigestAlg;
+  sig: s402SigAlg;
+}
+interface s402EnvelopeBase {
+  /** Protocol version — matches `s402-Version` header. */
+  s402Version: string;
+  /** Scheme name. */
+  scheme: s402Scheme;
+  /** Content-hash of the scheme spec this response was computed against (SRI form). */
+  specDigest: string;
+  /** Cryptographic request→response binding (SRI form). See `computeTxBinding`. */
+  txBinding: string;
+  /** Network identifier (e.g. "sui:mainnet"). Prevents cross-network replay. */
+  network: string;
+  /** Algorithm identifiers — enables migration without wire-break. */
+  algs: s402Algs;
+  /** ISO-8601 UTC millisecond timestamp. Client rejects if skew > 5 min. */
+  timestamp: string;
+  /** Facilitator identities that contributed to this envelope. */
+  facilitatorIds?: string[];
+}
+interface s402EnvelopeSettled extends s402EnvelopeBase {
+  status: 'settled';
+  settled: {
+    /** Chain-specific settlement blob — opaque at protocol layer. */settlement: unknown;
+    settledAt: string; /** Scheme-specific attestation (e.g., unlock TX2). Inline per ADR-008 S11. */
+    attestation?: unknown;
+  };
+}
+interface s402EnvelopeVerified extends s402EnvelopeBase {
+  status: 'verified';
+  verified: Record<string, never>;
+}
+interface s402EnvelopeRejected extends s402EnvelopeBase {
+  status: 'rejected';
+  rejected: {
+    error: {
+      code: s402ErrorCodeType;
+      message: string;
+    };
+  };
+}
+interface s402EnvelopePending extends s402EnvelopeBase {
+  status: 'pending';
+  pending: {
+    retryAfter?: number;
+    reason: string;
+  };
+}
+type s402Envelope = s402EnvelopeSettled | s402EnvelopeVerified | s402EnvelopeRejected | s402EnvelopePending;
+/**
+ * Compute the `txBinding` value for a request pair.
+ *
+ * ```
+ * txBinding = "sha256-" || base64url_no_pad(
+ *   sha256(
+ *     "s402-txbinding-v1\0"
+ *     || JCS(requirements)
+ *     || 0x1E
+ *     || JCS(payload)
+ *   )
+ * )
+ * ```
+ *
+ * Clients recompute this locally from their OWN `{requirements, payload}` and
+ * compare to `envelope.txBinding` using a constant-time primitive. See S14.
+ */
+declare function computeTxBinding(requirements: s402PaymentRequirements, payload: s402PaymentPayload, alg?: s402DigestAlg): Promise<string>;
+interface BuildEnvelopeContext {
+  s402Version: string;
+  scheme: s402Scheme;
+  specDigest: string;
+  network: string;
+  requirements: s402PaymentRequirements;
+  payload: s402PaymentPayload;
+  algs?: s402Algs;
+  facilitatorIds?: string[];
+  timestamp?: string;
+}
+declare function buildSettledEnvelope(ctx: BuildEnvelopeContext, settled: s402EnvelopeSettled['settled']): Promise<s402EnvelopeSettled>;
+declare function buildVerifiedEnvelope(ctx: BuildEnvelopeContext): Promise<s402EnvelopeVerified>;
+declare function buildRejectedEnvelope(ctx: BuildEnvelopeContext, error: {
+  code: s402ErrorCodeType;
+  message: string;
+}): Promise<s402EnvelopeRejected>;
+declare function buildPendingEnvelope(ctx: BuildEnvelopeContext, pending: s402EnvelopePending['pending']): Promise<s402EnvelopePending>;
+declare function encodeEnvelopeBody(envelope: s402Envelope): string;
+declare function decodeEnvelopeBody(body: string): s402Envelope;
+declare function validateEnvelopeShape(v: unknown): asserts v is s402Envelope;
+interface VerifyEnvelopeOptions {
+  /** The original request the client sent. `txBinding` is recomputed from these. */
+  originalRequest: {
+    requirements: s402PaymentRequirements;
+    payload: s402PaymentPayload;
+  };
+  /** Scheme-digest the client pinned or discovered. */
+  expectedSpecDigest: string;
+  /** Digest algorithms the client accepts. Reject anything outside this set. */
+  acceptedDigestAlgs?: s402DigestAlg[];
+  /** Signature algorithms the client accepts. Reject anything outside this set. */
+  acceptedSigAlgs?: s402SigAlg[];
+  /** Max acceptable skew between envelope.timestamp and local clock, in ms. */
+  maxTimestampSkewMs?: number;
+  /** Override clock for testing. */
+  now?: () => number;
+}
+/**
+ * Perform the ADR-007 client-side MUST checks. Throws on any failure.
+ *
+ * Scheme-match, spec-digest, network, txBinding (constant-time), timestamp,
+ * and algorithm acceptance. Resource-binding and unlock-attestation checks
+ * live in higher layers (they need request-intent + scheme-specific context).
+ */
+declare function verifyEnvelope(envelope: s402Envelope, options: VerifyEnvelopeOptions): Promise<void>;
+/**
+ * Constant-time string equality — S14 invariant.
+ *
+ * Compares every character regardless of mismatches, so the time-to-answer
+ * does not leak digest prefix information. Lengths are compared first (their
+ * difference is not secret — a mismatched length means the response is
+ * definitely not ours).
+ */
+declare function constantTimeStringEqual(a: string, b: string): boolean;
+//#endregion
+//#region src/canonicalization.d.ts
+/**
+ * s402 canonicalization — RFC 8785 JSON Canonicalization Scheme (JCS).
+ *
+ * JCS produces a deterministic byte sequence from a JSON value. Two parsers
+ * that honor JCS produce identical bytes for semantically equal JSON, enabling
+ * content-hashing and cross-language interop.
+ *
+ * Full spec: see `spec/canonicalization.md` (project-local, normative).
+ * Summary applied here:
+ *   - Object keys sorted by UTF-16 code unit order (RFC 8785 §3.2.3)
+ *   - Numbers rendered per ECMA-404 shortest-roundtrip (RFC 8785 §3.2.2)
+ *   - Strings escape only the minimum required (RFC 8785 §3.2.1)
+ *   - Arrays preserve order
+ *   - No whitespace
+ *   - Reject non-finite numbers, BigInt, undefined, functions, symbols
+ *
+ * This module implements JCS *serialization* only. Strict parsing with
+ * duplicate-key rejection is deferred to a later PR — envelope txBinding
+ * verification never parses untrusted canonical JSON, so dup-key handling is
+ * not on this critical path. (Client recomputes from its own objects.)
+ */
+/**
+ * JCS value type — mirrors JSON's data model.
+ * `unknown` arrays/objects are fine; we'll type-check at serialize time.
+ */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Serialize a JSON value to RFC 8785 canonical form.
+ *
+ * Returns a UTF-8 byte string (represented as `Uint8Array`). Callers hash the
+ * bytes directly; do NOT re-encode via `TextEncoder` (double-encoding risk).
+ *
+ * @throws {s402Error} INVALID_PAYLOAD on non-JSON-safe values (NaN, Infinity,
+ *                    bigint, undefined, functions, symbols, circular refs).
+ */
+declare function canonicalize(value: unknown): Uint8Array;
+/**
+ * Convenience: canonicalize to a UTF-8 string.
+ *
+ * Use only when a downstream API demands a string; prefer the Uint8Array form
+ * for digest inputs to avoid an extra encode/decode round-trip.
+ */
+declare function canonicalizeToString(value: unknown): string;
+//#endregion
+//#region src/accept-payment.d.ts
+/**
+ * `Accept-Payment` header — content negotiation for HTTP 402 protocols.
+ *
+ * Modeled on RFC 7231 `Accept` / `Accept-Language` with q-value preference.
+ * A client advertises which payment schemes it can produce; the server picks
+ * the best scheme both sides support. This lets s402, x402, and MPP
+ * ({@link https://machinepayments.org}) coexist on the same endpoint.
+ *
+ * Grammar (informal):
+ * ```
+ *   Accept-Payment = 1#( scheme [ OWS ";" OWS "q=" qvalue ] )
+ *   scheme         = token         e.g. "s402/prepaid", "tempo/charge"
+ *   qvalue         = 0.0 - 1.0     default 1.0, 3-decimal precision
+ * ```
+ *
+ * Entries with `q=0` are explicit rejections — they are retained in parsed
+ * output (callers may need to know the client named them) but {@link selectBestScheme}
+ * will never pick them.
+ *
+ * @packageDocumentation
+ */
+interface AcceptPaymentEntry {
+  /** Scheme token, normalized to lowercase (e.g. "s402/prepaid"). */
+  readonly scheme: string;
+  /** Quality value 0.0–1.0. Default 1.0 when omitted. */
+  readonly q: number;
+}
+/**
+ * Parse an `Accept-Payment` header into sorted preference entries.
+ *
+ * - Entries are returned in descending q-value order; ties preserve input order
+ *   (stable sort).
+ * - Malformed entries are dropped silently (robustness principle).
+ * - Scheme tokens are lowercased. Whitespace around `;` and `,` is tolerated.
+ * - Duplicate schemes: the highest-q occurrence wins.
+ *
+ * @example
+ * parseAcceptPayment('s402/prepaid, s402/exact;q=0.8, tempo/charge;q=0.5');
+ * // [
+ * //   { scheme: 's402/prepaid', q: 1 },
+ * //   { scheme: 's402/exact',   q: 0.8 },
+ * //   { scheme: 'tempo/charge', q: 0.5 },
+ * // ]
+ */
+declare function parseAcceptPayment(header: string | null | undefined): AcceptPaymentEntry[];
+/**
+ * Format a list of entries back into an `Accept-Payment` header string.
+ *
+ * Entries with `q=1` omit the parameter (it's the default). Other q-values
+ * are emitted with up to 3 decimals, trailing zeros trimmed.
+ *
+ * @example
+ * formatAcceptPayment([
+ *   { scheme: 's402/prepaid', q: 1 },
+ *   { scheme: 'tempo/charge', q: 0.5 },
+ * ]);
+ * // "s402/prepaid, tempo/charge;q=0.5"
+ */
+declare function formatAcceptPayment(entries: readonly AcceptPaymentEntry[]): string;
+/**
+ * Select the best scheme both sides agree on.
+ *
+ * - Walks `preferred` in order (parseAcceptPayment returns them sorted by q).
+ * - Returns the first scheme that appears in `supported`.
+ * - Entries with `q=0` are explicit rejections and are skipped.
+ * - Scheme comparison is case-insensitive; the returned string matches the
+ *   casing from `supported`.
+ * - If `preferred` is empty (no header), falls back to the first entry in
+ *   `supported` (server's default).
+ * - Returns `null` if no overlap exists.
+ */
+declare function selectBestScheme(preferred: readonly AcceptPaymentEntry[], supported: readonly string[]): string | null;
+//#endregion
+export { type AcceptPaymentEntry, type BuildEnvelopeContext, type JsonValue, MAX_BODY_BYTES, S402_CONTENT_TYPE, S402_ENVELOPE_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, type VerifyEnvelopeOptions, buildPendingEnvelope, buildRejectedEnvelope, buildSettledEnvelope, buildVerifiedEnvelope, canonicalize, canonicalizeToString, computeTxBinding, constantTimeStringEqual, createS402Error, decodeEnvelopeBody, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodeEnvelopeBody, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatAcceptPayment, formatReceiptHeader, getExtensionData, isValidAmount, isValidU64Amount, parseAcceptPayment, parseReceiptHeader, runExtensionHooks, type s402Algs, s402Client, type s402ClientExtension, type s402ClientScheme, type s402DigestAlg, type s402DirectScheme, type s402Discovery, type s402Envelope, type s402EnvelopeBase, type s402EnvelopePending, type s402EnvelopeRejected, type s402EnvelopeSettled, type s402EnvelopeVerified, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, type s402Extension, type s402ExtensionErrorHandler, s402ExtensionRegistry, s402Facilitator, type s402FacilitatorExtension, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402ProcessOptions, type s402Receipt, type s402ReceiptSigner, type s402ReceiptVerifier, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerExtension, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402SettlementOverrides, type s402SettlementVerification, type s402SigAlg, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402UptoExtra, type s402UptoPayload, type s402VerifyResponse, selectBestScheme, setExtensionData, validateEnvelopeShape, validateRequirementsShape, verifyEnvelope };