s402 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.1.1] - 2026-02-16
+
+### Fixed
+
+- Facilitator `verify()` and `settle()` now have the same defense-in-depth guards as `process()`:
+  - Reject non-number `expiresAt` values (prevents silent bypass with string types)
+  - Reject payload schemes not in `requirements.accepts` (scheme-mismatch guard)
+- `protocolFeeBps` validation now requires an integer (rejects `50.5`)
+- Sub-object fields (stream, escrow, unlock, prepaid, mandate) are now stripped of unknown keys at the trust boundary, matching the top-level field stripping behavior
+- `process()` now catches exceptions thrown by `scheme.settle()` and returns them as error results instead of propagating unhandled
+
+### Added
+
+- `isValidU64Amount()` — validates amount strings fit in a Sui u64 (format + magnitude check). The existing `isValidAmount()` remains format-only for chain-agnostic use.
+
 ## [0.1.0] - 2026-02-15
 
 ### Added

package/SECURITY.md

@@ -4,10 +4,10 @@
 
 **Please do not open public issues for security vulnerabilities.**
 
-If you discover a security issue in s402, please report it privately:
+If you discover a security issue in s402, please report it privately via either method:
 
-- **Email:** dannydevs@proton.me
-- **Subject line:** `[s402 security] <brief description>`
+- **Email:** dannydevs@proton.me (subject: `[s402 security] <brief description>`)
+- **GitHub:** [Open a private security advisory](https://github.com/s402-protocol/core/security/advisories/new)
 
 You will receive an acknowledgment within 48 hours. We aim to provide a fix or mitigation plan within 7 days of confirmation.
 

package/dist/http.d.mts

@@ -11,16 +11,40 @@ declare function encodeSettleResponse(response: s402SettleResponse): string;
 declare function pickRequirementsFields(obj: Record<string, unknown>): s402PaymentRequirements;
 /** Decode payment requirements from the `payment-required` header */
 declare function decodePaymentRequired(header: string): s402PaymentRequirements;
+/** Return a clean payload object with only known s402 payload fields. */
+declare function pickPayloadFields(obj: Record<string, unknown>): s402PaymentPayload;
 /** Decode payment payload from the `x-payment` header */
 declare function decodePaymentPayload(header: string): s402PaymentPayload;
+/** Return a clean settle response with only known s402 fields. */
+declare function pickSettleResponseFields(obj: Record<string, unknown>): s402SettleResponse;
 /** Decode settlement response from the `payment-response` header */
 declare function decodeSettleResponse(header: string): s402SettleResponse;
 /**
- * Check that a string represents a canonical non-negative integer (valid for Sui MIST amounts).
+ * Check that a string represents a canonical non-negative integer.
  * Rejects leading zeros ("007"), empty strings, negatives, decimals.
  * Accepts "0" as the only zero representation.
+ *
+ * NOTE: This is a **format-only** check — it validates the string is a well-formed
+ * non-negative integer but does NOT enforce magnitude bounds. Arbitrarily large
+ * integers (e.g. 100+ digits) pass this check. For Sui-specific u64 validation,
+ * use `isValidU64Amount()` which also checks that the value fits in a u64.
+ *
+ * A-13 (Semantic gap): "0" passes validation because it's a valid u64 on-chain.
+ * However, amount="0" in payment requirements is semantically ambiguous — it could
+ * mean "free" or be a misconfiguration. The s402 wire format intentionally allows it
+ * (some schemes like prepaid use amount="0" for deposit-based flows). Resource servers
+ * that want to reject zero-amount payments should check this in their business logic,
+ * not at the protocol level.
  */
 declare function isValidAmount(s: string): boolean;
+/**
+ * Check that a string represents a valid Sui u64 amount.
+ * Like `isValidAmount` but also rejects values exceeding u64 max (2^64 - 1).
+ *
+ * Use this in scheme implementations that target Sui's u64 amounts (MIST, etc.).
+ * The wire-format validator uses `isValidAmount` (format-only) to stay chain-agnostic.
+ */
+declare function isValidU64Amount(s: string): boolean;
 /**
  * Validate mandate requirements sub-object.
  * Mandate is protocol-level (used for authorization decisions), so we validate fully.
@@ -64,4 +88,4 @@ declare function detectProtocol(headers: Headers): 's402' | 'x402' | 'unknown';
  */
 declare function extractRequirementsFromResponse(response: Response): s402PaymentRequirements | null;
 //#endregion
-export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, pickRequirementsFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };
+export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };

