mppx 0.13.4 → 0.13.6

package/dist/tempo/session/server/Session.js

@@ -13,24 +13,33 @@ import * as Errors from '../../../Errors.js';
 import * as Expires from '../../../Expires.js';
 import * as Method from '../../../Method.js';
 import * as ChallengeMeta from '../../../server/internal/challengeMeta.js';
-import * as Store from '../../../Store.js';
 import * as Client from '../../../viem/Client.js';
 import * as Account from '../../internal/account.js';
 import * as defaults from '../../internal/defaults.js';
 import * as Methods from '../../Methods.js';
 import * as ChargeServer from '../../server/Charge.js';
+import { fallbackStore } from '../../server/internal/fallback-store.js';
 import * as Transport from '../../server/internal/transport.js';
+import * as Chain from '../precompile/Chain.js';
 import { tip20ChannelEscrow } from '../precompile/Protocol.js';
 import { deserializeSnapshot as deserializeSessionSnapshot, serializeSnapshot as serializeSessionSnapshot, } from '../Snapshot.js';
 import * as ChannelStore from './ChannelStore.js';
 import { broadcastCredentialPayload, validateCredentialPayload } from './CredentialVerification.js';
-import { requireSessionCredentialPayload } from './CredentialVerification.js';
+import { requireSessionCredentialPayload, validateChannelState } from './CredentialVerification.js';
 import { resolveCredentialVerificationContext, resolveSessionChannelId, resolveSessionSnapshot, resolveSessionPaymentRequest, } from './RequestState.js';
 import { respondToSessionCredential } from './RequestState.js';
-import { applyVerifiedHttpAccounting, chargeSessionChannel, shouldApplyVerifiedHttpAccounting, } from './Settlement.js';
+import { applyVerifiedHttpAccounting, chargeSessionChannel, shouldApplyVerifiedHttpAccounting, shouldChargeVoucherOnAcceptance, } from './Settlement.js';
 import { ignoreRetryableSettlementFailure, isSettlementDue, maybeSettleScheduled, reportSessionSettlementFailure, } from './Settlement.js';
 import { resolveSettlementSchedule, } from './Settlement.js';
 import * as Ws from './Ws.js';
