primcli 1.6.1 → 1.8.0

package/README.md

@@ -92,6 +92,13 @@ primitive payments charge --network base-sepolia --amount-usdc 0.01 --json > cha
 primitive payments pay --challenge-file challenge.json
 cat challenge.json | primitive payments pay
 
+# Email-native flow: the payee issues a challenge over an email thread.
+primitive payments create-email-challenge --from payee@your-domain.example \
+  --to payer@their-domain.example --amount 10000 --network base-sepolia
+# Payer: sign a received email challenge into an interaction.json payment step.
+# This does NOT send; attach the output to your reply (e.g. with `primitive reply`).
+primitive payments pay-email-step --challenge-file challenge.json > interaction.json
+
 # Inspect a challenge by id, or list your registered payout addresses.
 primitive payments get-challenge --id <challenge-id>
 primitive payments list-payout-addresses

package/dist/oclif/index.js

@@ -7,7 +7,7 @@ import process$1 from "node:process";
 import { createInterface } from "node:readline/promises";
 import { hostname } from "node:os";
 import { spawn } from "node:child_process";
-import { concat, hexToBytes, keccak256, stringToBytes } from "viem";
+import { concat, getAddress, hexToBytes, keccak256, stringToBytes } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -31,6 +31,7 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	createAgentAccount: () => createAgentAccount,
 	createAgentClaimLink: () => createAgentClaimLink,
 	createChallenge: () => createChallenge,
+	createEmailChallenge: () => createEmailChallenge,
 	createEndpoint: () => createEndpoint,
 	createFilter: () => createFilter,
 	createFunction: () => createFunction,
