@mcpaid/sdk 2.0.0 → 2.1.0

package/dist/settlement/edge-receipts.d.ts

@@ -0,0 +1,173 @@
+/**
+ * MCPaid Edge Receipts Engine
+ * Cryptographic minting and verification of tamper-proof single-use payment receipts
+ * for downstream backend enforcement (e.g. database writes, webhooks, microservices).
+ */
+import type { D1Database } from '../gateway/d1-store.js';
+export interface EdgeReceiptPayload {
+    v: 1;
+    serverId: string;
+    toolName: string;
+    challengeNonce: string;
+    amountMicro: string;
+    recipient: string;
+    treasury: string;
+    feeBps: number;
+    chainId: number;
+    settledAt: number;
+    exp: number;
+    agentWallet?: string;
+    /**
+     * Ledger transaction id of the settlement this receipt attests to.
+     * Present on edge-minted receipts. Lets a downstream backend attribute the
+     * receipt to a ledger entry (and, in future, check it was not refunded —
+     * a receipt proves settlement at time T, not final non-refunded settlement).
+     */
+    txId?: string;
+}
+export interface EdgeReceipt extends EdgeReceiptPayload {
+    sig: string;
+}
+export interface MintEdgeReceiptParams {
+    serverId: string;
+    toolName: string;
+    amountMicro: bigint | string | number;
+    challengeNonce?: string;
+    recipient?: string;
+    treasury?: string;
+    feeBps?: number;
+    chainId?: number;
+    agentWallet?: string;
+    txId?: string;
+    settledAt?: number;
+    ttlSeconds?: number;
+}
+export interface NonceClaimStore {
+    /**
+     * Atomically claims a challenge nonce.
+     * Returns true if successfully claimed (first time).
+     * Returns false if already claimed (replay attack detected).
+     */
+    claimNonce(nonce: string, meta: {
+        serverId: string;
+        toolName: string;
+        exp: number;
+    }): Promise<boolean>;
+    /**
+     * Checks if a nonce has already been claimed.
+     */
+    hasNonce(nonce: string): Promise<boolean>;
+}
+export interface VerifyReceiptEnv {
+    secret: string;
+    previousSecret?: string;
+    store?: NonceClaimStore;
+}
+export type VerifyReceiptInput = VerifyReceiptEnv | string;
+export interface VerifyReceiptOptions {
+    receipt: string | null | undefined;
+    expectedTool?: string;
+    expectedServer?: string;
+    minAmountMicro?: bigint | string | number;
+    maxAgeSeconds?: number;
+    clockSkewSeconds?: number;
+    nowSec?: number;
+}
+/**
+ * Portable base64url encoding.
+ */
+export declare function toBase64Url(input: string): string;
+/**
+ * Portable base64url decoding.
+ */
+export declare function fromBase64Url(input: string): string;
+/**
+ * Derives a deterministic per-server receipt secret from a master secret using HKDF-SHA256.
+ * Limits the blast radius of any individual compromised server secret.
+ * Format: `mcpaid_sec_${64-char hex}`
+ */
+export declare function deriveServerReceiptSecret(masterSecret: string, serverId: string, salt?: string): Promise<string>;
+/**
+ * Mints an authenticated Edge Receipt for a settled tool call.
+ * Returns the receipt object and its base64url-encoded string representation.
+ */
+export declare function mintEdgeReceipt(secret: string, params: MintEdgeReceiptParams): Promise<{
+    receipt: EdgeReceipt;
+    encoded: string;
+}>;
+/**
+ * Validates and verifies an Edge Receipt string against expected tool/server rules and replay claim store.
+ * Returns { valid: true, receipt } if valid, or { valid: false, error } on failure.
+ */
+export declare function parseAndVerifyEdgeReceipt(envInput: VerifyReceiptInput, opts: VerifyReceiptOptions): Promise<{
+    valid: true;
+    receipt: EdgeReceipt;
+} | {
+    valid: false;
+    error: string;
+}>;
+/**
+ * 5-line verification helper for downstream backends.
+ * Returns null if valid and nonce claimed, or an error string describing the failure.
+ *
+ * Note: store infrastructure failures (e.g. D1 outage) THROW rather than
+ * returning an error string, so backends answer 500 (not 402) and the outage
+ * is distinguishable from a replay in logs and monitoring.
+ *
+ * Usage:
+ * ```typescript
+ * const error = await verifyEdgeReceipt(env, {
+ *   receipt: request.headers.get('X-MCPaid-Receipt'),
+ *   expectedTool: 'contextwise_cloud_push',
+ * });
+ * if (error) return new Response(JSON.stringify({ error }), { status: 402 });
+ * ```
+ */
+export declare function verifyEdgeReceipt(env: VerifyReceiptInput, opts: VerifyReceiptOptions): Promise<string | null>;
+/**
+ * In-memory NonceClaimStore for local development, unit tests, and single-instance Node.js backends.
+ */
+export declare class MemoryReceiptStore implements NonceClaimStore {
+    private claimed;
+    /** Hard cap: oldest entries are evicted FIFO past this size (Map preserves insertion order). */
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    claimNonce(nonce: string, meta: {
+        serverId: string;
+        toolName: string;
+        exp: number;
+    }): Promise<boolean>;
+    hasNonce(nonce: string): Promise<boolean>;
+    pruneExpired(nowSec?: number): number;
+    clear(): void;
+}
+/**
+ * Cloudflare D1-backed NonceClaimStore for edge workers and serverless backends.
+ * Uses atomic SQLite INSERT ... ON CONFLICT to guarantee anti-replay under high concurrency.
+ */
+export declare class D1ReceiptStore implements NonceClaimStore {
+    private db;
+    private tableName;
+    constructor(db: D1Database, tableName?: string);
+    claimNonce(nonce: string, meta: {
+        serverId: string;
+        toolName: string;
+        exp: number;
+    }): Promise<boolean>;
+    hasNonce(nonce: string): Promise<boolean>;
+    pruneExpired(nowSec?: number): Promise<number>;
+}
+/**
+ * Drop-in Express / Connect / Node.js HTTP middleware for validating Edge Receipts.
+ */
+export declare function createReceiptMiddleware(options: {
+    secret: string;
+    previousSecret?: string;
+    expectedTool?: string;
+    expectedServer?: string;
+    minAmountMicro?: bigint | string | number;
+    maxAgeSeconds?: number;
+    store?: NonceClaimStore;
+    headerName?: string;
+}): (req: any, res: any, next: (err?: any) => void) => Promise<any>;
+//# sourceMappingURL=edge-receipts.d.ts.map

