s402 0.4.0 → 0.6.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, 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-tVj4sOr-.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 { 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-CKinOhyx.mjs";
 import { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader, s402Receipt, s402ReceiptSigner, s402ReceiptVerifier } from "./receipts.mjs";
 
 //#region src/client.d.ts
@@ -58,14 +58,208 @@ declare class s402Client {
   supports(network: string, scheme: s402Scheme): boolean;
 }
 //#endregion
+//#region src/extensions.d.ts
+/**
+ * Base extension interface. All three actor-specific interfaces extend this.
+ *
+ * Extensions use reverse-domain keys (per ADR-001 §4a) to avoid conflicts:
+ * e.g., "org.s402.discovery", "com.mycompany.ratelimit".
+ */
+interface s402Extension {
+  /** Reverse-domain key: e.g., "org.s402.discovery" */
+  readonly key: string;
+  /** Semver version (per ADR-001 §4b) */
+  readonly version: string;
+  /**
+   * If true, failure in this extension blocks the payment flow.
+   * If false, failure is logged but doesn't block (advisory).
+   */
+  readonly critical: boolean;
+  /** Keys of extensions that must run before this one. */
+  readonly dependsOn?: string[];
+}
+/**
+ * Client-side extension.
+ * Hooks fire during payment creation and settlement verification.
+ */
+interface s402ClientExtension extends s402Extension {
+  /** Enrich the payment payload before sending. */
+  enrichPayload?(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402PaymentPayload>;
+  /** Process extension data from the settle response. */
+  onSettlement?(response: s402SettleResponse, payload: s402PaymentPayload): Promise<void>;
+}
+/**
+ * Server-side extension (resource server).
+ * Hooks fire during requirements building and settlement response.
+ */
+interface s402ServerExtension extends s402Extension {
+  /** Enrich payment requirements before sending the 402 response. */
+  enrichRequirements?(requirements: s402PaymentRequirements, config: s402RouteConfig): s402PaymentRequirements;
+  /** Enrich the settlement response before returning to client. */
+  enrichSettleResponse?(response: s402SettleResponse, payload: s402PaymentPayload): Promise<s402SettleResponse>;
+}
+/**
+ * Facilitator-side extension.
+ * Hooks fire during the verify→settle pipeline.
+ *
+ * Four hooks covering every phase:
+ *   beforeVerify → verify() → afterVerify → beforeSettle → settle() → afterSettle
+ */
+interface s402FacilitatorExtension extends s402Extension {
+  /** Called before verify(). Can reject by throwing. */
+  beforeVerify?(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<void>;
+  /** Called after successful verify(), before settle(). */
+  afterVerify?(payload: s402PaymentPayload, verifyResult: s402VerifyResponse): Promise<void>;
+  /** Called before settle(). Last chance to abort. */
+  beforeSettle?(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<void>;
+  /** Called after successful settle() only (not on settlement failure).
+   *  Failures here never change the settle result — the tx is already on-chain. */
+  afterSettle?(payload: s402PaymentPayload, settleResult: s402SettleResponse): Promise<void>;
+}
+/**
+ * Type-safe extension data retrieval.
+ *
+ * The wire format is `Record<string, unknown>` for interop, but this helper
+ * provides typed access for TypeScript consumers.
+ *
+ * @example
+ * ```ts
+ * interface DiscoveryData { services: string[] }
+ * const data = getExtensionData<DiscoveryData>(requirements.extensions, 'org.s402.discovery');
+ * if (data) console.log(data.services);
+ * ```
+ */
+declare function getExtensionData<T>(extensions: Record<string, unknown> | undefined, key: string): T | undefined;
+/**
+ * Set extension data on an extensions record (creates if needed).
+ * Returns a new extensions object (does not mutate the input).
+ */
+declare function setExtensionData(extensions: Record<string, unknown> | undefined, key: string, data: unknown): Record<string, unknown>;
+/**
+ * Registry for extensions with dependency-ordered execution.
+ *
+ * Extensions are stored by key and sorted topologically based on `dependsOn`.
+ * Within the same dependency level, registration order is preserved.
+ *
+ * @example
+ * ```ts
+ * const registry = new s402ExtensionRegistry<s402FacilitatorExtension>();
+ * registry.register(rateLimitExtension);
+ * registry.register(analyticsExtension);
+ * const sorted = registry.sorted(); // dependency-ordered list
+ * ```
+ */
+declare class s402ExtensionRegistry<T extends s402Extension> {
+  private extensions;
+  private sortedCache;
+  /**
+   * Register an extension. Throws on duplicate key or dependency cycle.
+   */
+  register(ext: T): void;
+  /** Get a registered extension by key. */
+  get(key: string): T | undefined;
+  /** Number of registered extensions. */
+  get size(): number;
+  /**
+   * Return extensions in topological (dependency) order.
+   * Cached until a new extension is registered.
+   */
+  sorted(): T[];
+}
+/** Callback for advisory extension failures. */
+type s402ExtensionErrorHandler = (ext: s402Extension, error: unknown) => void;
+/**
+ * Run an async hook on all extensions in order.
+ * Critical extensions throw on failure; advisory extensions call the error handler.
+ */
+declare function runExtensionHooks<T extends s402Extension>(extensions: T[], hookName: string, runner: (ext: T) => Promise<void>, onError?: s402ExtensionErrorHandler): Promise<void>;
+//#endregion
 //#region src/facilitator.d.ts
+/**
+ * Options for `s402Facilitator.process()`.
+ *
+ * Callers can tune the verify→settle pipeline per-request.
+ */
+interface s402ProcessOptions {
+  /**
+   * Skip the verify() dry-run and go straight to settle().
+   *
+   * On chains where failed transactions cost zero gas (e.g., Sui PTBs revert
+   * atomically with no gas charge), the dry-run is pure latency overhead — it
+   * adds a full RPC round-trip (~200-400ms) just to predict what settle() will
+   * discover anyway. Setting `skipVerify: true` eliminates that round-trip.
+   *
+   * When `true`, process() still performs: expiration checks, scheme-mismatch
+   * checks, deduplication, and settle timeout. Only the dry-run is skipped.
+   *
+   * **Use when:** your chain adapter knows failures are free (Sui, Aptos).
+   * **Don't use when:** failed settlements cost gas (EVM L1s) — the dry-run
+   * saves real money by catching bad txs before broadcast.
+   *
+   * @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.
    */
   register(network: string, scheme: s402FacilitatorScheme): this;
+  /**
+   * Register a facilitator extension. Extensions fire in dependency order
+   * at four points in the process() pipeline: beforeVerify, afterVerify,
+   * beforeSettle, afterSettle.
+   *
+   * @throws {s402Error} `EXTENSION_FAILED` on duplicate key or dependency cycle
+   */
+  registerExtension(ext: s402FacilitatorExtension): this;
+  /**
+   * Set the handler for advisory (non-critical) extension failures.
+   * Critical extensions always throw; advisory extensions call this handler.
+   */
+  onExtensionError(handler: s402ExtensionErrorHandler): this;
   /**
    * Verify a payment payload by dispatching to the correct scheme.
    * Includes expiration guard and scheme-mismatch check.
@@ -88,6 +282,7 @@ declare class s402Facilitator {
    *
    * @param payload - Client's payment payload
    * @param requirements - Server's payment requirements
+   * @param options - Optional process configuration (e.g., `{ skipVerify: true }` for zero-cost-failure chains)
    * @returns Settlement result (check `result.success` and `result.errorCode`)
    *
    * @example
@@ -105,7 +300,10 @@ declare class s402Facilitator {
    * }
    * ```
    */
-  process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+  process(payload: s402PaymentPayload, requirements: s402PaymentRequirements, options?: s402ProcessOptions): Promise<s402SettleResponse>;
+  private executeProcess;
+  private getCached;
+  private cacheResult;
   /**
    * Check if a scheme is supported for a network.
    */
@@ -146,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));
    * ```
@@ -185,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, 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 };
+//#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 };