mppx 0.13.4 → 0.13.6

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # mppx
 
+## 0.13.6
+
+### Patch Changes
+
+- 82810df: Added `autoSwap.fallback` to Tempo charges. Setting `fallback: false` swaps only from `tokenIn`, as an allowlist, instead of also trying pathUSD and USDC afterwards.
+- 82810df: Added OUSD to the default Tempo auto-swap currencies, after pathUSD and USDC.
+- 0acc2bc: Fixed Tempo charge auto-swap finding no route for an access key whose authorization was not yet published. Balance and DEX quote reads no longer carry the client's account, which the node rejected with `KeyNotFound`.
+- 7827823: Bounded session management POSTs to 30 seconds so stalled endpoints cannot hold funding waiters indefinitely. Timed-out payments report an unknown outcome and ignore late responses.
+
+  Persisted uncertain top-up state in the channel store after dispatched management requests timed out, failed, or were cancelled and blocked new deposits, including from replacement managers. Callers must reconcile the pending transaction against trusted chain state before clearing that state.
+
+- 4de6876: Bounded payment authorization values to 64 KiB before scheme extraction and decoding.
+- 80f9a76: Rechecked sponsored subscription and session transaction deadlines before signing and submission. Aligned validity-window rounding and rejected maximum windows below the required 15 seconds.
+- 051510d: Fixed `compose()` dispatch for handlers without a static `scope`. Their challenges are scoped to the request's route, so dispatch now compares the credential's metadata with that scope merged in, instead of falling back to the first handler with the same method and intent.
+- 626afc6: Fixed `compose()` dispatching every `tempo/session` credential to the first session handler. Dispatch compared the credential with each handler's route request, which lacks the `chainId` and `sessionProtocol` the session request hook adds, so no handler matched; sessions offered in several currencies rejected all but the first with a currency mismatch.
+- f82decc: Sessions now read on-chain channel state concurrently with the stored channel when accepting a voucher, instead of after it. The forced on-chain refresh and error precedence are unchanged.
+- 7055666: Fixed manual streaming charges to commit before stream.charge() resolved, retaining charges when subsequent work was canceled or failed.
+- 3f95f89: Fixed the EVM CLI plugin to use the selected account when signing payments.
+- 3b18cd0: Paid session requests make fewer store round trips. Validating a voucher credential right before broadcasting it no longer reads the stored channel, since broadcasting checks it again. With `voucherStateMaxAge`, a voucher is checked against the stored channel inside the store update that accepts it, without a separate read. The new `chargeOnAcceptance` option charges request-priced content in that same update instead of a second update when the response is delivered.
+- 97eb961: Added `reusableChallenges` to `tempo.session()`. A session challenge then stays valid for later requests to the same route until it expires: it is bound to its route, currency, recipient and channel terms but not to the amount it quoted, and every request is charged its own price from the channel's accepted balance. Clients can send a voucher with a request instead of waiting for a `402`. Composed handlers with a stable binding are now also dispatched by the fields their route request defines, and with reusable challenges session SSE responses charge the verified route request's amount.
+- 22e5b42: Limited automatic swaps to the missing balance and bounded spending independently of DEX quotes. Added an explicit maxAmountIn budget for non-parity token pairs; defaults assumed 1:1 token units plus slippage. Sponsored charge validation accepted partial acquisition up to the payment amount.
+- 132a793: Stopped reusing cached relay receipts as new payment authorizations. Relay broadcasts now omit idempotency keys so reused credentials are rejected; applications should recover uncertain outcomes separately from executing protected operations.
+- 78d0a04: Serialized session-manager top-ups and refreshed the active deposit before subsequent funding decisions, preventing concurrent automatic requests from exceeding the configured deposit limit.
+- 9ad515a: Fixed Stripe-backed session offers to enforce the one-cent recording minimum before application offer policies.
+- d4dddfc: Checked on-chain escrow during managed SSE and WebSocket streams and stopped delivery when escrow closed or checks failed.
+- 13a9035: Added `voucherStateMaxAge` to `tempo.session()`. Vouchers within the deposit of on-chain state verified that recently are accepted without waiting for a fresh on-chain read, which finishes in the background and records a pending close for later vouchers. The verification time is persisted on the stored channel so every server instance can use it. The default `0` keeps reading on-chain state before every acceptance.
+
+## 0.13.5
+
+### Patch Changes
+
+- 19315c7: Bounded automatic MCP JSON and SSE payment-challenge inspection to 1 MiB while preserving the original response stream for callers.
+- 9da0e18: Removed retained native response bodies from manual payment event snapshots to prevent unbounded buffering while callers consume streams. Status and headers remained available; non-HTTP transport snapshots were unchanged.
+- 68381a4: Fixed Tempo charge `validBefore` to cover a fractional challenge expiry, so charge transactions stay valid for as long as their challenge.
+- ca6f04b: Exported `Attribution` from `mppx/tempo` so apps can encode, decode, and verify MPP attribution memos on TIP-20 transfers.
+- b085cae: Exposed the verified payer as `payer` on payment success contexts and per-method `onPaymentSuccess` hooks. Tempo charge and EVM charge validation now report the recovered payer address as `payer`.
+- 47beb31: Attached the original error as `cause` on `InternalPaymentError` so payment hooks can inspect unexpected failures, and added `CredentialReplayedError` (a `VerificationFailedError` subclass) for Tempo charge credentials whose payment already settled: replayed transaction hashes and proofs, claims held by a concurrent request, and settled transfers whose memo is bound to another challenge. The HTTP transport and session bootstrap answer it with a final 403 Problem Details response without a `WWW-Authenticate` challenge, so clients do not pay again; the problem type stays `verification-failed`.
+- 7271a85: Recovered confirmed Tempo charges when a synchronous broadcast returned an RPC error after inclusion.
+- 08fa745: Released Tempo charge transaction hash claims when settlement fails after a broadcast attempt, so retrying the same credential re-broadcasts and recovers the receipt instead of being rejected as a replay.
+- 1e692c3: Added `Errors.PaymentOutcomeUnknownError` and emitted it through `payment.failed` when a paid retry returns a 5xx response, carrying the challenge, credential, and the transaction hash for push and unsponsored Tempo charges. The response is still returned and never retried; when `payment.failed` is observed, its body is first buffered up to 64 KiB within 2 seconds so the connection is released, and a cut-off body is marked with `Mppx-Body-Truncated: true`. A thrown paid retry now passes the same error to `payment.failed` with the original error as `cause`, and the original error is still thrown.
+- 74533b0: Required at least 15 seconds of remaining validity before sponsoring and broadcasting transactions.
+- 94162a5: Fixed session settlements failing the charged request when a lagging RPC replica reverted the settle while preparing it (such as `ChannelNotFound` right after an open); `settle()` now retries reverted preparations.
+- 763a187: Shared default sponsor-budget storage across currency offers from tempo.charge and tempo.common, enforcing aggregate exposure limits without changing replay-store policy. Multi-process deployments still require a shared atomic store.
+- 68381a4: Shared one in-flight signing between concurrent Tempo charge requests for the same challenge and signer.
+- 61b4c10: Added `maxAmount` (display units, parsed with `decimals`) and `maxAtomicAmount` (base units) to the `tempo.charge()` client, matching the EVM charge client, plus a `currencies` allowlist that the caps require. Offers that exceed a cap or fail `currencies`, `expectedRecipients`, `expectedChainId`, or `allowedChainIds` are skipped during challenge selection and rejected before signing, and a `maxAmount` that would round is rejected.
+- 29855e8: Bounded synchronous Tempo charge broadcasts by a configurable `confirmationTimeoutMs` deadline (default 30 seconds). The broadcast may use at most two thirds of it, which leaves time for recovery. When the broadcast outcome is unknown, such as a timeout, a lost connection, or an "already known" response, the receipt is now polled until the deadline instead of failing while the transaction is still pending. Polling stops early once an expiring transaction is past its `validBefore`, followed by one final receipt lookup. Definitive RPC rejections still fail immediately.
+- 27213df: Added a one-time warning when Tempo `charge`, `session`, or `subscription` server methods fall back to an in-memory store, since replay protection backed by it only applies within a single instance.
+
 ## 0.13.4
 
 ### Patch Changes

