s402 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.5.0] - 2026-04-12
+
+### Added
+
+- **`upto` scheme V2 features (DAN-284).** Two new fields close x402's upto overcharge vulnerability:
+  - `estimatedAmount` on `s402UptoExtra` — server's advisory cost estimate so clients can set tight ceilings
+  - `settlementCeiling` on `s402UptoPayload` — client-chosen, on-chain-enforced cap. Move contract rejects `actualAmount > settlementCeiling`. Must satisfy `1 <= settlementCeiling <= maxAmount`. See ADR-003 §Decision 3 and §Decision 8.
+- **Extension system (DAN-285, ADR-004).** Typed, lifecycle-aware plugin architecture:
+  - Three actor-specific interfaces: `s402ClientExtension`, `s402ServerExtension`, `s402FacilitatorExtension`
+  - Four facilitator hooks in pipeline order: `beforeVerify` → `afterVerify` → `beforeSettle` → `afterSettle`
+  - `s402ExtensionRegistry` with dependency ordering via Kahn's topological sort
+  - Critical vs advisory error handling: `critical: true` extensions throw, advisory extensions log and continue
+  - `getExtensionData<T>()` / `setExtensionData()` type-safe helpers
+  - `./extensions` sub-path export added to package.json
+- **`skipVerify` option on `process()`.** New `s402ProcessOptions` interface with `skipVerify?: boolean`. Eliminates the verify() dry-run RPC round-trip (~200-400ms) for chains where failed transactions cost zero gas (Sui PTBs). All pre-flight checks (expiration, scheme-mismatch, dedup) still run.
+- **`EXTENSION_FAILED` error code** — `retryable: false`, for critical extension pipeline failures.
+- **154 conformance test vectors** (was ~130). New vectors for: upto requirements with estimatedAmount, upto payloads with settlementCeiling, settle responses with actualAmount/depositId, V2 rejection vectors, upto roundtrips, mandate.minPerTx validation.
+
+### Fixed
+
+- **Settle response type validation (M1).** `validateSettleShape` now rejects non-string `actualAmount` and `depositId` — a malicious facilitator could previously inject numeric types that passed through to consumer code.
+- **Prepaid payload amount validation (M2).** `ratePerCall` and `maxCalls` in payload now validated with `isValidAmount()`, matching the requirements-side validation. Previously only type-checked as strings.
+- **Mandate minPerTx amount validation (L1).** `mandate.minPerTx` now validated with `isValidAmount()` for consistency with other amount fields.
+- **afterSettle error observability.** Catch block now forwards to `extensionErrorHandler` instead of silently swallowing critical extension errors (the settlement result is still never changed — tx is already on-chain).
+- **Stale comment in validatePayloadShape.** Updated to document upto's scheme-specific inner keys alongside prepaid and unlock.
+
+### Changed
+
+- **831 tests across 17 files** (was 798). New coverage: standalone verify/settle guard tests, V2 validation edge cases, settle response type checks, prepaid amount validation, extension system integration.
+- Conformance README updated with `estimatedAmount` in upto sub-object keys and `settlementCeiling` in payload inner keys.
+
 ## [0.4.0] - 2026-04-11
 
 ### Changed

package/dist/compat.d.mts

