mppx 0.17.1 → 0.17.4

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # mppx
 
+## 0.17.4
+
+### Patch Changes
+
+- fa22d95: Fixed `ChannelStore` replacing the immediate send that a close request written during a failed queue send scheduled with the 60-second retry, and resending failed settlements forever when `minUnsettledAmount` is `0n` and the deposit is under 10 raw units: the threshold is now at least 1.
+- 3e44f83: Fixed `ChannelStore` giving up on a channel during the server's cooperative-close marker, which left a payer close request merged into it unsent, and spending watchdog attempts on alarms set for a close marker that a failed close then cleared. `ChannelStore` now rejects non-finite or negative `retryMs`, `staleAfterMs` and `watchdogMs` and a `maxAttempts` that is not a positive integer.
+- d11a756: Added `mppx/cloudflare`: a `ChannelStore` Durable Object that stores Tempo session channels and sends them to a settlement queue by amount or staleness, with a watchdog; `channels()`, the store and reusable-channel lookup for `tempo.session()`; and `settle()`, the queue consumer that settles them on-chain.
+- 48d97fa: Fixed `mppx/cloudflare` settlement and channel lookup: a payer close request stamped at or before the server's own cooperative-close marker is now sent to the settlement queue once that marker can no longer land, with an alarm at the marker's end; and a lookup add skips a channel that no longer resumes, while a full lookup entry drops closed channels before an open one.
+- b964dc4: Fixed `mppx/cloudflare` settlement and channel lookup: the server's own cooperative-close marker (recorded in the new `pendingCloseAt` channel field) no longer queues an immediate settlement, and `settle()` waits while that close may still land; a new payer close request after an earlier one cleared is sent at once; and each lookup entry keeps up to 8 of the payer's open channels, so closing one leaves the others findable.
+- 8e812d3: Fixed `mppx/cloudflare`'s `channels()` lookup returning a channel opened with another operator for a challenge without one, which mppx verifies against the zero operator, and losing a matching channel behind eight newer ones with other operators: lookup entries are now keyed by operator too (`mppx:session-lookup:v3`), so channels written before resume again after their next write. Fixed `ChannelStore` replacing the immediate send that a close request written during a queue send scheduled with a later watchdog alarm.
+- 7255375: Fixed `mppx/cloudflare` so `channels()` skips a channel opened with another operator than the challenge's, `settle()` renews its settlement lease while a settlement runs, and `ChannelStore` resends a closing channel within 2 minutes so every attempt fits in the escrow's close grace period.
+- 4adc283: Fixed follow-ups in `Store.durableObject` replay shards and `mppx/cloudflare`. Replay shards kept their claims in a table named `mppx_replay_claims`, so the shard alarm no longer clears a subclass's own `replay_claims` table. `ChannelStore` sent a channel to the settlement queue at once on a close request or a threshold's worth of new vouchers, instead of waiting for the watchdog after a failed job. `channels()` no longer let a delayed lookup write for a closed channel replace the entry of a channel the payer can still resume, and its lookup skipped entries whose channel had closed.
+- a9b2cbc: Added `onWrite` and `alarm` hooks to `Store.DurableObjectStore`: a subclass sees every applied write with its previous and next values in one storage transaction with the write (so the hook's own writes commit with it, and a hook that throws rolls it back), and can schedule and handle alarms through the protected `storage`, `state` and `env`.
+- 0968d3f: Renamed `Store.DurableObjectStore`'s store operations to `storeGet`, `storePut`, `storeDelete`, `storeSwap` and `storeClaim`, so Workers RPC reaches them on Workers whose Durable Object stubs keep the legacy `get`, `put` and `delete` methods, and `fetch` no longer calls a subclass's own methods of those names. `Store.DurableObjectStore.rpc()` now keeps a subclass's static members.
+
+  Fixed `DurableObjectStore.isReplayShard()` to match a replay shard's whole object name, so an ordinary key that starts with `mppx:replay:` is not taken for a shard, and the base `alarm()` clears claims only in an object that holds them.
+
+- 5ebce56: Added `DurableObjectStore.isReplayShard()`, so a subclass skips its own work (in `alarm`, handlers or its constructor, by the object's name) in the replay shards of `Store.durableObject`'s `replayShards`, which are objects of the same class, and documented that values stored at a key don't block its sharded replay claims.
+- 56e0c8c: Added `replayShards` and `replayShardVersion` options to `Store.durableObject`: replay claims spread over a fixed number of SQLite-backed shard objects, each claimed with one SQL statement and cleared by an alarm once expired, instead of one Durable Object per claimed key.
+- c776057: Added `transport: 'rpc'` and `encoding: 'native'` options to `Store.durableObject`: the store calls the object's methods over Workers RPC (with a class from `Store.DurableObjectStore.rpc(DurableObject)`), and native encoding stores structured-clone values, so bigints stay intact and values a Durable Object wrote with `storage.put` read back.
+- 2f96b5b: Improved the internal SSE parser's throughput on line-dense `text/event-stream` bodies by scanning with `indexOf` instead of a global RegExp.
+- 94d1e36: Fixed `Store.DurableObjectStore`'s native compare-and-swap treating a length-tracking view of a resizable `ArrayBuffer` as equal to a fixed-length one.
+- 5ba7bf5: Fixed `Store.durableObject` native compare-and-swap to compare object keys, map entries and set members in order, compare sparse arrays by their own elements instead of scanning to their length, and tell resizable `ArrayBuffer`s apart.
+- fa22d95: Changed `Store.DurableObjectStore`'s native encoding to reject views of resizable `ArrayBuffer`s, as it rejects other values it cannot compare, instead of probing their length tracking with a copy of the whole buffer resized to its maximum on every compare-and-swap.
+- 8e2f7fe: Fixed `tempo.charge` with `waitForConfirmation: false` to throw `Errors.BroadcastOutcomeUnknownError` with the transaction hash after an ambiguous broadcast failure, instead of the raw RPC error. `stripe.recordPayment` now returns the PaymentIntent's Stripe status as `paymentIntentStatus`.
+- ca6cc56: Fixed `Store.durableObject` storing a key named like a replay shard (`mppx:replay:v<version>:<shard>`) in that shard's object, where `DurableObjectStore.isReplayShard()` then reported it as a shard. Such keys, and keys starting with `mppx:key:`, now live in an object named `mppx:key:<key>`, so values stored at them before are no longer found.
+- d631e07: Fixed `Store.DurableObjectStore.rpc()` throwing when a subclass shadows a static member or method that an ancestor made non-configurable.
+- ed12b58: Added `Errors.BroadcastOutcomeUnknownError`, which `tempo.charge` now throws with the transaction hash and `validBefore` when an ambiguous broadcast leaves no receipt, instead of rethrowing the RPC error (still its `cause`). Added `stripe.recordPayment` to record a settled payment as a Stripe PaymentIntent, idempotent per transaction hash.
+- f54a1c9: Added `Errors.PaymentSimulationError`, which wraps a failed fee-sponsored preflight simulation with its `phase` (`sender` or `sponsored`), `sender`, `feePayer` and `paymentToken`, so callers can tell a payer's insufficient balance from a sponsor's. Fixed the sponsored simulation dropping a zero `maxPriorityFeePerGas`, which broke a hosted fee payer's signature.
+- a89d5f5: Added Zone payments to the `tempo` charge method. A server lists the Zones it accepts with `zones: [3, 7]`, or accepts any Zone with `zones: true`. A client pays from a Zone balance with `zone`: it withdraws to the recipient with a challenge-bound memo, waits for the withdrawal to settle on Tempo, and sends a `zone` credential with the settlement transaction hash, which the server verifies.
+
+  If the wait fails, the client throws `Errors.ZoneSettlementPendingError` and resumes the same withdrawal when the challenge is retried.
+
+- 3f60dcc: Fixed `mppx validate` and paid CLI retries rejecting every mppx server's retry Challenge as changed: the comparison now ignores the per-issuance `_mppx_nonce` and `_mppx_identity` in `opaque`. The malformed-Credential probe now sends the `-H` headers and puts the Credential in the header the server's Challenge names.
+- 64d852c: Fixed `mppx validate` error-handling hints to name the Credential header the server's Challenge uses instead of always `Authorization`.
+- 9ba2807: Fixed Zone ID validation to reject IDs that alias another Zone's portal address.
+
+## 0.17.3
+
+### Patch Changes
+
+- f8852c3: Removed the `eventsource-parser` dependency. The MCP client protocol now reads the first event of a `text/event-stream` response with a small internal SSE parser.
+
+## 0.17.2
+
+### Patch Changes
+
+- 247dc02: Rendered nested problem-details fields (such as `details`) as JSON in the CLI's Payment Rejected output instead of `[object Object]`.
+- d87c8bb: Removed `@stripe/stripe-js` from `dependencies`. The Stripe HTML payment page bundles Stripe.js at build time, and the Stripe Elements option types in `stripe.charge`'s `html.elements` are now inlined, so the published types no longer import `@stripe/stripe-js`.
+- a384733: Added `Store.durableObject()` and `Store.DurableObjectStore`, an atomic store backed by Cloudflare Durable Objects (one object per key, compare-and-swap with jittered retries), for running `tempo.session()` and replay protection on Cloudflare Workers.
+- adaeef7: Fixed Tempo and Stripe server bundles always including their HTML payment page: the page now loads with a dynamic `import()` the first time it is rendered, and `html.content` also accepts an async loader.
+- 2060c5f: Bound automatic session signatures and stored channel reuse to the authorized HTTP origin. Applied `trustedTempoProofRealms` to session challenges and forwarded manager pins. Added `session({ origin })` for direct credentials that will be reused over HTTP; originless stored channels must be explicitly migrated or closed rather than silently rebound. Use separate channel stores per HTTP origin because each payment scope retains a single channel.
+
+  Preserved request swap policies for automatic session top-ups and payment suppression through identity wrappers. Kept MCP adapter approval and payer selection authoritative when global payment fetch is installed. Limited proxy request bodies, including free routes, to 10 MiB by default with a configurable `maxRequestBodySize`.
+
+  Required explicit origin trust for remote snapshot recovery and rejected opaque origins. Preserved explicit CLI closing of legacy channels through validated origin migration. Returned payment challenges before buffering unpaid uploads and rejected oversized tee branches without waiting for sibling cancellation.
+
+- 55a7b62: Credited prepaid SSE items that failed before delivery when their spend remained unsettled. Added an idempotent merchant reconciliation hook for declined or uncertain credits, preserving settled funds and delivered-item charges.
+
+  Automatic prepaid credits are opt-in with `sse: { autoCreditPrepaid: true, onRefundRequired }`; existing merchant refund handlers remain unchanged. Delivery obligations persist in channel state before a managed stream starts, with bounded records and idempotent credit retries. Refund jobs distinguish uncertain writes from definite failures and expose only finalized captured funds as externally refundable. HTTP close receipts accept spend reduced by credits while retaining authorization and scope validation.
+
+- 7a18dac: Fixed sponsored preflight simulation billing the sender's fee token. Tempo nodes recover the fee payer of an `eth_call` only from `feePayerSignature` and ignore a bare `feePayer` address, so the final simulation charged the sender, and payments failed with "insufficient fee token balance" when the sponsor picked a fee token the sender did not hold. The simulation now carries the sponsor's signature: hosted sponsors return it from `eth_fillTransaction` (`fillHostedFeePayerTransaction` now returns `feePayerSignature`), and local fee-payer accounts sign a simulation-only copy with the new `signFeePayerSimulation`, only after the sender simulation passes. The sender simulation now runs at the transaction's exact gas limit with zero fee fields and the fields that set its intrinsic gas, so a transaction whose gas is too low is rejected before broadcast without needing a sender fee balance. The local simulation-only copy adds up to `sponsoredSimulationGasBuffer` (10,000) gas, because a sponsored `eth_call` charges more gas than the mined transaction uses, clamped to the fee payer policy's `maxGas` and `maxTotalFee` (`sponsoredSimulationGas`). When the sponsored simulation runs without the full buffer (hosted signatures, or clamped padding), a failure that is only out of gas no longer rejects the payment; fee balance errors and reverts still do.
+- a4d7a8e: Added `Store.sql()`, an atomic store on SQL databases (single-statement compare-and-swap, no transactions needed, and replay claims in one statement), with `Store.postgres()` for `pg`, Neon, Vercel Postgres, Supabase and PGlite, `Store.sqlite()` for `node:sqlite`, `better-sqlite3` and `bun:sqlite`, and `Store.d1()` for Cloudflare D1.
+- 8be5d55: Fixed esbuild bundles including all of `zod/mini` by importing it as a namespace in `mppx`'s zod helpers, so unused validators tree-shake.
+
 ## 0.17.1
 
 ### Patch Changes

package/dist/Errors.d.ts

@@ -196,6 +196,100 @@ export declare namespace PaymentOutcomeUnknownError {
         transactionHash?: string | undefined;
     };
 }
+/**
+ * A server broadcast a payment transaction, the broadcast failed in a way that does not say whether
+ * the node accepted it, and no receipt appeared before settlement stopped polling. The transaction
+ * may still be included until `validBefore`.
+ *
+ * Settle it by looking up the receipt for `transactionHash`: once `validBefore` has passed, the
+ * transaction can no longer be included, so one lookup after it is final. This is not a
+ * `PaymentError`: HTTP handlers still answer with a generic 500 `InternalPaymentError`, whose
+ * `cause` is this error.
+ */
+export declare class BroadcastOutcomeUnknownError extends Error {
+    readonly name = "BroadcastOutcomeUnknownError";
+    /** Hash of the broadcast transaction, as it will appear on chain if it is included. */
+    readonly transactionHash: `0x${string}`;
+    /** Unix time in seconds after which the transaction can no longer be included, when it expires. */
+    readonly validBefore: number | undefined;
+    constructor(options: BroadcastOutcomeUnknownError.Options);
+}
+export declare namespace BroadcastOutcomeUnknownError {
+    type Options = {
+        /** The broadcast error that left the outcome unknown. */
+        cause?: unknown;
+        /** Hash of the broadcast transaction. */
+        transactionHash: `0x${string}`;
+        /** Unix time in seconds after which the transaction can no longer be included. */
+        validBefore?: number | undefined;
+    };
+}
+/**
+ * A pre-broadcast simulation of a fee-sponsored payment failed, so the payment was not broadcast.
+ *
+ * `phase` says which simulation failed: `sender` runs the sender's calls before sponsorship, and
+ * `sponsored` runs the final envelope billed to `feePayer`. Callers use it, with `sender`,
+ * `feePayer` and `paymentToken`, to tell a payer's insufficient balance from a sponsor's without
+ * matching node messages. The node's error is the `cause`. This is not a `PaymentError`: HTTP
+ * handlers still answer with a generic 500 `InternalPaymentError`, whose `cause` is this error.
+ */
+export declare class PaymentSimulationError extends Error {
+    readonly name = "PaymentSimulationError";
+    /** Fee payer the sponsored simulation billed. Set only in the `sponsored` phase. */
+    readonly feePayer: `0x${string}` | undefined;
+    /** TIP-20 token of a single `transfer` or `transferWithMemo` call, when the transaction is one. */
+    readonly paymentToken: `0x${string}` | undefined;
+    /** Simulation that failed. */
+    readonly phase: PaymentSimulationError.Phase;
+    /** Sender of the simulated transaction. */
+    readonly sender: `0x${string}` | undefined;
+    constructor(options: PaymentSimulationError.Options);
+}
+export declare namespace PaymentSimulationError {
+    /** `sender`: the sender's calls before sponsorship. `sponsored`: the final sponsored envelope. */
+    type Phase = 'sender' | 'sponsored';
+    type Options = {
+        /** The simulation error. */
+        cause?: unknown;
+        /** Fee payer of the sponsored simulation. */
+        feePayer?: `0x${string}` | undefined;
+        /** TIP-20 token of a single transfer call. */
+        paymentToken?: `0x${string}` | undefined;
+        /** Simulation that failed. */
+        phase: Phase;
+        /** Sender of the simulated transaction. */
+        sender?: `0x${string}` | undefined;
+    };
+}
+/**
+ * A client withdrew from a Zone to pay a challenge, but the withdrawal did not settle on Tempo
+ * before the client stopped waiting. The withdrawal cannot be undone and may still settle.
+ *
+ * Retry the same challenge with the same `tempo.charge` client to resume waiting without
+ * withdrawing again, or find the settlement with `senderTag` on the Zone's portal.
+ */
+export declare class ZoneSettlementPendingError extends Error {
+    readonly name = "ZoneSettlementPendingError";
+    /** ID of the challenge the withdrawal pays. */
+    readonly challengeId: string;
+    /** Sender tag of the withdrawal, as the portal's `WithdrawalProcessed` event carries it. */
+    readonly senderTag: `0x${string}`;
+    /** ID of the Zone the withdrawal left. */
+    readonly zoneId: number;
+    constructor(options: ZoneSettlementPendingError.Options);
+}
+export declare namespace ZoneSettlementPendingError {
+    type Options = {
+        /** The error that ended the wait. */
+        cause?: unknown;
+        /** ID of the challenge the withdrawal pays. */
+        challengeId: string;
+        /** Sender tag of the withdrawal. */
+        senderTag: `0x${string}`;
+        /** ID of the Zone the withdrawal left. */
+        zoneId: number;
+    };
+}
 /**
  * No credential was provided but payment is required.
  */

package/dist/Errors.js

@@ -160,6 +160,89 @@ export class PaymentOutcomeUnknownError extends PaymentError {
         this.transactionHash = transactionHash;
     }
 }
