mppx 0.6.30 → 0.7.0

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

@@ -0,0 +1,244 @@
+import * as Constants from '../../../Constants.js';
+import * as Credential from '../../../Credential.js';
+import { createSessionReceipt, deserializeSessionReceipt, formatApplicationMessage, formatCloseReadyMessage, formatErrorMessage, formatNeedVoucherMessage, formatReceiptMessage, parseMessage, readSessionChallengeAmount, requireSessionCredentialContext, } from '../precompile/Protocol.js';
+import * as ChannelStore from './ChannelStore.js';
+import { meterIterable } from './MeteredStream.js';
+import { send, subscribe, toText } from './Transports.js';
+/** Public WebSocket payment frame helpers. */
+export { formatApplicationMessage, formatAuthorizationMessage, formatCloseReadyMessage, formatCloseRequestMessage, formatErrorMessage, formatNeedVoucherMessage, formatReceiptMessage, parseMessage, } from '../precompile/Protocol.js';
+/**
+ * Bridge a WebSocket connection to a Tempo session payment flow.
+ *
+ * Credential verification is performed by routing each in-band authorization
+ * frame through `route` as a **synthetic `POST` request** that carries only
+ * the `Authorization` header. The synthetic request does not include cookies,
+ * bodies, query parameters, or other headers from the original WebSocket
+ * upgrade request. Do not wrap `route` with middleware that depends on
+ * HTTP-specific context beyond the `Authorization` header.
+ */
+export async function serve(options) {
+    const { amount: expectedAmount, generate, pollIntervalMs = 100, route, socket, store: rawStore, url, } = options;
+    const store = 'getChannel' in rawStore ? rawStore : ChannelStore.fromStore(rawStore);
+    const requestUrl = normalizeHttpUrl(url);
+    const maxQueuedPaymentMessages = 32;
+    const abortController = new AbortController();
+    const runtime = {
+        closed: false,
+        closeReadySent: false,
+        closeRequestHandled: false,
+        closeRequested: false,
+        streamStarted: false,
+        streamTask: null,
+        streamContext: null,
+        action: Promise.resolve(),
+        queuedActions: 0,
+    };
+    const close = async (code = 1000, reason) => {
+        if (runtime.closed)
+            return;
+        runtime.closed = true;
+        abortController.abort();
+        unsubscribe();
+        await Promise.resolve(socket.close(code, reason));
+    };
+    const sendCloseReady = async () => {
+        if (runtime.closeReadySent || !runtime.streamContext || runtime.closed)
+            return;
+        runtime.closeReadySent = true;
+        const channel = await store.getChannel(runtime.streamContext.channelId);
+        if (!channel)
+            throw new Error('channel not found');
+        const receipt = createSessionReceipt({
+            challengeId: runtime.streamContext.challengeId,
+            channelId: runtime.streamContext.channelId,
+            acceptedCumulative: channel.highestVoucherAmount,
+            spent: channel.spent,
+            units: channel.units,
+        });
+        await send(socket, formatCloseReadyMessage(receipt));
+    };
+    const runStream = async (context) => {
+        try {
+            for await (const value of meterIterable({
+                store,
+                channelId: context.channelId,
+                tickCost: context.tickCost,
+                generate,
+                pollIntervalMs,
+                signal: abortController.signal,
+                emitNeedVoucher: (message) => send(socket, message),
+                formatNeedVoucher: formatNeedVoucherMessage,
+            })) {
+                if (abortController.signal.aborted)
+                    break;
+                await send(socket, formatApplicationMessage(value));
+            }
+            if (!abortController.signal.aborted)
+                await sendCloseReady();
+        }
+        catch (error) {
+            if (!abortController.signal.aborted) {
+                await send(socket, formatErrorMessage({
+                    message: error instanceof Error ? error.message : 'websocket session failed',
+                    status: 500,
+                }));
+                await close(1011, 'websocket session failed');
+            }
+        }
+        finally {
+            runtime.streamTask = null;
+        }
+    };
+    const requestClose = async () => {
+        if (runtime.closed)
+            return;
+        if (runtime.closeRequestHandled)
+            return;
+        runtime.closeRequestHandled = true;
+        runtime.closeRequested = true;
+        abortController.abort();
+        await runtime.streamTask?.catch(() => { });
+        await sendCloseReady();
+    };
+    const processAuthorization = async (authorization) => {
+        if (runtime.closed)
+            return;
+        const credential = Credential.deserialize(authorization);
+        const payload = requireSessionCredentialContext(credential.payload);
+        if (payload.action === 'close')
+            runtime.closeRequested = true;
+        if (expectedAmount && credential.challenge.request.amount !== expectedAmount) {
+            await send(socket, formatErrorMessage({
+                message: 'credential amount does not match this endpoint',
+                status: 402,
+            }));
+            await close(1008, 'credential amount does not match this endpoint');
+            return;
+        }
+        const authorizationResult = await authorizePaymentFrame({ authorization, requestUrl, route });
+        if (authorizationResult.status === 'rejected') {
+            await send(socket, formatErrorMessage({
+                message: authorizationResult.message,
+                status: authorizationResult.responseStatus,
+            }));
+            await close(1008, authorizationResult.message);
+            return;
+        }
+        const { receipt } = authorizationResult;
+        await send(socket, formatReceiptMessage(receipt));
+        if (payload.action === 'close') {
+            await close(1000, 'payment session closed');
+            return;
+        }
+        if (payload.action === 'topUp')
+            return;
+        if (runtime.streamStarted || runtime.closeRequested)
+            return;
+        runtime.streamStarted = true;
+        runtime.streamContext = {
+            challengeId: credential.challenge.id,
+            channelId: payload.channelId,
+            tickCost: readSessionChallengeAmount(credential.challenge),
+        };
+        // Defer the first application frame until after the client receives the
+        // auth receipt and has a chance to install its own message listeners.
+        setTimeout(() => {
+            if (runtime.closeRequested || runtime.closed || !runtime.streamContext)
+                return;
+            runtime.streamTask = runStream(runtime.streamContext);
+        }, 0);
+    };
+    const onMessage = (payload) => {
+        if (runtime.closed)
+            return;
+        const raw = toText(payload);
+        if (!raw)
+            return;
+        const message = parseMessage(raw);
+        if (!message)
+            return;
+        if (message.mpp === 'payment-close-request') {
+            runtime.closeRequested = true;
+            abortController.abort();
+        }
+        const work = message.mpp === 'authorization'
+            ? () => processAuthorization(message.authorization)
+            : message.mpp === 'payment-close-request'
+                ? () => requestClose()
+                : null;
+        if (!work)
+            return;
+        if (runtime.queuedActions >= maxQueuedPaymentMessages) {
+            void send(socket, formatErrorMessage({
+                message: 'too many queued payment messages',
+                status: 429,
+            })).catch(() => { });
+            void close(1008, 'too many queued payment messages');
+            return;
+        }
+        runtime.queuedActions++;
+        runtime.action = runtime.action
+            .then(async () => {
+            try {
+                if (runtime.closed)
+                    return;
+                await work();
+            }
+            finally {
+                runtime.queuedActions--;
+            }
+        })
+            .catch(async (error) => {
+            if (!runtime.closed) {
+                await send(socket, formatErrorMessage({
+                    message: error instanceof Error ? error.message : 'invalid payment message',
+                    status: 400,
+                }));
+                await close(1008, 'invalid payment message');
+            }
+        });
+    };
+    const onClose = () => {
+        if (runtime.closed)
+            return;
+        runtime.closed = true;
+        abortController.abort();
+        unsubscribe();
+    };
+    const unsubscribe = subscribe(socket, {
+        close: onClose,
+        error: onClose,
+        message: onMessage,
+    });
+}
+function normalizeHttpUrl(value) {
+    const url = new URL(value.toString());
+    if (url.protocol === 'ws:')
+        url.protocol = 'http:';
+    if (url.protocol === 'wss:')
+        url.protocol = 'https:';
+    return url.toString();
+}
+/** Verifies a WebSocket authorization frame and returns either a receipt or a payment error. */
+async function authorizePaymentFrame(parameters) {
+    const result = await parameters.route(new Request(parameters.requestUrl, {
+        method: 'POST',
+        headers: { [Constants.Headers.authorization]: parameters.authorization },
+    }));
+    if (result.status === 402) {
+        const response = result.challenge;
+        return {
+            status: 'rejected',
+            message: (await response.text().catch(() => '')) ||
+                response.statusText ||
+                'payment verification failed',
+            responseStatus: response.status,
+        };
+    }
+    const response = result.withReceipt(new Response(null, { status: 204 }));
+    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) };
+}
+//# sourceMappingURL=Ws.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Ws.js","sourceRoot":"","sources":["../../../../src/tempo/session/server/Ws.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+export { charge, session, settle, settleBatch } from './Session.js';
+/** Server-side automatic settlement schedule. */
+export type { ResolveSessionChannelId, ResolveSessionChannelIdParameters, SessionChannelIdRequest, SettlementSchedule, } from './Session.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tempo/session/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AACnE,iDAAiD;AACjD,YAAY,EACV,uBAAuB,EACvB,iCAAiC,EACjC,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAA"}

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

