mppx 0.14.0 → 0.15.0

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

@@ -1,6 +1,6 @@
 import { type Hex } from 'viem';
 import * as Chain from '../precompile/Chain.js';
-import { type OnSessionSettlementFailure, type SessionStoreInput, type SettlementTransactionOptions } from './Settlement.js';
+import { type OnSessionSettlementFailure, type ResolvedSettlementSchedule, type SessionStoreInput, type SettlementTransactionOptions } from './Settlement.js';
 /** Channels whose escrow states one call reads, bounding its calldata and response size. */
 export declare const defaultBatchSize = 50;
 /** Widest log query `rpc.tempo.xyz` accepts; wider ones fail with "query exceeds max block range". */
@@ -15,6 +15,8 @@ export declare const defaultCloseSearchMarginBlocks = 2000n;
 export type CloseSupervisionOutcome = 
 /** Open with no close request, or not yet open at the pinned block. */
 'open'
+/** Open, and settled because its spend crossed `settlementSchedule`. */
+ | 'settled'
 /** Close requested, with nothing above the settled amount to capture; the payer's withdrawal finalizes it. */
  | 'closing'
 /** A close request recorded on the channel was cancelled on-chain, so the channel accepts charges again. */
@@ -45,6 +47,8 @@ export type CloseSupervision = {
     closed: number;
     /** Channels that failed. */
     failed: number;
+    /** Open channels settled on `settlementSchedule`. */
+    settled: number;
     /** Channels whose deposit left the escrow before their spend was captured. */
     unrecovered: number;
     /**
@@ -78,6 +82,14 @@ export type SuperviseClosesParameters = Pick<SettlementTransactionOptions, 'acco
     onSessionSettlementFailure?: OnSessionSettlementFailure | undefined;
     /** `block` of the last `complete` supervision, which bounds close-event searches. */
     previousBlock?: bigint | undefined;
+    /**
+     * Settles open channels whose spend since their last settlement crossed this schedule, in raw
+     * token units, with the account and fee options of closes. Servers that charge channels with
+     * `charge()` rather than through the session handler, whose own schedule runs on each
+     * charge, use it to collect spend without waiting for a close. Settlement captures only a voucher
+     * within spend. Without it, open channels are only read.
+     */
+    settlementSchedule?: ResolvedSettlementSchedule | undefined;
     /** Server channel store. */
     store: SessionStoreInput;
 };

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

@@ -4,7 +4,7 @@ import { VerificationFailedError } from '../../../Errors.js';
 import * as Chain from '../precompile/Chain.js';
 import { escrowAbi } from '../precompile/escrow.abi.js';
 import * as ChannelStore from './ChannelStore.js';
-import { assertSettlementSender, getClientAccount, reportSessionSettlementFailure, resolveChannelStore, } from './Settlement.js';
+import { assertSettlementSender, getClientAccount, maybeSettleScheduled, reportSessionSettlementFailure, resolveChannelStore, } from './Settlement.js';
 /** Escrow event every close and withdrawal emits, with the amount paid to the payee. */
 const channelClosedEvent = getAbiItem({ abi: escrowAbi, name: 'ChannelClosed' });
 /** Channels whose escrow states one call reads, bounding its calldata and response size. */