+const streamVerifiers = new WeakMap();
+/** @internal Reuses a method's escrow verifier when composing shared currency helpers. */
+export function verifyStream(method, channelId) {
+    const verify = streamVerifiers.get(method);
+    if (!verify)
+        throw new Error('Session stream verifier is not configured');
+    return verify(channelId);
+}
 export { settle, settleBatch } from './Settlement.js';
 function deriveServerDefaults(values) {
     // `Method.toServer()` models defaults from request input fields. Tempo session
@@ -66,17 +75,14 @@ function createBootstrapChallenge(parameters) {
     });
 }
 function respondBootstrapChallenge(challenge, error) {
-    const headers = new Headers({
-        [Constants.Headers.wwwAuthenticate]: Challenge.serialize(challenge),
-        'Cache-Control': 'no-store',
-    });
+    const headers = new Headers({ 'Cache-Control': 'no-store' });
+    // A 403 is final: omit the challenge, as `Transport.http()` does.
+    if (error?.status !== 403)
+        headers.set(Constants.Headers.wwwAuthenticate, Challenge.serialize(challenge));
     if (!error)
         return new Response(null, { status: 402, headers });
     headers.set('Content-Type', 'application/problem+json');
-    return new Response(JSON.stringify(error.toProblemDetails(challenge.id)), {
-        status: error.status,
-        headers,
-    });
+    return new Response(JSON.stringify(error.toProblemDetails(error.status === 403 ? undefined : challenge.id)), { status: error.status, headers });
 }
 function assertBootstrapChallengeMatches(expected, actual) {
     if (actual.method !== Constants.Methods.tempo || actual.intent !== Constants.Intents.charge)
@@ -164,7 +170,9 @@ async function handleBootstrapPreflight(parameters) {
         });
     }
     catch (error) {
-        return respondBootstrapChallenge(challenge, error instanceof Errors.PaymentError ? error : new Errors.InternalPaymentError());
+        return respondBootstrapChallenge(challenge, error instanceof Errors.PaymentError
+            ? error
+            : new Errors.InternalPaymentError({ cause: error }));
     }
     const channelId = await resolveSessionChannelId({
         capturedRequest: parameters.capturedRequest,
@@ -192,10 +200,23 @@ async function handleBootstrapPreflight(parameters) {
     }
     return new Response(null, { status: 204, headers });
 }
+/** Binds a reusable session challenge to its route and channel terms but not to its quoted amount. */
+const reusableSessionBinding = (request) => {
+    const { methodDetails } = request;
+    return {
+        chainId: methodDetails.chainId,
+        currency: request.currency,
+        escrowContract: methodDetails.escrowContract,
+        operator: methodDetails.operator,
+        recipient: request.recipient,
+        sessionProtocol: methodDetails[Constants.MethodDetailKeys.sessionProtocol],
+        unitType: request.unitType,
+    };
+};
 /** Creates a server-side TIP20EscrowChannel precompile session payment method. */
 export function session(p) {
     const parameters = p;
-    const { amount, channelStateTtl = 5_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, operator, store: rawStore = Store.memory(), suggestedDeposit, unitType, } = parameters;
+    const { amount, channelStateTtl = 5_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, operator, store: rawStore = fallbackStore('tempo.session'), suggestedDeposit, unitType, } = parameters;
     const settlementSchedule = resolveSettlementSchedule(parameters.settlementSchedule, decimals);
     const onSessionSettlement = parameters.onSessionSettlement;
     const onSessionSettlementFailure = parameters.onSessionSettlementFailure;
@@ -237,8 +258,33 @@ export function session(p) {
     // A failed scheduled settlement is reported and retried by the next one; the charged request
     // stays served because the payer's voucher already covers the charge.
     const settleCharged = (channel) => settleScheduled(channel).catch(ignoreRetryableSettlementFailure);
+    // Stream checks have a bounded TTL even when callers disable validation caching.
+    // Cache only successful reads; RPC failures must stop delivery.
+    const beforeStreamCharge = async (channelId) => {
+        channelId = ChannelStore.normalizeChannelId(channelId);
+        const channel = await store.getChannel(channelId);
+        if (!channel || channel.finalized || channel.closeRequestedAt !== 0n)
+            throw new Errors.ChannelClosedError({ reason: 'stream channel is closed' });
+        const now = Date.now();
+        const ttl = Math.min(Math.max(channelStateTtl, 0), 5_000);
+        const lastVerified = lastOnChainVerified.get(channelId);
+        if (lastVerified !== undefined && now >= lastVerified && now - lastVerified < ttl)
+            return;
+        let state;
+        try {
+            const client = await getClient({ chainId: channel.chainId });
+            state = await Chain.getChannelState(client, channelId, channel.escrowContract);
+        }
+        catch {
+            // Transport errors can include private RPC URLs or authentication details.
+            throw new Error('Unable to verify stream escrow');
+        }
+        validateChannelState(state);
+        lastOnChainVerified.set(channelId, now);
+    };
     const serveWebSocket = (options) => Ws.serve({
         ...options,
+        beforeCharge: beforeStreamCharge,
         onChargeCommitted: settleCharged,
         store,
     });
@@ -254,9 +300,11 @@ export function session(p) {
     });
     const transport = parameters.sse
         ? Transport.sse({
+            ...(typeof parameters.sse === 'object' ? parameters.sse : {}),
+            beforeCharge: beforeStreamCharge,
+            reusableChallenges: parameters.reusableChallenges,
             settleCharged,
             store,
-            ...(typeof parameters.sse === 'object' ? parameters.sse : undefined),
         })
         : undefined;
     const validateCredential = async ({ credential, operation, request, }) => {
@@ -268,24 +316,31 @@ export function session(p) {
             minVoucherDelta: parameters.minVoucherDelta,
             request,
         });
-        const details = await validateCredentialPayload({
-            account,
-            allowPendingClose: operation === 'broadcast',
-            challenge: credential.challenge,
-            channelStateTtl,
-            chainId: context.chainId,
-            client: context.client,
-            credentialSource: credential.source,
-            escrow: context.escrow,
-            expectedOperator: context.methodDetails.operator,
-            feePayer: context.feePayer,
-            feePayerPolicy: parameters.feePayerPolicy,
-            feeToken: context.methodDetails.feeToken,
-            lastOnChainVerified,
-            minVoucherDelta: context.minVoucherDelta,
-            payload,
-            store,
-        });
+        // A broadcast voucher is checked against the stored channel by the update that accepts it.
+        const details = operation === 'broadcast' && payload.action === 'voucher'
+            ? {
+                action: payload.action,
+                channelId: ChannelStore.normalizeChannelId(payload.channelId),
+            }
+            : await validateCredentialPayload({
+                account,
+                allowPendingClose: operation === 'broadcast',
+                challenge: credential.challenge,
+                channelStateTtl,
+                chainId: context.chainId,
+                client: context.client,
+                credentialSource: credential.source,
+                escrow: context.escrow,
+                expectedOperator: context.methodDetails.operator,
+                feePayer: context.feePayer,
+                feePayerPolicy: parameters.feePayerPolicy,
+                feeToken: context.methodDetails.feeToken,
+                lastOnChainVerified,
+                minVoucherDelta: context.minVoucherDelta,
+                payload,
+                store,
+                voucherStateMaxAge: parameters.voucherStateMaxAge,
+            });
         return {
             challenge: credential.challenge,
             credential: { ...credential, payload },
@@ -306,9 +361,34 @@ export function session(p) {
             minVoucherDelta: parameters.minVoucherDelta,
             request,
         });
+        const chargeAmount = parameters.chargeOnAcceptance &&
+            shouldChargeVoucherOnAcceptance({
+                capturedRequest: envelope?.capturedRequest,
+                payloadAction: payload.action,
+                unitType: context.request.unitType,
+            })
+            ? BigInt(context.request.amount ?? challenge.request.amount)
+            : undefined;
+        const acceptance = {};
+        const settleAcceptedCharge = (channel) => maybeSettleScheduled({
+            account,
+            client: context.client,
+            ...(context.feePayer ? { feePayer: context.feePayer } : {}),
+            feePayerPolicy: parameters.feePayerPolicy,
+            feeToken: parameters.feeToken,
+            onSessionSettlement,
+            onSessionSettlementFailure,
+            schedule: settlementSchedule,
+            store,
+            channel,
+        }).catch(ignoreRetryableSettlementFailure);
         const sessionReceipt = await broadcastCredentialPayload({
             account,
             challenge,
+            chargeAmount,
+            onCharged: (channel) => {
+                acceptance.charged = channel;
+            },
             channelStateTtl,
             chainId: context.chainId,
             client: context.client,
@@ -329,7 +409,16 @@ export function session(p) {
                 sseEnabled: Boolean(parameters.sse),
             }),
             store,
+            voucherStateMaxAge: parameters.voucherStateMaxAge,
         });
+        if (acceptance.charged) {
+            const settlementTxHash = await settleAcceptedCharge(acceptance.charged);
+            const receipt = {
+                ...sessionReceipt,
+                ...(settlementTxHash ? { txHash: settlementTxHash } : {}),
+            };
+            return parameters.sse ? Transport.markPrepaidSessionTick(receipt) : receipt;
+        }
         return applyVerifiedHttpAccounting({
             capturedRequest: envelope?.capturedRequest,
             payloadAction: payload.action,
@@ -338,18 +427,7 @@ export function session(p) {
             sseEnabled: Boolean(parameters.sse),
             markPrepaidReceipt: Transport.markPrepaidSessionTick,
             charge: (channelId, requestAmount) => chargeSessionChannel({ store, channelId, amount: requestAmount }),
-            settleCharged: (channel) => maybeSettleScheduled({
-                account,
-                client: context.client,
-                ...(context.feePayer ? { feePayer: context.feePayer } : {}),
-                feePayerPolicy: parameters.feePayerPolicy,
-                feeToken: parameters.feeToken,
-                onSessionSettlement,
-                onSessionSettlementFailure,
-                schedule: settlementSchedule,
-                store,
-                channel,
-            }).catch(ignoreRetryableSettlementFailure),
+            settleCharged: settleAcceptedCharge,
         });
     };
     const method = Method.toServer(Methods.session, {
@@ -365,6 +443,7 @@ export function session(p) {
             unitType,
         }),
         extensions: { serveWebSocket, settleScheduled },
+        ...(parameters.reusableChallenges ? { stableBinding: reusableSessionBinding } : {}),
         transport: deriveTransport(transport),
         preflight: parameters.bootstrap
             ? async ({ capturedRequest, credential, expires, input, options, realm, secretKey }) => {
@@ -431,6 +510,7 @@ export function session(p) {
             });
         },
     });