@@ -58,7 +58,7 @@ interface x402PaymentPayload {
  * Handles both V1 (`maxAmountRequired`) and V2 (`amount`) wire formats.
  * Maps x402's single scheme to s402's accepts array.
  */
-declare function fromX402Requirements(x402: x402PaymentRequirements): s402PaymentRequirements;
+declare function fromX402Requirements(x402: x402PaymentRequirements, now?: number): s402PaymentRequirements;
 /**
  * Convert inbound x402 payment payload to s402 format.
  * Validates that required fields are present and correctly typed.
@@ -66,7 +66,7 @@ declare function fromX402Requirements(x402: x402PaymentRequirements): s402Paymen
 declare function fromX402Payload(x402: x402PaymentPayload): s402ExactPayload;
 /**
  * Convert outbound s402 requirements to x402 V1 wire format.
- * Strips s402-only fields (mandate, stream, escrow, unlock extensions).
+ * Strips s402-only fields (mandate, upto, prepaid, stream, escrow, unlock extensions).
  * Only works for "exact" scheme — other schemes have no x402 equivalent.
  *
  * Includes both `maxAmountRequired` (V1) and `amount` (V2) for maximum interop.
@@ -101,7 +101,7 @@ declare function isX402Envelope(obj: Record<string, unknown>): boolean;
  * Picks the first requirement from the `accepts` array.
  * Copies `x402Version` from the envelope onto the requirement for downstream processing.
  */
-declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope): s402PaymentRequirements;
+declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope, now?: number): s402PaymentRequirements;
 /**
  * Auto-detect and normalize: if x402, convert to s402. If already s402, validate and pass through.
  * Handles x402 V1 (flat), x402 V2 (envelope with accepts array), and s402 formats.
@@ -123,6 +123,6 @@ declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope): s402Pa
  * // Always returns s402PaymentRequirements regardless of input format
  * ```
  */
-declare function normalizeRequirements(obj: Record<string, unknown>): s402PaymentRequirements;
+declare function normalizeRequirements(obj: Record<string, unknown>, now?: number): s402PaymentRequirements;
 //#endregion
 export { fromX402Envelope, fromX402Payload, fromX402Requirements, isS402, isX402, isX402Envelope, normalizeRequirements, toX402Payload, toX402Requirements, x402PaymentPayload, x402PaymentRequiredEnvelope, x402PaymentRequirements };

package/dist/compat.mjs

@@ -8,7 +8,7 @@ import { isValidAmount, pickRequirementsFields, validateRequirementsShape } from
 * Handles both V1 (`maxAmountRequired`) and V2 (`amount`) wire formats.
 * Maps x402's single scheme to s402's accepts array.
 */