package/dist/http.mjs

@@ -56,10 +56,50 @@ const S402_REQUIREMENTS_KEYS = new Set([
 	"prepaid",
 	"extensions"
 ]);
+/** Known keys for each sub-object type — used to strip extra keys at the trust boundary. */
+const S402_SUB_OBJECT_KEYS = {
+	mandate: new Set([
+		"required",
+		"minPerTx",
+		"coinType"
+	]),
+	stream: new Set([
+		"ratePerSecond",
+		"budgetCap",
+		"minDeposit",
+		"streamSetupUrl"
+	]),
+	escrow: new Set([
+		"seller",
+		"arbiter",
+		"deadlineMs"
+	]),
+	unlock: new Set([
+		"encryptionId",
+		"walrusBlobId",
+		"encryptionPackageId"
+	]),
+	prepaid: new Set([
+		"ratePerCall",
+		"maxCalls",
+		"minDeposit",
+		"withdrawalDelayMs"
+	])
+};
+/** Strip unknown keys from a sub-object, returning a clean copy. */
+function pickSubObjectFields(key, value) {
+	const allowedKeys = S402_SUB_OBJECT_KEYS[key];
+	if (!allowedKeys || value == null || typeof value !== "object" || Array.isArray(value)) return value;
+	const obj = value;
+	const clean = {};
+	for (const k of allowedKeys) if (k in obj) clean[k] = obj[k];
+	return clean;
+}
 /** Return a clean object with only known s402 requirement fields. */
 function pickRequirementsFields(obj) {
 	const result = {};
-	for (const key of S402_REQUIREMENTS_KEYS) if (key in obj) result[key] = obj[key];
+	for (const key of S402_REQUIREMENTS_KEYS) if (key in obj) if (key in S402_SUB_OBJECT_KEYS) result[key] = pickSubObjectFields(key, obj[key]);
+	else result[key] = obj[key];
 	return result;
 }
 /** Decode payment requirements from the `payment-required` header */
@@ -74,6 +114,50 @@ function decodePaymentRequired(header) {
 	validateRequirementsShape(parsed);
 	return pickRequirementsFields(parsed);
 }