package/dist/settlement/edge-receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-receipts.d.ts","sourceRoot":"","sources":["../../src/settlement/edge-receipts.ts"],"names":[],"mappings":"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"}

package/dist/settlement/edge-receipts.js

@@ -0,0 +1,472 @@
+/**
+ * MCPaid Edge Receipts Engine
+ * Cryptographic minting and verification of tamper-proof single-use payment receipts
+ * for downstream backend enforcement (e.g. database writes, webhooks, microservices).
+ */
+import { canonicalJsonStringify } from '../utils/units.js';
+/**
+ * Portable base64url encoding.
+ */
+export function toBase64Url(input) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(input, 'utf-8').toString('base64url');
+    }
+    const bytes = new TextEncoder().encode(input);
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++) {
+        bin += String.fromCharCode(bytes[i]);
+    }
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Portable base64url decoding.
+ */
+export function fromBase64Url(input) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(input, 'base64url').toString('utf-8');
+    }
+    let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4 !== 0) {
+        base64 += '=';
+    }
+    const bin = atob(base64);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) {
+        bytes[i] = bin.charCodeAt(i);
+    }
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * Computes an HMAC-SHA256 hex signature using standard Web Crypto API.
+ */
+async function computeHmacSha256(keyString, message) {
+    const enc = new TextEncoder();
+    const keyData = enc.encode(keyString);
+    const msgData = enc.encode(message);
+    const cryptoKey = await crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sigBuffer = await crypto.subtle.sign('HMAC', cryptoKey, msgData);
+    const bytes = new Uint8Array(sigBuffer);
+    let hex = '';
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/**
+ * Constant-time cryptographic verification of HMAC-SHA256 signature using Web Crypto.
+ */
+async function verifyHmacSha256(keyString, expectedSigHex, message) {
+    if (!expectedSigHex || expectedSigHex.length !== 64 || !/^[0-9a-fA-F]+$/.test(expectedSigHex)) {
+        return false;
+    }
+    const enc = new TextEncoder();
+    const keyData = enc.encode(keyString);
+    const msgData = enc.encode(message);
+    try {
+        const cryptoKey = await crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        const sigBytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            sigBytes[i] = parseInt(expectedSigHex.slice(i * 2, i * 2 + 2), 16);
+        }
+        return await crypto.subtle.verify('HMAC', cryptoKey, sigBytes, msgData);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Derives a deterministic per-server receipt secret from a master secret using HKDF-SHA256.
+ * Limits the blast radius of any individual compromised server secret.
+ * Format: `mcpaid_sec_${64-char hex}`
+ */
+export async function deriveServerReceiptSecret(masterSecret, serverId, salt) {
+    if (!masterSecret) {
+        throw new Error('Master secret is required for server receipt secret derivation');
+    }
+    if (!serverId) {
+        throw new Error('serverId is required for server receipt secret derivation');
+    }
+    if (!/^[a-zA-Z0-9_\-\.]{3,64}$/.test(serverId)) {
+        throw new Error('Invalid serverId: must be 3-64 alphanumeric, dash, period, or underscore characters');
+    }
+    const enc = new TextEncoder();
+    const masterKey = await crypto.subtle.importKey('raw', enc.encode(masterSecret), 'HKDF', false, ['deriveBits']);
+    const derivedBits = await crypto.subtle.deriveBits({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: salt ? enc.encode(salt) : new Uint8Array(0),
+        info: enc.encode(`mcpaid-edge-receipt-v1:${serverId}`),
+    }, masterKey, 256 // 32 bytes (256 bits)
+    );
+    const bytes = new Uint8Array(derivedBits);
+    let hex = '';
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return `mcpaid_sec_${hex}`;
+}
+/**
+ * Mints an authenticated Edge Receipt for a settled tool call.
+ * Returns the receipt object and its base64url-encoded string representation.
+ */
+export async function mintEdgeReceipt(secret, params) {
+    if (!secret) {
+        throw new Error('Receipt secret is required to mint an Edge Receipt');
+    }
+    const settledAt = params.settledAt ?? Math.floor(Date.now() / 1000);
+    const ttl = params.ttlSeconds ?? 300; // 5 minutes
+    const exp = settledAt + ttl;
+    const challengeNonce = params.challengeNonce ?? (typeof crypto !== 'undefined' && crypto.randomUUID
+        ? `rcpt_${crypto.randomUUID().replace(/-/g, '')}`
+        : `rcpt_${Date.now().toString(36)}_${Math.random().toString(36).substring(2)}`);
+    const recipient = (params.recipient || '0x0000000000000000000000000000000000000000').toLowerCase();
+    const treasury = (params.treasury || '0x0000000000000000000000000000000000000000').toLowerCase();
+    const feeBps = params.feeBps ?? 300;
+    const chainId = params.chainId ?? 8453;
+    const payload = {
+        v: 1,
+        serverId: params.serverId,
+        toolName: params.toolName,
+        challengeNonce,
+        amountMicro: params.amountMicro.toString(),
+        recipient,
+        treasury,
+        feeBps,
+        chainId,
+        settledAt,
+        exp,
+        ...(params.agentWallet ? { agentWallet: params.agentWallet.toLowerCase() } : {}),
+        ...(params.txId ? { txId: params.txId } : {}),
+    };
+    const canonical = canonicalJsonStringify(payload);
+    const sig = await computeHmacSha256(secret, canonical);
+    const receipt = {
+        ...payload,
+        sig,
+    };
+    const jsonStr = JSON.stringify(receipt);
+    const encoded = toBase64Url(jsonStr);
+    return { receipt, encoded };
+}
+/**
+ * Validates and verifies an Edge Receipt string against expected tool/server rules and replay claim store.
+ * Returns { valid: true, receipt } if valid, or { valid: false, error } on failure.
+ */
+export async function parseAndVerifyEdgeReceipt(envInput, opts) {
+    const env = typeof envInput === 'string' ? { secret: envInput } : envInput;
+    if (!env.secret && !env.previousSecret) {
+        return { valid: false, error: 'Verification error: No verification secret configured' };
+    }
+    const raw = opts.receipt?.trim();
+    if (!raw) {
+        return { valid: false, error: 'Missing receipt: X-MCPaid-Receipt header not provided' };
+    }
+    let receipt;
+    try {
+        const jsonStr = fromBase64Url(raw);
+        receipt = JSON.parse(jsonStr);
+    }
+    catch (err) {
+        return { valid: false, error: `Malformed receipt format: ${err.message}` };
+    }
+    // Version check
+    if (receipt.v !== 1) {
+        return { valid: false, error: `Unsupported receipt version: ${receipt.v}` };
+    }
+    // Required field checks
+    if (!receipt.serverId ||
+        !receipt.toolName ||
+        !receipt.challengeNonce ||
+        !receipt.amountMicro ||
+        !receipt.sig ||
+        receipt.settledAt === undefined ||
+        receipt.exp === undefined) {
+        return { valid: false, error: 'Malformed receipt: missing required fields' };
+    }
+    const nowSec = opts.nowSec ?? Math.floor(Date.now() / 1000);
+    const skew = opts.clockSkewSeconds ?? 60;
+    // Expiry check (with clock skew allowance)
+    if (nowSec > receipt.exp + skew) {
+        return { valid: false, error: `Receipt expired at ${receipt.exp} (current time: ${nowSec})` };
+    }
+    // Max age check
+    const maxAge = opts.maxAgeSeconds ?? 300;
+    if (nowSec - receipt.settledAt > maxAge + skew) {
+        return { valid: false, error: `Receipt age exceeds maximum allowed age (${nowSec - receipt.settledAt}s > ${maxAge}s)` };
+    }
+    // Future timestamp check (prevent pre-dated receipts)
+    if (receipt.settledAt > nowSec + skew) {
+        return { valid: false, error: `Receipt settledAt is in the future (${receipt.settledAt} > ${nowSec})` };
+    }
+    // Server binding check
+    if (opts.expectedServer && receipt.serverId !== opts.expectedServer) {
+        return {
+            valid: false,
+            error: `Receipt server mismatch: expected "${opts.expectedServer}", got "${receipt.serverId}"`,
+        };
+    }
+    // Tool binding check
+    if (opts.expectedTool && receipt.toolName !== opts.expectedTool) {
+        return {
+            valid: false,
+            error: `Receipt tool mismatch: expected "${opts.expectedTool}", got "${receipt.toolName}"`,
+        };
+    }
+    // Minimum amount check
+    if (opts.minAmountMicro !== undefined) {
+        const required = BigInt(opts.minAmountMicro);
+        const actual = BigInt(receipt.amountMicro);
+        if (actual < required) {
+            return {
+                valid: false,
+                error: `Receipt underpaid: required ${required} micro-units, receipt contains ${actual}`,
+            };
+        }
+    }
+    // Recompute HMAC on canonical JSON without `sig`
+    const { sig, ...payload } = receipt;
+    const canonical = canonicalJsonStringify(payload);
+    let isSigValid = false;
+    if (env.secret) {
+        isSigValid = await verifyHmacSha256(env.secret, sig, canonical);
+    }
+    if (!isSigValid && env.previousSecret) {
+        isSigValid = await verifyHmacSha256(env.previousSecret, sig, canonical);
+    }
+    if (!isSigValid) {
+        return { valid: false, error: 'Cryptographic signature mismatch: receipt tampered or secret invalid' };
+    }
+    // Atomic replay defense via NonceClaimStore
+    if (env.store) {
+        const claimed = await env.store.claimNonce(receipt.challengeNonce, {
+            serverId: receipt.serverId,
+            toolName: receipt.toolName,
+            exp: receipt.exp,
+        });
+        if (!claimed) {
+            return {
+                valid: false,
+                error: `Receipt replay attack detected: challenge nonce "${receipt.challengeNonce}" has already been claimed`,
+            };
+        }
+    }
+    else {
+        warnMissingStoreOnce();
+    }
+    return { valid: true, receipt };
+}
+/**
+ * One-time warning when receipts are verified without a replay store.
+ * Signature-only verification cannot detect reuse within the TTL window —
+ * pass a NonceClaimStore (MemoryReceiptStore / D1ReceiptStore) for enforcement.
+ */
+let warnedMissingStore = false;
+function warnMissingStoreOnce() {
+    if (warnedMissingStore)
+        return;
+    warnedMissingStore = true;
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+        console.warn('[MCPaid] verifyEdgeReceipt called without a NonceClaimStore: ' +
+            'signature is checked but replays are NOT rejected. ' +
+            'Pass store: new MemoryReceiptStore() or new D1ReceiptStore(db) for enforcement.');
+    }
+}
+/**
+ * 5-line verification helper for downstream backends.
+ * Returns null if valid and nonce claimed, or an error string describing the failure.
+ *
+ * Note: store infrastructure failures (e.g. D1 outage) THROW rather than
+ * returning an error string, so backends answer 500 (not 402) and the outage
+ * is distinguishable from a replay in logs and monitoring.
+ *
+ * Usage:
+ * ```typescript
+ * const error = await verifyEdgeReceipt(env, {
+ *   receipt: request.headers.get('X-MCPaid-Receipt'),
+ *   expectedTool: 'contextwise_cloud_push',
+ * });
+ * if (error) return new Response(JSON.stringify({ error }), { status: 402 });
+ * ```
+ */
+export async function verifyEdgeReceipt(env, opts) {
+    const result = await parseAndVerifyEdgeReceipt(env, opts);
+    return result.valid ? null : result.error;
+}
+/**
+ * In-memory NonceClaimStore for local development, unit tests, and single-instance Node.js backends.
+ */
+export class MemoryReceiptStore {
+    claimed = new Map();
+    /** Hard cap: oldest entries are evicted FIFO past this size (Map preserves insertion order). */
+    maxSize;
+    constructor(maxSize = 5000) {
+        this.maxSize = maxSize;
+    }
+    async claimNonce(nonce, meta) {
+        const key = nonce.toLowerCase().trim();
+        if (this.claimed.has(key)) {
+            return false; // Already claimed
+        }
+        // Prefer dropping expired entries; if still over budget, evict oldest.
+        if (this.claimed.size >= this.maxSize) {
+            this.pruneExpired();
+            while (this.claimed.size >= this.maxSize) {
+                const oldest = this.claimed.keys().next();
+                if (oldest.done)
+                    break;
+                this.claimed.delete(oldest.value);
+            }
+        }
+        this.claimed.set(key, meta);
+        return true;
+    }
+    async hasNonce(nonce) {
+        return this.claimed.has(nonce.toLowerCase().trim());
+    }
+    pruneExpired(nowSec = Math.floor(Date.now() / 1000)) {
+        let count = 0;
+        for (const [k, v] of this.claimed.entries()) {
+            if (v.exp < nowSec) {
+                this.claimed.delete(k);
+                count++;
+            }
+        }
+        return count;
+    }
+    clear() {
+        this.claimed.clear();
+    }
+}
+/**
+ * Cloudflare D1-backed NonceClaimStore for edge workers and serverless backends.
+ * Uses atomic SQLite INSERT ... ON CONFLICT to guarantee anti-replay under high concurrency.
+ */
+export class D1ReceiptStore {
+    db;
+    tableName;
+    constructor(db, tableName = 'mcpaid_receipt_nonces') {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tableName)) {
+            throw new Error(`Invalid receipt nonce table name: "${tableName}"`);
+        }
+        this.db = db;
+        this.tableName = tableName;
+    }
+    async claimNonce(nonce, meta) {
+        const key = nonce.toLowerCase().trim();
+        try {
+            const stmt = this.db
+                .prepare(`INSERT INTO ${this.tableName} (nonce, server_id, tool_name, exp)
+           VALUES (?, ?, ?, ?)
+           ON CONFLICT(nonce) DO NOTHING`)
+                .bind(key, meta.serverId, meta.toolName, meta.exp);
+            const res = await stmt.run();
+            // Opportunistic pruning: ~2% of claims sweep expired rows so the
+            // table does not grow by one row per paid call forever. A scheduled
+            // `DELETE WHERE exp < now()` is still recommended for high volume.
+            if (Math.random() < 0.02) {
+                await this.pruneExpired().catch(() => { });
+            }
+            const changes = res.meta?.changes ?? res.meta?.rows_written;
+            if (changes !== undefined) {
+                return changes > 0;
+            }
+            return !(await this.hasNonce(key));
+        }
+        catch (err) {
+            // Fail closed, but distinguish a genuine replay (unique violation)
+            // from an infrastructure outage so the two are observable separately.
+            if (isUniqueViolation(err)) {
+                return false;
+            }
+            throw new Error(`Receipt nonce claim failed: ${err?.message || err}`);
+        }
+    }
+    async hasNonce(nonce) {
+        const key = nonce.toLowerCase().trim();
+        const row = await this.db
+            .prepare(`SELECT nonce FROM ${this.tableName} WHERE nonce = ?`)
+            .bind(key)
+            .first();
+        return Boolean(row);
+    }
+    async pruneExpired(nowSec = Math.floor(Date.now() / 1000)) {
+        const res = await this.db
+            .prepare(`DELETE FROM ${this.tableName} WHERE exp < ?`)
+            .bind(nowSec)
+            .run();
+        return res.meta?.changes ?? 0;
+    }
+}
+/**
+ * Detects unique-constraint violations across SQLite/D1 drivers so a genuine
+ * replay is distinguishable from a transport outage (see D1ReceiptStore).
+ */
+function isUniqueViolation(err) {
+    const msg = `${err?.message || err || ''}`.toLowerCase();
+    return (msg.includes('unique') ||
+        msg.includes('constraint') ||
+        msg.includes('conflict') ||
+        msg.includes('already exists') ||
+        (typeof err?.code === 'string' && /constraint|conflict|unique/i.test(err.code)));
+}
+/**
+ * Drop-in Express / Connect / Node.js HTTP middleware for validating Edge Receipts.
+ */
+export function createReceiptMiddleware(options) {
+    // Tool binding is load-bearing: without it a receipt for a cheap tool
+    // authorizes an expensive one. Refuse to construct an unbound middleware
+    // instead of silently falling back to body-sniffing (which fails open
+    // whenever the body is absent or not a tools/call).
+    if (!options.expectedTool || typeof options.expectedTool !== 'string') {
+        throw new Error('createReceiptMiddleware requires expectedTool: a receipt for one tool must never authorize another');
+    }
+    const header = options.headerName || 'x-mcpaid-receipt';
+    const prevSecret = options.previousSecret ||
+        (typeof process !== 'undefined' ? process.env?.MCPAID_PREVIOUS_RECEIPT_SECRET : undefined);
+    return async (req, res, next) => {
+        try {
+            let receiptHeader;
+            if (typeof req.get === 'function') {
+                receiptHeader = req.get(header);
+            }
+            if (!receiptHeader && req.headers && typeof req.headers === 'object') {
+                const target = header.toLowerCase();
+                for (const [k, v] of Object.entries(req.headers)) {
+                    if (k.toLowerCase() === target) {
+                        receiptHeader = Array.isArray(v) ? v[0] : v;
+                        break;
+                    }
+                }
+            }
+            // expectedTool is guaranteed by the constructor guard above.
+            const result = await parseAndVerifyEdgeReceipt({
+                secret: options.secret,
+                previousSecret: prevSecret,
+                store: options.store,
+            }, {
+                receipt: receiptHeader,
+                expectedTool: options.expectedTool,
+                expectedServer: options.expectedServer,
+                minAmountMicro: options.minAmountMicro,
+                maxAgeSeconds: options.maxAgeSeconds,
+            });
+            if (!result.valid) {
+                if (typeof res.status === 'function' && typeof res.json === 'function') {
+                    return res.status(402).json({
+                        error: 'payment_required',
+                        message: result.error,
+                    });
+                }
+                res.writeHead(402, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'payment_required', message: result.error }));
+                return;
+            }
+            req.mcpaidReceipt = result.receipt;
+            next();
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+}
+//# sourceMappingURL=edge-receipts.js.map