@primitivedotdev/sdk 1.6.0 → 1.7.0

package/README.md

@@ -266,6 +266,60 @@ const receipt = await x402.pay(challenge, { signer: payer });
 console.log(receipt.status, receipt.settle_tx); // settled, on-chain tx hash
 ```
 
+### Signing primitives (lower level)
+
+`pay()` builds and signs the payment for you. When you need to drive the signing yourself, for example to sign a challenge carried in an email reply and submit the payment separately, the same building blocks are exported directly:
+
+- `deriveEip3009Nonce(binding)` derives the interaction-bound EIP-3009 nonce. The byte layout (`keccak256` over the lowercased `interaction_id`, a `0x00` separator, the lowercased `challenge_step_id`, a `0x00` separator, and the 32 raw bytes of the challenge nonce) is locked to a normative vector the platform recomputes.
+- `computePaymentValidityWindow({ challengeExpiresAtSec, nowSec })` returns the `{ validAfter, validBefore }` window. `validBefore` covers the challenge expiry plus a settlement margin; the total window is hard-capped (24h) so an over-wide authorization can never be produced.
+- `signInteractionPayment({ sign, payer, domain, payTo, amount, nonceBinding, validAfter, validBefore })` derives the bound nonce, assembles the authorization, and signs it with your `sign` callback. Returns `{ authorization, signature }`. The key never leaves the caller.
+- `buildExactEvmPaymentPayload({ network, authorization, signature })` assembles the exact-EVM x402 wire payload, validating the nonce and signature shape.
+
+```ts
+import {
+  buildExactEvmPaymentPayload,
+  computePaymentValidityWindow,
+  signInteractionPayment,
+} from "@primitivedotdev/sdk/x402";
+import { privateKeyToAccount } from "viem/accounts";
+
+const payer = privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`);
+const pr = challenge.payment_requirements;
+const nowSec = Math.floor(Date.now() / 1000);
+
+const { validAfter, validBefore } = computePaymentValidityWindow({
+  challengeExpiresAtSec: Math.floor(Date.parse(challenge.expires_at) / 1000),
+  nowSec,
+});
+
+const { authorization, signature } = await signInteractionPayment({
+  sign: (typedData) => payer.signTypedData(typedData),
+  payer: payer.address,
+  domain: {
+    name: pr.extra.name,
+    version: pr.extra.version,
+    chainId: 84532, // base-sepolia
+    verifyingContract: pr.asset as `0x${string}`,
+  },
+  payTo: pr.payTo as `0x${string}`,
+  amount: BigInt(pr.maxAmountRequired),
+  nonceBinding: {
+    interactionId: challenge.nonce_binding.interaction_id,
+    challengeStepId: challenge.nonce_binding.challenge_step_id,
+    challengeNonce: challenge.nonce_binding.challenge_nonce,
+  },
+  validAfter,
+  validBefore,
+});
+
+const payment = buildExactEvmPaymentPayload({
+  network: "base-sepolia",
+  authorization,
+  signature,
+});
+// submit `payment` to /v1/x402/challenges/{id}/pay
+```
+
 ### Read and set the spend policy
 
 The spend policy guards outbound payments: a `paused` kill-switch, per-payment and daily caps (token base units, or `null` for no cap), and a payee `allowlist` (`null` means any on-net payee, `[]` denies all). `setSpendPolicy` merges: only the fields you pass change, and omitted fields keep their current value. Pass `null` to clear a cap.

package/dist/x402/index.d.ts

@@ -132,6 +132,65 @@ interface X402PaymentPayload {
 }
 /** Assemble the wire payload from a signed authorization. */
 declare function toPaymentPayload(network: string, auth: TransferAuthorization, signature: Hex): X402PaymentPayload;
