s402 0.1.1 → 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

@@ -20,10 +20,15 @@ declare function pickSettleResponseFields(obj: Record<string, unknown>): s402Set
 /** 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
@@ -32,6 +37,14 @@ declare function decodeSettleResponse(header: string): s402SettleResponse;
  * 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.
@@ -75,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, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, 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 */
@@ -172,10 +212,15 @@ 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
@@ -186,6 +231,21 @@ const VALID_SCHEMES = new Set([
 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}`);
@@ -289,7 +349,7 @@ function validateRequirementsShape(obj) {
 	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}`);
@@ -352,4 +412,4 @@ function extractRequirementsFromResponse(response) {
 }
 
 //#endregion
-export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, 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, 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, validateRequirementsShape } from "./http.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,12 +128,12 @@ declare class s402Facilitator {
   register(network: string, scheme: s402FacilitatorScheme): this;
   /**
    * Verify a payment payload by dispatching to the correct scheme.
-   * Includes expiration guard — rejects expired requirements before verification.
+   * 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 — rejects expired requirements before settlement.
+   * Includes expiration guard and scheme-mismatch check.
    */
   settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
   /**
@@ -191,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 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 };
+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,29 +138,51 @@ var s402Facilitator = class {
 	}
 	/**
 	* Verify a payment payload by dispatching to the correct scheme.
-	* Includes expiration guard — rejects expired requirements before verification.
+	* Includes expiration guard and scheme-mismatch check.
 	*/
 	async verify(payload, requirements) {
-		if (typeof requirements.expiresAt === "number" && Number.isFinite(requirements.expiresAt)) {
+		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 — rejects expired requirements before settlement.
+	* Includes expiration guard and scheme-mismatch check.
 	*/
 	async settle(payload, requirements) {
-		if (typeof requirements.expiresAt === "number" && Number.isFinite(requirements.expiresAt)) {
+		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);
 	}
 	/**
@@ -203,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.
@@ -228,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s402",
-  "version": "0.1.1",
+  "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"
   }
-}
+}