s402 0.1.5 → 0.1.7

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

@@ -45,11 +45,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 +161,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 +261,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 +306,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/compat.mjs

@@ -12,6 +12,13 @@ function fromX402Requirements(x402) {
 	const amount = x402.amount ?? x402.maxAmountRequired;
 	if (!amount) throw new s402Error("INVALID_PAYLOAD", "x402 requirements missing both \"amount\" (V2) and \"maxAmountRequired\" (V1)");
 	if (!isValidAmount(amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${amount}": must be a non-negative integer string`);
+	if (x402.facilitatorUrl !== void 0) try {
+		const url = new URL(x402.facilitatorUrl);
+		if (url.protocol !== "https:" && url.protocol !== "http:") throw new s402Error("INVALID_PAYLOAD", `facilitatorUrl must use https:// or http://, got "${url.protocol}"`);
+	} catch (e) {
+		if (e instanceof s402Error) throw e;
+		throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl is not a valid URL");
+	}
 	return {
 		s402Version: S402_VERSION,
 		accepts: ["exact"],

package/dist/errors.d.mts

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

package/dist/errors.mjs

@@ -21,7 +21,8 @@ const s402ErrorCode = {
 	NETWORK_MISMATCH: "NETWORK_MISMATCH",
 	SIGNATURE_INVALID: "SIGNATURE_INVALID",
 	REQUIREMENTS_EXPIRED: "REQUIREMENTS_EXPIRED",
-	VERIFICATION_FAILED: "VERIFICATION_FAILED"
+	VERIFICATION_FAILED: "VERIFICATION_FAILED",
+	SETTLEMENT_FAILED: "SETTLEMENT_FAILED"
 };
 /** Error recovery hints for each error code */
 const ERROR_HINTS = {
@@ -80,6 +81,10 @@ const ERROR_HINTS = {
 	VERIFICATION_FAILED: {
 		retryable: false,
 		suggestedAction: "Check payment amount and transaction structure"
+	},
+	SETTLEMENT_FAILED: {
+		retryable: true,
+		suggestedAction: "Transient RPC failure during settlement — retry in a few seconds"
 	}
 };
 /**

package/dist/http.mjs

@@ -341,10 +341,12 @@ function validateRequirementsShape(obj) {
 	if (typeof record.network !== "string") missing.push("network (string)");
 	if (typeof record.asset !== "string") missing.push("asset (string)");
 	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`);
+	else if (!isValidU64Amount(record.amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${record.amount}": must be a non-negative integer string within u64 range`);
 	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)}..."`);
+	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}`);
@@ -352,7 +354,14 @@ function validateRequirementsShape(obj) {
 		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}`);
+		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);
 }

package/dist/index.d.mts

@@ -122,6 +122,7 @@ declare class s402Client {
 //#region src/facilitator.d.ts
 declare class s402Facilitator {
   private schemes;
+  private inFlight;
   /**
    * Register a scheme-specific facilitator for a network.
    */

package/dist/index.mjs

@@ -128,6 +128,7 @@ var s402ResourceServer = class {
 //#region src/facilitator.ts
 var s402Facilitator = class {
 	schemes = /* @__PURE__ */ new Map();
+	inFlight = /* @__PURE__ */ new Set();
 	/**
 	* Register a scheme-specific facilitator for a network.
 	*/
@@ -157,7 +158,18 @@ var s402Facilitator = class {
 				invalidReason: `Scheme "${payload.scheme}" is not accepted by these requirements. Accepted: [${requirements.accepts.join(", ")}]`
 			};
 		}
-		return this.resolveScheme(payload.scheme, requirements.network).verify(payload, requirements);
+		try {
+			return this.resolveScheme(payload.scheme, requirements.network).verify(payload, requirements);
+		} catch (e) {
+			if (e instanceof s402Error) return {
+				valid: false,
+				invalidReason: e.message
+			};
+			return {
+				valid: false,
+				invalidReason: "Unexpected error resolving scheme"
+			};
+		}
 	}
 	/**
 	* Settle a payment by dispatching to the correct scheme.
@@ -183,7 +195,20 @@ var s402Facilitator = class {
 				errorCode: "SCHEME_NOT_SUPPORTED"
 			};
 		}
-		return this.resolveScheme(payload.scheme, requirements.network).settle(payload, requirements);
+		try {
+			return this.resolveScheme(payload.scheme, requirements.network).settle(payload, requirements);
+		} catch (e) {
+			if (e instanceof s402Error) return {
+				success: false,
+				error: e.message,
+				errorCode: e.code
+			};
+			return {
+				success: false,
+				error: "Unexpected error resolving scheme",
+				errorCode: "SCHEME_NOT_SUPPORTED"
+			};
+		}
 	}
 	/**
 	* Expiration-guarded verify + settle in one call.
@@ -213,26 +238,60 @@ var s402Facilitator = class {
 				errorCode: "SCHEME_NOT_SUPPORTED"
 			};
 		}
-		const scheme = this.resolveScheme(payload.scheme, requirements.network);
-		const verifyResult = await scheme.verify(payload, requirements);
-		if (!verifyResult.valid) return {
-			success: false,
-			error: verifyResult.invalidReason ?? "Payment verification failed",
-			errorCode: "VERIFICATION_FAILED"
-		};
-		if (typeof requirements.expiresAt === "number" && Date.now() > requirements.expiresAt) return {
-			success: false,
-			error: `Payment requirements expired during verification at ${new Date(requirements.expiresAt).toISOString()}`,
-			errorCode: "REQUIREMENTS_EXPIRED"
-		};
+		let scheme;
 		try {
-			return await scheme.settle(payload, requirements);
+			scheme = this.resolveScheme(payload.scheme, requirements.network);
 		} catch (e) {
+			if (e instanceof s402Error) return {
+				success: false,
+				error: e.message,
+				errorCode: e.code
+			};
 			return {
 				success: false,
-				error: e instanceof Error ? e.message : "Settlement failed with an unexpected error",
+				error: "Failed to resolve payment scheme",
+				errorCode: "SCHEME_NOT_SUPPORTED"
+			};
+		}
+		const dedupeKey = JSON.stringify(payload);
+		if (this.inFlight.has(dedupeKey)) return {
+			success: false,
+			error: "Duplicate payment request already in flight",
+			errorCode: "INVALID_PAYLOAD"
+		};
+		this.inFlight.add(dedupeKey);
+		try {
+			let verifyResult;
+			try {
+				verifyResult = await Promise.race([scheme.verify(payload, requirements), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("Verification timed out after 5s")), 5e3))]);
+			} catch (e) {
+				return {
+					success: false,
+					error: e instanceof Error ? e.message : "Verification threw an unexpected error",
+					errorCode: "VERIFICATION_FAILED"
+				};
+			}
+			if (!verifyResult.valid) return {
+				success: false,
+				error: verifyResult.invalidReason ?? "Payment verification failed",
 				errorCode: "VERIFICATION_FAILED"
 			};
+			if (typeof requirements.expiresAt === "number" && Date.now() > requirements.expiresAt) return {
+				success: false,
+				error: `Payment requirements expired during verification at ${new Date(requirements.expiresAt).toISOString()}`,
+				errorCode: "REQUIREMENTS_EXPIRED"
+			};
+			try {
+				return await Promise.race([scheme.settle(payload, requirements), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("Settlement timed out after 15s")), 15e3))]);
+			} catch (e) {
+				return {
+					success: false,
+					error: e instanceof Error ? e.message : "Settlement failed with an unexpected error",
+					errorCode: "SETTLEMENT_FAILED"
+				};
+			}
+		} finally {
+			this.inFlight.delete(dedupeKey);
 		}
 	}
 	/**

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.5",
+  "version": "0.1.7",
   "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",