+/**
+ * A server broadcast a payment transaction, the broadcast failed in a way that does not say whether
+ * the node accepted it, and no receipt appeared before settlement stopped polling. The transaction
+ * may still be included until `validBefore`.
+ *
+ * Settle it by looking up the receipt for `transactionHash`: once `validBefore` has passed, the
+ * transaction can no longer be included, so one lookup after it is final. This is not a
+ * `PaymentError`: HTTP handlers still answer with a generic 500 `InternalPaymentError`, whose
+ * `cause` is this error.
+ */
+export class BroadcastOutcomeUnknownError extends Error {
+    name = 'BroadcastOutcomeUnknownError';
+    /** Hash of the broadcast transaction, as it will appear on chain if it is included. */
+    transactionHash;
+    /** Unix time in seconds after which the transaction can no longer be included, when it expires. */
+    validBefore;
+    constructor(options) {
+        const { cause, transactionHash, validBefore } = options;
+        super(`Broadcast outcome is unknown for transaction ${transactionHash}. Look up its receipt before retrying.`);
+        this.transactionHash = transactionHash;
+        this.validBefore = validBefore;
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        if (cause !== undefined)
+            Object.defineProperty(this, 'cause', { configurable: true, value: cause, writable: true });
+    }
+}
+/**
+ * A pre-broadcast simulation of a fee-sponsored payment failed, so the payment was not broadcast.
+ *
+ * `phase` says which simulation failed: `sender` runs the sender's calls before sponsorship, and
+ * `sponsored` runs the final envelope billed to `feePayer`. Callers use it, with `sender`,
+ * `feePayer` and `paymentToken`, to tell a payer's insufficient balance from a sponsor's without
+ * matching node messages. The node's error is the `cause`. This is not a `PaymentError`: HTTP
+ * handlers still answer with a generic 500 `InternalPaymentError`, whose `cause` is this error.
+ */
+export class PaymentSimulationError extends Error {
+    name = 'PaymentSimulationError';
+    /** Fee payer the sponsored simulation billed. Set only in the `sponsored` phase. */
+    feePayer;
+    /** TIP-20 token of a single `transfer` or `transferWithMemo` call, when the transaction is one. */
+    paymentToken;
+    /** Simulation that failed. */
+    phase;
+    /** Sender of the simulated transaction. */
+    sender;
+    constructor(options) {
+        const { cause, feePayer, paymentToken, phase, sender } = options;
+        super('Payment simulation failed');
+        this.feePayer = feePayer;
+        this.paymentToken = paymentToken;
+        this.phase = phase;
+        this.sender = sender;
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        if (cause !== undefined)
+            Object.defineProperty(this, 'cause', { configurable: true, value: cause, writable: true });
+    }
+}
+/**
+ * A client withdrew from a Zone to pay a challenge, but the withdrawal did not settle on Tempo
+ * before the client stopped waiting. The withdrawal cannot be undone and may still settle.
+ *
+ * Retry the same challenge with the same `tempo.charge` client to resume waiting without
+ * withdrawing again, or find the settlement with `senderTag` on the Zone's portal.
+ */
+export class ZoneSettlementPendingError extends Error {
+    name = 'ZoneSettlementPendingError';
+    /** ID of the challenge the withdrawal pays. */
+    challengeId;
+    /** Sender tag of the withdrawal, as the portal's `WithdrawalProcessed` event carries it. */
+    senderTag;
+    /** ID of the Zone the withdrawal left. */
+    zoneId;
+    constructor(options) {
+        const { cause, challengeId, senderTag, zoneId } = options;
+        super(`Zone ${zoneId} withdrawal ${senderTag} for challenge "${challengeId}" has not settled on Tempo yet. Retry the challenge to resume waiting instead of paying again.`);
+        this.challengeId = challengeId;
+        this.senderTag = senderTag;
+        this.zoneId = zoneId;
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        if (cause !== undefined)
+            Object.defineProperty(this, 'cause', { configurable: true, value: cause, writable: true });
+    }
+}
 /**
  * No credential was provided but payment is required.
  */