s402 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.6] - 2026-02-19
+
+### Fixed
+
+- **Security audit patches** (15 true positives, H-1 through M-6, L-2):
+  - H-1: `process()` wraps `resolveScheme`/`verify`/`settle` in try/catch — unhandled rejections no longer crash server middleware; returns `{success: false}` instead
+  - H-2: In-flight dedup `Set` on `process()` — concurrent identical payloads can no longer both reach `scheme.settle()`
+  - H-3: `Promise.race()` timeouts — 5s for verify, 15s for settle — prevents hanging RPC calls from exhausting the event loop
+  - M-1: `facilitatorUrl` in x402 compat now validated via `new URL()` — rejects `javascript:`, `file://`, and other non-http(s) schemes (SSRF guard)
+  - M-2: `isValidAmount` → `isValidU64Amount` on decode — rejects amounts above u64 max at the wire boundary
+  - M-5: Settle catch returns `SETTLEMENT_FAILED` (`retryable: true`) instead of `VERIFICATION_FAILED` (`retryable: false`) — agents can now retry on transient RPC failures
+  - M-6: `payTo` validation tightened from `startsWith('0x')` to full Sui address regex `/^0x[0-9a-fA-F]{64}$/` — rejects `'0x'` alone and non-hex chars
+  - L-2: `expiresAt` guard extended to reject `<= 0` — negative timestamps and zero are now invalid at decode time
+
+## [0.1.5] - 2026-02-19
+
+### Changed
+
+- Author updated to SweeInc brand name
+- Renamed `@sweepay/*` → `@sweefi/*` across all documentation
+
+## [0.1.4] - 2026-02-18
+
+_Version bump for npm publish after license change._
+
+## [0.1.3] - 2026-02-18
+
+### Changed
+
+- License changed from MIT to Apache-2.0
+- Documentation consolidated (removed codebase-tour, added complete guide)
+- Updated tagline to "HTTP 402 payment protocol"
+
+### Added
+
+- CI and npm version badges to README
+
+## [0.1.2] - 2026-02-16
+
+### Added
+
+- CI workflow (GitHub Actions) with tag-based npm releases
+- Separate build job for Node 22
+
 ## [0.1.1] - 2026-02-16
 
 ### Fixed
@@ -33,4 +77,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Property-based fuzz testing via fast-check
 - 207 tests, zero runtime dependencies
 
+[0.1.6]: https://github.com/s402-protocol/core/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/s402-protocol/core/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/s402-protocol/core/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/s402-protocol/core/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/s402-protocol/core/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/s402-protocol/core/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/s402-protocol/core/releases/tag/v0.1.0

package/README.md

@@ -5,6 +5,8 @@
 
 **Sui-native HTTP 402 protocol.** Atomic settlement via Sui's Programmable Transaction Blocks (PTBs). Includes an optional compat layer (`s402/compat`) for normalizing x402 input.
 
+s402 is the Sui-native implementation of HTTP 402 (Payment Required) — an open protocol that lets AI agents pay for API calls in a single HTTP request with no per-call on-chain transaction. Unlike Coinbase's x402 on Ethereum, s402 uses Sui's Programmable Transaction Blocks to reduce 1,000 payments to just 2 on-chain transactions via the Prepaid scheme, cutting per-call effective gas from $0.007 to $0.000014 and making micropayments economically viable for AI agents for the first time.
+
 ```bash
 npm install s402
 pnpm add s402
@@ -45,11 +47,14 @@ s402          <-- You are here. Protocol spec. Zero runtime deps.
   |-- Compat        Optional x402 migration aid
   |-- Errors        Typed error codes with recovery hints
   |
-@sweefi/sui         <-- Sui-specific implementations (coming soon)
-@sweefi/sdk         <-- High-level DX (coming soon)
+@sweefi/sui         <-- Sui adapter: 40 PTB builders + SuiPaymentAdapter + createS402Client
+@sweefi/server      <-- Chain-agnostic HTTP: s402Gate middleware + wrapFetchWithS402
+@sweefi/ui-core     <-- State machine + PaymentAdapter interface
+@sweefi/vue         <-- Vue 3 plugin + useSweefiPayment() composable
+@sweefi/react       <-- React context + useSweefiPayment() hook
 ```
 