@@ -0,0 +1,2 @@
+export { charge, session, settle, settleBatch } from './Session.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/tempo/session/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.6.30",
+  "version": "0.7.0",
   "main": "./dist/index.js",
   "license": "MIT",
+  "homepage": "https://github.com/wevm/mppx#readme",
+  "bugs": {
+    "url": "https://github.com/wevm/mppx/issues"
+  },
   "files": [
     "CHANGELOG.md",
     "dist",
@@ -143,8 +147,9 @@
     }
   },
   "dependencies": {
-    "incur": "^0.4.5",
-    "ox": "0.14.24",
+    "@stripe/stripe-js": "9.7.0",
+    "incur": "^0.4.8",
+    "ox": "0.14.27",
     "zod": "^4.4.3"
   },
   "repository": {

package/src/Challenge.ts

@@ -1,5 +1,6 @@
 import { Base64, Bytes, Hash } from 'ox'
 
+import * as Constants from './Constants.js'
 import { constantTimeEqual } from './internal/constantTimeEqual.js'
 import type { OneOf } from './internal/types.js'
 import type * as Method from './Method.js'
@@ -309,7 +310,7 @@ export function serialize(challenge: Challenge): string {
   else if (challenge.meta !== undefined)
     parts.push(authParam('opaque', PaymentRequest.serialize(challenge.meta)))
 
-  return `Payment ${parts.join(', ')}`
+  return `${Constants.Schemes.payment} ${parts.join(', ')}`
 }
 
 /** @internal */
@@ -361,7 +362,7 @@ export function deserialize<const methods extends readonly Method.Method[] | und
 
 /** @internal Extracts the `Payment` scheme from a WWW-Authenticate value that may contain multiple schemes. */
 function extractPaymentAuthParams(header: string): string | null {
-  const token = 'Payment'
+  const token = Constants.Schemes.payment
   let inQuotes = false
   let escaped = false
 
@@ -493,8 +494,8 @@ export function fromHeaders<const methods extends readonly Method.Method[] | und
   headers: Headers,
   options?: from.Options<methods>,
 ): from.ReturnType<from.Parameters, methods> {
-  const header = headers.get('WWW-Authenticate')
-  if (!header) throw new Error('Missing WWW-Authenticate header.')
+  const header = headers.get(Constants.Headers.wwwAuthenticate)
+  if (!header) throw new Error(`Missing ${Constants.Headers.wwwAuthenticate} header.`)
   return deserialize(header, options)
 }
 
@@ -564,8 +565,8 @@ export function fromResponseList<
 export function fromHeadersList<
   const methods extends readonly Method.Method[] | undefined = undefined,
 >(headers: Headers, options?: from.Options<methods>): from.ReturnType<from.Parameters, methods>[] {
-  const header = headers.get('WWW-Authenticate')
-  if (!header) throw new Error('Missing WWW-Authenticate header.')
+  const header = headers.get(Constants.Headers.wwwAuthenticate)
+  if (!header) throw new Error(`Missing ${Constants.Headers.wwwAuthenticate} header.`)
   return deserializeList(header, options)
 }
 
@@ -582,7 +583,8 @@ export function deserializeList<
 >(value: string, options?: from.Options<methods>): from.ReturnType<from.Parameters, methods>[] {
   // Find the start index of each `Payment ` scheme prefix.
   const starts: number[] = []
-  for (const match of value.matchAll(/Payment\s+/gi)) {
+  const schemePattern = new RegExp(`${Constants.Schemes.payment}\\s+`, 'gi')
+  for (const match of value.matchAll(schemePattern)) {
     starts.push(match.index!)
   }
   if (starts.length === 0) throw new Error('No Payment schemes found.')

package/src/Constants.ts

@@ -0,0 +1,58 @@
+/** HTTP header names used by the Payment authentication scheme. */
+export const Headers = {
+  acceptPayment: 'Accept-Payment',
+  authorization: 'Authorization',
+  paymentReceipt: 'Payment-Receipt',
+  paymentSession: 'Payment-Session',
+  paymentSessionSnapshot: 'Payment-Session-Snapshot',
+  wwwAuthenticate: 'WWW-Authenticate',
+} as const
+
+/** Authentication scheme names used by mppx transports. */
+export const Schemes = {
+  payment: 'Payment',
+} as const
+
+/** Payment method names used by built-in mppx methods. */
+export const Methods = {
+  evm: 'evm',
+  stripe: 'stripe',
+  tempo: 'tempo',
+} as const
+
+/** Payment intent names used by built-in mppx methods. */
+export const Intents = {
+  charge: 'charge',
+  session: 'session',
+  subscription: 'subscription',
+} as const
+
+/** Method detail object keys used by built-in methods. */
+export const MethodDetailKeys = {
+  sessionProtocol: 'sessionProtocol',
+  sessionSnapshot: 'sessionSnapshot',
+} as const
+
+/** Tempo session protocol versions advertised under `request.methodDetails`. */
+export const SessionProtocols = {
+  /** Legacy contract-backed Tempo session protocol. */
+  v1: 'v1',
+  /** TIP-1034 precompile-backed Tempo session protocol. */
+  v2: 'v2',
+} as const
+
+/** Known Tempo session protocol version markers. */
+export type SessionProtocol = (typeof SessionProtocols)[keyof typeof SessionProtocols]
+
+type MethodDetailKey = (typeof MethodDetailKeys)[keyof typeof MethodDetailKeys]
+
+/**
+ * Reads a typed method detail value from a challenge request.
+ */
+export function getMethodDetail<Value>(
+  methodDetails: unknown,
+  key: MethodDetailKey,
+): Value | undefined {
+  if (!methodDetails || typeof methodDetails !== 'object') return undefined
+  return (methodDetails as Record<string, Value | undefined>)[key]
+}

package/src/Credential.ts

@@ -1,6 +1,7 @@
 import { Base64 } from 'ox'
 
 import * as Challenge from './Challenge.js'
+import * as Constants from './Constants.js'
 import * as PaymentRequest from './PaymentRequest.js'
 
 /**
@@ -58,7 +59,7 @@ export class InvalidCredentialEncodingError extends Error {
  * ```
  */
 export function deserialize<payload = unknown>(value: string): Credential<payload> {
-  const prefixMatch = value.match(/^Payment\s+(.+)$/i)
+  const prefixMatch = value.match(new RegExp(`^${Constants.Schemes.payment}\\s+(.+)$`, 'i'))
   if (!prefixMatch?.[1]) throw new MissingPaymentSchemeError()
   try {
     const json = Base64.toString(prefixMatch[1])
@@ -163,7 +164,7 @@ export declare namespace from {
  * ```
  */
 export function fromRequest<payload = unknown>(request: Request): Credential<payload> {
-  const header = request.headers.get('Authorization')
+  const header = request.headers.get(Constants.Headers.authorization)
   if (!header) throw new MissingAuthorizationHeaderError()
   const payment = extractPaymentScheme(header)
   if (!payment) throw new MissingPaymentSchemeError()
@@ -200,7 +201,7 @@ export function serialize(credential: Credential): string {
   }
   const json = JSON.stringify(wire)
   const encoded = Base64.fromString(json, { pad: false, url: true })
-  return `Payment ${encoded}`
+  return `${Constants.Schemes.payment} ${encoded}`
 }
 
 /**
@@ -212,5 +213,5 @@ export function serialize(credential: Credential): string {
  */
 export function extractPaymentScheme(header: string): string | null {
   const schemes = header.split(',').map((s) => s.trim())
-  return schemes.find((s) => /^Payment\s+/i.test(s)) ?? null
+  return schemes.find((s) => new RegExp(`^${Constants.Schemes.payment}\\s+`, 'i').test(s)) ?? null
 }

package/src/Method.ts

@@ -59,6 +59,7 @@ export type Client<
   method extends Method = Method,
   context extends z.ZodMiniType | undefined = z.ZodMiniType | undefined,
 > = method & {
+  canHandleChallenge?: CanHandleChallengeFn | undefined
   context?: context
   createCredential: CreateCredentialFn<
     method,
@@ -130,18 +131,21 @@ export type Server<
   defaults extends ExactPartial<z.input<method['schema']['request']>> = {},
   transportOverride = undefined,
   extensions extends object = {},
+  alias extends string | undefined = string | undefined,
 > = method & {
+  alias?: alias | undefined
   authorize?: AuthorizeFn<method> | undefined
   defaults?: defaults | undefined
   extensions?: extensions | undefined
   html?: Html.Options | undefined
+  preflight?: PreflightFn<method> | undefined
   request?: RequestFn<method> | undefined
   respond?: RespondFn<method> | undefined
   stableBinding?: StableBindingFn<method> | undefined
   transport?: transportOverride | undefined
   verify: VerifyFn<method>
 }
-export type AnyServer = Server<any, any, any, any>
+export type AnyServer = Server<any, any, any, any, any>
 
 /** Credential creation function for a single method. */
 export type CreateCredentialFn<method extends Method, context = unknown> = (
@@ -154,6 +158,9 @@ export type CreateCredentialFn<method extends Method, context = unknown> = (
   } & ([keyof context] extends [never] ? unknown : { context: context }),
 ) => Promise<string>
 
+/** Predicate used when multiple client implementations share a wire method/intent. */
+export type CanHandleChallengeFn = (parameters: { challenge: Challenge.Challenge }) => boolean
+
 /** Request transform function for a single method. */
 export type RequestFn<method extends Method> = (
   options: RequestContext<method>,
@@ -188,6 +195,22 @@ export type AuthorizeResult = {
   response?: globalThis.Response | undefined
 }
 
+/**
+ * Optional HTTP preflight hook for method-specific management requests.
+ *
+ * Called before the normal challenge/verification path. Returning a response
+ * fully handles the request.
+ */
+export type PreflightFn<method extends Method> = (parameters: {
+  capturedRequest?: CapturedRequest | undefined
+  credential: Credential.Credential | null
+  expires?: string | undefined
+  input: globalThis.Request
+  options: z.input<method['schema']['request']>
+  realm: string
+  secretKey: string
+}) => MaybePromise<globalThis.Response | undefined>
+
 /**
  * Produces the stable request fields used to bind credentials to a route.
  *
@@ -252,9 +275,10 @@ export function toClient<
   const method extends Method,
   const context extends z.ZodMiniType | undefined = undefined,
 >(method: method, options: toClient.Options<method, context>): Client<method, context> {
-  const { context, createCredential } = options
+  const { canHandleChallenge, context, createCredential } = options
   return {
     ...method,
+    canHandleChallenge,
     context,
     createCredential,
   } as Client<method, context>
@@ -262,6 +286,7 @@ export function toClient<
 
 export declare namespace toClient {
   type Options<method extends Method, context extends z.ZodMiniType | undefined = undefined> = {
+    canHandleChallenge?: CanHandleChallengeFn | undefined
     context?: context
     createCredential: CreateCredentialFn<
       method,
@@ -291,15 +316,24 @@ export function toServer<
   const defaults extends RequestDefaults<method> = {},
   const transportOverride extends Transport.AnyTransport | undefined = undefined,
   const extensions extends object = {},
+  const options extends toServer.Options<
+    method,
+    defaults,
+    transportOverride,
+    extensions,
+    string | undefined
+  > = toServer.Options<method, defaults, transportOverride, extensions, string | undefined>,
 >(
   method: method,
-  options: toServer.Options<method, defaults, transportOverride, extensions>,
-): Server<method, defaults, transportOverride, extensions> {
+  options: options,
+): Server<method, defaults, transportOverride, extensions, toServer.Alias<options>> {
   const {
+    alias,
     authorize,
     defaults,
     extensions,
     html,
+    preflight,
     request,
     respond,
     stableBinding,
@@ -308,29 +342,36 @@ export function toServer<
   } = options
   return {
     ...method,
+    alias,
     authorize,
     defaults,
     extensions,
     html,
+    preflight,
     request,
     respond,
     stableBinding,
     transport,
     verify,
-  } as Server<method, defaults, transportOverride, extensions>
+  } as Server<method, defaults, transportOverride, extensions, toServer.Alias<options>>
 }
 
 export declare namespace toServer {
+  type Alias<options> = options extends { alias: infer alias extends string } ? alias : undefined
+
   type Options<
     method extends Method,
     defaults extends RequestDefaults<method> = {},
     transportOverride extends Transport.AnyTransport | undefined = undefined,
     extensions extends object = {},
+    alias extends string | undefined = undefined,
   > = {
+    alias?: alias | undefined
     authorize?: AuthorizeFn<method> | undefined
     defaults?: defaults | undefined
     extensions?: extensions | undefined
     html?: Html.Options | undefined
+    preflight?: PreflightFn<method> | undefined
     request?: RequestFn<method> | undefined
     respond?: RespondFn<method> | undefined
     stableBinding?: StableBindingFn<method> | undefined

package/src/Receipt.ts

@@ -1,5 +1,6 @@
 import { Base64 } from 'ox'
 
+import * as Constants from './Constants.js'
 import * as z from './zod.js'
 
 /**
@@ -126,7 +127,7 @@ export function serialize(receipt: Receipt): string {
  * ```
  */
 export function fromResponse(response: Response): Receipt {
-  const header = response.headers.get('Payment-Receipt')
-  if (!header) throw new Error('Missing Payment-Receipt header.')
+  const header = response.headers.get(Constants.Headers.paymentReceipt)
+  if (!header) throw new Error(`Missing ${Constants.Headers.paymentReceipt} header.`)
   return deserialize(header)
 }