mppx 0.17.0 → 0.17.1

package/dist/proxy/internal/Replay.js

@@ -0,0 +1,257 @@
+import { Base64, Bytes, Hash } from 'ox';
+import * as Credential from '../../Credential.js';
+const keyPrefix = 'mppx:proxy:replay:';
+/** Applies defaults to replay options. */
+export function resolve(options) {
+    const ttl = options.ttl ?? 900_000;
+    // AbortSignal.timeout needs a positive integer that fits a 32-bit timer.
+    if (!Number.isSafeInteger(ttl) || ttl <= 0 || ttl > 2_147_483_647)
+        throw new RangeError('replay.ttl must be a positive integer number of milliseconds up to 2147483647.');
+    return {
+        maxAttempts: options.maxAttempts ?? 3,
+        maxBodySize: options.maxBodySize ?? 1_048_576,
+        maxRequestBodySize: options.maxRequestBodySize ?? 1_048_576,
+        retryAfter: options.retryAfter ?? 5,
+        store: options.store,
+        ttl,
+        waitUntil: options.waitUntil,
+    };
+}
+/** Returns the request's Payment credential header value, if it carries one. */
+export function credentialOf(request, headerNames = ['authorization']) {
+    // Only the headers the route's payment handler verifies can name a replay.
+    for (const name of headerNames) {
+        const header = request.headers.get(name);
+        const payment = header ? Credential.extractPaymentScheme(header) : null;
+        if (payment)
+            return payment;
+    }
+    return undefined;
+}
+/** Reads a request body, or returns null when it is larger than maxRequestBodySize. */
+export async function readBody(request, maxRequestBodySize) {
+    const length = Number(request.headers.get('content-length'));
+    if (Number.isFinite(length) && length > maxRequestBodySize)
+        return null;
+    if (!request.body)
+        return new Uint8Array();
+    return keep(request.body, maxRequestBodySize);
+}
+/** Derives the replay key from the credential and the exact request (origin, path, query, method, body) it paid for. */
+export function key(parameters) {
+    const bodyHash = Hash.sha256(parameters.body, { as: 'Hex' });
+    const input = JSON.stringify([
+        parameters.credential,
+        parameters.method.toUpperCase(),
+        parameters.target,
+        bodyHash,
+    ]);
+    return keyPrefix + Hash.sha256(Bytes.fromString(input), { as: 'Hex' }).slice(2);
+}
+/** Rebuilds a request around an already-read body, optionally with another abort signal. */
+export function withBody(request, body, signal, headers) {
+    const method = request.method.toUpperCase();
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    return new globalThis.Request(request.url, {
+        // An empty body stays absent, as on the original request: payment
+        // transports tell management requests apart by a missing body.
+        body: hasBody && body.byteLength > 0 ? body : null,
+        headers: headers ?? request.headers,
+        method: request.method,
+        redirect: request.redirect,
+        signal: signal ?? request.signal,
+    });
+}
+/** Looks up a delivery and, for a failed one, claims the next upstream attempt. */
+export async function lookup(replay, replayKey) {
+    const now = Date.now();
+    // Read first: only a failed delivery needs an atomic claim, so unknown
+    // credentials never cause a store write.
+    const seen = (await replay.store.get(replayKey));
+    if (!seen)
+        return { type: 'none' };
+    if (seen.expires > now && seen.status !== 'failed')
+        return { response: respond(replay, seen), type: 'respond' };
+    const result = await replay.store.update(replayKey, (current) => {
+        const record = current;
+        if (!record)
+            return { op: 'noop', result: { type: 'none' } };
+        if (record.expires <= now)
+            return { op: 'delete', result: { type: 'none' } };
+        if (record.status !== 'failed' || record.attempts >= replay.maxAttempts)
+            return { op: 'noop', result: record };
+        const attempts = record.attempts + 1;
+        return {
+            op: 'set',
+            value: { ...record, attempts, status: 'pending' },
+            result: {
+                attempts,
+                receipt: record.receipt,
+                requestHeaders: record.requestHeaders,
+                type: 'retry',
+            },
+        };
+    });
+    if ('type' in result)
+        return result;
+    return { response: respond(replay, result), type: 'respond' };
+}
+/** Builds the response for a recorded delivery that is not retried. */
+function respond(replay, record) {
+    if (record.status === 'complete')
+        return fromRecord(record);
+    if (record.status === 'delivered')
+        return Response.json({ error: 'The paid response was delivered and is not stored for replay.' }, { status: 410 });
+    if (record.status === 'pending')
+        return new Response(null, {
+            headers: { 'Retry-After': String(replay.retryAfter) },
+            status: 202,
+        });
+    return withReceiptHeader(Response.json({ error: 'The paid upstream request failed.' }, { status: 502 }), record.receipt);
+}
+/** Runs a paid upstream delivery detached from the client and records its outcome. */
+export async function deliver(parameters) {
+    const { applyReceipt, attempts, replay, replayKey, requestHeaders } = parameters;
+    // Outcomes are kept for ttl from when they are recorded, not from the start.
+    const expires = () => Date.now() + replay.ttl;
+    await record(replay, replayKey, {
+        attempts,
+        expires: expires(),
+        receipt: null,
+        requestHeaders,
+        status: 'pending',
+    });
+    let response;
+    try {
+        // ttl bounds the wait for the upstream to respond, not how long its body
+        // streams: a paid stream keeps going once it has started.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new DOMException('Replay ttl elapsed.', 'TimeoutError')), replay.ttl);
+        let upstream;
+        try {
+            upstream = await parameters.run(controller.signal);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        response = await applyReceipt(upstream);
+    }
+    catch {
+        const failed = await applyReceipt(Response.json({ error: 'The paid upstream request failed.' }, { status: 502 }));
+        await recordFailure(replay, replayKey, attempts, requestHeaders, expires(), failed.headers.get('Payment-Receipt'));
+        return failed;
+    }
+    const receipt = response.headers.get('Payment-Receipt');
+    if (response.status >= 500) {
+        await recordFailure(replay, replayKey, attempts, requestHeaders, expires(), receipt);
+        return response;
+    }
+    if (!response.body) {
+        await record(replay, replayKey, toRecord(response, new Uint8Array(), expires()));
+        return response;
+    }
+    if (/^text\/event-stream/i.test(response.headers.get('content-type') ?? '')) {
+        await record(replay, replayKey, { expires: expires(), status: 'delivered' });
+        return response;
+    }
+    // Keep a copy while the client reads the other branch, so a client that
+    // disconnects mid-body can still collect the response on retry.
+    const [client, kept] = response.body.tee();
+    const stored = keep(kept, replay.maxBodySize)
+        .then((body) => replay.store.put(replayKey, body
+        ? toRecord(response, body, expires())
+        : { expires: expires(), status: 'delivered' }), 
+    // The upstream body broke off: let the payer retry the delivery.
+    () => recordFailure(replay, replayKey, attempts, requestHeaders, expires(), receipt))
+        // A failed background write leaves the record pending until it expires.
+        .catch(() => { });
+    replay.waitUntil?.(stored);
+    return new Response(client, {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+    });
+}
+/** Reads a body branch up to maxBodySize, or returns null when it is larger. */
+async function keep(stream, maxBodySize) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBodySize) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+    const body = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+/**
+ * Writes a replay record without letting a store failure break the paid
+ * delivery: the payer still gets the upstream response, only replay is lost.
+ */
+async function record(replay, replayKey, value) {
+    try {
+        await replay.store.put(replayKey, value);
+    }
+    catch { }
+}
+async function recordFailure(replay, replayKey, attempts, requestHeaders, expires, receipt) {
+    await record(replay, replayKey, {
+        attempts,
+        expires,
+        receipt,
+        requestHeaders,
+        status: 'failed',
+    });
+}
+/** Adds a stored receipt to a response built for a retried delivery. */
+export function withReceiptHeader(response, receipt) {
+    if (!receipt)
+        return response;
+    const headers = new Headers(response.headers);
+    headers.set('Payment-Receipt', receipt);
+    headers.set('Cache-Control', withPrivateCacheControl(headers.get('Cache-Control')));
+    return new Response(response.body, {
+        headers,
+        status: response.status,
+        statusText: response.statusText,
+    });
+}
+function withPrivateCacheControl(value) {
+    if (!value)
+        return 'private';
+    const directives = value.split(',').map((directive) => directive.trim().toLowerCase());
+    if (directives.includes('private'))
+        return value;
+    return `${value}, private`;
+}
+function toRecord(response, body, expires) {
+    return {
+        body: Base64.fromBytes(body),
+        expires,
+        headers: [...response.headers.entries()],
+        responseStatus: response.status,
+        status: 'complete',
+        statusText: response.statusText,
+    };
+}
+function fromRecord(record) {
+    const nullBody = [101, 204, 205, 304].includes(record.responseStatus);
+    return new Response(nullBody ? null : Base64.toBytes(record.body), {
+        headers: record.headers,
+        status: record.responseStatus,
+        statusText: record.statusText,
+    });
+}
+//# sourceMappingURL=Replay.js.map