+/**
+* Known top-level keys on s402PaymentPayload.
+* Used by decodePaymentPayload to strip unknown keys at the HTTP trust boundary.
+*/
+const S402_PAYLOAD_TOP_KEYS = new Set([
+	"s402Version",
+	"scheme",
+	"payload"
+]);
+/**
+* Known inner payload keys per scheme. All schemes share transaction + signature;
+* unlock adds encryptionId, prepaid adds ratePerCall + maxCalls.
+*/
+const S402_PAYLOAD_INNER_KEYS = {
+	exact: new Set(["transaction", "signature"]),
+	stream: new Set(["transaction", "signature"]),
+	escrow: new Set(["transaction", "signature"]),
+	unlock: new Set([
+		"transaction",
+		"signature",
+		"encryptionId"
+	]),
+	prepaid: new Set([
+		"transaction",
+		"signature",
+		"ratePerCall",
+		"maxCalls"
+	])
+};
+/** Return a clean payload object with only known s402 payload fields. */
+function pickPayloadFields(obj) {
+	const result = {};
+	for (const key of S402_PAYLOAD_TOP_KEYS) if (key in obj) result[key] = obj[key];
+	if (result.payload && typeof result.payload === "object" && typeof result.scheme === "string") {
+		const allowedInner = S402_PAYLOAD_INNER_KEYS[result.scheme];
+		if (allowedInner) {
+			const inner = result.payload;
+			const cleanInner = {};
+			for (const key of allowedInner) if (key in inner) cleanInner[key] = inner[key];
+			result.payload = cleanInner;
+		}
+	}
+	return result;
+}
 /** Decode payment payload from the `x-payment` header */
 function decodePaymentPayload(header) {
 	if (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `x-payment header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
@@ -84,7 +168,28 @@ function decodePaymentPayload(header) {
 		throw new s402Error("INVALID_PAYLOAD", `Failed to decode x-payment header: ${e instanceof Error ? e.message : "invalid base64 or JSON"}`);
 	}
 	validatePayloadShape(parsed);
-	return parsed;
+	return pickPayloadFields(parsed);
+}
+/**
+* Known top-level keys on s402SettleResponse.
+* Used by decodeSettleResponse to strip unknown keys at the HTTP trust boundary.
+*/
+const S402_SETTLE_RESPONSE_KEYS = new Set([
+	"success",
+	"txDigest",
+	"receiptId",
+	"finalityMs",
+	"streamId",
+	"escrowId",
+	"balanceId",
+	"error",
+	"errorCode"
+]);
+/** Return a clean settle response with only known s402 fields. */
+function pickSettleResponseFields(obj) {
+	const result = {};
+	for (const key of S402_SETTLE_RESPONSE_KEYS) if (key in obj) result[key] = obj[key];
+	return result;
 }
 /** Decode settlement response from the `payment-response` header */
 function decodeSettleResponse(header) {
@@ -96,7 +201,7 @@ function decodeSettleResponse(header) {
 		throw new s402Error("INVALID_PAYLOAD", `Failed to decode payment-response header: ${e instanceof Error ? e.message : "invalid base64 or JSON"}`);
 	}
 	validateSettleShape(parsed);
-	return parsed;
+	return pickSettleResponseFields(parsed);
 }
 /** Valid s402 payment scheme values */
 const VALID_SCHEMES = new Set([
@@ -107,13 +212,40 @@ const VALID_SCHEMES = new Set([
 	"prepaid"
 ]);
 /**
-* Check that a string represents a canonical non-negative integer (valid for Sui MIST amounts).
+* Check that a string represents a canonical non-negative integer.
 * Rejects leading zeros ("007"), empty strings, negatives, decimals.
 * Accepts "0" as the only zero representation.
+*
+* NOTE: This is a **format-only** check — it validates the string is a well-formed
+* non-negative integer but does NOT enforce magnitude bounds. Arbitrarily large
+* integers (e.g. 100+ digits) pass this check. For Sui-specific u64 validation,
+* use `isValidU64Amount()` which also checks that the value fits in a u64.
+*
+* A-13 (Semantic gap): "0" passes validation because it's a valid u64 on-chain.
+* However, amount="0" in payment requirements is semantically ambiguous — it could
+* mean "free" or be a misconfiguration. The s402 wire format intentionally allows it
+* (some schemes like prepaid use amount="0" for deposit-based flows). Resource servers
+* that want to reject zero-amount payments should check this in their business logic,
+* not at the protocol level.
 */
 function isValidAmount(s) {
 	return /^(0|[1-9][0-9]*)$/.test(s);
 }
+/** Maximum value representable as a Sui u64: 2^64 - 1 */
+const U64_MAX = "18446744073709551615";
+/**
+* Check that a string represents a valid Sui u64 amount.
+* Like `isValidAmount` but also rejects values exceeding u64 max (2^64 - 1).
+*
+* Use this in scheme implementations that target Sui's u64 amounts (MIST, etc.).
+* The wire-format validator uses `isValidAmount` (format-only) to stay chain-agnostic.
+*/
+function isValidU64Amount(s) {
+	if (!isValidAmount(s)) return false;
+	if (s.length > 20) return false;
+	if (s.length < 20) return true;
+	return s <= U64_MAX;
+}
 /** Helper: assert obj is a plain object (not null/array/primitive). */
 function assertPlainObject(value, label) {
 	if (value == null || typeof value !== "object" || Array.isArray(value)) throw new s402Error("INVALID_PAYLOAD", `${label} must be a plain object, got ${Array.isArray(value) ? "array" : typeof value}`);
@@ -145,8 +277,11 @@ function validateStreamShape(value) {
 	assertPlainObject(value, "stream");
 	const obj = value;
 	assertString(obj, "ratePerSecond", "stream");
+	if (typeof obj.ratePerSecond === "string" && !isValidAmount(obj.ratePerSecond)) throw new s402Error("INVALID_PAYLOAD", `stream.ratePerSecond must be a non-negative integer string, got "${obj.ratePerSecond}"`);
 	assertString(obj, "budgetCap", "stream");
+	if (typeof obj.budgetCap === "string" && !isValidAmount(obj.budgetCap)) throw new s402Error("INVALID_PAYLOAD", `stream.budgetCap must be a non-negative integer string, got "${obj.budgetCap}"`);
 	assertString(obj, "minDeposit", "stream");
+	if (typeof obj.minDeposit === "string" && !isValidAmount(obj.minDeposit)) throw new s402Error("INVALID_PAYLOAD", `stream.minDeposit must be a non-negative integer string, got "${obj.minDeposit}"`);
 	assertOptionalString(obj, "streamSetupUrl", "stream");
 }
 /**
@@ -157,6 +292,7 @@ function validateEscrowShape(value) {
 	const obj = value;
 	assertString(obj, "seller", "escrow");
 	assertString(obj, "deadlineMs", "escrow");
+	if (typeof obj.deadlineMs === "string" && !isValidAmount(obj.deadlineMs)) throw new s402Error("INVALID_PAYLOAD", `escrow.deadlineMs must be a non-negative integer string (Unix timestamp ms), got "${obj.deadlineMs}"`);
 	assertOptionalString(obj, "arbiter", "escrow");
 }
 /**
@@ -176,8 +312,11 @@ function validatePrepaidShape(value) {
 	assertPlainObject(value, "prepaid");
 	const obj = value;
 	assertString(obj, "ratePerCall", "prepaid");
+	if (typeof obj.ratePerCall === "string" && !isValidAmount(obj.ratePerCall)) throw new s402Error("INVALID_PAYLOAD", `prepaid.ratePerCall must be a non-negative integer string, got "${obj.ratePerCall}"`);
 	assertString(obj, "minDeposit", "prepaid");
+	if (typeof obj.minDeposit === "string" && !isValidAmount(obj.minDeposit)) throw new s402Error("INVALID_PAYLOAD", `prepaid.minDeposit must be a non-negative integer string, got "${obj.minDeposit}"`);
 	assertString(obj, "withdrawalDelayMs", "prepaid");
+	if (typeof obj.withdrawalDelayMs === "string" && !isValidAmount(obj.withdrawalDelayMs)) throw new s402Error("INVALID_PAYLOAD", `prepaid.withdrawalDelayMs must be a non-negative integer string (milliseconds), got "${obj.withdrawalDelayMs}"`);
 	assertOptionalString(obj, "maxCalls", "prepaid");
 }
 /**
@@ -204,12 +343,13 @@ function validateRequirementsShape(obj) {
 	if (typeof record.amount !== "string") missing.push("amount (string)");
 	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.startsWith("0x")) throw new s402Error("INVALID_PAYLOAD", `payTo must be a hex address starting with "0x", got "${record.payTo.substring(0, 20)}..."`);
 	if (missing.length > 0) throw new s402Error("INVALID_PAYLOAD", `Malformed payment requirements: missing ${missing.join(", ")}`);
 	if (Array.isArray(record.accepts) && record.accepts.length === 0) throw new s402Error("INVALID_PAYLOAD", "accepts array must contain at least one scheme");
 	const accepts = record.accepts;
 	for (const scheme of accepts) if (typeof scheme !== "string") throw new s402Error("INVALID_PAYLOAD", `Invalid entry in accepts array: expected string, got ${typeof scheme}`);
 	if (record.protocolFeeBps !== void 0) {
-		if (typeof record.protocolFeeBps !== "number" || !Number.isFinite(record.protocolFeeBps) || record.protocolFeeBps < 0 || record.protocolFeeBps > 1e4) throw new s402Error("INVALID_PAYLOAD", `protocolFeeBps must be a finite number between 0 and 10000, got ${record.protocolFeeBps}`);
+		if (typeof record.protocolFeeBps !== "number" || !Number.isFinite(record.protocolFeeBps) || !Number.isInteger(record.protocolFeeBps) || record.protocolFeeBps < 0 || record.protocolFeeBps > 1e4) throw new s402Error("INVALID_PAYLOAD", `protocolFeeBps must be an integer between 0 and 10000, got ${record.protocolFeeBps}`);
 	}
 	if (record.expiresAt !== void 0) {
 		if (typeof record.expiresAt !== "number" || !Number.isFinite(record.expiresAt)) throw new s402Error("INVALID_PAYLOAD", `expiresAt must be a finite number (Unix timestamp ms), got ${typeof record.expiresAt}`);
@@ -246,6 +386,7 @@ function validateSettleShape(obj) {
 function detectProtocol(headers) {
 	const paymentRequired = headers.get(S402_HEADERS.PAYMENT_REQUIRED);
 	if (!paymentRequired) return "unknown";
+	if (paymentRequired.length > MAX_HEADER_BYTES) return "unknown";
 	try {
 		const decoded = JSON.parse(fromBase64(paymentRequired));
 		if (decoded != null && typeof decoded === "object" && "s402Version" in decoded) return "s402";
@@ -271,4 +412,4 @@ function extractRequirementsFromResponse(response) {
 }
 
 //#endregion
-export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, pickRequirementsFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };
+export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { createS402Error, s402Error, s402ErrorCode, s402ErrorCodeType, s402ErrorInfo } from "./errors.mjs";
-import { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PrepaidExtra, s402PrepaidPayload, s402Scheme, s402SettleResponse, s402SettlementMode, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402VerifyResponse } from "./types.mjs";
-import { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, validateRequirementsShape } from "./http.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 { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
 
 //#region src/scheme.d.ts
 /** Implemented by each scheme on the client side */
@@ -128,10 +128,12 @@ declare class s402Facilitator {
   register(network: string, scheme: s402FacilitatorScheme): this;
   /**
    * Verify a payment payload by dispatching to the correct scheme.
+   * Includes expiration guard and scheme-mismatch check.
    */
   verify(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402VerifyResponse>;
   /**
    * Settle a payment by dispatching to the correct scheme.
+   * Includes expiration guard and scheme-mismatch check.
    */
   settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
   /**
@@ -189,4 +191,4 @@ declare class s402ResourceServer {
   process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
 }
 //#endregion
-export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, 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 s402PrepaidExtra, type s402PrepaidPayload, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402SettleResponse, type s402SettlementMode, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };
+export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, 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 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 };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { S402_HEADERS, S402_VERSION } from "./types.mjs";
 import { createS402Error, s402Error, s402ErrorCode } from "./errors.mjs";
-import { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, validateRequirementsShape } from "./http.mjs";
+import { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
 
 //#region src/client.ts
 var s402Client = class {
@@ -138,14 +138,51 @@ var s402Facilitator = class {
 	}
 	/**
 	* Verify a payment payload by dispatching to the correct scheme.
+	* Includes expiration guard and scheme-mismatch check.
 	*/
 	async verify(payload, requirements) {
+		if (requirements.expiresAt != null) {
+			if (typeof requirements.expiresAt !== "number" || !Number.isFinite(requirements.expiresAt)) return {
+				valid: false,
+				invalidReason: `Invalid expiresAt value: expected finite number, got ${typeof requirements.expiresAt}`
+			};
+			if (Date.now() > requirements.expiresAt) return {
+				valid: false,
+				invalidReason: `Payment requirements expired at ${new Date(requirements.expiresAt).toISOString()}`
+			};
+		}
+		if (requirements.accepts && requirements.accepts.length > 0) {
+			if (!requirements.accepts.includes(payload.scheme)) return {
+				valid: false,
+				invalidReason: `Scheme "${payload.scheme}" is not accepted by these requirements. Accepted: [${requirements.accepts.join(", ")}]`
+			};
+		}
 		return this.resolveScheme(payload.scheme, requirements.network).verify(payload, requirements);
 	}
 	/**
 	* Settle a payment by dispatching to the correct scheme.
+	* Includes expiration guard and scheme-mismatch check.
 	*/
 	async settle(payload, requirements) {
+		if (requirements.expiresAt != null) {
+			if (typeof requirements.expiresAt !== "number" || !Number.isFinite(requirements.expiresAt)) return {
+				success: false,
+				error: `Invalid expiresAt value: expected finite number, got ${typeof requirements.expiresAt}`,
+				errorCode: "INVALID_PAYLOAD"
+			};
+			if (Date.now() > requirements.expiresAt) return {
+				success: false,
+				error: `Payment requirements expired at ${new Date(requirements.expiresAt).toISOString()}`,
+				errorCode: "REQUIREMENTS_EXPIRED"
+			};
+		}
+		if (requirements.accepts && requirements.accepts.length > 0) {
+			if (!requirements.accepts.includes(payload.scheme)) return {
+				success: false,
+				error: `Scheme "${payload.scheme}" is not accepted by these requirements. Accepted: [${requirements.accepts.join(", ")}]`,
+				errorCode: "SCHEME_NOT_SUPPORTED"
+			};
+		}
 		return this.resolveScheme(payload.scheme, requirements.network).settle(payload, requirements);
 	}
 	/**
@@ -169,6 +206,13 @@ var s402Facilitator = class {
 				errorCode: "REQUIREMENTS_EXPIRED"
 			};
 		}
+		if (requirements.accepts && requirements.accepts.length > 0) {
+			if (!requirements.accepts.includes(payload.scheme)) return {
+				success: false,
+				error: `Scheme "${payload.scheme}" is not accepted by these requirements. Accepted: [${requirements.accepts.join(", ")}]`,
+				errorCode: "SCHEME_NOT_SUPPORTED"
+			};
+		}
 		const scheme = this.resolveScheme(payload.scheme, requirements.network);
 		const verifyResult = await scheme.verify(payload, requirements);
 		if (!verifyResult.valid) return {
@@ -181,7 +225,15 @@ var s402Facilitator = class {
 			error: `Payment requirements expired during verification at ${new Date(requirements.expiresAt).toISOString()}`,
 			errorCode: "REQUIREMENTS_EXPIRED"
 		};
-		return scheme.settle(payload, requirements);
+		try {
+			return await scheme.settle(payload, requirements);
+		} catch (e) {
+			return {
+				success: false,
+				error: e instanceof Error ? e.message : "Settlement failed with an unexpected error",
+				errorCode: "VERIFICATION_FAILED"
+			};
+		}
 	}
 	/**
 	* Check if a scheme is supported for a network.
@@ -206,4 +258,4 @@ var s402Facilitator = class {
 };
 
 //#endregion
-export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };
+export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };

package/dist/types.d.mts

@@ -46,7 +46,15 @@ interface s402PaymentRequirements {
   unlock?: s402UnlockExtra;
   /** Extra fields for prepaid scheme */
   prepaid?: s402PrepaidExtra;
-  /** Arbitrary extension data (forward-compatible extensibility) */
+  /**
+   * Arbitrary extension data (forward-compatible extensibility).
+   *
+   * D-10 (Trust boundary): extensions is an opaque bag — the s402 library
+   * passes it through without validation. Consumers MUST treat extension values
+   * as untrusted input. Do not use extensions for security-critical fields
+   * (use first-class typed fields instead). Scheme implementations should
+   * validate any extension keys they consume.
+   */
   extensions?: Record<string, unknown>;
 }
 /** Stream-specific requirements */
@@ -237,6 +245,61 @@ interface s402Discovery {
   /** Address that receives the protocol fee */
   protocolFeeAddress?: string;
 }
+/**
+ * Tracks the lifecycle of a single payment exchange.
+ * Used by s402 clients (SDK fetch wrapper, MCP tools) to correlate
+ * the 402 response → payment creation → settlement result.
+ */
+interface s402PaymentSession {
+  /** Unique session ID (client-generated, e.g., crypto.randomUUID()) */
+  id: string;
+  /** When the session started (Date.now()) */
+  startedAt: number;
+  /** The payment requirements from the 402 response */
+  requirements: s402PaymentRequirements;
+  /** The payment payload sent to the facilitator/server (null until created) */
+  payload: s402PaymentPayload | null;
+  /** Settlement result (null until settled) */
+  result: s402SettleResponse | null;
+  /** Current session state */
+  state: 'pending' | 'paying' | 'settled' | 'failed';
+  /** Number of retry attempts */
+  retries: number;
+  /** Error message if state is 'failed' */
+  error?: string;
+}
+/**
+ * A single s402-enabled service endpoint in a registry.
+ * Supports multi-service discovery (e.g., an API gateway advertising
+ * multiple endpoints with different payment requirements).
+ */
+interface s402ServiceEntry {
+  /** Service name (human-readable) */
+  name: string;
+  /** Service endpoint URL */
+  url: string;
+  /** Payment schemes this service accepts */
+  accepts: s402Scheme[];
+  /** Supported coin types */
+  assets: string[];
+  /** Base price in smallest unit (MIST for SUI, micro for USDC) */
+  baseAmount: string;
+  /** Facilitator URL (if not direct settlement) */
+  facilitatorUrl?: string;
+}
+/**
+ * Query parameters for service registry lookups.
+ */
+interface s402RegistryQuery {
+  /** Filter by supported scheme */
+  scheme?: s402Scheme;
+  /** Filter by coin type */
+  asset?: string;
+  /** Filter by network */
+  network?: string;
+  /** Maximum number of results */
+  limit?: number;
+}
 /**
  * HTTP headers used by s402 (same names as x402 for compatibility).
  * All lowercase per HTTP/2 spec (RFC 9113 §8.2.1). The Headers API
@@ -249,4 +312,4 @@ declare const S402_HEADERS: {
   readonly STREAM_ID: "x-stream-id";
 };
 //#endregion
-export { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PrepaidExtra, s402PrepaidPayload, s402Scheme, s402SettleResponse, s402SettlementMode, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402VerifyResponse };
+export { 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s402",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "s402 — Sui-native HTTP 402 wire format. Types, HTTP encoding, and scheme registry for five payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "MIT",
@@ -78,22 +78,21 @@
       "default": "./dist/errors.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"
   }
-}
+}