@@ -1671,6 +1672,34 @@ const registerPayoutAddress = (options) => (options.client ?? client).post({
 	}
 });
 /**
+* Create an email-native payment challenge
+*
+* Issue an x402 payment challenge over a real email thread (the payee
+* side). Unlike `createChallenge` (which mints a synthetic challenge id),
+* this sends the challenge as an email from `from` to `to` and binds the
+* payment to that DKIM-authenticated thread. The `pay_to` address and the
+* token asset are resolved server-side from your registered default payout
+* address for the network, never from the request. The response carries
+* the thread's `interaction_id` plus the `challenge` (the
+* `payment_requirements`, the `nonce_binding`, and `expires_at`) the payer
+* needs to sign; the payer replies with a signed `payment` interaction
+* step. Amounts are in token base units (USDC has 6 decimals, so `"10000"`
+* is 0.01 USDC).
+*
+*/
+const createEmailChallenge = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/x402/email-challenges",
+	...options,
+	headers: {
+		...options.body !== void 0 && { "Content-Type": "application/json" },
+		...options.headers
+	}
+});
+/**
 * Create a payment challenge
 *
 * Create an x402 payment challenge (the payee side of a payment). The
@@ -4172,6 +4201,40 @@ const openapiDocument = {
 				}
 			}
 		},
+		"/x402/email-challenges": { "post": {
+			"operationId": "createEmailChallenge",
+			"summary": "Create an email-native payment challenge",
+			"description": "Issue an x402 payment challenge over a real email thread (the payee\nside). Unlike `createChallenge` (which mints a synthetic challenge id),\nthis sends the challenge as an email from `from` to `to` and binds the\npayment to that DKIM-authenticated thread. The `pay_to` address and the\ntoken asset are resolved server-side from your registered default payout\naddress for the network, never from the request. The response carries\nthe thread's `interaction_id` plus the `challenge` (the\n`payment_requirements`, the `nonce_binding`, and `expires_at`) the payer\nneeds to sign; the payer replies with a signed `payment` interaction\nstep. Amounts are in token base units (USDC has 6 decimals, so `\"10000\"`\nis 0.01 USDC).\n",
+			"tags": ["Payments"],
+			"security": [{ "BearerAuth": [] }],
+			"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailChallengeInput" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "Idempotent replay: a request with a previously-used idempotency key\nreturns the original issued challenge without sending a second email.\n",
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/X402EmailChallenge" } }
+					}] } } }
+				},
+				"201": {
+					"description": "Email challenge issued",
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/X402EmailChallenge" } }
+					}] } } }
+				},
+				"400": { "$ref": "#/components/responses/ValidationError" },
+				"401": { "$ref": "#/components/responses/Unauthorized" },
+				"403": { "$ref": "#/components/responses/Forbidden" },
+				"409": { "$ref": "#/components/responses/Conflict" },
+				"422": { "$ref": "#/components/responses/UnprocessableEntity" },
+				"429": { "$ref": "#/components/responses/RateLimited" }
+			}
+		} },
 		"/x402/challenges": { "post": {
 			"operationId": "createChallenge",
 			"summary": "Create a payment challenge",
@@ -4341,6 +4404,16 @@ const openapiDocument = {
 				},
 				"description": "Resource UUID"
 			},
+			"IdempotencyKey": {
+				"name": "idempotency-key",
+				"in": "header",
+				"required": false,
+				"schema": {
+					"type": "string",
+					"maxLength": 255
+				},
+				"description": "Optional idempotency key. Retrying a request with the same key returns\nthe original result instead of repeating the side effect (for\n`createEmailChallenge`, re-sending the email).\n"
+			},
 			"Cursor": {
 				"name": "cursor",
 				"in": "query",
@@ -4781,6 +4854,94 @@ const openapiDocument = {
 					"expires_at"
 				]
 			},
+			"CreateEmailChallengeInput": {
+				"type": "object",
+				"additionalProperties": false,
+				"description": "Issue a payment challenge over an email thread. `from` is your sending\naddress (the funds receiver; ownership is enforced at send, exactly as\nfor outbound mail) and `to` is the payer's address. The `pay_to` payout\nwallet and the token asset are resolved server-side, never taken from\nthe request.\n",
+				"properties": {
+					"from": {
+						"type": "string",
+						"format": "email",
+						"description": "Your sending address (the payee / funds receiver). Must be an\naddress your org is allowed to send from.\n"
+					},
+					"to": {
+						"type": "string",
+						"format": "email",
+						"description": "The payer's email address the challenge is sent to."
+					},
+					"amount": {
+						"type": "string",
+						"pattern": "^[1-9][0-9]{0,38}$",
+						"description": "Amount to collect, in token base units. USDC has 6 decimals, so\n`\"10000\"` is 0.01 USDC.\n"
+					},
+					"network": {
+						"type": "string",
+						"enum": ["base", "base-sepolia"]
+					},
+					"expires_in": {
+						"type": "integer",
+						"minimum": 60,
+						"maximum": 86400,
+						"description": "Seconds until the challenge expires. Defaults to 3600."
+					},
+					"resource": {
+						"type": "string",
+						"format": "uri",
+						"maxLength": 2048,
+						"description": "Optional URL identifying what is being paid for."
+					},
+					"description": {
+						"type": "string",
+						"maxLength": 512,
+						"description": "Optional human-readable description of the payment."
+					}
+				},
+				"required": [
+					"from",
+					"to",
+					"amount",
+					"network"
+				]
+			},
+			"X402EmailChallengeDetails": {
+				"type": "object",
+				"description": "The challenge the payer needs to sign and pay, carried inside an\nemail-native challenge response.\n",
+				"properties": {
+					"payment_requirements": { "$ref": "#/components/schemas/X402PaymentRequirements" },
+					"nonce_binding": { "$ref": "#/components/schemas/X402NonceBinding" },
+					"expires_at": {
+						"type": "string",
+						"format": "date-time",
+						"description": "ISO-8601 expiry of the challenge."
+					}
+				},
+				"required": [
+					"payment_requirements",
+					"nonce_binding",
+					"expires_at"
+				]
+			},
+			"X402EmailChallenge": {
+				"type": "object",
+				"description": "The result of issuing an email-native payment challenge. `interaction_id`\nis the real email thread id (`uuid@domain`) the payment is bound to;\n`challenge_id` is the underlying challenge record. Hand the `challenge`\nto the payer, who replies with a signed `payment` interaction step (the\nSDK `payEmailChallenge` helper builds it).\n",
+				"properties": {
+					"interaction_id": {
+						"type": "string",
+						"description": "The email thread id (`uuid@domain`) the payment is bound to."
+					},
+					"challenge_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "The underlying challenge record id."
+					},
+					"challenge": { "$ref": "#/components/schemas/X402EmailChallengeDetails" }
+				},
+				"required": [
+					"interaction_id",
+					"challenge_id",
+					"challenge"
+				]
+			},
 			"X402PaymentPayload": {
 				"type": "object",
 				"description": "A signed x402 v1 `PaymentPayload`. The SDK `pay()` helper builds this;\ncallers rarely construct it by hand. Field names are x402-native.\n",
@@ -14629,6 +14790,178 @@ const operationManifest = [
 		"tag": "Payments",
 		"tagCommand": "payments"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "create-email-challenge",
+		"description": "Issue an x402 payment challenge over a real email thread (the payee\nside). Unlike `createChallenge` (which mints a synthetic challenge id),\nthis sends the challenge as an email from `from` to `to` and binds the\npayment to that DKIM-authenticated thread. The `pay_to` address and the\ntoken asset are resolved server-side from your registered default payout\naddress for the network, never from the request. The response carries\nthe thread's `interaction_id` plus the `challenge` (the\n`payment_requirements`, the `nonce_binding`, and `expires_at`) the payer\nneeds to sign; the payer replies with a signed `payment` interaction\nstep. Amounts are in token base units (USDC has 6 decimals, so `\"10000\"`\nis 0.01 USDC).\n",
+		"hasJsonBody": true,
+		"method": "POST",
+		"operationId": "createEmailChallenge",
+		"path": "/x402/email-challenges",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Issue a payment challenge over an email thread. `from` is your sending\naddress (the funds receiver; ownership is enforced at send, exactly as\nfor outbound mail) and `to` is the payer's address. The `pay_to` payout\nwallet and the token asset are resolved server-side, never taken from\nthe request.\n",
+			"properties": {
+				"from": {
+					"type": "string",
+					"format": "email",
+					"description": "Your sending address (the payee / funds receiver). Must be an\naddress your org is allowed to send from.\n"
+				},
+				"to": {
+					"type": "string",
+					"format": "email",
+					"description": "The payer's email address the challenge is sent to."
+				},
+				"amount": {
+					"type": "string",
+					"pattern": "^[1-9][0-9]{0,38}$",
+					"description": "Amount to collect, in token base units. USDC has 6 decimals, so\n`\"10000\"` is 0.01 USDC.\n"
+				},
+				"network": {
+					"type": "string",
+					"enum": ["base", "base-sepolia"]
+				},
+				"expires_in": {
+					"type": "integer",
+					"minimum": 60,
+					"maximum": 86400,
+					"description": "Seconds until the challenge expires. Defaults to 3600."
+				},
+				"resource": {
+					"type": "string",
+					"format": "uri",
+					"maxLength": 2048,
+					"description": "Optional URL identifying what is being paid for."
+				},
+				"description": {
+					"type": "string",
+					"maxLength": 512,
+					"description": "Optional human-readable description of the payment."
+				}
+			},
+			"required": [
+				"from",
+				"to",
+				"amount",
+				"network"
+			]
+		},
+		"responseSchema": {
+			"type": "object",
+			"description": "The result of issuing an email-native payment challenge. `interaction_id`\nis the real email thread id (`uuid@domain`) the payment is bound to;\n`challenge_id` is the underlying challenge record. Hand the `challenge`\nto the payer, who replies with a signed `payment` interaction step (the\nSDK `payEmailChallenge` helper builds it).\n",
+			"properties": {
+				"interaction_id": {
+					"type": "string",
+					"description": "The email thread id (`uuid@domain`) the payment is bound to."
+				},
+				"challenge_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "The underlying challenge record id."
+				},
+				"challenge": {
+					"type": "object",
+					"description": "The challenge the payer needs to sign and pay, carried inside an\nemail-native challenge response.\n",
+					"properties": {
+						"payment_requirements": {
+							"type": "object",
+							"description": "The x402 `PaymentRequirements` the payer signs over. Field names are\nx402's native camelCase, preserved byte-for-byte.\n",
+							"properties": {
+								"scheme": {
+									"type": "string",
+									"description": "The x402 settlement scheme. Always `exact` for v1.",
+									"example": "exact"
+								},
+								"network": {
+									"type": "string",
+									"enum": ["base", "base-sepolia"]
+								},
+								"maxAmountRequired": {
+									"type": "string",
+									"description": "Amount in token base units."
+								},
+								"payTo": {
+									"type": "string",
+									"description": "The payee's resolved payout address (checksummed)."
+								},
+								"asset": {
+									"type": "string",
+									"description": "The token contract address (checksummed). USDC."
+								},
+								"resource": { "type": "string" },
+								"description": { "type": "string" },
+								"maxTimeoutSeconds": { "type": "integer" },
+								"extra": {
+									"type": "object",
+									"description": "The token's load-bearing EIP-712 domain params. `name` differs by\nchain (Base mainnet USDC is `USD Coin`, Base Sepolia is `USDC`); a\nwrong value produces a signature the verifier rejects.\n",
+									"properties": {
+										"name": { "type": "string" },
+										"version": { "type": "string" }
+									},
+									"required": ["name", "version"]
+								}
+							},
+							"required": [
+								"scheme",
+								"network",
+								"maxAmountRequired",
+								"payTo",
+								"asset",
+								"extra"
+							]
+						},
+						"nonce_binding": {
+							"type": "object",
+							"description": "The interaction binding the payer hashes into the EIP-3009 nonce\n(`deriveEip3009Nonce`). Pinning the nonce to this binding is what lets an\nx402 payment ride asynchronous transports safely: a replayed challenge\ncan't redirect funds and a signed payment can't settle twice.\n",
+							"properties": {
+								"interaction_id": {
+									"type": "string",
+									"description": "Interaction id, including its `@domain` part."
+								},
+								"challenge_step_id": {
+									"type": "string",
+									"format": "uuid"
+								},
+								"challenge_nonce": {
+									"type": "string",
+									"pattern": "^[0-9a-f]{64}$",
+									"description": "32 random bytes as 64 lowercase hex chars."
+								}
+							},
+							"required": [
+								"interaction_id",
+								"challenge_step_id",
+								"challenge_nonce"
+							]
+						},
+						"expires_at": {
+							"type": "string",
+							"format": "date-time",
+							"description": "ISO-8601 expiry of the challenge."
+						}
+					},
+					"required": [
+						"payment_requirements",
+						"nonce_binding",
+						"expires_at"
+					]
+				}
+			},
+			"required": [
+				"interaction_id",
+				"challenge_id",
+				"challenge"
+			]
+		},
+		"sdkName": "createEmailChallenge",
+		"summary": "Create an email-native payment challenge",
+		"tag": "Payments",
+		"tagCommand": "payments"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
@@ -21020,8 +21353,8 @@ const PRIMITIVE_TEAM_AUTHOR = {
 	name: "Primitive Team",
 	url: "https://primitive.dev"
 };
-const SDK_VERSION_RANGE = "^1.6.0";
-const CLI_VERSION_RANGE = "^1.6.0";
+const SDK_VERSION_RANGE = "^1.8.0";
+const CLI_VERSION_RANGE = "^1.8.0";
 const ESBUILD_VERSION_RANGE = "^0.27.0";
 function renderHandler() {
 	return `// env.PRIMITIVE_API_KEY, env.PRIMITIVE_WEBHOOK_SECRET, and
@@ -24509,6 +24842,43 @@ 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";
+/** 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 {
@@ -24528,12 +24898,77 @@ function toPaymentPayload(network, auth, signature) {
 		}
 	};
 }
+/**
+* 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);
+}
+/**
+* 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,
@@ -24545,6 +24980,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$1(human) {
 	const trimmed = human.trim();
 	if (!/^\d+(\.\d+)?$/.test(trimmed)) return null;
@@ -24581,13 +25027,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;
@@ -24647,6 +25117,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$1(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.
 	*/
