@primitivedotdev/sdk 1.6.0 → 1.8.0

package/dist/x402/index.js

@@ -1,4 +1,5 @@
-import { concat, hexToBytes, keccak256, stringToBytes } from "viem";
+import { randomUUID } from "node:crypto";
+import { concat, getAddress, hexToBytes, keccak256, stringToBytes } from "viem";
 //#region src/x402/sign.ts
 /**
 * x402 client-side signing.
@@ -97,6 +98,44 @@ function buildPayoutRegistrationMessage(input) {
 		`issued: ${input.issuedAt}`
 	].join("\n");
 }
+/**
+* The protocol the email-native payment interaction runs (`x402.payment/1`).
+* The payer's reply carries the `payment` step of this protocol.
+*/
+const X402_INTERACTION_PROTOCOL = "x402.payment";
+const X402_INTERACTION_PROTOCOL_VERSION = 1;
+/** A UUID (used for `interaction_id`'s local part and the step ids). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** An interaction id is `uuid@domain`. */
+const WIRE_ID_RE = new RegExp(`^${UUID_RE.source.slice(1, -1)}@[^\\s@]+$`, "i");
+/**
+* Build the section-2.3 interaction.json envelope for a `payment` step. Pure: no
+* I/O. `payment` is the signed exact-EVM payload (from
+* `buildExactEvmPaymentPayload`); `prevStepId` is the challenge step id this
+* payment answers, and `stepId` is a fresh UUID for the payment step. Returns
+* the envelope and its canonical JSON, so the bytes the platform reads back are
+* exactly the ones produced here.
+*/
+function buildPaymentStepEnvelope(params) {
+	if (!WIRE_ID_RE.test(params.interactionId)) throw new Error("buildPaymentStepEnvelope: interactionId must be uuid@domain");
+	if (!UUID_RE.test(params.stepId)) throw new Error("buildPaymentStepEnvelope: stepId must be a uuid");
+	if (!UUID_RE.test(params.prevStepId)) throw new Error("buildPaymentStepEnvelope: prevStepId must be a uuid");
+	const envelope = {
+		interaction_version: 1,
+		interaction_id: params.interactionId,
+		protocol: X402_INTERACTION_PROTOCOL,
+		protocol_version: 1,
+		step: "payment",
+		step_id: params.stepId,
+		prev_step_id: params.prevStepId,
+		expires_at: params.expiresAt ?? null,
+		payload: { payment: params.payment }
+	};
+	return {
+		envelope,
+		json: JSON.stringify(envelope)
+	};
+}
 /** Assemble the wire payload from a signed authorization. */
 function toPaymentPayload(network, auth, signature) {
 	return {
@@ -116,14 +155,87 @@ 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
+/**
+* x402 agent-to-agent payments.
+*
+* `charge()` (payee) asks for a payment; `pay()` (payer) signs and settles it
+* with the customer's own key. The signing is local and non-custodial; the key
+* never leaves the caller. The server resolves the real payee address, verifies
+* every signed field against its own records, and enforces the spend policy, so
+* the SDK's job is just: derive the bound authorization, sign, and submit.
+*/
 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,
@@ -135,6 +247,17 @@ const CHARGE_INPUT_KEYS = {
 	expiresIn: true,
 	idempotencyKey: true
 };
+const EMAIL_CHARGE_INPUT_KEYS = {
+	from: true,
+	to: true,
+	amount: true,
+	amountUsdc: true,
+	network: true,
+	description: true,
+	resource: true,
+	expiresIn: true,
+	idempotencyKey: true
+};
 function usdcToBaseUnits(human) {
 	const trimmed = human.trim();
 	if (!/^\d+(\.\d+)?$/.test(trimmed)) return null;
@@ -171,13 +294,37 @@ function validateChallenge(c) {
 	if (!c.expires_at) bad("expires_at");
 	const nb = c.nonce_binding;
 	if (!nb?.interaction_id || !nb.challenge_step_id || !nb.challenge_nonce) bad("nonce_binding");
-	const pr = c.payment_requirements;
+	validatePaymentRequirements(c.payment_requirements, bad);
+}
+/** Validate the x402 PaymentRequirements shared by both challenge shapes. */
+function validatePaymentRequirements(pr, bad) {
 	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)");
 }
+/**
+* Assert an email-native challenge is fully hydrated before signing, so a
+* missing field fails with a named X402Error instead of an opaque error
+* mid-sign. The interaction_id and the challenge step id (the nonce binding's
+* fields) drive both the bound nonce and the payment-step envelope, so they are
+* checked here.
+*/
+function validateEmailChallenge(c) {
+	const bad = (field) => {
+		throw new X402Error(`email challenge is missing or malformed: ${field}`, 0);
+	};
+	if (!c || typeof c !== "object") bad("email challenge");
+	if (!c.interaction_id) bad("interaction_id");
+	const ch = c.challenge;
+	if (!ch || typeof ch !== "object") bad("challenge");
+	if (!ch.expires_at) bad("challenge.expires_at");
+	const nb = ch.nonce_binding;
+	if (!nb?.interaction_id || !nb.challenge_step_id || !nb.challenge_nonce) bad("challenge.nonce_binding");
+	if (nb.interaction_id !== c.interaction_id) bad("interaction_id (mismatch with challenge.nonce_binding.interaction_id)");
+	validatePaymentRequirements(ch.payment_requirements, bad);
+}
 var X402Client = class {
 	#apiKey;
 	#baseUrl;
@@ -237,6 +384,99 @@ var X402Client = class {
 		return this.#request("POST", "/v1/x402/challenges", body, { headers: input.idempotencyKey ? { "idempotency-key": input.idempotencyKey } : void 0 });
 	}
 	/**
+	* Issue a payment challenge over an email thread (payee side). Sends the
+	* challenge as an email from `from` to `to` and binds the payment to that
+	* thread. Returns the challenge (including the real `interaction_id`); deliver
+	* it to the payer, who calls `payEmailChallenge` to build the signed payment.
+	*
+	* Provide exactly one of `amount` (base units) or `amountUsdc` (human USDC).
+	*/
+	async createEmailChallenge(input) {
+		for (const key of Object.keys(input)) if (!(key in EMAIL_CHARGE_INPUT_KEYS)) throw new X402Error(`unknown createEmailChallenge() option "${key}"; expected one of: ${Object.keys(EMAIL_CHARGE_INPUT_KEYS).join(", ")}`, 0);
+		if (!input.from) throw new X402Error("createEmailChallenge() requires `from`", 0);
+		if (!input.to) throw new X402Error("createEmailChallenge() requires `to`", 0);
+		if (input.amount !== void 0 && input.amountUsdc !== void 0) throw new X402Error("createEmailChallenge() takes exactly one of `amount` (base units) or `amountUsdc` (human USDC), not both", 0);
+		const amount = input.amountUsdc !== void 0 ? usdcToBaseUnits(input.amountUsdc) : input.amount ?? null;
+		if (!amount || !/^[1-9][0-9]{0,38}$/.test(amount)) throw new X402Error("createEmailChallenge() requires `amount` as a positive integer string in token base units (e.g. \"10000\"), or `amountUsdc` as a positive USDC amount with at most 6 decimals (e.g. \"0.01\")", 0);
+		const body = {
+			from: input.from,
+			to: input.to,
+			amount,
+			network: input.network ?? "base-sepolia"
+		};
+		if (input.description) body.description = input.description;
+		if (input.resource) body.resource = input.resource;
+		if (input.expiresIn !== void 0) body.expires_in = input.expiresIn;
+		return this.#request("POST", "/v1/x402/email-challenges", body, { headers: input.idempotencyKey ? { "idempotency-key": input.idempotencyKey } : void 0 });
+	}
+	/**
+	* Build the signed payment step for an email-native challenge (payer side).
+	* Given a received `X402EmailChallenge` and the caller's signer, this derives
+	* the interaction-bound authorization, signs it locally, and returns the
+	* signed `interaction.json` payment-step envelope plus its canonical JSON
+	* bytes. It does NOT send anything.
+	*
+	* The caller sends `result.json` back as an `interaction.json` attachment on a
+	* reply to the challenge email (e.g. via the SDK's `send` / `reply`); the
+	* platform reads the envelope from those exact bytes, re-derives the bound
+	* nonce, and settles.
+	*/
+	async payEmailChallenge(challenge, options) {
+		if (!options?.signer?.address || typeof options.signer.signTypedData !== "function") throw new X402Error("payEmailChallenge() requires options.signer with { address, signTypedData } (e.g. a viem LocalAccount)", 0);
+		validateEmailChallenge(challenge);
+		const details = challenge.challenge;
+		const pr = details.payment_requirements;
+		const network = pr.network;
+		const chainId = CHAIN_IDS[network];
+		if (chainId === void 0) throw new X402Error(`unsupported network: ${network}`, 0);
+		if (pr.scheme !== "exact") throw new X402Error(`unsupported payment scheme: ${pr.scheme}`, 0);
+		const nowSec = Math.floor(Date.now() / 1e3);
+		const expiresAtMs = Date.parse(details.expires_at);
+		if (Number.isNaN(expiresAtMs)) throw new X402Error(`challenge has an invalid expires_at: ${details.expires_at}`, 0);
+		const expiresAtSec = Math.floor(expiresAtMs / 1e3);
+		if (expiresAtSec <= nowSec) throw new X402Error(`challenge has already expired (expires_at ${details.expires_at}); not signing`, 0);
+		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: details.nonce_binding.interaction_id,
+				challengeStepId: details.nonce_binding.challenge_step_id,
+				challengeNonce: details.nonce_binding.challenge_nonce
+			},
+			validAfter,
+			validBefore
+		});
+		const payment = buildExactEvmPaymentPayload({
+			network,
+			authorization,
+			signature
+		});
+		return buildPaymentStepEnvelope({
+			interactionId: challenge.interaction_id,
+			stepId: randomUUID(),
+			prevStepId: details.nonce_binding.challenge_step_id,
+			payment
+		});
+	}
+	/**
 	* Pay a challenge (payer side). Derives the interaction-bound authorization,
 	* signs it locally with the caller's key, and submits it for settlement.
 	*/
@@ -248,33 +488,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 +599,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, X402_INTERACTION_PROTOCOL, X402_INTERACTION_PROTOCOL_VERSION, buildExactEvmPaymentPayload, buildPaymentStepEnvelope, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/package.json

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