@@ -45,6 +45,7 @@ export async function superviseCloses(parameters) {
         closed: 0,
         complete: false,
         failed: 0,
+        settled: 0,
         supervised: 0,
         timestamp: pinned.timestamp,
         unrecovered: 0,
@@ -54,6 +55,7 @@ export async function superviseCloses(parameters) {
         if (outcome === 'cancelled' ||
             outcome === 'closed' ||
             outcome === 'failed' ||
+            outcome === 'settled' ||
             outcome === 'unrecovered')
             supervision[outcome] += 1;
         supervision.channels.push({ channelId, outcome, ...details });
@@ -172,7 +174,7 @@ async function superviseChannel(parameters, store, channel, state, blocks) {
             : current);
     if (state.closeRequestedAt === 0) {
         if (channel.closeRequestedAt === 0n)
-            return { outcome: 'open' };
+            return settleDue(parameters, store, channel);
         // A pinned read without a request means the payer cancelled it, unless the record holds a
         // server close that may still land: those expire before they are cleared.
         const cleared = {};
@@ -198,6 +200,25 @@ async function superviseChannel(parameters, store, channel, state, blocks) {
         return { outcome: 'finalized' };
     return closeAtSpend(parameters, store, closing, state);
 }
+/** Settles an open channel when its spend crossed the settlement schedule. */
+async function settleDue(parameters, store, channel) {
+    const { client, settlementSchedule } = parameters;
+    if (!settlementSchedule)
+        return { outcome: 'open' };
+    const txHash = await maybeSettleScheduled({
+        account: parameters.account ?? getClientAccount(client),
+        channel,
+        client,
+        ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
+        ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
+        ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
+        onSessionSettlement: parameters.onSessionSettlement,
+        onSessionSettlementFailure: parameters.onSessionSettlementFailure,
+        schedule: settlementSchedule,
+        store,
+    });
+    return txHash ? { outcome: 'settled', txHash } : { outcome: 'open' };
+}
 /** Sends a payee close capturing the channel's spend and finalizes the channel. */
 async function closeAtSpend(parameters, store, channel, state) {
     const { client } = parameters;

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

@@ -1,3 +1,4 @@
+import type * as Challenge from '../../../Challenge.js';
 import { type SessionCredentialContext } from '../precompile/Protocol.js';
 import * as ChannelStore from './ChannelStore.js';
 import type { MeteredStreamOptions, SessionController } from './MeteredStream.js';
@@ -13,6 +14,7 @@ export type SessionRouteResult = {
     challenge: Response;
 } | {
     status: 200;
+    challenge?: Challenge.Challenge | undefined;
     withReceipt(response?: Response): Response | Promise<Response>;
 };
 /** HTTP route used to perform a WebSocket payment probe. */
@@ -36,14 +38,15 @@ export declare function serve(options: serve.Options): Promise<void>;
 /** Type helpers for {@link serve}. */
 export declare namespace serve {
     type Options = {
-        /** Expected per-tick amount in raw units. When set, credentials whose
+        /** Expected per-tick amount in raw units. Required for custom routes that
+         *  do not return their canonical challenge. When set, credentials whose
          *  challenge `request.amount` does not match are rejected. Use this to
          *  pin the price when the route is backed by `Mppx.compose()` with
          *  multiple offers — otherwise a client can select the cheapest offer
          *  and still receive the same stream. */
         amount?: string | undefined;
         /** Application stream. A manual stream can call `charge(amount)` with a
-         *  per-message raw-unit amount; omitting it uses the challenge tick cost. */
+         *  per-message raw-unit amount; omitting it uses the canonical route tick cost. */
         generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>);
         /** Maximum accepted inbound WebSocket frame size in bytes. @default 65536 */
         maxIncomingMessageBytes?: number | undefined;

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

@@ -133,6 +133,11 @@ export async function serve(options) {
             return;
         }
         const { receipt } = authorizationResult;
+        const tickCost = expectedAmount !== undefined ? BigInt(expectedAmount) : authorizationResult.amount;
+        if (tickCost === undefined) {
+            await close(1008, 'WebSocket route must provide canonical pricing or an explicit amount');
+            return;
+        }
         if (payload.action === 'voucher' && runtime.streamContext) {
             runtime.streamContext.challengeId = credential.challenge.id;
         }
@@ -149,7 +154,7 @@ export async function serve(options) {
         runtime.streamContext = {
             challengeId: credential.challenge.id,
             channelId: payload.channelId,
-            tickCost: readSessionChallengeAmount(credential.challenge),
+            tickCost,
         };
         // Defer the first application frame until after the client receives the
         // auth receipt and has a chance to install its own message listeners.
@@ -299,6 +304,10 @@ async function authorizePaymentFrame(parameters) {
     const receiptHeader = response.headers.get(Constants.Headers.paymentReceipt);
     if (!receiptHeader)
         throw new Error('management response missing Payment-Receipt header');
-    return { status: 'accepted', receipt: deserializeSessionReceipt(receiptHeader) };
+    return {
+        status: 'accepted',
+        amount: result.challenge ? readSessionChallengeAmount(result.challenge) : undefined,
+        receipt: deserializeSessionReceipt(receiptHeader),
+    };
 }
 //# sourceMappingURL=Ws.js.map

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

@@ -9,6 +9,8 @@ export type { ChargeOptions, CreditDeclineReason, CreditOptions, CreditResult, S
 export type { Parameters as SponsorshipLimitParameters } from './SponsorshipLimit.js';
 /** SSE helpers and types for Tempo session streams. */
 export * as Sse from './Sse.js';
-/** Server-side automatic settlement schedule. */
+/** Server-side automatic settlement schedule, and its raw-unit form `superviseCloses` takes. */
+export { resolveSettlementSchedule } from './Settlement.js';
+export type { ResolvedSettlementSchedule } from './Settlement.js';
 export type { OnSessionSettlement, OnSessionSettlementFailure, ResolveSessionChannelId, ResolveSessionChannelIdParameters, SessionChannelIdRequest, SessionSettlementContext, SessionSettlementFailureContext, SettlementSchedule, } from './Session.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -5,4 +5,6 @@ export { superviseCloses } from './CloseSupervisor.js';
 export { IdempotencyKeyConflictError, resolveSettleableVoucher } from './ChannelStore.js';
 /** SSE helpers and types for Tempo session streams. */
 export * as Sse from './Sse.js';
+/** Server-side automatic settlement schedule, and its raw-unit form `superviseCloses` takes. */
+export { resolveSettlementSchedule } from './Settlement.js';
 //# sourceMappingURL=index.js.map

package/dist/tempo/subscription/Store.d.ts

@@ -13,9 +13,13 @@ export type SubscriptionStore = {
     /** Looks up a generated access key for a resolved request key. */
     getAccessKey(key: string): Promise<SubscriptionAccessKeyRecord | null>;
     /** Looks up a generated access key by its public access key address. */
-    getAccessKeyByAddress(address: string): Promise<SubscriptionAccessKeyRecord | null>;
+    getAccessKeyByAddress(address: string, keyToken?: `0x${string}`): Promise<SubscriptionAccessKeyRecord | null>;
     /** Looks up the active subscription for a resolved request key. */
     getByKey(key: string): Promise<SubscriptionRecord | null>;
+    /** Creates a key sealed in a client-carried token, without retaining per-challenge state. */
+    createChallengeAccessKey(): Promise<SubscriptionAccessKeyRecord>;
+    /** Retains a key after verified payment submission for subsequent subscription billing. */
+    retainAccessKey(key: string, record: SubscriptionAccessKeyRecord): Promise<void>;
     /** Gets or creates the server-owned access key for a resolved request key. */
     getOrCreateAccessKey(key: string): Promise<SubscriptionAccessKeyRecord>;
     /** Upserts a subscription record and marks it as active for its lookup key. */
@@ -85,6 +89,8 @@ export declare namespace fromStore {
     type Options = {
         /** Key prefix for server-owned subscription access keys. @default `'tempo:subscription:access-key:'` */
         accessKeyPrefix?: string | undefined;
+        /** Namespace for the persistent anonymous-challenge sealing key. */
+        pendingAccessKeyPrefix?: string | undefined;
         /** Key prefix for resolved subscription activation locks. @default `'tempo:subscription:activation:'` */
         activationPrefix?: string | undefined;
         /** Milliseconds before a stuck activation lock can be replaced. @default `900000` */

package/dist/tempo/subscription/Store.js

@@ -1,15 +1,16 @@
-import { Secp256k1 } from 'ox';
+import { Hex, Secp256k1 } from 'ox';
 import { Account as TempoAccount } from 'viem/tempo';
 const defaultRecordPrefix = 'tempo:subscription:record:';
 const defaultKeyPrefix = 'tempo:subscription:key:';
 const defaultActivationPrefix = 'tempo:subscription:activation:';
 const defaultAccessKeyPrefix = 'tempo:subscription:access-key:';
+const defaultPendingAccessKeyPrefix = 'tempo:subscription:pending-access-key:';
 const defaultCredentialPrefix = 'tempo:subscription:credential:';
 const defaultActivationTimeoutMs = 15 * 60 * 1_000;
 const defaultRenewalTimeoutMs = 15 * 60 * 1_000;
 /** Wraps a generic key-value {@link Store.Store} with subscription-specific accessors. */
 export function fromStore(store, options) {
-    const { accessKeyPrefix = defaultAccessKeyPrefix, activationPrefix = defaultActivationPrefix, activationTimeoutMs = defaultActivationTimeoutMs, credentialPrefix = defaultCredentialPrefix, keyPrefix = defaultKeyPrefix, recordPrefix = defaultRecordPrefix, renewalTimeoutMs = defaultRenewalTimeoutMs, } = options ?? {};
+    const { accessKeyPrefix = defaultAccessKeyPrefix, activationPrefix = defaultActivationPrefix, activationTimeoutMs = defaultActivationTimeoutMs, credentialPrefix = defaultCredentialPrefix, keyPrefix = defaultKeyPrefix, recordPrefix = defaultRecordPrefix, pendingAccessKeyPrefix = defaultPendingAccessKeyPrefix, renewalTimeoutMs = defaultRenewalTimeoutMs, } = options ?? {};
     function recordKey(subscriptionId) {
         return `${recordPrefix}${subscriptionId}`;
     }
@@ -61,7 +62,35 @@ export function fromStore(store, options) {
         const marker = (await store.get(activationKey(lookupKey)));
         return marker?.challengeId === challengeId;
     }
+    const sealingKey = `${pendingAccessKeyPrefix}sealing-key`;
+    // One shared secret survives across workers; anonymous issuance never grows the store.
+    async function getSealingKey() {
+        const candidate = Hex.fromBytes(crypto.getRandomValues(new Uint8Array(32)));
+        const secret = await store.update(sealingKey, (current) => current
+            ? { op: 'noop', result: current }
+            : { op: 'set', value: candidate, result: candidate });
+        return crypto.subtle.importKey('raw', new Uint8Array(Hex.toBytes(secret)), 'AES-GCM', false, [
+            'encrypt',
+            'decrypt',
+        ]);
+    }
     return {
+        async createChallengeAccessKey() {
+            const privateKey = Secp256k1.randomPrivateKey();
+            const account = TempoAccount.fromSecp256k1(privateKey);
+            const iv = crypto.getRandomValues(new Uint8Array(12));
+            const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, await getSealingKey(), new Uint8Array(Hex.toBytes(privateKey))));
+            return {
+                accessKeyAddress: account.address.toLowerCase(),
+                keyType: account.keyType,
+                privateKey,
+                keyToken: Hex.fromBytes(new Uint8Array([...iv, ...sealed])),
+            };
+        },
+        async retainAccessKey(key, record) {
+            await store.put(accessKeyKey(key), record);
+            await store.put(accessKeyAddressKey(record.accessKeyAddress), record);
+        },
         async activate({ challengeId, create, isReusable, lookupKey }) {
             const claimed = await store.update(credentialKey(challengeId), (current) => {
                 if (current)
@@ -155,8 +184,31 @@ export function fromStore(store, options) {
         async getAccessKey(key) {
             return (await store.get(accessKeyKey(key)));
         },
-        async getAccessKeyByAddress(address) {
-            return (await store.get(accessKeyAddressKey(address)));
+        async getAccessKeyByAddress(address, keyToken) {
+            const stored = (await store.get(accessKeyAddressKey(address)));
+            if (stored)
+                return stored;
+            if (!keyToken)
+                return null;
+            try {
+                const bytes = Hex.toBytes(keyToken);
+                // 12-byte nonce, 32-byte private key, and 16-byte authentication tag.
+                if (bytes.length !== 60)
+                    return null;
+                const privateKey = Hex.fromBytes(new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: bytes.slice(0, 12) }, await getSealingKey(), bytes.slice(12))));
+                const account = TempoAccount.fromSecp256k1(privateKey);
+                if (account.address.toLowerCase() !== address.toLowerCase())
+                    return null;
+                return {
+                    accessKeyAddress: account.address.toLowerCase(),
+                    keyType: account.keyType,
+                    privateKey,
+                    keyToken,
+                };
+            }
+            catch {
+                return null;
+            }
         },
         async getByKey(key) {
             return getByLookupKey(key);

package/dist/tempo/subscription/Types.d.ts

@@ -5,6 +5,8 @@ export type SubscriptionPeriodUnit = 'dev_second' | 'day' | 'week';
 export type SubscriptionAccessKey = {
     accessKeyAddress: Address;
     keyType: 'p256' | 'secp256k1' | 'webAuthn';
+    /** Opaque server-sealed key for stateless anonymous setup. */
+    keyToken?: `0x${string}` | undefined;
 };
 /** Server-owned subscription access key persisted for automatic billing. */
 export type SubscriptionAccessKeyRecord = SubscriptionAccessKey & {

package/package.json

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