-`s402` is **chain-agnostic protocol plumbing**. It defines _what_ gets sent over HTTP. The Sui-specific _how_ will live in `@sweefi/sui` (coming soon).
+`s402` is **chain-agnostic protocol plumbing**. It defines _what_ gets sent over HTTP. The Sui-specific _how_ lives in [`@sweefi/sui`](https://www.npmjs.com/package/@sweefi/sui).
 
 ## Payment Schemes
 
@@ -158,7 +163,7 @@ const requirements: s402PaymentRequirements = {
   network: 'sui:mainnet',
   asset: '0x2::sui::SUI',
   amount: '1000000', // 0.001 SUI in MIST
-  payTo: '0xrecipient...',
+  payTo: '0x0000000000000000000000000000000000000000000000000000000000000001',
 };
 
 response.status = 402;
@@ -258,7 +263,7 @@ import type {
 } from 's402';
 ```
 
-The reference Sui implementation of all five schemes will be available in `@sweefi/sui` (coming soon).
+The reference Sui implementation of all five schemes is available in [`@sweefi/sui`](https://www.npmjs.com/package/@sweefi/sui).
 
 ## Wire Format
 
@@ -303,7 +308,7 @@ const requirements: s402PaymentRequirements = {
   network: 'sui:mainnet',
   asset: '0x2::sui::SUI',
   amount: '1000000',
-  payTo: '0xrecipient...',
+  payTo: '0x0000000000000000000000000000000000000000000000000000000000000001',
   expiresAt: Date.now() + 5 * 60 * 1000, // 5-minute window
 };
 ```

package/SECURITY.md

@@ -15,7 +15,7 @@ You will receive an acknowledgment within 48 hours. We aim to provide a fix or m
 
 This policy covers the `s402` npm package — the protocol types, HTTP encoding/decoding, scheme registry, and compat layer.
 
-Security issues in downstream packages (`@sweefi/sui`, `@sweefi/sdk`, etc.) should be reported to the same email.
+Security issues in downstream packages (`@sweefi/sui`, `@sweefi/server`, `@sweefi/ui-core`, etc.) should be reported to the same email.
 
 ## What qualifies
 

package/dist/http.d.mts

@@ -74,6 +74,31 @@ declare function validatePrepaidShape(value: unknown): void;
 declare function validateSubObjects(record: Record<string, unknown>): void;
 /** Validate that decoded payment requirements have the required shape. */
 declare function validateRequirementsShape(obj: unknown): void;
+/** Content type for s402 JSON body transport */
+declare const S402_CONTENT_TYPE: "application/s402+json";
+/** Encode payment requirements as JSON string (for response body) */
+declare function encodeRequirementsBody(requirements: s402PaymentRequirements): string;
+/** Decode payment requirements from JSON string (from response body) */
+declare function decodeRequirementsBody(body: string): s402PaymentRequirements;
+/** Encode payment payload as JSON string (for request body) */
+declare function encodePayloadBody(payload: s402PaymentPayload): string;
+/** Decode payment payload from JSON string (from request body) */
+declare function decodePayloadBody(body: string): s402PaymentPayload;
+/** Encode settlement response as JSON string (for response body) */
+declare function encodeSettleBody(response: s402SettleResponse): string;
+/** Decode settlement response from JSON string (from response body) */
+declare function decodeSettleBody(body: string): s402SettleResponse;
+/**
+ * Detect transport mode from an incoming request.
+ *
+ * Checks Content-Type for body transport, then falls back to header detection.
+ * Returns 'body' if Content-Type is application/s402+json.
+ * Returns 'header' if x-payment header is present.
+ * Returns 'unknown' otherwise.
+ */
+declare function detectTransport(request: {
+  headers: Headers;
+}): 'header' | 'body' | 'unknown';
 /**
  * Detect whether a 402 response uses s402 or x402 protocol.
  *
@@ -88,4 +113,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, 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, validateStreamShape, validateSubObjects, validateUnlockShape };

package/dist/http.mjs

@@ -83,7 +83,9 @@ const S402_SUB_OBJECT_KEYS = {
 		"ratePerCall",
 		"maxCalls",
 		"minDeposit",
-		"withdrawalDelayMs"
+		"withdrawalDelayMs",
+		"providerPubkey",
+		"disputeWindowMs"
 	])
 };
 /** Strip unknown keys from a sub-object, returning a clean copy. */
@@ -318,6 +320,8 @@ function validatePrepaidShape(value) {
 	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");
+	assertOptionalString(obj, "providerPubkey", "prepaid");
+	assertOptionalString(obj, "disputeWindowMs", "prepaid");
 }
 /**
 * Validate all optional sub-objects on a requirements record.
@@ -345,6 +349,8 @@ function validateRequirementsShape(obj) {
 	if (typeof record.payTo !== "string") missing.push("payTo (string)");
 	else if (!/^0x[0-9a-fA-F]{64}$/.test(record.payTo)) throw new s402Error("INVALID_PAYLOAD", `payTo must be a 32-byte Sui address (0x + 64 hex chars), got "${record.payTo.substring(0, 20)}..."`);
 	if (missing.length > 0) throw new s402Error("INVALID_PAYLOAD", `Malformed payment requirements: missing ${missing.join(", ")}`);
+	if (/[\x00-\x1f\x7f]/.test(record.network)) throw new s402Error("INVALID_PAYLOAD", "network contains control characters");
+	if (/[\x00-\x1f\x7f]/.test(record.asset)) throw new s402Error("INVALID_PAYLOAD", "asset contains control characters");
 	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}`);
@@ -354,6 +360,13 @@ function validateRequirementsShape(obj) {
 	if (record.expiresAt !== void 0) {
 		if (typeof record.expiresAt !== "number" || !Number.isFinite(record.expiresAt) || record.expiresAt <= 0) throw new s402Error("INVALID_PAYLOAD", `expiresAt must be a positive finite number (Unix timestamp ms), got ${record.expiresAt}`);
 	}
+	if (record.protocolFeeAddress !== void 0) {
+		if (typeof record.protocolFeeAddress !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(record.protocolFeeAddress)) throw new s402Error("INVALID_PAYLOAD", `protocolFeeAddress must be a 32-byte Sui address (0x + 64 hex chars), got "${String(record.protocolFeeAddress).substring(0, 20)}..."`);
+	}
+	if (record.facilitatorUrl !== void 0) {
+		if (typeof record.facilitatorUrl !== "string") throw new s402Error("INVALID_PAYLOAD", `facilitatorUrl must be a string, got ${typeof record.facilitatorUrl}`);
+		if (/[\x00-\x1f\x7f]/.test(record.facilitatorUrl)) throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl contains control characters (potential header injection)");
+	}
 	validateSubObjects(record);
 }
 /** Validate that a decoded payment payload has the required shape. */
@@ -377,6 +390,66 @@ function validateSettleShape(obj) {
 	if (obj == null || typeof obj !== "object") throw new s402Error("INVALID_PAYLOAD", "Settle response is not an object");
 	if (typeof obj.success !== "boolean") throw new s402Error("INVALID_PAYLOAD", "Malformed settle response: missing or invalid \"success\" (boolean)");
 }
+/** Content type for s402 JSON body transport */
+const S402_CONTENT_TYPE = "application/s402+json";
+/** Encode payment requirements as JSON string (for response body) */
+function encodeRequirementsBody(requirements) {
+	return JSON.stringify(requirements);
+}
+/** Decode payment requirements from JSON string (from response body) */
+function decodeRequirementsBody(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (e) {
+		throw new s402Error("INVALID_PAYLOAD", `Failed to parse s402 requirements body: ${e instanceof Error ? e.message : "invalid JSON"}`);
+	}
+	validateRequirementsShape(parsed);
+	return pickRequirementsFields(parsed);
+}
+/** Encode payment payload as JSON string (for request body) */
+function encodePayloadBody(payload) {
+	return JSON.stringify(payload);
+}
+/** Decode payment payload from JSON string (from request body) */
+function decodePayloadBody(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (e) {
+		throw new s402Error("INVALID_PAYLOAD", `Failed to parse s402 payload body: ${e instanceof Error ? e.message : "invalid JSON"}`);
+	}
+	validatePayloadShape(parsed);
+	return pickPayloadFields(parsed);
+}
+/** Encode settlement response as JSON string (for response body) */
+function encodeSettleBody(response) {
+	return JSON.stringify(response);
+}
+/** Decode settlement response from JSON string (from response body) */
+function decodeSettleBody(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (e) {
+		throw new s402Error("INVALID_PAYLOAD", `Failed to parse s402 settle body: ${e instanceof Error ? e.message : "invalid JSON"}`);
+	}
+	validateSettleShape(parsed);
+	return pickSettleResponseFields(parsed);
+}
+/**
+* Detect transport mode from an incoming request.
+*
+* Checks Content-Type for body transport, then falls back to header detection.
+* Returns 'body' if Content-Type is application/s402+json.
+* Returns 'header' if x-payment header is present.
+* Returns 'unknown' otherwise.
+*/
+function detectTransport(request) {
+	if (request.headers.get("content-type")?.includes(S402_CONTENT_TYPE)) return "body";
+	if (request.headers.get(S402_HEADERS.PAYMENT)) return "header";
+	return "unknown";
+}
 /**
 * Detect whether a 402 response uses s402 or x402 protocol.
 *
@@ -412,4 +485,4 @@ function extractRequirementsFromResponse(response) {
 }
 
 //#endregion
-export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, 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, 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, isValidU64Amount, validateRequirementsShape } from "./http.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";
 
 //#region src/scheme.d.ts
 /** Implemented by each scheme on the client side */
@@ -192,4 +192,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, 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 };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, 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, isValidU64Amount, validateRequirementsShape } from "./http.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";
 
 //#region src/client.ts
 var s402Client = class {
@@ -317,4 +317,4 @@ var s402Facilitator = class {
 };
 
 //#endregion
-export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };

