mppx 0.16.0 → 0.17.0

package/dist/cli/validate/payment.js

@@ -740,33 +740,57 @@ export function captureEventStream(fetch) {
             const response = await fetch(input, init);
             if (!response.body ||
                 !isEventStream(response) ||
-                response.headers.has(Constants.Headers.paymentReceipt))
+                response.headers.get(Constants.Headers.paymentReceipt))
                 return response;
             // Session management requests (such as mid-stream voucher posts) share this fetch, so a
             // later stream without a receipt must not discard one already seen.
             receipt ??= null;
             const decoder = new TextDecoder();
-            let pending = '';
+            // Normalized pieces of the current partial event, joined only when the event ends, so a
+            // long event costs linear time. A CR that may start a CRLF is held apart.
+            let parts = [];
+            let size = 0;
+            let heldCr = false;
             // Set after an oversized event is dropped, until its end, so its remaining lines are
             // never parsed as an event of their own.
             let skipping = false;
             const scan = (text, done) => {
-                pending += text;
-                // Keep a trailing CR: the next chunk may complete a CRLF.
-                const end = done || !pending.endsWith('\r') ? pending.length : pending.length - 1;
-                const events = pending
-                    .slice(0, end)
-                    .replace(/\r\n|\r/g, '\n')
-                    .split('\n\n');
-                const rest = done ? '' : (events.pop() ?? '');
-                if (skipping && (events.length > 0 || done)) {
+                let chunk = heldCr ? `\r${text}` : text;
+                heldCr = !done && chunk.endsWith('\r');
+                if (heldCr)
+                    chunk = chunk.slice(0, -1);
+                let rest = chunk.replace(/\r\n|\r/g, '\n');
+                const events = [];
+                // A boundary split across chunks: the partial event ends in a newline and this text starts with one.
+                if (rest.startsWith('\n') && parts.at(-1)?.endsWith('\n')) {
+                    events.push(parts.join('').slice(0, -1));
+                    parts = [];
+                    size = 0;
+                    rest = rest.slice(1);
+                }
+                for (let index = rest.indexOf('\n\n'); index !== -1; index = rest.indexOf('\n\n')) {
+                    events.push(parts.join('') + rest.slice(0, index));
+                    parts = [];
+                    size = 0;
+                    rest = rest.slice(index + 2);
+                }
+                if (rest) {
+                    parts.push(rest);
+                    size += rest.length;
+                }
+                if (done) {
+                    events.push(parts.join(''));
+                    parts = [];
+                    size = 0;
+                }
+                if (skipping && events.length > 0) {
                     events.shift();
                     skipping = false;
                 }
-                pending = rest + pending.slice(end);
-                if (pending.length > maxPendingEventBytes) {
-                    // Keep a trailing line ending: it may be the first half of the event's boundary.
-                    pending = /[\r\n]*$/.exec(pending)?.[0] ?? '';
+                if (size > maxPendingEventBytes) {
+                    // Keep a trailing newline: it may be the first half of the event's boundary.
+                    parts = parts.at(-1)?.endsWith('\n') ? ['\n'] : [];
+                    size = parts.length;
                     skipping = true;
                 }
                 for (const raw of events) {

package/dist/client/internal/protocols/Mpp.js

@@ -5,8 +5,11 @@ import { paymentRequiredStatus, setCredentialHeader } from './Shared.js';
 export function mpp() {
     return {
         getChallenges(response) {
+            const header = response.headers.get(Constants.Headers.wwwAuthenticate);
+            // A 402 without a Payment challenge (such as `WWW-Authenticate: X402`) is left to other protocols.
             if (response.status !== paymentRequiredStatus ||
-                !response.headers.has(Constants.Headers.wwwAuthenticate))
+                !header ||
+                !Challenge.hasPaymentScheme(header))
                 return [];
             return Challenge.fromResponseList(response);
         },

package/dist/identity/Client.js

@@ -57,7 +57,7 @@ export function from(provers) {
                     continue;
                 const copy = response.clone();
                 copies.push(copy);
-                if (await prover.retry(copy, context))
+                if (await prover.retry(copy))
                     retry = true;
             }
             if (!retry) {
@@ -69,11 +69,11 @@ export function from(provers) {
         },
         async challenge(response, context, url) {
             for (const prover of inScope(url)) {
-                if (!prover.retry)
+                if (!prover.prepare)
                     continue;
                 const copy = response.clone();
                 try {
-                    await prover.retry(copy, context);
+                    await prover.prepare(copy, context);
                 }
                 finally {
                     release([copy]);

package/dist/identity/Server.d.ts

@@ -35,6 +35,19 @@ export type Outcome = {
  * when several handlers evaluate the same request.
  */
 export declare function verify(request: Request, verifiers: readonly Types.Verifier[], context?: Types.Context): Promise<Outcome>;
+/**
+ * Collects the challenge headers of payment-stage verifiers for one 402.
+ *
+ * Each verifier's hook runs at most once per request and nonce, so every offer
+ * in a composed 402 carries the same challenge. @internal
+ */
+export declare function challenge(request: Request, verifiers: readonly Types.Verifier[], nonce: string): Promise<Headers>;
+/**
+ * Returns the identity nonce for every 402 issued on one request.
+ *
+ * Composed routes call each offer with the same request, so all offers share it. @internal
+ */
+export declare function nonceFor(request: Request, create: () => string): string;
 /** Builds the rejection response for a failed request-stage outcome. @internal */
 export declare function toResponse(outcome: Exclude<Outcome, {
     status: 'valid';

package/dist/identity/Server.js

@@ -90,6 +90,48 @@ export async function verify(request, verifiers, context = {}) {
         reason: missing.reason ?? 'Identity verification is required.',
     };
 }
+/**
+ * Collects the challenge headers of payment-stage verifiers for one 402.
+ *
+ * Each verifier's hook runs at most once per request and nonce, so every offer
+ * in a composed 402 carries the same challenge. @internal
+ */
+export async function challenge(request, verifiers, nonce) {
+    const headers = new Headers();
+    for (const verifier of verifiers) {
+        for (const member of leaves(verifier)) {
+            if (!member.challenge)
+                continue;
+            let byVerifier = challenges.get(request);
+            if (!byVerifier)
+                challenges.set(request, (byVerifier = new Map()));
+            let byNonce = byVerifier.get(member);
+            if (!byNonce)
+                byVerifier.set(member, (byNonce = new Map()));
+            let result = byNonce.get(nonce);
+            if (!result) {
+                result = Promise.resolve(member.challenge(request, { nonce }));
+                byNonce.set(nonce, result);
+            }
+            const init = await result;
+            if (init)
+                for (const [name, value] of new Headers(init))
+                    headers.append(name, value);
+        }
+    }
+    return headers;
+}
+/**
+ * Returns the identity nonce for every 402 issued on one request.
+ *
+ * Composed routes call each offer with the same request, so all offers share it. @internal
+ */
+export function nonceFor(request, create) {
+    let nonce = nonces.get(request);
+    if (!nonce)
+        nonces.set(request, (nonce = create()));
+    return nonce;
+}
 /** Builds the rejection response for a failed request-stage outcome. @internal */
 export function toResponse(outcome) {
     const headers = new Headers(outcome.headers);
@@ -112,6 +154,13 @@ export function stageOf(verifier) {
         throw new TypeError(`Unknown identity verifier stage "${String(stage)}".`);
     return stage;
 }
+/** Returns a verifier and, through `anyOf`, every member it wraps. */
+function leaves(verifier) {
+    const nested = verifier[members];
+    return nested ? nested.flatMap(leaves) : [verifier];
+}
+const nonces = new WeakMap();
+const challenges = new WeakMap();
 const cache = new WeakMap();
 function run(verifier, request, context) {
     let byVerifier = cache.get(request);
@@ -121,7 +170,7 @@ function run(verifier, request, context) {
     if (!byContext)
         byVerifier.set(verifier, (byContext = new Map()));
     // Decisions can depend on the credential, so each credential object gets its own entry.
-    const key = context.challenge?.id ?? '';
+    const key = `${context.challenge?.id ?? ''}|${context.nonce ?? ''}`;
     let byCredential = byContext.get(key);
     if (!byCredential)
         byContext.set(key, (byCredential = new Map()));

package/dist/identity/Types.d.ts

@@ -5,23 +5,34 @@ import type { MaybePromise } from '../internal/types.js';
  * When a verifier runs on the server.
  *
  * `request` verifiers run before any payment challenge is issued and reject
- * the request with their own status code. `payment` verifiers run when a
- * challenge is issued (to add their own challenge headers to the 402) and
- * again on the paid retry, before the credential is settled.
+ * the request with their own status code. `payment` verifiers add their own
+ * challenge headers to the 402 (through `challenge`) and run on the paid
+ * retry, before the credential is settled.
  */
 export type Stage = 'request' | 'payment';
 /**
  * Payment state passed to verifiers and provers.
  *
  * Request-stage verifiers receive an empty context. Payment-stage verifiers
- * receive the challenge being issued, or the challenge and credential being
- * answered on the paid retry.
+ * receive the answered challenge, its credential and the 402's identity nonce.
  */
 export type Context = {
-    /** The MPP challenge being issued or answered. */
+    /** The MPP challenge being answered (or, for provers, selected). */
     challenge?: Challenge.Challenge | undefined;
     /** The payment credential submitted with the request. */
     credential?: Credential.Credential | undefined;
+    /**
+     * The identity nonce of the 402 being answered.
+     *
+     * Every payment offer in one 402 carries the same HMAC-bound nonce, so a proof
+     * bound to it is bound to that 402 whichever offer the client pays.
+     */
+    nonce?: string | undefined;
+};
+/** Context passed to a payment-stage verifier's `challenge` hook. */
+export type ChallengeContext = {
+    /** The identity nonce shared by every payment offer in the 402. Bind the proof request to it. */
+    nonce: string;
 };
 /**
  * The outcome of one identity verifier.
@@ -54,6 +65,12 @@ export type Verification<value = unknown> = {
 export type Verifier<value = unknown> = {
     /** When the verifier runs. @default 'request' */
     stage?: Stage | undefined;
+    /**
+     * Returns the protocol's challenge headers to add to a 402, such as a proof request.
+     *
+     * Payment stage only. Runs once per 402, however many payment offers it carries.
+     */
+    challenge?: ((request: Request, context: ChallengeContext) => MaybePromise<HeadersInit | undefined>) | undefined;
     /** Returns the protocol's verification outcome for the request. */
     verify: (request: Request, context: Context) => MaybePromise<Verification<value>>;
 };
@@ -80,11 +97,16 @@ export type Prover = {
     /** Returns a new request carrying the protocol's identity material. */
     prove: (request: Request, context: ProveContext) => MaybePromise<Request>;
     /**
-     * Inspects a rejected or 402 response and prepares a proof for the next attempt.
+     * Prepares a proof from a 402 before the payment retry, such as answering its proof request.
      *
-     * Return `true` to resend a rejected (non-402) request once. On a 402 the
-     * context carries the selected challenge and the payment retry always follows.
+     * The context carries the selected challenge; `prove` receives the same challenge
+     * on the paid retry.
+     */
+    prepare?: ((response: Response, context: Context) => MaybePromise<void>) | undefined;
+    /**
+     * Inspects a rejected (non-402) response. Return `true` to prove and resend the
+     * request once. Paid attempts are never resent.
      */
-    retry?: ((response: Response, context: Context) => MaybePromise<boolean | undefined>) | undefined;
+    retry?: ((response: Response) => MaybePromise<boolean | undefined>) | undefined;
 };
 //# sourceMappingURL=Types.d.ts.map

package/dist/internal/version.d.ts

@@ -1,5 +1,5 @@
 /** Current mppx package version. */
-export declare const version = "0.16.0";
+export declare const version = "0.17.0";
 /** Canonical SDK identifier for this mppx release. */
-export declare const sdkIdentifier = "mppx/0.16.0";
+export declare const sdkIdentifier = "mppx/0.17.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/internal/version.js

@@ -1,6 +1,6 @@
 // Generated by scripts/sync-version.ts.
 /** Current mppx package version. */
-export const version = '0.16.0';
+export const version = '0.17.0';
 /** Canonical SDK identifier for this mppx release. */
 export const sdkIdentifier = `mppx/${version}`;
 //# sourceMappingURL=version.js.map

package/dist/server/Mppx.d.ts

@@ -412,8 +412,8 @@ type ConfiguredHandler<transport extends Transport.AnyTransport = Transport.Http
         scope?: string | undefined;
         _canonicalRequest: Record<string, unknown>;
         _stableBinding?: Method.StableBindingFn<Method.Method> | undefined;
-        /** Whether the offer requires payment-stage identity. */
-        _paymentIdentity?: boolean | undefined;
+        /** The offer's payment-stage identity verifiers, if any. */
+        _paymentIdentity?: readonly Identity.Verifier[] | undefined;
         _transport: Transport.AnyTransport;
     };
 };

package/dist/server/Mppx.js

@@ -467,7 +467,7 @@ function createMethodFn(parameters) {
                 ]),
             ],
             _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
-            _paymentIdentity: paymentVerifiers.length > 0,
+            _paymentIdentity: paymentVerifiers.length > 0 ? paymentVerifiers : undefined,
             _stableBinding: stableBinding,
             _transport: transport,
         };
@@ -500,6 +500,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 +546,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 +561,7 @@ function createMethodFn(parameters) {
                             statusText: response.statusText,
                         });
                         identityChallenges.set(response, identityHeaders);
+                        paymentChallenges.set(response, paymentChallenge);
                     }
                 }
                 if (isIssuedChallengeResponse(response))
@@ -594,7 +596,7 @@ function createMethodFn(parameters) {
                 description,
                 expires,
                 header: credentialHeader,
-                meta: effectiveMeta,
+                meta: challengeMeta,
                 method,
                 realm,
                 request: parameters.request,
@@ -609,7 +611,7 @@ function createMethodFn(parameters) {
                     description,
                     expires,
                     header: credentialHeader,
-                    meta: effectiveMeta,
+                    meta: challengeMeta,
                     method,
                     realm,
                     routeRequest: rest,
@@ -897,6 +899,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 +1351,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 +1592,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 +1656,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 +1830,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 +1847,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 +1888,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 +1908,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);
@@ -1896,6 +1917,10 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
     return composed;
 }
 /** Returns the flattened configured offers accepted by a handler. */
+/** 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]);
+}
 function getConfiguredOffers(handler) {
     const internal = handler._internal;
     if (!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,6 +6,17 @@ 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;

package/dist/tempo/client/Charge.js

@@ -17,6 +17,17 @@ 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()),
@@ -199,7 +210,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 +247,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 +279,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/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',