-function fromX402Requirements(x402) {
+function fromX402Requirements(x402, now) {
 	const amount = x402.amount ?? x402.maxAmountRequired;
 	if (!amount) throw new s402Error("INVALID_PAYLOAD", "x402 requirements missing both \"amount\" (V2) and \"maxAmountRequired\" (V1)");
 	if (!isValidAmount(amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${amount}": must be a non-negative integer string`);
@@ -20,6 +20,7 @@ function fromX402Requirements(x402) {
 		if (e instanceof s402Error) throw e;
 		throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl is not a valid URL");
 	}
+	const expiresAt = x402.maxTimeoutSeconds != null && x402.maxTimeoutSeconds > 0 ? (now ?? Date.now()) + x402.maxTimeoutSeconds * 1e3 : void 0;
 	return {
 		s402Version: S402_VERSION,
 		accepts: ["exact"],
@@ -28,6 +29,7 @@ function fromX402Requirements(x402) {
 		amount,
 		payTo: x402.payTo,
 		facilitatorUrl: x402.facilitatorUrl,
+		expiresAt,
 		extensions: x402.extensions
 	};
 }
@@ -50,7 +52,7 @@ function fromX402Payload(x402) {
 }
 /**
 * Convert outbound s402 requirements to x402 V1 wire format.
-* Strips s402-only fields (mandate, stream, escrow, unlock extensions).
+* Strips s402-only fields (mandate, upto, prepaid, stream, escrow, unlock extensions).
 * Only works for "exact" scheme — other schemes have no x402 equivalent.
 *
 * Includes both `maxAmountRequired` (V1) and `amount` (V2) for maximum interop.
@@ -113,14 +115,14 @@ function isX402Envelope(obj) {
 * Picks the first requirement from the `accepts` array.
 * Copies `x402Version` from the envelope onto the requirement for downstream processing.
 */
-function fromX402Envelope(envelope) {
+function fromX402Envelope(envelope, now) {
 	if (!envelope.accepts || envelope.accepts.length === 0) throw new s402Error("INVALID_PAYLOAD", "x402 V2 envelope has empty accepts array");
 	const req = {
 		...envelope.accepts[0],
 		x402Version: envelope.x402Version
 	};
 	validateX402Shape(req);
-	return fromX402Requirements(req);
+	return fromX402Requirements(req, now);
 }
 /**
 * Auto-detect and normalize: if x402, convert to s402. If already s402, validate and pass through.
@@ -143,20 +145,20 @@ function fromX402Envelope(envelope) {
 * // Always returns s402PaymentRequirements regardless of input format
 * ```
 */
-function normalizeRequirements(obj) {
+function normalizeRequirements(obj, now) {
 	if (obj == null || typeof obj !== "object" || Array.isArray(obj)) throw new s402Error("INVALID_PAYLOAD", `Payment requirements must be a plain object, got ${obj === null ? "null" : Array.isArray(obj) ? "array" : typeof obj}`);
 	if (isS402(obj)) {
 		validateRequirementsShape(obj);
 		return pickRequirementsFields(obj);
 	}
 	if (isX402Envelope(obj)) {
-		const record = fromX402Envelope(obj);
+		const record = fromX402Envelope(obj, now);
 		validateRequirementsShape(record);
 		return pickRequirementsFields(record);
 	}
 	if (isX402(obj)) {
 		validateX402Shape(obj);
-		const record = fromX402Requirements(obj);
+		const record = fromX402Requirements(obj, now);
 		validateRequirementsShape(record);
 		return pickRequirementsFields(record);
 	}

package/dist/errors.d.mts

@@ -24,6 +24,7 @@ declare const s402ErrorCode: {
   readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
   readonly SETTLEMENT_FAILED: "SETTLEMENT_FAILED";
   readonly DIGEST_MISMATCH: "DIGEST_MISMATCH";
+  readonly EXTENSION_FAILED: "EXTENSION_FAILED";
 };
 type s402ErrorCodeType = (typeof s402ErrorCode)[keyof typeof s402ErrorCode];
 interface s402ErrorInfo {

package/dist/errors.mjs

@@ -23,7 +23,8 @@ const s402ErrorCode = {
 	REQUIREMENTS_EXPIRED: "REQUIREMENTS_EXPIRED",
 	VERIFICATION_FAILED: "VERIFICATION_FAILED",
 	SETTLEMENT_FAILED: "SETTLEMENT_FAILED",
-	DIGEST_MISMATCH: "DIGEST_MISMATCH"
+	DIGEST_MISMATCH: "DIGEST_MISMATCH",
+	EXTENSION_FAILED: "EXTENSION_FAILED"
 };
 /** Error recovery hints for each error code */
 const ERROR_HINTS = {
@@ -90,6 +91,10 @@ const ERROR_HINTS = {
 	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."
+	},
+	EXTENSION_FAILED: {
+		retryable: false,
+		suggestedAction: "A critical extension blocked the payment flow. Contact the extension provider or disable the extension."
 	}
 };
 /**

package/dist/http.d.mts

@@ -117,9 +117,13 @@ declare function isValidU64Amount(s: string): boolean;
  */
 declare function validateMandateShape(value: unknown): void;
 /**
- * Validate stream sub-object.
- * Checks required fields are present and correctly typed.
+ * Validate upto sub-object (usage-based variable settlement).
  */
+declare function validateUptoShape(value: unknown): void;
+/**
+ * Validate settlementOverrides sub-object.
+ */
+declare function validateSettlementOverridesShape(value: unknown): void;
 declare function validateStreamShape(value: unknown): void;
 /**
  * Validate escrow sub-object.
@@ -195,4 +199,4 @@ declare function detectProtocol(headers: Headers): 's402' | 'x402' | 'unknown';
  */
 declare function extractRequirementsFromResponse(response: Response): s402PaymentRequirements | null;
 //#endregion
-export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };
+export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateSettlementOverridesShape, validateStreamShape, validateSubObjects, validateUnlockShape, validateUptoShape };

package/dist/http.mjs

@@ -83,10 +83,12 @@ const S402_REQUIREMENTS_KEYS = new Set([
 	"receiptRequired",
 	"settlementMode",
 	"expiresAt",
+	"upto",
+	"settlementOverrides",
+	"prepaid",
 	"stream",
 	"escrow",
 	"unlock",
-	"prepaid",
 	"extensions"
 ]);
 /** Known keys for each sub-object type — used to strip extra keys at the trust boundary. */
@@ -96,6 +98,21 @@ const S402_SUB_OBJECT_KEYS = {
 		"minPerTx",
 		"coinType"
 	]),
+	upto: new Set([
+		"maxAmount",
+		"settlementDeadlineMs",
+		"usageReportUrl",
+		"estimatedAmount"
+	]),
+	settlementOverrides: new Set(["actualAmount"]),
+	prepaid: new Set([
+		"ratePerCall",
+		"maxCalls",
+		"minDeposit",
+		"withdrawalDelayMs",
+		"providerPubkey",
+		"disputeWindowMs"
+	]),
 	stream: new Set([
 		"ratePerSecond",
 		"budgetCap",
@@ -111,14 +128,6 @@ const S402_SUB_OBJECT_KEYS = {
 		"encryptionId",
 		"encryptedContentId",
 		"encryptionServiceId"
-	]),
-	prepaid: new Set([
-		"ratePerCall",
-		"maxCalls",
-		"minDeposit",
-		"withdrawalDelayMs",
-		"providerPubkey",
-		"disputeWindowMs"
 	])
 };
 /** Strip unknown keys from a sub-object, returning a clean copy. */
@@ -178,22 +187,29 @@ const S402_PAYLOAD_TOP_KEYS = new Set([
 ]);
 /**
 * Known inner payload keys per scheme. All schemes share transaction + signature;
-* unlock adds encryptionId, prepaid adds ratePerCall + maxCalls.
+* upto adds maxAmount + settlementCeiling, prepaid adds ratePerCall + maxCalls,
+* unlock adds encryptionId.
 */
 const S402_PAYLOAD_INNER_KEYS = {
 	exact: new Set(["transaction", "signature"]),
-	stream: new Set(["transaction", "signature"]),
-	escrow: new Set(["transaction", "signature"]),
-	unlock: new Set([
+	upto: new Set([
 		"transaction",
 		"signature",
-		"encryptionId"
+		"maxAmount",
+		"settlementCeiling"
 	]),
 	prepaid: new Set([
 		"transaction",
 		"signature",
 		"ratePerCall",
 		"maxCalls"
+	]),
+	stream: new Set(["transaction", "signature"]),
+	escrow: new Set(["transaction", "signature"]),
+	unlock: new Set([
+		"transaction",
+		"signature",
+		"encryptionId"
 	])
 };
 /** Return a clean payload object with only known s402 payload fields. */
@@ -249,9 +265,11 @@ const S402_SETTLE_RESPONSE_KEYS = new Set([
 	"txDigest",
 	"receiptId",
 	"finalityMs",
+	"actualAmount",
+	"depositId",
+	"balanceId",
 	"streamId",
 	"escrowId",
-	"balanceId",
 	"error",
 	"errorCode"
 ]);
@@ -277,10 +295,11 @@ function decodeSettleResponse(header) {
 /** Valid s402 payment scheme values */
 const VALID_SCHEMES = new Set([
 	"exact",
+	"upto",
+	"prepaid",
 	"stream",
 	"escrow",
-	"unlock",
-	"prepaid"
+	"unlock"
 ]);
 /**
 * Check that a string represents a canonical non-negative integer.
@@ -338,12 +357,37 @@ function validateMandateShape(value) {
 	const obj = value;
 	if (typeof obj.required !== "boolean") throw new s402Error("INVALID_PAYLOAD", `mandate.required must be a boolean, got ${typeof obj.required}`);
 	assertOptionalString(obj, "minPerTx", "mandate");
+	if (typeof obj.minPerTx === "string" && !isValidAmount(obj.minPerTx)) throw new s402Error("INVALID_PAYLOAD", `mandate.minPerTx must be a non-negative integer string, got "${obj.minPerTx}"`);
 	assertOptionalString(obj, "coinType", "mandate");
 }
 /**
-* Validate stream sub-object.
-* Checks required fields are present and correctly typed.
+* Validate upto sub-object (usage-based variable settlement).
+*/
+function validateUptoShape(value) {
+	assertPlainObject(value, "upto");
+	const obj = value;
+	assertString(obj, "maxAmount", "upto");
+	if (typeof obj.maxAmount === "string" && !isValidAmount(obj.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto.maxAmount must be a non-negative integer string, got "${obj.maxAmount}"`);
+	assertString(obj, "settlementDeadlineMs", "upto");
+	if (typeof obj.settlementDeadlineMs === "string" && !isValidAmount(obj.settlementDeadlineMs)) throw new s402Error("INVALID_PAYLOAD", `upto.settlementDeadlineMs must be a non-negative integer string (Unix timestamp ms), got "${obj.settlementDeadlineMs}"`);
+	assertOptionalString(obj, "usageReportUrl", "upto");
+	assertOptionalString(obj, "estimatedAmount", "upto");
+	if (typeof obj.estimatedAmount === "string") {
+		if (!isValidAmount(obj.estimatedAmount)) throw new s402Error("INVALID_PAYLOAD", `upto.estimatedAmount must be a non-negative integer string, got "${obj.estimatedAmount}"`);
+		if (typeof obj.maxAmount === "string" && isValidAmount(obj.maxAmount)) {
+			if (BigInt(obj.estimatedAmount) > BigInt(obj.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto.estimatedAmount (${obj.estimatedAmount}) must be <= maxAmount (${obj.maxAmount})`);
+		}
+	}
+}
+/**
+* Validate settlementOverrides sub-object.
 */
+function validateSettlementOverridesShape(value) {
+	assertPlainObject(value, "settlementOverrides");
+	const obj = value;
+	assertString(obj, "actualAmount", "settlementOverrides");
+	if (typeof obj.actualAmount === "string" && !isValidAmount(obj.actualAmount)) throw new s402Error("INVALID_PAYLOAD", `settlementOverrides.actualAmount must be a non-negative integer string, got "${obj.actualAmount}"`);
+}
 function validateStreamShape(value) {
 	assertPlainObject(value, "stream");
 	const obj = value;
@@ -404,10 +448,12 @@ function validatePrepaidShape(value) {
 */
 function validateSubObjects(record) {
 	if (record.mandate !== void 0) validateMandateShape(record.mandate);
+	if (record.upto !== void 0) validateUptoShape(record.upto);
+	if (record.settlementOverrides !== void 0) validateSettlementOverridesShape(record.settlementOverrides);
+	if (record.prepaid !== void 0) validatePrepaidShape(record.prepaid);
 	if (record.stream !== void 0) validateStreamShape(record.stream);
 	if (record.escrow !== void 0) validateEscrowShape(record.escrow);
 	if (record.unlock !== void 0) validateUnlockShape(record.unlock);
-	if (record.prepaid !== void 0) validatePrepaidShape(record.prepaid);
 }
 /** Validate that decoded payment requirements have the required shape. */
 function validateRequirementsShape(obj) {
@@ -474,8 +520,25 @@ function validatePayloadShape(obj) {
 	if (typeof inner.transaction !== "string") throw new s402Error("INVALID_PAYLOAD", `payload.transaction must be a string, got ${typeof inner.transaction}`);
 	if (typeof inner.signature !== "string") throw new s402Error("INVALID_PAYLOAD", `payload.signature must be a string, got ${typeof inner.signature}`);
 	if (record.scheme === "unlock" && typeof inner.encryptionId !== "string") throw new s402Error("INVALID_PAYLOAD", `unlock payload requires encryptionId (string), got ${typeof inner.encryptionId}`);
-	if (record.scheme === "prepaid" && typeof inner.ratePerCall !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload requires ratePerCall (string), got ${typeof inner.ratePerCall}`);
-	if (record.scheme === "prepaid" && inner.maxCalls !== void 0 && typeof inner.maxCalls !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload maxCalls must be a string if provided, got ${typeof inner.maxCalls}`);
+	if (record.scheme === "upto") {
+		if (typeof inner.maxAmount !== "string") throw new s402Error("INVALID_PAYLOAD", `upto payload requires maxAmount (string), got ${typeof inner.maxAmount}`);
+		if (!isValidAmount(inner.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto payload maxAmount must be a non-negative integer string, got "${inner.maxAmount}"`);
+		if (inner.settlementCeiling !== void 0) {
+			if (typeof inner.settlementCeiling !== "string") throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling must be a string if provided, got ${typeof inner.settlementCeiling}`);
+			if (!isValidAmount(inner.settlementCeiling)) throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling must be a non-negative integer string, got "${inner.settlementCeiling}"`);
+			const ceiling = BigInt(inner.settlementCeiling);
+			if (ceiling < 1n) throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling must be >= 1, got "${inner.settlementCeiling}"`);
+			if (ceiling > BigInt(inner.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling (${inner.settlementCeiling}) must be <= maxAmount (${inner.maxAmount})`);
+		}
+	}
+	if (record.scheme === "prepaid") {
+		if (typeof inner.ratePerCall !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload requires ratePerCall (string), got ${typeof inner.ratePerCall}`);
+		if (!isValidAmount(inner.ratePerCall)) throw new s402Error("INVALID_PAYLOAD", `prepaid payload ratePerCall must be a non-negative integer string, got "${inner.ratePerCall}"`);
+		if (inner.maxCalls !== void 0) {
+			if (typeof inner.maxCalls !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload maxCalls must be a string if provided, got ${typeof inner.maxCalls}`);
+			if (!isValidAmount(inner.maxCalls)) throw new s402Error("INVALID_PAYLOAD", `prepaid payload maxCalls must be a non-negative integer string, got "${inner.maxCalls}"`);
+		}
+	}
 }
 /** Validate that a decoded settle response has the required shape. */
 function validateSettleShape(obj) {
@@ -488,6 +551,8 @@ function validateSettleShape(obj) {
 	if (record.streamId !== void 0 && typeof record.streamId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: streamId must be a string, got ${typeof record.streamId}`);
 	if (record.escrowId !== void 0 && typeof record.escrowId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: escrowId must be a string, got ${typeof record.escrowId}`);
 	if (record.balanceId !== void 0 && typeof record.balanceId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: balanceId must be a string, got ${typeof record.balanceId}`);
+	if (record.actualAmount !== void 0 && typeof record.actualAmount !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: actualAmount must be a string, got ${typeof record.actualAmount}`);
+	if (record.depositId !== void 0 && typeof record.depositId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: depositId must be a string, got ${typeof record.depositId}`);
 	if (record.error !== void 0 && typeof record.error !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: error must be a string, got ${typeof record.error}`);
 	if (record.errorCode !== void 0 && typeof record.errorCode !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: errorCode must be a string, got ${typeof record.errorCode}`);
 }
@@ -605,4 +670,4 @@ function extractRequirementsFromResponse(response) {
 }
 
 //#endregion
-export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };
+export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateSettlementOverridesShape, validateStreamShape, validateSubObjects, validateUnlockShape, validateUptoShape };

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_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-tVj4sOr-.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 { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader, s402Receipt, s402ReceiptSigner, s402ReceiptVerifier } from "./receipts.mjs";
 
 //#region src/client.d.ts
@@ -58,14 +58,170 @@ 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;
+}
 declare class s402Facilitator {
   private schemes;
   private inFlight;
+  private extensionRegistry;
+  private extensionErrorHandler?;
   /**
    * 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 +244,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 +262,7 @@ declare class s402Facilitator {
    * }
    * ```
    */
-  process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+  process(payload: s402PaymentPayload, requirements: s402PaymentRequirements, options?: s402ProcessOptions): Promise<s402SettleResponse>;
   /**
    * Check if a scheme is supported for a network.
    */
@@ -185,4 +342,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 s402SettlementVerification, 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, 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 };