@@ -24658,33 +25221,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) {
@@ -25054,6 +25629,116 @@ var PaymentsPayCommand = class PaymentsPayCommand extends Command {
 	}
 };
 //#endregion
+//#region src/oclif/commands/payments-pay-email-step.ts
+function readEmailChallenge(input) {
+	let raw;
+	if (input.inline !== void 0) raw = input.inline;
+	else if (input.file !== void 0) raw = readFileSync(input.file, "utf8");
+	else {
+		if (process.stdin.isTTY) process.stderr.write("Reading the email challenge JSON from stdin; paste it and press Ctrl-D (or use --challenge / --challenge-file).\n");
+		raw = readFileSync(0, "utf8");
+	}
+	const trimmed = raw.trim();
+	if (!trimmed) throw new Error("no challenge provided; pass --challenge '<json>', --challenge-file <path>, or pipe the email challenge JSON on stdin");
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		throw new Error("challenge is not valid JSON");
+	}
+	if (parsed && typeof parsed === "object" && "data" in parsed) {
+		const data = parsed.data;
+		if (!data || typeof data !== "object") throw new Error("challenge envelope has no `data` object; pass the email challenge JSON itself or a `{ \"data\": { ... } }` envelope");
+		return data;
+	}
+	return parsed;
+}
+var PaymentsPayEmailStepCommand = class PaymentsPayEmailStepCommand extends Command {
+	static description = `Sign an email-native x402 challenge into a payment-step interaction.json.
+
+  Reads the email challenge the payee issued (the JSON from
+  \`payments create-email-challenge\`), derives and signs the interaction-bound
+  EIP-3009 authorization locally with your wallet key (read from
+  ${PRIVATE_KEY_ENV} by default), and prints the signed \`interaction.json\`
+  payment-step envelope. The key never leaves your machine.
+
+  This command does NOT send the payment. Attach the printed envelope as the
+  \`interaction.json\` part of your reply to the challenge email, for example:
+    primitive payments pay-email-step --challenge-file challenge.json > interaction.json
+    primitive reply --attachment interaction.json
+
+  Provide the challenge inline with --challenge, from a file with
+  --challenge-file, or piped on stdin.`;
+	static summary = "Sign an email x402 challenge into a payment-step envelope";
+	static examples = [
+		"<%= config.bin %> payments pay-email-step --challenge-file challenge.json > interaction.json",
+		"<%= config.bin %> payments pay-email-step --challenge '{\"interaction_id\":\"...\",\"challenge\":{...}}'",
+		"cat challenge.json | <%= config.bin %> payments pay-email-step"
+	];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		"private-key": Flags.string({
+			description: PRIVATE_KEY_FLAG_DESCRIPTION,
+			env: PRIVATE_KEY_ENV
+		}),
+		challenge: Flags.string({
+			description: "The email challenge object as a JSON string.",
+			exclusive: ["challenge-file"]
+		}),
+		"challenge-file": Flags.string({
+			description: "Path to a file containing the email challenge JSON.",
+			exclusive: ["challenge"]
+		}),
+		json: Flags.boolean({ description: "Print the full signed envelope object (default prints the interaction.json bytes)." }),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(PaymentsPayEmailStepCommand);
+		const requestConfig = resolveCliApiRequestConfig({
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		const baseUrlOverridden = requestConfig.baseUrlOverridden;
+		const auth = {
+			apiKey: flags["api-key"],
+			apiBaseUrl: requestConfig.resolvedApiBaseUrl,
+			source: "none",
+			credentials: null
+		};
+		await runWithTiming(flags.time, async () => {
+			const client = createX402Client({
+				apiKey: flags["api-key"] || void 0,
+				baseUrl: x402BaseUrl(requestConfig.resolvedApiBaseUrl)
+			});
+			try {
+				const challenge = readEmailChallenge({
+					inline: flags.challenge,
+					file: flags["challenge-file"]
+				});
+				const signer = signerFromPrivateKey(flags["private-key"] ?? "");
+				const built = await client.payEmailChallenge(challenge, { signer });
+				if (flags.json) this.log(JSON.stringify(built.envelope, null, 2));
+				else this.log(built.json);
+			} catch (error) {
+				reportX402Error(error, {
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir
+				});
+				process.exitCode = 1;
+			}
+		});
+	}
+};
+//#endregion
 //#region src/oclif/commands/payments-register-payout-address.ts
 var PaymentsRegisterPayoutAddressCommand = class PaymentsRegisterPayoutAddressCommand extends Command {
 	static description = `Register the default payout address your org receives x402 payments at.
@@ -26653,7 +27338,8 @@ const COMMANDS = {
 	"payments:register-payout": PaymentsRegisterPayoutAddressCommand,
 	"payments:charge": PaymentsChargeCommand,
 	"payments:pay-challenge": PaymentsPayCommand,
-	"payments:pay": PaymentsPayCommand
+	"payments:pay": PaymentsPayCommand,
+	"payments:pay-email-step": PaymentsPayEmailStepCommand
 };
 //#endregion
 export { CANONICAL_OPERATION_ALIASES, COMMANDS, lookupOperation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,