package/dist/Credential.d.ts

@@ -24,6 +24,7 @@ export declare class InvalidCredentialEncodingError extends Error {
 }
 /**
  * Deserializes a Payment credential header value to a credential.
+ * Rejects values longer than 64 KiB before decoding.
  * Accepts the spec-compliant base64url `opaque` string shape and the legacy
  * object-shaped `opaque` form emitted by older mppx versions.
  *
@@ -106,6 +107,8 @@ export declare function serialize(credential: Credential): string;
  * Extracts the `Payment` scheme from an Authorization header value
  * that may contain multiple schemes (comma-separated per RFC 9110).
  *
+ * Values longer than 64 KiB are rejected before splitting.
+ *
  * @param header - The raw Authorization header value.
  * @returns The `Payment ...` scheme string, or `null` if not found.
  */

package/dist/Credential.js

@@ -2,6 +2,8 @@ import { Base64 } from 'ox';
 import * as Challenge from './Challenge.js';
 import * as Constants from './Constants.js';
 import * as PaymentRequest from './PaymentRequest.js';
+// Allow the echoed challenge and payment payload to expand during JSON/base64 encoding.
+const maxAuthorizationLength = 64 * 1024;
 export class MissingAuthorizationHeaderError extends Error {
     name = 'MissingAuthorizationHeaderError';
     constructor(header = Constants.Headers.authorization) {
@@ -22,6 +24,7 @@ export class InvalidCredentialEncodingError extends Error {
 }
 /**
  * Deserializes a Payment credential header value to a credential.
+ * Rejects values longer than 64 KiB before decoding.
  * Accepts the spec-compliant base64url `opaque` string shape and the legacy
  * object-shaped `opaque` form emitted by older mppx versions.
  *
@@ -36,6 +39,8 @@ export class InvalidCredentialEncodingError extends Error {
  * ```
  */
 export function deserialize(value) {
+    if (value.length > maxAuthorizationLength)
+        throw new InvalidCredentialEncodingError();
     const prefixMatch = value.match(new RegExp(`^${Constants.Schemes.payment}\\s+(.+)$`, 'i'));
     if (!prefixMatch?.[1])
         throw new MissingPaymentSchemeError();
@@ -162,10 +167,14 @@ export function serialize(credential) {
  * Extracts the `Payment` scheme from an Authorization header value
  * that may contain multiple schemes (comma-separated per RFC 9110).
  *
+ * Values longer than 64 KiB are rejected before splitting.
+ *
  * @param header - The raw Authorization header value.
  * @returns The `Payment ...` scheme string, or `null` if not found.
  */
 export function extractPaymentScheme(header) {
+    if (header.length > maxAuthorizationLength)
+        return null;
     const schemes = header.split(',').map((s) => s.trim());
     return schemes.find((s) => new RegExp(`^${Constants.Schemes.payment}\\s+`, 'i').test(s)) ?? null;
 }

package/dist/Errors.d.ts

@@ -1,3 +1,4 @@
+import type * as Challenge from './Challenge.js';
 /** Default hint messages for payment errors. */
 export declare const Hints: {
     readonly paymentRequired: 'Use a supported wallet to pay for this resource using one of the supported payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md';
@@ -24,6 +25,8 @@ export declare abstract class PaymentError extends Error {
 }
 export declare namespace PaymentError {
     type Options = {
+        /** Underlying error. Never serialized into Problem Details. */
+        cause?: unknown;
         details?: Record<string, unknown> | undefined;
     };
     type ProblemDetails = {
@@ -82,7 +85,7 @@ export declare namespace InvalidChallengeError {
  * Payment proof is invalid or verification failed.
  */
 export declare class VerificationFailedError extends PaymentError {
-    readonly name = "VerificationFailedError";
+    readonly name: string;
     readonly title = "Verification Failed";
     readonly type = "https://paymentauth.org/problems/verification-failed";
     constructor(options?: VerificationFailedError.Options);
@@ -95,15 +98,43 @@ export declare namespace VerificationFailedError {
         reason?: string;
     };
 }
+/**
+ * The payment behind a credential is already used or bound elsewhere: the
+ * credential was consumed by an earlier request, is being settled by a
+ * concurrent one, or its settled transfer is bound to another challenge.
+ *
+ * Answered with 403 and no challenge (the payment was valid, but policy
+ * denies access), since a fresh 402 challenge would invite an auto-paying
+ * client to pay again. The problem type stays `verification-failed`.
+ */
+export declare class CredentialReplayedError extends VerificationFailedError {
+    readonly name = "CredentialReplayedError";
+    readonly status = 403;
+    constructor(options?: CredentialReplayedError.Options);
+}
+export declare namespace CredentialReplayedError {
+    type Options = {
+        /** Reason the credential was rejected (e.g., "Transaction hash has already been used"). */
+        reason?: string;
+    };
+}
 /**
  * Payment processing failed because of an unexpected internal error.
+ *
+ * The response stays generic; the original error is only available on `cause`.
  */
 export declare class InternalPaymentError extends PaymentError {
     readonly name = "InternalPaymentError";
     readonly title = "Internal Payment Error";
     readonly status = 500;
     readonly type = "https://paymentauth.org/problems/internal-payment-error";
-    constructor();
+    constructor(options?: InternalPaymentError.Options);
+}
+export declare namespace InternalPaymentError {
+    type Options = {
+        /** Original error, for server-side hooks and logging. Never sent to clients. */
+        cause?: unknown;
+    };
 }
 /**
  * Payment requires additional action (e.g., 3DS authentication).
@@ -135,6 +166,36 @@ export declare namespace PaymentExpiredError {
         expires?: string;
     };
 }
+/**
+ * A credential was sent, but the payment result could not be confirmed.
+ *
+ * Reconcile with `credential` (and `transactionHash` when the method can derive it)
+ * instead of retrying, which could pay twice.
+ */
+export declare class PaymentOutcomeUnknownError extends PaymentError {
+    readonly name = "PaymentOutcomeUnknownError";
+    readonly title = "Payment Outcome Unknown";
+    readonly type = "https://paymentauth.org/problems/payment-outcome-unknown";
+    /** Challenge the credential paid for. */
+    readonly challenge: Challenge.Challenge;
+    /** Serialized credential sent with the paid request. */
+    readonly credential: string;
+    /** On-chain hash the payment will have if it settled, when derivable from the credential. */
+    readonly transactionHash: string | undefined;
+    constructor(options: PaymentOutcomeUnknownError.Options);
+}
+export declare namespace PaymentOutcomeUnknownError {
+    type Options = {
+        /** Error thrown by the paid request, when it failed without a response. */
+        cause?: unknown;
+        /** Challenge the credential paid for. */
+        challenge: Challenge.Challenge;
+        /** Serialized credential sent with the paid request. */
+        credential: string;
+        /** On-chain hash the payment will have if it settled. */
+        transactionHash?: string | undefined;
+    };
+}
 /**
  * No credential was provided but payment is required.
  */

package/dist/Errors.js

@@ -17,6 +17,13 @@ export class PaymentError extends Error {
     constructor(message, options = {}) {
         super(message);
         this.details = options.details;
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        if (options.cause !== undefined)
+            Object.defineProperty(this, 'cause', {
+                configurable: true,
+                value: options.cause,
+                writable: true,
+            });
     }
     /** Converts the error to RFC 9457 Problem Details format. */
     toProblemDetails(challengeId) {
@@ -74,16 +81,35 @@ export class VerificationFailedError extends PaymentError {
         });
     }
 }
+/**
+ * The payment behind a credential is already used or bound elsewhere: the
+ * credential was consumed by an earlier request, is being settled by a
+ * concurrent one, or its settled transfer is bound to another challenge.
+ *
+ * Answered with 403 and no challenge (the payment was valid, but policy
+ * denies access), since a fresh 402 challenge would invite an auto-paying
+ * client to pay again. The problem type stays `verification-failed`.
+ */
+export class CredentialReplayedError extends VerificationFailedError {
+    name = 'CredentialReplayedError';
+    status = 403;
+    constructor(options = {}) {
+        const { reason = 'Credential has already been used' } = options;
+        super({ reason });
+    }
+}
 /**
  * Payment processing failed because of an unexpected internal error.
+ *
+ * The response stays generic; the original error is only available on `cause`.
  */
 export class InternalPaymentError extends PaymentError {
     name = 'InternalPaymentError';
     title = 'Internal Payment Error';
     status = 500;
     type = 'https://paymentauth.org/problems/internal-payment-error';
-    constructor() {
-        super('An internal payment error occurred.');
+    constructor(options = {}) {
+        super('An internal payment error occurred.', { cause: options.cause });
     }
 }
 /**
@@ -110,6 +136,30 @@ export class PaymentExpiredError extends PaymentError {
         super(expires ? `Payment expired at ${expires}.` : 'Payment has expired.');
     }
 }
+/**
+ * A credential was sent, but the payment result could not be confirmed.
+ *
+ * Reconcile with `credential` (and `transactionHash` when the method can derive it)
+ * instead of retrying, which could pay twice.
+ */
+export class PaymentOutcomeUnknownError extends PaymentError {
+    name = 'PaymentOutcomeUnknownError';
+    title = 'Payment Outcome Unknown';
+    type = 'https://paymentauth.org/problems/payment-outcome-unknown';
+    /** Challenge the credential paid for. */
+    challenge;
+    /** Serialized credential sent with the paid request. */
+    credential;
+    /** On-chain hash the payment will have if it settled, when derivable from the credential. */
+    transactionHash;
+    constructor(options) {
+        const { cause, challenge, credential, transactionHash } = options;
+        super(`Payment outcome is unknown after sending a credential for challenge "${challenge.id}". Do not blindly retry.`, { cause });
+        this.challenge = challenge;
+        this.credential = credential;
+        this.transactionHash = transactionHash;
+    }
+}
 /**
  * No credential was provided but payment is required.
  */

package/dist/Method.d.ts

@@ -127,6 +127,14 @@ export type Validation<method extends Method = Method, details = unknown> = Read
     intent: method['intent'];
     /** The validated payment method, repeated for convenient dispatch. */
     method: method['name'];
+    /**
+     * Payer identity established by method-specific validation, when the method
+     * can determine one (for example, the Tempo address that sent the payment).
+     *
+     * Unlike `source`, this is derived from the verified credential payload.
+     * Its format is method-specific.
+     */
+    payer?: string | undefined;
     /**
      * The validated method request after the method's schema transforms.
      *
@@ -191,6 +199,8 @@ export type OnPaymentSuccessFn<method extends Method> = (parameters: {
     /** Challenge associated with the successful payment. */
     challenge?: DeepReadonly<Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>> | undefined;
     input?: globalThis.Request;
+    /** Payer identity verified by the method, when available. See {@link Validation.payer}. */
+    payer?: string | undefined;
     receipt: DeepReadonly<Receipt.Receipt>;
     /** Canonical payment request included in the challenge. */
     request: DeepReadonly<z.output<method['schema']['request']>>;