package/dist/server/Mppx.d.ts

@@ -414,6 +414,8 @@ type ConfiguredHandler<transport extends Transport.AnyTransport = Transport.Http
         _stableBinding?: Method.StableBindingFn<Method.Method> | undefined;
         /** The offer's payment-stage identity verifiers, if any. */
         _paymentIdentity?: readonly Identity.Verifier[] | undefined;
+        /** Whether the route requires identity verifiers (request or payment stage). */
+        _identity?: boolean | undefined;
         _transport: Transport.AnyTransport;
     };
 };

package/dist/server/Mppx.js

@@ -468,6 +468,7 @@ function createMethodFn(parameters) {
             ],
             _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
             _paymentIdentity: paymentVerifiers.length > 0 ? paymentVerifiers : undefined,
+            _identity: identity.length > 0,
             _stableBinding: stableBinding,
             _transport: transport,
         };
@@ -1916,11 +1917,11 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
         composed._internal = { offers, handlers: handlers, 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]);
 }
+/** Returns the flattened configured offers accepted by a handler. */
 function getConfiguredOffers(handler) {
     const internal = handler._internal;
     if (!internal)

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

@@ -21,6 +21,7 @@ export declare const validityWindowSeconds = 25;
 export type ChargeContext = {
     account?: Account.getResolver.Parameters['account'] | undefined;
     autoSwap?: AutoSwap.resolve.Value | undefined;
+    feeToken?: Address | undefined;
     mode?: Methods.ChargeMode | undefined;
 };
 /**
@@ -41,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";
@@ -192,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;
     }>;
 };
@@ -210,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

@@ -31,6 +31,7 @@ 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)),
 });
 /**
@@ -188,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) {

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/server/Charge.js

@@ -1042,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) {
@@ -1054,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;