mppx 0.0.1 → 0.1.1

package/dist/tempo/stream/Sse.js

@@ -0,0 +1,288 @@
+import * as Credential from '../../Credential.js';
+import * as ChannelStore from './ChannelStore.js';
+import { createStreamReceipt } from './Receipt.js';
+/**
+ * Format a stream receipt as a Server-Sent Event.
+ *
+ * Produces a valid SSE event string with `event: payment-receipt`
+ * and the receipt JSON as the `data` field.
+ */
+export function formatReceiptEvent(receipt) {
+    return `event: payment-receipt\ndata: ${JSON.stringify(receipt)}\n\n`;
+}
+/**
+ * Format a need-voucher event as a Server-Sent Event.
+ *
+ * Emitted when the channel balance is exhausted mid-stream.
+ * The client responds by sending a new voucher credential to
+ * any mppx-protected endpoint.
+ */
+export function formatNeedVoucherEvent(params) {
+    return `event: payment-need-voucher\ndata: ${JSON.stringify(params)}\n\n`;
+}
+/**
+ * Parse a raw SSE event string into a typed event.
+ *
+ * Handles the three event types used by mppx streaming:
+ * - `message` (default / no event field) — application data
+ * - `payment-need-voucher` — balance exhausted, client should send voucher
+ * - `payment-receipt` — final receipt
+ */
+export function parseEvent(raw) {
+    let eventType = 'message';
+    const dataLines = [];
+    for (const line of raw.split('\n')) {
+        if (line.startsWith('event: ')) {
+            eventType = line.slice(7).trim();
+        }
+        else if (line.startsWith('data: ')) {
+            dataLines.push(line.slice(6));
+        }
+        else if (line === 'data:') {
+            dataLines.push('');
+        }
+    }
+    if (dataLines.length === 0)
+        return null;
+    const data = dataLines.join('\n');
+    switch (eventType) {
+        case 'message':
+            return { type: 'message', data };
+        case 'payment-need-voucher':
+            return { type: 'payment-need-voucher', data: JSON.parse(data) };
+        case 'payment-receipt':
+            return { type: 'payment-receipt', data: JSON.parse(data) };
+        default:
+            return { type: 'message', data };
+    }
+}
+/**
+ * Wrap an async iterable with payment metering, producing an SSE stream.
+ *
+ * `generate` may be either:
+ * - An `AsyncIterable<string>` — each yielded value is automatically charged
+ *   (one `tickCost` per value).
+ * - A callback `(stream: StreamController) => AsyncIterable<string>` — the
+ *   generator controls when charges happen by calling `stream.charge()`.
+ *
+ * For each emitted value the stream:
+ * 1. Deducts `tickCost` from the channel balance atomically (auto or manual).
+ * 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. On generator completion, emits a final `event: payment-receipt`.
+ *
+ * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
+ */
+export function serve(options) {
+    const { store, channelId, challengeId, tickCost, generate, pollIntervalMs = 100, signal, } = options;
+    const encoder = new TextEncoder();
+    return new ReadableStream({
+        async start(controller) {
+            const aborted = () => signal?.aborted ?? false;
+            const emit = (event) => controller.enqueue(encoder.encode(event));
+            const charge = () => chargeOrWait({
+                store,
+                channelId,
+                amount: tickCost,
+                emit,
+                pollIntervalMs,
+                signal,
+            });
+            const iterable = typeof generate === 'function' ? generate({ charge }) : generate;
+            try {
+                for await (const value of iterable) {
+                    if (aborted())
+                        break;
+                    if (typeof generate !== 'function')
+                        await charge();
+                    controller.enqueue(encoder.encode(`event: message\ndata: ${value}\n\n`));
+                }
+                if (!aborted()) {
+                    const channel = await store.getChannel(channelId);
+                    if (channel) {
+                        const receipt = createStreamReceipt({
+                            challengeId,
+                            channelId,
+                            acceptedCumulative: channel.highestVoucherAmount,
+                            spent: channel.spent,
+                            units: channel.units,
+                        });
+                        controller.enqueue(encoder.encode(formatReceiptEvent(receipt)));
+                    }
+                }
+            }
+            catch (e) {
+                if (!aborted())
+                    controller.error(e);
+            }
+            finally {
+                controller.close();
+            }
+        },
+    });
+}
+/**
+ * Wrap a `ReadableStream<Uint8Array>` (from {@link serve}) in an HTTP
+ * `Response` with the correct SSE headers.
+ */
+export function toResponse(body) {
+    return new Response(body, {
+        headers: {
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+            'Content-Type': 'text/event-stream; charset=utf-8',
+        },
+    });
+}
+/**
+ * Extract `channelId`, `challengeId`, and `tickCost` from a `Request`'s
+ * `Authorization: Payment …` header.
+ *
+ * This is a convenience for callers that receive a raw `Request` and need
+ * the parameters required by {@link serve}.
+ */
+export function fromRequest(request) {
+    const header = request.headers.get('Authorization');
+    if (!header)
+        throw new Error('Missing Authorization header.');
+    const payment = Credential.extractPaymentScheme(header);
+    if (!payment)
+        throw new Error('Missing Payment credential in Authorization header.');
+    const credential = Credential.deserialize(payment);
+    const payload = credential.payload;
+    return {
+        challengeId: credential.challenge.id,
+        channelId: payload.channelId,
+        tickCost: BigInt(credential.challenge.request.amount),
+    };
+}
+/**
+ * Atomically deduct `amount` from a channel, retrying when balance is
+ * insufficient. Uses `store.waitForUpdate()` when available for
+ * event-driven wakeups, falling back to polling otherwise. Emits
+ * `payment-need-voucher` events via `emit` while waiting.
+ */
+async function chargeOrWait(options) {
+    const { store, channelId, amount, emit, pollIntervalMs, signal } = options;
+    let result = await ChannelStore.deductFromChannel(store, channelId, amount);
+    if (!result.ok) {
+        // Emit a single need-voucher event, then poll/wait until the client
+        // sends an updated voucher. The requiredCumulative is constant here:
+        // `spent` only changes on successful deduction (which exits the loop),
+        // so re-emitting on every poll cycle would just cause redundant
+        // voucher POSTs from the client.
+        emit(formatNeedVoucherEvent({
+            channelId,
+            requiredCumulative: (result.channel.spent + amount).toString(),
+            acceptedCumulative: result.channel.highestVoucherAmount.toString(),
+            deposit: result.channel.deposit.toString(),
+        }));
+        while (!result.ok) {
+            await waitForUpdate(store, channelId, pollIntervalMs, signal);
+            result = await ChannelStore.deductFromChannel(store, channelId, amount);
+        }
+    }
+}
+async function waitForUpdate(store, channelId, pollIntervalMs, signal) {
+    if (signal?.aborted)
+        throw new Error('Aborted while waiting for voucher');
+    if (store.waitForUpdate) {
+        await Promise.race([store.waitForUpdate(channelId), ...(signal ? [abortPromise(signal)] : [])]);
+    }
+    else {
+        await sleep(pollIntervalMs);
+    }
+    if (signal?.aborted)
+        throw new Error('Aborted while waiting for voucher');
+}
+function abortPromise(signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Check whether a `Response` carries an SSE event stream.
+ *
+ * Returns `true` when the `Content-Type` header starts with
+ * `text/event-stream` (case-insensitive, ignoring charset params).
+ */
+export function isEventStream(response) {
+    const ct = response.headers.get('content-type');
+    return ct?.toLowerCase().startsWith('text/event-stream') ?? false;
+}
+/**
+ * Parse an SSE `Response` body into an async iterable of `data:` payloads.
+ *
+ * Yields the raw `data:` field content for each SSE event in the stream.
+ * Events whose data matches the `skip` predicate are silently dropped
+ * (e.g. `[DONE]` sentinels used by OpenAI-compatible APIs).
+ *
+ * Each yielded value typically becomes one charge tick when fed to
+ * {@link serve} via the SSE transport's auto-charge mode.
+ *
+ * @example
+ * ```ts
+ * const upstream = await fetch('https://api.example.com/stream')
+ * for await (const data of Sse.iterateData(upstream)) {
+ *   console.log(data)
+ * }
+ * ```
+ */
+export async function* iterateData(response, options) {
+    const skip = options?.skip;
+    const body = response.body;
+    if (!body)
+        return;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Split on double-newline SSE event boundaries.
+            const events = buffer.split('\n\n');
+            // Last element may be incomplete — keep in buffer.
+            buffer = events.pop() ?? '';
+            for (const event of events) {
+                if (!event.trim())
+                    continue;
+                const data = extractData(event);
+                if (data === null)
+                    continue;
+                if (skip?.(data))
+                    continue;
+                yield data;
+            }
+        }
+        // Flush remaining buffer.
+        if (buffer.trim()) {
+            const data = extractData(buffer);
+            if (data !== null && !skip?.(data))
+                yield data;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** Extract the `data:` field value from a single SSE event block. */
+function extractData(event) {
+    const dataLines = [];
+    for (const line of event.split('\n')) {
+        if (line.startsWith('data: '))
+            dataLines.push(line.slice(6));
+        else if (line === 'data:')
+            dataLines.push('');
+    }
+    return dataLines.length > 0 ? dataLines.join('\n') : null;
+}
+//# sourceMappingURL=Sse.js.map

package/dist/tempo/stream/Sse.js.map

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

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

@@ -0,0 +1,78 @@
+import type { Address, Hex } from 'viem';
+/**
+ * Voucher for cumulative payment.
+ * Cumulative monotonicity prevents replay attacks.
+ */
+export interface Voucher {
+    channelId: Hex;
+    cumulativeAmount: bigint;
+}
+/**
+ * Signed voucher with EIP-712 signature.
+ */
+export interface SignedVoucher extends Voucher {
+    signature: Hex;
+}
+/**
+ * Stream credential payload (discriminated union).
+ */
+export type StreamCredentialPayload = {
+    action: 'open';
+    type: 'transaction';
+    channelId: Hex;
+    transaction: Hex;
+    signature: Hex;
+    authorizedSigner?: Address | undefined;
+    cumulativeAmount: string;
+} | {
+    action: 'topUp';
+    type: 'transaction';
+    channelId: Hex;
+    transaction: Hex;
+    additionalDeposit: string;
+} | {
+    action: 'voucher';
+    channelId: Hex;
+    cumulativeAmount: string;
+    signature: Hex;
+} | {
+    action: 'close';
+    channelId: Hex;
+    cumulativeAmount: string;
+    signature: Hex;
+};
+/**
+ * SSE event emitted when session balance is exhausted mid-stream.
+ * The client responds by sending a new voucher credential.
+ *
+ * Per spec §11.6, the event data contains:
+ * - `channelId` — channel identifier
+ * - `requiredCumulative` — minimum cumulative amount the next voucher must authorize
+ * - `acceptedCumulative` — current highest accepted voucher amount
+ * - `deposit` — current on-chain deposit ceiling; when `requiredCumulative > deposit`
+ *   the client must top up the channel before sending a new voucher
+ */
+export interface NeedVoucherEvent {
+    channelId: Hex;
+    requiredCumulative: string;
+    acceptedCumulative: string;
+    deposit: string;
+}
+/**
+ * Stream receipt returned in Payment-Receipt header.
+ */
+export interface StreamReceipt {
+    method: 'tempo';
+    intent: 'session';
+    status: 'success';
+    timestamp: string;
+    /** Payment reference (channelId). Satisfies Receipt.Receipt contract. */
+    reference: string;
+    challengeId: string;
+    channelId: Hex;
+    acceptedCumulative: string;
+    spent: string;
+    units?: number | undefined;
+    txHash?: Hex | undefined;
+}
+//# sourceMappingURL=Types.d.ts.map

package/dist/tempo/stream/Types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../../src/tempo/stream/Types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAExC;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,GAAG,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,OAAO;IAC5C,SAAS,EAAE,GAAG,CAAA;CACf;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IACE,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,aAAa,CAAA;IACnB,SAAS,EAAE,GAAG,CAAA;IACd,WAAW,EAAE,GAAG,CAAA;IAChB,SAAS,EAAE,GAAG,CAAA;IACd,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,gBAAgB,EAAE,MAAM,CAAA;CACzB,GACD;IACE,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,aAAa,CAAA;IACnB,SAAS,EAAE,GAAG,CAAA;IACd,WAAW,EAAE,GAAG,CAAA;IAChB,iBAAiB,EAAE,MAAM,CAAA;CAC1B,GACD;IACE,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,GAAG,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,GAAG,CAAA;CACf,GACD;IACE,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,GAAG,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,GAAG,CAAA;CACf,CAAA;AAEL;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,GAAG,CAAA;IACd,kBAAkB,EAAE,MAAM,CAAA;IAC1B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,GAAG,CAAA;IACd,kBAAkB,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,MAAM,CAAC,EAAE,GAAG,GAAG,SAAS,CAAA;CACzB"}

package/dist/tempo/stream/Types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Types.js.map

package/dist/tempo/stream/Types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Types.js","sourceRoot":"","sources":["../../../src/tempo/stream/Types.ts"],"names":[],"mappings":""}

package/dist/tempo/stream/Voucher.d.ts

@@ -0,0 +1,20 @@
+import { type Address } from 'ox';
+import type { Account, Client, Hex } from 'viem';
+import type { SignedVoucher, Voucher } from './Types.js';
+/**
+ * Sign a voucher with an account.
+ */
+export declare function signVoucher(client: Client, account: Account, message: Voucher, escrowContract: Address.Address, chainId: number, authorizedSigner?: Address.Address | undefined): Promise<Hex>;
+/**
+ * Verify a voucher signature matches the expected signer.
+ *
+ * Supports both direct signatures (secp256k1/p256/webAuthn) and
+ * Tempo access key (keychain) signatures. For keychain signatures,
+ * the envelope's `userAddress` is compared to `expectedSigner`.
+ */
+export declare function verifyVoucher(escrowContract: Address.Address, chainId: number, voucher: SignedVoucher, expectedSigner: Address.Address): Promise<boolean>;
+/**
+ * Parse a voucher from credential payload.
+ */
+export declare function parseVoucherFromPayload(channelId: Hex, cumulativeAmount: string, signature: Hex): SignedVoucher;
+//# sourceMappingURL=Voucher.d.ts.map

package/dist/tempo/stream/Voucher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Voucher.d.ts","sourceRoot":"","sources":["../../../src/tempo/stream/Voucher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,IAAI,CAAA;AAE5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAGhD,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AA8BxD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,OAAO,CAAC,OAAO,EAC/B,OAAO,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,OAAO,CAAC,OAAO,GAAG,SAAS,GAC7C,OAAO,CAAC,GAAG,CAAC,CAyBd;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,cAAc,EAAE,OAAO,CAAC,OAAO,EAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,EACtB,cAAc,EAAE,OAAO,CAAC,OAAO,GAC9B,OAAO,CAAC,OAAO,CAAC,CAuBlB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,GAAG,EACd,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,GAAG,GACb,aAAa,CAMf"}

package/dist/tempo/stream/Voucher.js

@@ -0,0 +1,98 @@
+import { Signature } from 'ox';
+import { SignatureEnvelope } from 'ox/tempo';
+import { isAddressEqual, recoverTypedDataAddress } from 'viem';
+import { signTypedData } from 'viem/actions';
+/** Must match the on-chain TempoStreamChannel DOMAIN_SEPARATOR name. */
+const DOMAIN_NAME = 'Tempo Stream Channel';
+/** Must match the on-chain TempoStreamChannel DOMAIN_SEPARATOR version. */
+const DOMAIN_VERSION = '1';
+/**
+ * EIP-712 domain for voucher signing.
+ */
+function getVoucherDomain(escrowContract, chainId) {
+    return {
+        name: DOMAIN_NAME,
+        version: DOMAIN_VERSION,
+        chainId,
+        verifyingContract: escrowContract,
+    };
+}
+/**
+ * EIP-712 types for voucher signing.
+ * Matches @tempo/stream-channels/voucher and on-chain VOUCHER_TYPEHASH.
+ */
+const voucherTypes = {
+    Voucher: [
+        { name: 'channelId', type: 'bytes32' },
+        { name: 'cumulativeAmount', type: 'uint128' },
+    ],
+};
+/**
+ * Sign a voucher with an account.
+ */
+export async function signVoucher(client, account, message, escrowContract, chainId, authorizedSigner) {
+    const signature = await signTypedData(client, {
+        account,
+        domain: getVoucherDomain(escrowContract, chainId),
+        types: voucherTypes,
+        primaryType: 'Voucher',
+        message: {
+            channelId: message.channelId,
+            cumulativeAmount: message.cumulativeAmount,
+        },
+    });
+    // When a separate authorizedSigner is used (e.g. access key), unwrap the
+    // keychain envelope — the escrow contract verifies raw ECDSA signatures
+    // against authorizedSigner, not keychain-wrapped ones.
+    // TODO: when TIP-1020 is implemented, we can remove this.
+    if (authorizedSigner) {
+        try {
+            const envelope = SignatureEnvelope.from(signature);
+            if (envelope.type === 'keychain' && envelope.inner.type === 'secp256k1')
+                return Signature.toHex(envelope.inner.signature);
+        }
+        catch { }
+    }
+    return signature;
+}
+/**
+ * Verify a voucher signature matches the expected signer.
+ *
+ * Supports both direct signatures (secp256k1/p256/webAuthn) and
+ * Tempo access key (keychain) signatures. For keychain signatures,
+ * the envelope's `userAddress` is compared to `expectedSigner`.
+ */
+export async function verifyVoucher(escrowContract, chainId, voucher, expectedSigner) {
+    try {
+        const domain = getVoucherDomain(escrowContract, chainId);
+        const message = {
+            channelId: voucher.channelId,
+            cumulativeAmount: voucher.cumulativeAmount,
+        };
+        const envelope = SignatureEnvelope.from(voucher.signature);
+        if (envelope.type === 'keychain')
+            return isAddressEqual(envelope.userAddress, expectedSigner);
+        const signer = await recoverTypedDataAddress({
+            domain,
+            types: voucherTypes,
+            primaryType: 'Voucher',
+            message,
+            signature: voucher.signature,
+        });
+        return isAddressEqual(signer, expectedSigner);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse a voucher from credential payload.
+ */
+export function parseVoucherFromPayload(channelId, cumulativeAmount, signature) {
+    return {
+        channelId,
+        cumulativeAmount: BigInt(cumulativeAmount),
+        signature,
+    };
+}
+//# sourceMappingURL=Voucher.js.map

package/dist/tempo/stream/Voucher.js.map

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