s402 0.1.0 → 0.1.1

package/dist/http.d.mts

@@ -11,14 +11,25 @@ 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).
  * Rejects leading zeros ("007"), empty strings, negatives, decimals.
  * Accepts "0" as the only zero representation.
+ *
+ * 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;
 /**
@@ -64,4 +75,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, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };

package/dist/http.mjs

@@ -74,6 +74,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 +128,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 +161,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([
@@ -110,6 +175,13 @@ const VALID_SCHEMES = new Set([
 * Check that a string represents a canonical non-negative integer (valid for Sui MIST amounts).
 * Rejects leading zeros ("007"), empty strings, negatives, decimals.
 * Accepts "0" as the only zero representation.
+*
+* 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);
@@ -145,8 +217,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 +232,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 +252,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,6 +283,7 @@ 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;
@@ -246,6 +326,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 +352,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, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 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 { 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";
 
 //#region src/scheme.d.ts
@@ -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 — rejects expired requirements before verification.
    */
   verify(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402VerifyResponse>;
   /**
    * Settle a payment by dispatching to the correct scheme.
+   * Includes expiration guard — rejects expired requirements before settlement.
    */
   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, 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

@@ -138,14 +138,29 @@ var s402Facilitator = class {
 	}
 	/**
 	* Verify a payment payload by dispatching to the correct scheme.
+	* Includes expiration guard — rejects expired requirements before verification.
 	*/
 	async verify(payload, requirements) {
+		if (typeof requirements.expiresAt === "number" && Number.isFinite(requirements.expiresAt)) {
+			if (Date.now() > requirements.expiresAt) return {
+				valid: false,
+				invalidReason: `Payment requirements expired at ${new Date(requirements.expiresAt).toISOString()}`
+			};
+		}
 		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.
 	*/
 	async settle(payload, requirements) {
+		if (typeof requirements.expiresAt === "number" && Number.isFinite(requirements.expiresAt)) {
+			if (Date.now() > requirements.expiresAt) return {
+				success: false,
+				error: `Payment requirements expired at ${new Date(requirements.expiresAt).toISOString()}`,
+				errorCode: "REQUIREMENTS_EXPIRED"
+			};
+		}
 		return this.resolveScheme(payload.scheme, requirements.network).settle(payload, requirements);
 	}
 	/**
@@ -169,6 +184,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 {

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.1",
   "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",