+    streamVerifiers.set(method, beforeStreamCharge);
     return method;
 }
 (function (session) {

package/dist/tempo/session/server/Settlement.d.ts

@@ -174,6 +174,15 @@ export type ApplyVerifiedHttpAccountingParameters = {
 };
 /** Returns whether an accepted credential will authorize and charge an HTTP content response. */
 export declare function shouldApplyVerifiedHttpAccounting(parameters: Pick<ApplyVerifiedHttpAccountingParameters, 'capturedRequest' | 'payloadAction' | 'sseEnabled'>): boolean;
+/**
+ * Returns whether a voucher pays for its request in the store update that accepts it. A
+ * request-priced content request is charged exactly once, so this is the charge the HTTP
+ * accounting or the streamed response would make, without a second store update; the receipt is
+ * then marked prepaid so an SSE response does not charge again.
+ */
+export declare function shouldChargeVoucherOnAcceptance(parameters: Pick<ApplyVerifiedHttpAccountingParameters, 'capturedRequest' | 'payloadAction'> & {
+    unitType: unknown;
+}): boolean;
 /** Applies the default HTTP content charge after a session credential has been accepted. */
 export declare function applyVerifiedHttpAccounting(parameters: ApplyVerifiedHttpAccountingParameters): Promise<SessionReceipt>;
 /** Atomically deducts spend from a channel and maps store failures to typed session errors. */

package/dist/tempo/session/server/Settlement.js

@@ -1,4 +1,4 @@
-import { BaseError as viem_BaseError, HttpRequestError, InternalRpcError, isAddress, isAddressEqual, LimitExceededRpcError, parseUnits, ResourceUnavailableRpcError, RpcRequestError, SocketClosedError, TimeoutError, WaitForTransactionReceiptTimeoutError, WebSocketRequestError, zeroAddress, } from 'viem';
+import { BaseError as viem_BaseError, ExecutionRevertedError, HttpRequestError, InternalRpcError, isAddress, isAddressEqual, LimitExceededRpcError, parseUnits, ResourceUnavailableRpcError, RpcRequestError, SocketClosedError, TimeoutError, WaitForTransactionReceiptTimeoutError, WebSocketRequestError, zeroAddress, } from 'viem';
 import { BadRequestError, ChannelClosedError, ChannelNotFoundError, InsufficientBalanceError, VerificationFailedError, } from '../../../Errors.js';
 import { isSessionContentRequest } from '../../server/internal/request-body.js';
 import * as Chain from '../precompile/Chain.js';
@@ -171,6 +171,18 @@ export function shouldApplyVerifiedHttpAccounting(parameters) {
         return false;
     return isSessionContentRequest(capturedRequest);
 }
+/**
+ * Returns whether a voucher pays for its request in the store update that accepts it. A
+ * request-priced content request is charged exactly once, so this is the charge the HTTP
+ * accounting or the streamed response would make, without a second store update; the receipt is
+ * then marked prepaid so an SSE response does not charge again.
+ */
+export function shouldChargeVoucherOnAcceptance(parameters) {
+    const { capturedRequest, payloadAction, unitType } = parameters;
+    if (!capturedRequest || payloadAction !== 'voucher' || unitType !== 'request')
+        return false;
+    return isSessionContentRequest(capturedRequest);
+}
 /** Applies the default HTTP content charge after a session credential has been accepted. */
 export async function applyVerifiedHttpAccounting(parameters) {
     const { receipt, sseEnabled } = parameters;
@@ -307,7 +319,10 @@ export async function settle(store_, client, channelId_, options) {
         sender: account?.address,
     });
     const amount = uint96(channel.highestVoucher.cumulativeAmount);
-    const txHash = await Chain.settleOnChain(client, channel.descriptor, amount, channel.highestVoucher.signature, escrow, account
+    const { signature } = channel.highestVoucher;
+    // A replica behind the open or top-up that admitted this voucher rejects the settle while
+    // preparing it (e.g. `ChannelNotFound`); nothing was broadcast, so retry until it catches up.
+    const txHash = await Chain.readbackWithRetry(() => Chain.settleOnChain(client, channel.descriptor, amount, signature, escrow, account
         ? {
             account,
             ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
@@ -315,7 +330,7 @@ export async function settle(store_, client, channelId_, options) {
             ...(options?.feeToken ? { feeToken: options.feeToken } : {}),
             candidateFeeTokens: options?.candidateFeeTokens ?? [channel.token],
         }
-        : undefined);
+        : undefined), { shouldRetry: isExecutionRevert });
     const receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
     const settled = readSettledReceiptFields(Chain.getChannelEvent(receipt, 'Settled', channelId));
     const { deltaPaid, newSettled } = settled;
@@ -389,6 +404,11 @@ export function ignoreRetryableSettlementFailure(error) {
         return undefined;
     throw error;
 }
+/** Whether a settlement failed because the node's execution reverted it. */
+function isExecutionRevert(error) {
+    return (error instanceof viem_BaseError &&
+        Boolean(error.walk((cause) => cause instanceof ExecutionRevertedError)));
+}
 function isRetryableSettlementFailure(error) {
     if (error instanceof SettlementLeaseError)
         return true;

package/dist/tempo/session/server/Sse.d.ts

@@ -27,9 +27,8 @@ export type { SessionController } from './MeteredStream.js';
  * 2. If balance is sufficient, emits `event: message` with the value.
  * 3. If balance is exhausted, emits `event: payment-need-voucher`
  *    and polls store until the client tops up the channel.
- * 4. Commits the reserved charge immediately before the chunk is emitted. If a
- *    manual generator completes after charging without yielding another chunk,
- *    commits that terminal charge on successful completion.
+ * 4. Commits automatic charges before emission and manual charges before
+ *    `stream.charge()` resolves, retaining them on cancellation or failure.
  * 5. On generator completion, emits a final `event: payment-receipt`.
  *
  * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
@@ -43,6 +42,8 @@ export declare namespace serve {
         challengeId: string;
         tickCost: bigint;
         generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>);
+        /** Verifies live escrow before charging and delivering stream items. */
+        beforeCharge?: MeteredStreamOptions['beforeCharge'];
         /** Callback invoked after each nonzero stream charge is committed. */
         onChargeCommitted?: MeteredStreamOptions['onChargeCommitted'];
         pollIntervalMs?: number | undefined;

package/dist/tempo/session/server/Sse.js

@@ -26,9 +26,8 @@ export { extractData, formatMessageEvent, formatNeedVoucherEvent, formatReceiptE
  * 2. If balance is sufficient, emits `event: message` with the value.
  * 3. If balance is exhausted, emits `event: payment-need-voucher`
  *    and polls store until the client tops up the channel.
- * 4. Commits the reserved charge immediately before the chunk is emitted. If a
- *    manual generator completes after charging without yielding another chunk,
- *    commits that terminal charge on successful completion.
+ * 4. Commits automatic charges before emission and manual charges before
+ *    `stream.charge()` resolves, retaining them on cancellation or failure.
  * 5. On generator completion, emits a final `event: payment-receipt`.
  *
  * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
@@ -44,6 +43,7 @@ export function serve(options) {
         channelId,
         tickCost,
         generate,
+        beforeCharge: options.beforeCharge,
         onChargeCommitted: options.onChargeCommitted,
         pollIntervalMs,
         prepaidUnits: options.prepaidUnits,

package/dist/tempo/session/server/Ws.d.ts

@@ -1,3 +1,4 @@
+import { type SessionCredentialContext } from '../precompile/Protocol.js';
 import * as ChannelStore from './ChannelStore.js';
 import type { MeteredStreamOptions, SessionController } from './MeteredStream.js';
 import type { SettleChargedSessionChannel } from './Settlement.js';
@@ -16,6 +17,11 @@ export type SessionRouteResult = {
 };
 /** HTTP route used to perform a WebSocket payment probe. */
 export type SessionRoute = (request: Request) => Promise<SessionRouteResult>;
+type StreamContext = {
+    challengeId: string;
+    channelId: SessionCredentialContext['channelId'];
+    tickCost: bigint;
+};
 /**
  * Bridge a WebSocket connection to a Tempo session payment flow.
  *
@@ -47,7 +53,9 @@ export declare namespace serve {
         /** Payment route handler. Receives synthetic `POST` requests with only
          *  the `Authorization` header — no cookies, bodies, or upgrade headers. */
         route: SessionRoute;
-        /** Optional low-level hook invoked after each committed stream charge. */
+        /** Verifies live escrow before charging and delivering stream items. */
+        beforeCharge?: ((channelId: StreamContext['channelId']) => void | Promise<void>) | undefined;
+        /** Callback invoked after each nonzero stream charge is committed. */
         onChargeCommitted?: MeteredStreamOptions['onChargeCommitted'];
         /** @deprecated Use `onChargeCommitted`. */
         settleScheduled?: SettleChargedSessionChannel | undefined;

package/dist/tempo/session/server/Ws.js

@@ -65,6 +65,7 @@ export async function serve(options) {
                 channelId: context.channelId,
                 tickCost: context.tickCost,
                 generate,
+                beforeCharge: () => options.beforeCharge?.(context.channelId),
                 onChargeCommitted: options.onChargeCommitted ?? options.settleScheduled,
                 pollIntervalMs,
                 signal: abortController.signal,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "main": "./dist/index.js",
   "license": "MIT",
   "homepage": "https://github.com/wevm/mppx#readme",