mppx 0.13.4 → 0.13.5

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # mppx
 
+## 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/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']>>;