package/dist/types.d.mts

@@ -28,9 +28,27 @@ interface s402PaymentRequirements {
   facilitatorUrl?: string;
   /** AP2 mandate requirements (if agent spending authorization is needed) */
   mandate?: s402MandateRequirements;
-  /** Protocol fee in basis points (0-10000). 0 = no fee. */
+  /**
+   * Protocol fee in basis points (0-10000). **Advisory only.**
+   *
+   * This field is a transparency hint for the client's UI — it lets the payer
+   * see the total cost before committing. It is NOT the source of truth for
+   * settlement math. The authoritative fee rate is owned by the Facilitator
+   * (configured in its ProtocolState or equivalent on-chain object) and
+   * enforced at the smart contract level.
+   *
+   * Resource Servers SHOULD omit this field and let the Facilitator provide
+   * it via its `/.well-known/s402-facilitator` endpoint. If included, it MUST
+   * match the Facilitator's configured rate — a mismatch is a warning sign.
+   *
+   * Trust model: Facilitator owns the fee. Resource Server cannot override it.
+   */
   protocolFeeBps?: number;
-  /** Address that receives the protocol fee. Defaults to payTo if omitted. */
+  /**
+   * Address that receives the protocol fee.
+   * Advisory only — authoritative value is in Facilitator's on-chain config.
+   * Defaults to the Facilitator's own address if omitted.
+   */
   protocolFeeAddress?: string;
   /** Whether the server requires an on-chain receipt NFT */
   receiptRequired?: boolean;
@@ -107,6 +125,19 @@ interface s402PrepaidExtra {
   minDeposit: string;
   /** Withdrawal delay in ms. Agent must wait this long after last claim. Min 60s, max 7d. */
   withdrawalDelayMs: string;
+  /**
+   * Provider's Ed25519 public key (hex string, 32 bytes).
+   * When present, enables v0.2 signed receipt mode — claims enter a pending
+   * state and can be disputed with cryptographic fraud proofs.
+   * @since v0.2
+   */
+  providerPubkey?: string;
+  /**
+   * Dispute window in milliseconds. Min 60s (60000), max 24h (86400000).
+   * Only relevant when providerPubkey is set.
+   * @since v0.2
+   */
+  disputeWindowMs?: string;
 }
 /** Mandate requirements in a 402 response — tells client what mandate is needed */
 interface s402MandateRequirements {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s402",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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": "Apache-2.0",