mppx 0.16.0 → 0.17.1

package/dist/server/Mppx.js

@@ -467,7 +467,8 @@ function createMethodFn(parameters) {
                 ]),
             ],
             _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
-            _paymentIdentity: paymentVerifiers.length > 0,
+            _paymentIdentity: paymentVerifiers.length > 0 ? paymentVerifiers : undefined,
+            _identity: identity.length > 0,
             _stableBinding: stableBinding,
             _transport: transport,
         };
@@ -500,6 +501,12 @@ function createMethodFn(parameters) {
             const effectiveMeta = scope === undefined && input instanceof globalThis.Request
                 ? Scope.merge({ meta: staticMeta, scope: Scope.get(input) })
                 : staticMeta;
+            // Every offer of one 402 shares the identity nonce (composed routes pass each offer the
+            // same request), so a payment-stage proof is bound to the 402, whichever offer is paid.
+            const identityNonce = paymentVerifiers.length > 0 && input instanceof globalThis.Request
+                ? IdentityServer.nonceFor(input, ChallengeMeta.createNonce)
+                : undefined;
+            const challengeMeta = ChallengeMeta.withIdentity(effectiveMeta, identityNonce);
             // Extract credential once — getCredential may have side effects (e.g. SSE transports).
             let [credential, credentialError] = (() => {
                 try {
@@ -540,17 +547,12 @@ function createMethodFn(parameters) {
                     ...(parameters.html && { html: parameters.html }),
                 });
                 // Payment-stage verifiers add their own challenge headers to the 402.
-                if (paymentVerifiers.length > 0 &&
+                if (identityNonce !== undefined &&
                     input instanceof globalThis.Request &&
                     response instanceof globalThis.Response) {
-                    const outcome = await IdentityServer.verify(input, paymentVerifiers, {
-                        challenge: parameters.challenge,
-                    });
-                    const identityHeaders = new Headers();
-                    if (outcome.status !== 'valid')
-                        for (const [name, value] of outcome.headers)
-                            identityHeaders.append(name, value);
+                    const identityHeaders = await IdentityServer.challenge(input, paymentVerifiers, identityNonce);
                     if ([...identityHeaders].length > 0) {
+                        const paymentChallenge = response.headers.get(paymentAuthChallengeHeader);
                         const headers = new Headers(response.headers);
                         for (const [name, value] of identityHeaders)
                             headers.append(name, value);
@@ -560,6 +562,7 @@ function createMethodFn(parameters) {
                             statusText: response.statusText,
                         });
                         identityChallenges.set(response, identityHeaders);
+                        paymentChallenges.set(response, paymentChallenge);
                     }
                 }
                 if (isIssuedChallengeResponse(response))
@@ -594,7 +597,7 @@ function createMethodFn(parameters) {
                 description,
                 expires,
                 header: credentialHeader,
-                meta: effectiveMeta,
+                meta: challengeMeta,
                 method,
                 realm,
                 request: parameters.request,
@@ -609,7 +612,7 @@ function createMethodFn(parameters) {
                     description,
                     expires,
                     header: credentialHeader,
-                    meta: effectiveMeta,
+                    meta: challengeMeta,
                     method,
                     realm,
                     routeRequest: rest,
@@ -897,6 +900,7 @@ function createMethodFn(parameters) {
                 const outcome = await IdentityServer.verify(input, paymentVerifiers, {
                     challenge: credential.challenge,
                     credential: parsedCredential,
+                    nonce: ChallengeMeta.identity(credential.challenge.meta),
                 });
                 if (outcome.status !== 'valid') {
                     const error = new Errors.VerificationFailedError({ reason: outcome.reason });
@@ -1348,6 +1352,7 @@ async function resolveRouteChallenge(parameters) {
             ? (await parameters.request({
                 capturedRequest: parameters.capturedRequest,
                 credential: parameters.credential,
+                expires: parameters.credential?.challenge.expires ?? parameters.expires,
                 request: merged,
             }))
             : merged;
@@ -1588,17 +1593,30 @@ const paymentAuthChallengeHeader = Constants.Headers.wwwAuthenticate;
 const identityChallenges = new WeakMap();
 /** Identity rejections (401/403) returned on a route's non-success branch. @internal */
 const identityRejections = new WeakSet();
+/**
+ * A 402's Payment `WWW-Authenticate` value without its identity challenge, keyed by response.
+ * Composers merge these and append the shared identity challenge once. @internal
+ */
+const paymentChallenges = new WeakMap();
 /** Records a merged 402's identity challenge so an outer composer can forward it. @internal */
-function withIdentityChallenge(response, headers) {
-    if (headers)
+function withIdentityChallenge(response, headers, paymentChallenge) {
+    if (headers) {
         identityChallenges.set(response, headers);
+        paymentChallenges.set(response, paymentChallenge);
+    }
     return response;
 }
 const challengeHeaderMerges = [
     {
         name: paymentAuthChallengeHeader,
         values: (context) => context.challengeEntries
-            .map((entry) => entry.result.challenge.headers.get(paymentAuthChallengeHeader))
+            .map((entry) => {
+            const response = entry.result.challenge;
+            // Identity challenges are appended once by the composer, not once per offer.
+            return paymentChallenges.has(response)
+                ? paymentChallenges.get(response)
+                : response.headers.get(paymentAuthChallengeHeader);
+        })
             .filter((value) => value !== null),
         merge: (values) => values,
     },
@@ -1639,9 +1657,13 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
     });
     if (handlers.length === 0)
         throw new Error('compose() requires at least one handler');
-    // A 402 carries one identity challenge, bound to one payment challenge.
-    if (handlers.flatMap(getConfiguredOffers).filter((offer) => offer._paymentIdentity).length > 1)
-        throw new TypeError('A composed route can include at most one offer with payment-stage identity.');
+    // A 402 carries one identity challenge, shared by its offers through the identity nonce, so
+    // every offer that requires payment-stage identity must require the same verifiers.
+    const identityOffers = handlers
+        .flatMap(getConfiguredOffers)
+        .flatMap((offer) => (offer._paymentIdentity ? [offer._paymentIdentity] : []));
+    if (identityOffers.some((verifiers) => !sameVerifiers(verifiers, identityOffers[0])))
+        throw new TypeError('Offers in a composed route must require the same payment-stage identity verifiers.');
     const offerSelector = selectOffers;
     const offerEntries = handlers.map((handler) => {
         const internal = handler._internal;
@@ -1809,8 +1831,8 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 ...unnegotiatedX402Responses,
             ]
             : challengeResponses;
-        // At most one offer carries an identity challenge (enforced when composing); forward it
-        // only if its payment challenge is still advertised after negotiation.
+        // Offers share one identity challenge (enforced when composing); forward it only if an
+        // offer that carries it is still advertised after negotiation.
         const identityHeaders = negotiatedChallengeResponses
             .map((response) => identityChallenges.get(response))
             .find((headers) => headers !== undefined);
@@ -1826,11 +1848,11 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 mergedHeaders.append(header.name, value);
             }
         }
-        // Identity WWW-Authenticate values already arrive in the merged offer value above.
+        // The merged offer values above exclude identity challenges; append the shared one once.
+        const paymentChallenge = mergedHeaders.get(paymentAuthChallengeHeader);
         if (identityHeaders)
             for (const [name, value] of identityHeaders)
-                if (name !== paymentAuthChallengeHeader.toLowerCase())
-                    mergedHeaders.append(name, value);
+                mergedHeaders.append(name, value);
         // Collect html-enabled handlers and their challenges
         const htmlEntries = challengeEntries.filter((entry) => entry.handler._internal?.html);
         const wantsHtml = input.headers.get('Accept')?.includes('text/html');
@@ -1867,7 +1889,7 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
             });
             return {
                 status: 402,
-                challenge: withIdentityChallenge(new Response(body, { status: 402, headers: mergedHeaders }), identityHeaders),
+                challenge: withIdentityChallenge(new Response(body, { status: 402, headers: mergedHeaders }), identityHeaders, paymentChallenge),
             };
         }
         // Non-HTML fallback: prefer the first Payment-auth body, otherwise use
@@ -1887,7 +1909,7 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
         }
         return {
             status: 402,
-            challenge: withIdentityChallenge(new Response(body, { status: 402, headers: mergedHeaders }), identityHeaders),
+            challenge: withIdentityChallenge(new Response(body, { status: 402, headers: mergedHeaders }), identityHeaders, paymentChallenge),
         };
     };
     const offers = handlers.flatMap(getConfiguredOffers);
@@ -1895,6 +1917,10 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
         composed._internal = { offers, handlers: handlers, selectOffers };
     return composed;
 }
+/** Whether two verifier lists hold the same verifiers in the same order. */
+function sameVerifiers(a, b) {
+    return a.length === b.length && a.every((verifier, i) => verifier === b[i]);
+}
 /** Returns the flattened configured offers accepted by a handler. */
 function getConfiguredOffers(handler) {
     const internal = handler._internal;

package/dist/server/internal/challengeMeta.d.ts

@@ -1,5 +1,11 @@
 /** Adds fresh issuance randomness while preserving application and route metadata. */
 export declare function withNonce(meta: Record<string, string> | undefined): Record<string, string>;
+/** Returns fresh randomness for an identity nonce. */
+export declare function createNonce(): string;
+/** Adds an identity nonce to challenge metadata. */
+export declare function withIdentity(meta: Record<string, string> | undefined, nonce: string | undefined): Record<string, string> | undefined;
+/** Reads the identity nonce from challenge metadata. */
+export declare function identity(meta: Record<string, string> | undefined): string | undefined;
 /** Removes issuance-only metadata when comparing stable route requirements. */
 export declare function routeMeta(meta: Record<string, string> | undefined): Record<string, string> | undefined;
 //# sourceMappingURL=challengeMeta.d.ts.map

package/dist/server/internal/challengeMeta.js

@@ -6,9 +6,25 @@ export function withNonce(meta) {
     // Ox uses runtime-specific secure randomness, including Node without global Web Crypto.
     return { ...meta, [nonceKey]: Secp256k1.randomPrivateKey() };
 }
+/** Reserved metadata key for the HMAC-bound identity nonce shared by every offer in one 402. */
+const identityKey = '_mppx_identity';
+/** Returns fresh randomness for an identity nonce. */
+export function createNonce() {
+    return Secp256k1.randomPrivateKey();
+}
+/** Adds an identity nonce to challenge metadata. */
+export function withIdentity(meta, nonce) {
+    if (nonce === undefined)
+        return meta;
+    return { ...meta, [identityKey]: nonce };
+}
+/** Reads the identity nonce from challenge metadata. */
+export function identity(meta) {
+    return meta?.[identityKey];
+}
 /** Removes issuance-only metadata when comparing stable route requirements. */
 export function routeMeta(meta) {
-    const { [nonceKey]: _, ...rest } = meta ?? {};
+    const { [nonceKey]: _, [identityKey]: __, ...rest } = meta ?? {};
     return Object.keys(rest).length ? rest : undefined;
 }
 //# sourceMappingURL=challengeMeta.js.map

package/dist/tempo/client/Charge.d.ts

@@ -6,10 +6,22 @@ import * as z from '../../zod.js';
 import * as AutoSwap from '../internal/auto-swap.js';
 import * as Methods from '../Methods.js';
 import type * as AccountResolution from './ResolveAccount.js';
+/**
+ * Seconds from now the client sets as the expiring-nonce `validBefore`,
+ * capped at the challenge expiry.
+ *
+ * Fee payers require at least `defaults.minRemainingValiditySeconds` (15s) of
+ * remaining validity when they co-sign, so a 25s window leaves about 10s for
+ * clock skew between client and server, signing and round trips. It stays inside
+ * the server's default 30s confirmation timeout and within sponsor policies whose
+ * `maxValidityWindowSeconds` is 25 or more.
+ */
+export declare const validityWindowSeconds = 25;
 /** Runtime context accepted by the Tempo charge client method. */
 export type ChargeContext = {
     account?: Account.getResolver.Parameters['account'] | undefined;
     autoSwap?: AutoSwap.resolve.Value | undefined;
+    feeToken?: Address | undefined;
     mode?: Methods.ChargeMode | undefined;
 };
 /**
@@ -30,6 +42,7 @@ export declare function charge(parameters?: charge.Parameters): {
     readonly context?: z.ZodMiniObject<{
         account: z.ZodMiniOptional<z.ZodMiniCustom<`0x${string}` | Account.Account | undefined, `0x${string}` | Account.Account | undefined>>;
         autoSwap: z.ZodMiniOptional<z.ZodMiniCustom<AutoSwap.resolve.Value | undefined, AutoSwap.resolve.Value | undefined>>;
+        feeToken: z.ZodMiniOptional<z.ZodMiniCustom<`0x${string}` | undefined, `0x${string}` | undefined>>;
         mode: z.ZodMiniOptional<z.ZodMiniEnum<{
             pull: "pull";
             push: "push";
@@ -181,6 +194,7 @@ export declare function charge(parameters?: charge.Parameters): {
     }, {
         account?: `0x${string}` | Account.Account | undefined;
         autoSwap?: AutoSwap.resolve.Value | undefined;
+        feeToken?: `0x${string}` | undefined;
         mode?: "pull" | "push" | undefined;
     }>;
 };
@@ -199,6 +213,12 @@ export declare namespace charge {
         autoSwap?: AutoSwap | undefined;
         /** Client identifier used to derive the client fingerprint in attribution memos. */
         clientId?: string | undefined;
+        /**
+         * Token the payer pays its transaction fee in, when the challenge is not fee-sponsored.
+         * Set it for an access key whose spending limits do not cover the default fee token,
+         * such as a key limited to OUSD paying a USDC.e charge.
+         */
+        feeToken?: Address | undefined;
         /**
          * Chain ID this client is willing to pay on. When set, the client rejects
          * any challenge whose `methodDetails.chainId` differs, and signs on this

package/dist/tempo/client/Charge.js

@@ -17,9 +17,21 @@ import { defaultFeeTokens, resolveFeeToken } from '../internal/fee-token.js';
 import * as MachineTokenCharge from '../internal/machine-token-charge.js';
 import * as Proof from '../internal/proof.js';
 import * as Methods from '../Methods.js';
+/**
+ * Seconds from now the client sets as the expiring-nonce `validBefore`,
+ * capped at the challenge expiry.
+ *
+ * Fee payers require at least `defaults.minRemainingValiditySeconds` (15s) of
+ * remaining validity when they co-sign, so a 25s window leaves about 10s for
+ * clock skew between client and server, signing and round trips. It stays inside
+ * the server's default 30s confirmation timeout and within sponsor policies whose
+ * `maxValidityWindowSeconds` is 25 or more.
+ */
+export const validityWindowSeconds = 25;
 const chargeContextSchema = z.object({
     account: z.optional(z.custom()),
     autoSwap: z.optional(z.custom()),
+    feeToken: z.optional(z.custom()),
     mode: z.optional(z.enum(Methods.chargeModes)),
 });
 /**
@@ -177,15 +189,18 @@ export function charge(parameters = {}) {
             }
             const calls = machineTokenRoute?.calls ?? [...(swapCalls ?? []), ...transferCalls];
             const allowedFeeTokens = defaultFeeTokens(chainId);
-            const feeToken = machineTokenRoute || isMachineTokenCurrency
-                ? await resolveFeeToken({
-                    account: account.address,
-                    allowedTokens: allowedFeeTokens,
-                    candidateTokens: allowedFeeTokens,
-                    client,
-                    prioritizeCandidates: true,
-                })
-                : undefined;
+            const explicitFeeToken = context?.feeToken ?? parameters.feeToken;
+            const feeToken = explicitFeeToken
+                ? explicitFeeToken
+                : machineTokenRoute || isMachineTokenCurrency
+                    ? await resolveFeeToken({
+                        account: account.address,
+                        allowedTokens: allowedFeeTokens,
+                        candidateTokens: allowedFeeTokens,
+                        client,
+                        prioritizeCandidates: true,
+                    })
+                    : undefined;
             const mode = (() => {
                 const explicitMode = context?.mode ?? parameters.mode;
                 if (explicitMode) {
@@ -199,7 +214,7 @@ export function charge(parameters = {}) {
                 return supportedModes[0];
             })();
             const validBefore = (() => {
-                const defaultExpiry = Math.floor(Date.now() / 1000) + 25;
+                const defaultExpiry = Math.floor(Date.now() / 1000) + validityWindowSeconds;
                 if (!challenge.expires)
                     return defaultExpiry;
                 // `validBefore` is an exclusive whole-second bound, so cap at the second
@@ -236,6 +251,22 @@ export function charge(parameters = {}) {
                     source: Proof.proofSource({ address: account.address, chainId }),
                 });
             }
+            // The fee payer rejects a sponsored transaction with under the minimum remaining validity,
+            // so refuse before signing rather than produce a credential the server must reject.
+            // The fee payer checks the signed `validBefore`, which is fixed before preparation, so the
+            // re-check measures both it and the challenge expiry against the current time.
+            const assertSponsorable = () => {
+                if (methodDetails?.feePayer !== true)
+                    return;
+                const minimumMs = defaults.minRemainingValiditySeconds * 1000;
+                const expiresMs = challenge.expires ? new Date(challenge.expires).getTime() : Infinity;
+                const now = Date.now();
+                if (!(expiresMs - now >= minimumMs))
+                    throw new Error(`Sponsored challenge expires in less than ${defaults.minRemainingValiditySeconds} seconds; the fee payer would reject the transaction. Request a new challenge.`);
+                if (!(validBefore * 1000 - now >= minimumMs))
+                    throw new Error(`Sponsored transaction preparation took too long: less than ${defaults.minRemainingValiditySeconds} seconds of its validity window remain, so the fee payer would reject it.`);
+            };
+            assertSponsorable();
             const prepared = await prepareTransactionRequest(client, {
                 account,
                 calls,
@@ -252,6 +283,8 @@ export function charge(parameters = {}) {
                 delete sponsored.feeToken;
                 sponsored.feePayer = true;
             }
+            // Preparation is asynchronous: check again immediately before signing.
+            assertSponsorable();
             const signature = await signTransaction(client, prepared);
             return Credential.serialize({
                 challenge,

package/dist/tempo/client/Methods.d.ts

@@ -24,6 +24,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
     readonly context?: import("zod/mini").ZodMiniObject<{
         account: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<`0x${string}` | import("../../viem/Account.js").Account | undefined, `0x${string}` | import("../../viem/Account.js").Account | undefined>>;
         autoSwap: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<import("../internal/auto-swap.js").resolve.Value | undefined, import("../internal/auto-swap.js").resolve.Value | undefined>>;
+        feeToken: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<`0x${string}` | undefined, `0x${string}` | undefined>>;
         mode: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniEnum<{
             pull: "pull";
             push: "push";
@@ -175,6 +176,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
     }, {
         account?: `0x${string}` | import("../../viem/Account.js").Account | undefined;
         autoSwap?: import("../internal/auto-swap.js").resolve.Value | undefined;
+        feeToken?: `0x${string}` | undefined;
         mode?: "pull" | "push" | undefined;
     }>;
 }, import("../../Method.js").Client<{

package/dist/tempo/internal/defaults.d.ts

@@ -37,6 +37,15 @@ export declare const machineToken: Readonly<{
  * runtimes should set `decimals` explicitly to match their token.
  */
 export declare const decimals = 6;
+/**
+ * Minimum remaining validity, in seconds, of a fee-sponsored transaction.
+ *
+ * Servers refuse to co-sign a sponsored transaction whose `validBefore` is
+ * closer than this, clients refuse to sign for a sponsored challenge that
+ * expires sooner, and servers refuse to issue a sponsored challenge that
+ * expires sooner after issuance.
+ */
+export declare const minRemainingValiditySeconds = 15;
 /** Default payment-channel escrow contract addresses per chain. */
 export declare const escrowContract: {
     readonly 4217: '0x33b901018174DDabE4841042ab76ba85D4e24f25';

package/dist/tempo/internal/defaults.js

@@ -37,6 +37,15 @@ export const machineToken = Object.freeze({
  * runtimes should set `decimals` explicitly to match their token.
  */
 export const decimals = 6;
+/**
+ * Minimum remaining validity, in seconds, of a fee-sponsored transaction.
+ *
+ * Servers refuse to co-sign a sponsored transaction whose `validBefore` is
+ * closer than this, clients refuse to sign for a sponsored challenge that
+ * expires sooner, and servers refuse to issue a sponsored challenge that
+ * expires sooner after issuance.
+ */
+export const minRemainingValiditySeconds = 15;
 /** Default payment-channel escrow contract addresses per chain. */
 export const escrowContract = {
     [chainId.mainnet]: '0x33b901018174DDabE4841042ab76ba85D4e24f25',

package/dist/tempo/internal/fee-payer.js

@@ -445,8 +445,8 @@ export function assertRemainingValidity(parameters) {
         return fail('fee-sponsored transaction must declare validBefore for the expiring nonce');
     if (validBefore <= Math.floor(now.getTime() / 1_000))
         fail('fee-sponsored transaction has already expired');
-    if (validBefore < Math.ceil(now.getTime() / 1_000) + 15)
-        fail('fee-sponsored transaction needs at least 15 seconds of remaining validity');
+    if (validBefore < Math.ceil(now.getTime() / 1_000) + defaults.minRemainingValiditySeconds)
+        fail(`fee-sponsored transaction needs at least ${defaults.minRemainingValiditySeconds} seconds of remaining validity`);
 }
 /** Validates sponsor fee policy limits for a fee-payer transaction. */
 export function assertTransactionPolicy(parameters) {

package/dist/tempo/server/Charge.js

@@ -350,7 +350,7 @@ export function charge(parameters = {}) {
             }
             : undefined,
         // TODO: dedupe `{charge,session}.request`
-        async request({ credential, request }) {
+        async request({ credential, expires, request }) {
             const chainId = await (async () => {
                 if (request.chainId)
                     return request.chainId;
@@ -385,6 +385,17 @@ export function charge(parameters = {}) {
                     return account ?? (remoteFeePayer ? true : undefined);
                 return account || remoteFeePayer ? true : undefined;
             })();
+            // Issued sponsored challenges must leave room for the fee payer's
+            // minimum remaining validity, or every credential for them is rejected.
+            // Zero-amount proofs and push-only routes never use the fee payer.
+            const modes = (request.supportedModes ?? supportedModes);
+            if (!credential &&
+                resolvedFeePayer &&
+                Number(request.amount) > 0 &&
+                (modes === undefined || modes.includes('pull')) &&
+                expires !== undefined &&
+                !(Date.parse(expires) - Date.now() >= defaults.minRemainingValiditySeconds * 1000))
+                throw new Error(`Sponsored charge challenges must expire at least ${defaults.minRemainingValiditySeconds} seconds after issuance.`);
             return {
                 ...request,
                 machineTokenEnabled: request.machineTokenEnabled || undefined,
@@ -1031,6 +1042,8 @@ const ambiguousErrorNames = new Set([
  * - JSON-RPC code `4`: the EIP-7966 timeout for a pooled, unconfirmed transaction.
  * - Messages containing the words "already known" or "known transaction": already
  *   pooled ("unknown transaction type" does not match).
+ * - Tempo's `ExpiringNonceReplay`: an expiring-nonce transaction with this hash was
+ *   already accepted, such as when a transport retries a send the node took.
  */
 function isAmbiguousBroadcastError(error) {
     for (let cause = error; cause; cause = cause.cause) {
@@ -1043,7 +1056,8 @@ function isAmbiguousBroadcastError(error) {
             return true;
         if (code === 4)
             return true;
-        if (typeof message === 'string' && /\balready ?known\b|\bknown transaction\b/i.test(message))
+        if (typeof message === 'string' &&
+            /\balready ?known\b|\bknown transaction\b|\bExpiringNonceReplay\b/i.test(message))
             return true;
     }
     return false;