+/**
+ * Absolute ceiling on the total signed window (validBefore - validAfter). A
+ * signed EIP-3009 authorization stays settleable on-chain until validBefore
+ * regardless of the interaction state, so an unbounded window is a standing
+ * "funds committed" risk. The real window is minutes; this 24h cap is the hard
+ * safety ceiling, enforced so a caller-supplied window cannot bypass it.
+ */
+declare const DEFAULT_MAX_WINDOW_SEC: number;
+/**
+ * Compute the EIP-3009 validity window for a payment. `validBefore` is the
+ * value that governs on-chain validity, so it MUST cover the challenge's
+ * `expires_at` plus a settlement margin; `validAfter` is set generously in the
+ * past for clock skew. The total window is hard-capped at `maxWindowSec` so
+ * neither a far-future `challengeExpiresAtSec` nor a widened margin can produce
+ * a window the platform verifier would later reject.
+ */
+declare function computePaymentValidityWindow(params: {
+  /** The challenge's expires_at, unix seconds. */challengeExpiresAtSec: number; /** Current time, unix seconds. */
+  nowSec: number; /** Headroom past expiry for verify+settle to complete. Default 5 min. */
+  settlementMarginSec?: number; /** How far in the past to set validAfter for clock skew. Default 5 min. */
+  clockSkewSec?: number; /** Hard ceiling on validBefore - validAfter. Default 24h. */
+  maxWindowSec?: number;
+}): {
+  validAfter: bigint;
+  validBefore: bigint;
+};
+/** The x402 named networks supported in v1 (testnet first). */
+type X402Network = "base-sepolia" | "base";
+/**
+ * The interaction-aware signer: derive the bound nonce, assemble the
+ * authorization, and sign it. This is the one piece a stock x402 signer cannot
+ * do (it generates the nonce internally with no injection point), so the payer
+ * side needs this Primitive-provided helper. The key never leaves the caller.
+ */
+declare function signInteractionPayment(params: {
+  /** Sign EIP-712 typed data with the caller's own key. */sign: (typedData: TransferWithAuthorizationTypedData) => Promise<Hex>; /** Payer (from) address. */
+  payer: Address;
+  domain: TokenDomain; /** Recipient (the challenger's payTo). */
+  payTo: Address; /** Amount in token base units. */
+  amount: bigint; /** Inputs that derive the interaction-bound EIP-3009 nonce. */
+  nonceBinding: NonceBinding;
+  validAfter: bigint;
+  validBefore: bigint;
+}): Promise<{
+  authorization: TransferAuthorization;
+  signature: Hex;
+}>;
+/**
+ * Assemble (and validate) the exact-EVM x402 wire payload from an
+ * interaction-bound, locally-signed authorization. The numeric authorization
+ * fields are decimal strings in the wire schema, so the bigints are stringified
+ * here; the nonce passes through as hex. Validation rejects a malformed nonce or
+ * signature loudly rather than emitting a payload the platform will reject.
+ */
+declare function buildExactEvmPaymentPayload(params: {
+  network: X402Network;
+  authorization: TransferAuthorization;
+  signature: Hex;
+}): X402PaymentPayload;
 //#endregion
 //#region src/x402/client.d.ts
 interface X402PaymentRequirements {
@@ -292,4 +351,4 @@ declare class X402Client {
 }
 declare function createX402Client(options?: X402ClientOptions): X402Client;
 //#endregion
-export { NonceBinding, PayoutRegistrationMessageInput, TRANSFER_WITH_AUTHORIZATION_TYPES, TokenDomain, TransferAuthorization, TransferWithAuthorizationTypedData, X402Challenge, X402ChargeInput, X402Client, X402ClientOptions, X402DeclinedPayment, X402Error, X402PaymentPayload, X402PaymentRequirements, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, buildPayoutRegistrationMessage, createX402Client, deriveEip3009Nonce, toPaymentPayload, transferWithAuthorizationTypedData };
+export { DEFAULT_MAX_WINDOW_SEC, NonceBinding, PayoutRegistrationMessageInput, TRANSFER_WITH_AUTHORIZATION_TYPES, TokenDomain, TransferAuthorization, TransferWithAuthorizationTypedData, X402Challenge, X402ChargeInput, X402Client, X402ClientOptions, X402DeclinedPayment, X402Error, X402Network, X402PaymentPayload, X402PaymentRequirements, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, buildExactEvmPaymentPayload, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/dist/x402/index.js

@@ -1,4 +1,4 @@
-import { concat, hexToBytes, keccak256, stringToBytes } from "viem";
+import { concat, getAddress, hexToBytes, keccak256, stringToBytes } from "viem";
 //#region src/x402/sign.ts
 /**
 * x402 client-side signing.
@@ -116,14 +116,78 @@ function toPaymentPayload(network, auth, signature) {
 		}
 	};
 }
+/**
+* Absolute ceiling on the total signed window (validBefore - validAfter). A
+* signed EIP-3009 authorization stays settleable on-chain until validBefore
+* regardless of the interaction state, so an unbounded window is a standing
+* "funds committed" risk. The real window is minutes; this 24h cap is the hard
+* safety ceiling, enforced so a caller-supplied window cannot bypass it.
+*/
+const DEFAULT_MAX_WINDOW_SEC = 1440 * 60;
+/**
+* Compute the EIP-3009 validity window for a payment. `validBefore` is the
+* value that governs on-chain validity, so it MUST cover the challenge's
+* `expires_at` plus a settlement margin; `validAfter` is set generously in the
+* past for clock skew. The total window is hard-capped at `maxWindowSec` so
+* neither a far-future `challengeExpiresAtSec` nor a widened margin can produce
+* a window the platform verifier would later reject.
+*/
+function computePaymentValidityWindow(params) {
+	const margin = params.settlementMarginSec ?? 300;
+	const skew = params.clockSkewSec ?? 300;
+	const validBefore = BigInt(params.challengeExpiresAtSec + margin);
+	const validAfter = BigInt(params.nowSec - skew);
+	if (validBefore <= validAfter) throw new Error("invalid validity window: validBefore must be after validAfter (challenge already expired?)");
+	const maxWindow = BigInt(params.maxWindowSec ?? 86400);
+	if (validBefore - validAfter > maxWindow) throw new Error(`invalid validity window: total window exceeds the ${maxWindow}s cap (challenge expiry too far out?)`);
+	return {
+		validAfter,
+		validBefore
+	};
+}
+/**
+* The interaction-aware signer: derive the bound nonce, assemble the
+* authorization, and sign it. This is the one piece a stock x402 signer cannot
+* do (it generates the nonce internally with no injection point), so the payer
+* side needs this Primitive-provided helper. The key never leaves the caller.
+*/
+async function signInteractionPayment(params) {
+	const authorization = {
+		from: getAddress(params.payer),
+		to: getAddress(params.payTo),
+		value: params.amount,
+		validAfter: params.validAfter,
+		validBefore: params.validBefore,
+		nonce: deriveEip3009Nonce(params.nonceBinding)
+	};
+	return {
+		authorization,
+		signature: await params.sign(transferWithAuthorizationTypedData(params.domain, authorization))
+	};
+}
+/** The authorization nonce is 32 bytes rendered as a 0x-prefixed 64-char hex string. */
+const NONCE_HEX_RE = /^0x[0-9a-fA-F]{64}$/;
+/** A shape-valid EIP signature is 65 bytes (r,s,v) rendered as 130 hex chars. */
+const SIGNATURE_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
+/**
+* Assemble (and validate) the exact-EVM x402 wire payload from an
+* interaction-bound, locally-signed authorization. The numeric authorization
+* fields are decimal strings in the wire schema, so the bigints are stringified
+* here; the nonce passes through as hex. Validation rejects a malformed nonce or
+* signature loudly rather than emitting a payload the platform will reject.
+*/
+function buildExactEvmPaymentPayload(params) {
+	if (params.network !== "base" && params.network !== "base-sepolia") throw new Error(`buildExactEvmPaymentPayload: unsupported network ${params.network}`);
+	if (!SIGNATURE_HEX_RE.test(params.signature)) throw new Error("buildExactEvmPaymentPayload: signature must be a 0x-prefixed 65-byte (130 hex char) EIP signature");
+	if (!NONCE_HEX_RE.test(params.authorization.nonce)) throw new Error("buildExactEvmPaymentPayload: authorization.nonce must be a 0x-prefixed 32-byte (64 hex char) value");
+	return toPaymentPayload(params.network, params.authorization, params.signature);
+}
 //#endregion
 //#region src/x402/client.ts
 const CHAIN_IDS = {
 	"base-sepolia": 84532,
 	base: 8453
 };
-const CLOCK_SKEW_SEC = 300;
-const SETTLEMENT_MARGIN_SEC = 300;
 const DEFAULT_BASE_URL = "https://api.primitive.dev";
 const CHARGE_INPUT_KEYS = {
 	amount: true,
@@ -173,7 +237,7 @@ function validateChallenge(c) {
 	if (!nb?.interaction_id || !nb.challenge_step_id || !nb.challenge_nonce) bad("nonce_binding");
 	const pr = c.payment_requirements;
 	if (!pr) bad("payment_requirements");
-	if (!pr.maxAmountRequired) bad("payment_requirements.maxAmountRequired");
+	if (!/^[1-9][0-9]{0,38}$/.test(pr.maxAmountRequired ?? "")) bad("payment_requirements.maxAmountRequired (expected a positive integer string in token base units)");
 	if (!/^0x[0-9a-fA-F]{40}$/.test(pr.payTo ?? "")) bad("payment_requirements.payTo (expected a 0x address)");
 	if (!/^0x[0-9a-fA-F]{40}$/.test(pr.asset ?? "")) bad("payment_requirements.asset (expected a 0x address)");
 	if (!pr.extra?.name || !pr.extra.version) bad("payment_requirements.extra (name/version)");
@@ -248,33 +312,45 @@ var X402Client = class {
 		const pr = challenge.payment_requirements;
 		if (pr.network !== challenge.network) throw new X402Error(`challenge network mismatch: ${challenge.network} vs payment_requirements ${pr.network}`, 0);
 		if (pr.scheme !== "exact") throw new X402Error(`unsupported payment scheme: ${pr.scheme}`, 0);
-		const nonce = deriveEip3009Nonce({
-			interactionId: challenge.nonce_binding.interaction_id,
-			challengeStepId: challenge.nonce_binding.challenge_step_id,
-			challengeNonce: challenge.nonce_binding.challenge_nonce
-		});
 		const nowSec = Math.floor(Date.now() / 1e3);
 		const expiresAtMs = Date.parse(challenge.expires_at);
 		if (Number.isNaN(expiresAtMs)) throw new X402Error(`challenge has an invalid expires_at: ${challenge.expires_at}`, 0);
 		const expiresAtSec = Math.floor(expiresAtMs / 1e3);
 		if (expiresAtSec <= nowSec) throw new X402Error(`challenge has already expired (expires_at ${challenge.expires_at}); not signing`, 0);
-		const validAfter = BigInt(nowSec - CLOCK_SKEW_SEC);
-		const validBefore = BigInt(expiresAtSec + SETTLEMENT_MARGIN_SEC);
-		const auth = {
-			from: options.signer.address,
-			to: pr.payTo,
-			value: BigInt(pr.maxAmountRequired),
+		let validAfter;
+		let validBefore;
+		try {
+			({validAfter, validBefore} = computePaymentValidityWindow({
+				challengeExpiresAtSec: expiresAtSec,
+				nowSec
+			}));
+		} catch (cause) {
+			throw new X402Error(cause instanceof Error ? cause.message : String(cause), 0, void 0, { cause });
+		}
+		const { authorization, signature } = await signInteractionPayment({
+			sign: (typedData) => options.signer.signTypedData(typedData),
+			payer: options.signer.address,
+			domain: {
+				name: pr.extra.name,
+				version: pr.extra.version,
+				chainId,
+				verifyingContract: pr.asset
+			},
+			payTo: pr.payTo,
+			amount: BigInt(pr.maxAmountRequired),
+			nonceBinding: {
+				interactionId: challenge.nonce_binding.interaction_id,
+				challengeStepId: challenge.nonce_binding.challenge_step_id,
+				challengeNonce: challenge.nonce_binding.challenge_nonce
+			},
 			validAfter,
-			validBefore,
-			nonce
-		};
-		const signature = await options.signer.signTypedData(transferWithAuthorizationTypedData({
-			name: pr.extra.name,
-			version: pr.extra.version,
-			chainId,
-			verifyingContract: pr.asset
-		}, auth));
-		return this.#request("POST", `/v1/x402/challenges/${challenge.id}/pay`, { payment: toPaymentPayload(challenge.network, auth, signature) });
+			validBefore
+		});
+		return this.#request("POST", `/v1/x402/challenges/${challenge.id}/pay`, { payment: buildExactEvmPaymentPayload({
+			network: challenge.network,
+			authorization,
+			signature
+		}) });
 	}
 	/** Fetch a challenge by id (scoped to the challenger org that created it). */
 	async getChallenge(id) {
@@ -347,4 +423,4 @@ function createX402Client(options = {}) {
 	return new X402Client(options);
 }
 //#endregion
-export { TRANSFER_WITH_AUTHORIZATION_TYPES, X402Client, X402Error, buildPayoutRegistrationMessage, createX402Client, deriveEip3009Nonce, toPaymentPayload, transferWithAuthorizationTypedData };
+export { DEFAULT_MAX_WINDOW_SEC, TRANSFER_WITH_AUTHORIZATION_TYPES, X402Client, X402Error, buildExactEvmPaymentPayload, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules.",
   "type": "module",
   "module": "./dist/index.js",