s402 0.1.4 → 0.1.6

package/README.md

@@ -45,11 +45,11 @@ s402          <-- You are here. Protocol spec. Zero runtime deps.
   |-- Compat        Optional x402 migration aid
   |-- Errors        Typed error codes with recovery hints
   |
-@sweepay/sui        <-- Sui-specific implementations (coming soon)
-@sweepay/sdk        <-- High-level DX (coming soon)
+@sweefi/sui         <-- Sui-specific implementations (coming soon)
+@sweefi/sdk         <-- High-level DX (coming soon)
 ```
 
-`s402` is **chain-agnostic protocol plumbing**. It defines _what_ gets sent over HTTP. The Sui-specific _how_ will live in `@sweepay/sui` (coming soon).
+`s402` is **chain-agnostic protocol plumbing**. It defines _what_ gets sent over HTTP. The Sui-specific _how_ will live in `@sweefi/sui` (coming soon).
 
 ## Payment Schemes
 
@@ -212,7 +212,7 @@ import { s402Client } from 's402';
 
 const client = new s402Client();
 
-// Register scheme implementations (from @sweepay/sui or your own)
+// Register scheme implementations (from @sweefi/sui or your own)
 client.register('sui:mainnet', exactScheme);
 client.register('sui:mainnet', streamScheme);
 
@@ -258,7 +258,7 @@ import type {
 } from 's402';
 ```
 
-The reference Sui implementation of all five schemes will be available in `@sweepay/sui` (coming soon).
+The reference Sui implementation of all five schemes will be available in `@sweefi/sui` (coming soon).
 
 ## Wire Format
 
@@ -310,7 +310,7 @@ const requirements: s402PaymentRequirements = {
 
 ## Design Principles
 
-1. **Protocol-agnostic core, Sui-native reference.** `s402` defines chain-agnostic protocol types and HTTP encoding. The reference implementation (`@sweepay/sui`, coming soon) will exploit Sui's unique properties — PTBs, object model, sub-second finality. Other chains can implement s402 schemes using their own primitives.
+1. **Protocol-agnostic core, Sui-native reference.** `s402` defines chain-agnostic protocol types and HTTP encoding. The reference implementation (`@sweefi/sui`, coming soon) will exploit Sui's unique properties — PTBs, object model, sub-second finality. Other chains can implement s402 schemes using their own primitives.
 
 2. **Optional x402 compat.** The `s402/compat` subpath provides a migration aid for codebases with x402-formatted JSON. It normalizes x402 V1 (`maxAmountRequired`) and V2 (`amount`) to s402 format. This is opt-in — the core protocol has no x402 dependency.
 

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 (`@sweepay/sui`, `@sweepay/sdk`, etc.) should be reported to the same email.
+Security issues in downstream packages (`@sweefi/sui`, `@sweefi/sdk`, 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,9 +341,9 @@ 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 (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;
@@ -352,7 +352,7 @@ 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}`);
 	}
 	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/package.json

@@ -1,10 +1,10 @@
 {
   "name": "s402",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
-  "author": "Swee Group LLC <daniel@sweeinc.com> (https://s402-protocol.org)",
+  "author": "SweeInc <daniel@sweeinc.com> (https://s402-protocol.org)",
   "repository": {
     "type": "git",
     "url": "https://github.com/s402-protocol/core.git"