@runtab/mcp 0.0.1

package/dist/payment-envelope-journal.js

@@ -0,0 +1,116 @@
+import { readPaymentAuthorizationState } from "./payment-authorization-state.js";
+import { parsePaymentEnvelope } from "./payment-envelope.js";
+import { PaymentEnvelopeStoreError } from "./payment-envelope-store.js";
+import { parsePaymentSettlementObservation } from "./payment-settlement-observation.js";
+export class PaymentIdempotencyRequiredError extends Error {
+    code = "PAYMENT_IDEMPOTENCY_KEY_REQUIRED";
+    constructor() {
+        super("A payment idempotency key is required for paid requests.");
+        this.name = "PaymentIdempotencyRequiredError";
+    }
+}
+export class PaymentReconciliationRequiredError extends Error {
+    code = "PAYMENT_RECONCILIATION_REQUIRED";
+    constructor() {
+        super("A previous payment must be reconciled before a new authorization can be created.");
+        this.name = "PaymentReconciliationRequiredError";
+    }
+}
+export class PaymentEnvelopeJournal {
+    #address;
+    #authorizationState;
+    #nowSeconds;
+    #paymentProfile;
+    #signer;
+    #store;
+    constructor(options) {
+        this.#address = options.address;
+        this.#authorizationState = options.authorizationState ?? readPaymentAuthorizationState;
+        this.#nowSeconds = options.nowSeconds ?? (() => Math.floor(Date.now() / 1_000));
+        this.#paymentProfile = options.paymentProfile;
+        this.#signer = options.signer;
+        this.#store = options.store;
+    }
+    async #removeIfExpiredAndUnused(idempotencyKey, requestFingerprint, envelope) {
+        if (envelope.state === "settled" || envelope.validBefore > this.#nowSeconds())
+            return false;
+        let authorizationState;
+        try {
+            return await this.#store.removeIfPending(idempotencyKey, requestFingerprint, async (current) => {
+                if (current.validBefore > this.#nowSeconds())
+                    return false;
+                const parsed = await parsePaymentEnvelope(current.paymentSignature, this.#address, this.#paymentProfile);
+                authorizationState = await this.#authorizationState(parsed);
+                if (authorizationState !== "unused")
+                    return false;
+                return this.#signer.reconcileExpiredPayment(current.receiptId);
+            });
+        }
+        catch (error) {
+            if (error instanceof PaymentEnvelopeStoreError &&
+                error.code === "PAYMENT_ENVELOPE_CHAIN_STATE_UNRESOLVED" &&
+                authorizationState === "used") {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async load(idempotencyKey, requestFingerprint) {
+        const pending = await this.#store.findUnsettled();
+        if (pending && pending.idempotencyKey !== idempotencyKey) {
+            const removed = await this.#removeIfExpiredAndUnused(pending.idempotencyKey, pending.record.requestFingerprint, pending.record);
+            if (!removed)
+                throw new PaymentReconciliationRequiredError();
+        }
+        const existing = await this.#store.find(idempotencyKey, requestFingerprint);
+        if (!existing)
+            return null;
+        const removed = await this.#removeIfExpiredAndUnused(idempotencyKey, requestFingerprint, existing);
+        return removed ? null : existing;
+    }
+    async getOrCreate(idempotencyKey, requestFingerprint, factory) {
+        try {
+            return (await this.#store.getOrCreate(idempotencyKey, requestFingerprint, factory)).record;
+        }
+        catch (error) {
+            if (error instanceof PaymentEnvelopeStoreError && error.code === "PAYMENT_ENVELOPE_PENDING") {
+                throw new PaymentReconciliationRequiredError();
+            }
+            throw error;
+        }
+    }
+    async parse(envelope) {
+        const parsed = await parsePaymentEnvelope(envelope.paymentSignature, this.#address, this.#paymentProfile);
+        if (parsed.validBefore !== envelope.validBefore) {
+            throw new Error("Stored payment envelope is invalid");
+        }
+        this.#signer.restorePaymentCorrelation(parsed.signature, envelope.receiptId, envelope.validBefore);
+        return parsed;
+    }
+    async recordObservation(idempotencyKey, requestFingerprint, parsed, value) {
+        const observation = parsePaymentSettlementObservation(value, {
+            amount: parsed.payload.accepted.amount,
+            network: parsed.payload.accepted.network,
+            payer: this.#address,
+        });
+        if (!observation)
+            return null;
+        return this.#store.markObserved(idempotencyKey, requestFingerprint, observation);
+    }
+    async reconcileObserved(idempotencyKey, requestFingerprint, envelope, parsed) {
+        if (!envelope.settlementObservation)
+            return { status: "ignored", verified: false };
+        const result = await this.#signer.reportPaymentObservation({
+            paymentPayload: parsed.payload,
+            requirements: parsed.payload.accepted,
+            settleResponse: envelope.settlementObservation,
+        });
+        if (result.status === "settled" && result.verified) {
+            await this.#store.markSettled(idempotencyKey, requestFingerprint);
+        }
+        return result;
+    }
+    markSettled(idempotencyKey, requestFingerprint) {
+        return this.#store.markSettled(idempotencyKey, requestFingerprint);
+    }
+}

package/dist/payment-envelope-lock.d.ts

@@ -0,0 +1,5 @@
+export interface PaymentEnvelopeLockOptions {
+    lockRetryDelayMs: number;
+    lockTimeoutMs: number;
+}
+export declare function withPaymentEnvelopeLock<T>(directory: string, options: PaymentEnvelopeLockOptions, deadline: number, task: () => Promise<T>): Promise<T>;

package/dist/payment-envelope-lock.js

@@ -0,0 +1,88 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { performance } from "node:perf_hooks";
+import { tryLock, unlock } from "fs-native-extensions";
+import { PaymentEnvelopeStoreError } from "./payment-envelope-model.js";
+const LOCK_FILE = ".payment-envelopes.lock";
+function lockFailure() {
+    return new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_CORRUPT", "The durable payment envelope lock failed safely.");
+}
+function pause(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function openAnchor(directory) {
+    let handle;
+    try {
+        handle = await open(`${directory}/${LOCK_FILE}`, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+        const metadata = await handle.stat();
+        if (!metadata.isFile())
+            throw lockFailure();
+        await handle.chmod(0o600);
+        return handle;
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        if (error instanceof PaymentEnvelopeStoreError)
+            throw error;
+        throw lockFailure();
+    }
+}
+async function acquire(directory, options, deadline) {
+    const handle = await openAnchor(directory);
+    try {
+        while (true) {
+            if (performance.now() >= deadline) {
+                throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_LOCK_TIMEOUT", "The durable payment envelope lock timed out.");
+            }
+            let acquired;
+            try {
+                acquired = tryLock(handle.fd);
+            }
+            catch {
+                throw lockFailure();
+            }
+            if (acquired)
+                return handle;
+            const remaining = deadline - performance.now();
+            if (remaining <= 0) {
+                throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_LOCK_TIMEOUT", "The durable payment envelope lock timed out.");
+            }
+            await pause(Math.min(options.lockRetryDelayMs, remaining));
+        }
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+export async function withPaymentEnvelopeLock(directory, options, deadline, task) {
+    const handle = await acquire(directory, options, deadline);
+    let completed = false;
+    let releaseError;
+    let taskError;
+    let value;
+    try {
+        value = await task();
+        completed = true;
+    }
+    catch (error) {
+        taskError = error;
+    }
+    try {
+        unlock(handle.fd);
+    }
+    catch {
+        releaseError = lockFailure();
+    }
+    try {
+        await handle.close();
+    }
+    catch {
+        releaseError = lockFailure();
+    }
+    if (releaseError)
+        throw releaseError;
+    if (!completed)
+        throw taskError;
+    return value;
+}

package/dist/payment-envelope-model.d.ts

@@ -0,0 +1,32 @@
+import { type PaymentSettlementObservation } from "./payment-settlement-observation.js";
+export declare const MAX_PAYMENT_ENVELOPE_RECORDS = 1024;
+export declare const MAX_PAYMENT_ENVELOPE_STORE_BYTES: number;
+export type PaymentEnvelopeState = "observed" | "pending" | "settled";
+export interface PaymentEnvelopeRecord {
+    readonly createdAt: string;
+    readonly paymentSignature: string;
+    readonly receiptId: string;
+    readonly requestFingerprint: string;
+    readonly settlementObservation?: PaymentSettlementObservation;
+    readonly state: PaymentEnvelopeState;
+    readonly updatedAt: string;
+    readonly validBefore: number;
+}
+export interface NewPaymentEnvelope {
+    readonly paymentSignature: string;
+    readonly receiptId: string;
+    readonly validBefore: number;
+}
+export interface PaymentEnvelopeDocument {
+    records: Record<string, PaymentEnvelopeRecord>;
+    version: 1;
+}
+export type PaymentEnvelopeStoreErrorCode = "PAYMENT_ENVELOPE_CAPACITY" | "PAYMENT_ENVELOPE_CHAIN_STATE_UNRESOLVED" | "PAYMENT_ENVELOPE_CONFLICT" | "PAYMENT_ENVELOPE_CORRUPT" | "PAYMENT_ENVELOPE_INVALID_INPUT" | "PAYMENT_ENVELOPE_LOCK_TIMEOUT" | "PAYMENT_ENVELOPE_NOT_FOUND" | "PAYMENT_ENVELOPE_OVERSIZE" | "PAYMENT_ENVELOPE_PENDING";
+export declare class PaymentEnvelopeStoreError extends Error {
+    readonly code: PaymentEnvelopeStoreErrorCode;
+    constructor(code: PaymentEnvelopeStoreErrorCode, message: string);
+}
+export declare function validatePaymentIdempotencyKey(value: string): string;
+export declare function validateRequestFingerprint(value: string): string;
+export declare function validateNewPaymentEnvelope(value: NewPaymentEnvelope): NewPaymentEnvelope;
+export declare function parsePaymentEnvelopeDocument(value: unknown): PaymentEnvelopeDocument;

package/dist/payment-envelope-model.js

@@ -0,0 +1,123 @@
+import { parsePaymentSettlementObservation, } from "./payment-settlement-observation.js";
+export const MAX_PAYMENT_ENVELOPE_RECORDS = 1_024;
+export const MAX_PAYMENT_ENVELOPE_STORE_BYTES = 4 * 1_024 * 1_024;
+export class PaymentEnvelopeStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PaymentEnvelopeStoreError";
+    }
+}
+function invalid() {
+    throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_CORRUPT", "The durable payment envelope store is invalid.");
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+        invalid();
+    }
+}
+function canonicalTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const timestamp = new Date(value);
+    return Number.isFinite(timestamp.valueOf()) && timestamp.toISOString() === value;
+}
+export function validatePaymentIdempotencyKey(value) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) {
+        throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_INVALID_INPUT", "The payment idempotency key is invalid.");
+    }
+    return value;
+}
+export function validateRequestFingerprint(value) {
+    if (!/^[0-9a-f]{64}$/.test(value)) {
+        throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_INVALID_INPUT", "The payment request fingerprint is invalid.");
+    }
+    return value;
+}
+function validPaymentSignature(value) {
+    return typeof value === "string" && value.length <= 32_768 && /^[A-Za-z0-9+/_=-]+$/.test(value);
+}
+function validReceiptId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
+}
+function validBefore(value) {
+    return Number.isSafeInteger(value) && typeof value === "number" && value > 0;
+}
+export function validateNewPaymentEnvelope(value) {
+    if (!record(value) ||
+        !validPaymentSignature(value.paymentSignature) ||
+        !validReceiptId(value.receiptId) ||
+        !validBefore(value.validBefore)) {
+        throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_INVALID_INPUT", "The new payment envelope is invalid.");
+    }
+    exactKeys(value, ["paymentSignature", "receiptId", "validBefore"]);
+    return value;
+}
+function validateStoredRecord(value) {
+    if (!record(value))
+        invalid();
+    const baseKeys = [
+        "createdAt",
+        "paymentSignature",
+        "receiptId",
+        "requestFingerprint",
+        "state",
+        "updatedAt",
+        "validBefore",
+    ];
+    const hasObservation = Object.hasOwn(value, "settlementObservation");
+    exactKeys(value, hasObservation ? [...baseKeys, "settlementObservation"] : baseKeys);
+    if (!canonicalTimestamp(value.createdAt) ||
+        !validPaymentSignature(value.paymentSignature) ||
+        !validReceiptId(value.receiptId) ||
+        typeof value.requestFingerprint !== "string" ||
+        !/^[0-9a-f]{64}$/.test(value.requestFingerprint) ||
+        (value.state !== "pending" && value.state !== "observed" && value.state !== "settled") ||
+        !canonicalTimestamp(value.updatedAt) ||
+        !validBefore(value.validBefore)) {
+        invalid();
+    }
+    const observation = hasObservation
+        ? parsePaymentSettlementObservation(value.settlementObservation)
+        : null;
+    if ((hasObservation && !observation) ||
+        (value.state === "observed" && !observation) ||
+        (value.state === "pending" && hasObservation)) {
+        invalid();
+    }
+    if (observation)
+        value.settlementObservation = observation;
+    return value;
+}
+export function parsePaymentEnvelopeDocument(value) {
+    if (!record(value))
+        invalid();
+    exactKeys(value, ["records", "version"]);
+    if (value.version !== 1 || !record(value.records))
+        invalid();
+    const entries = Object.entries(value.records);
+    if (entries.length > MAX_PAYMENT_ENVELOPE_RECORDS)
+        invalid();
+    const records = {};
+    let pending = 0;
+    for (const [key, stored] of entries) {
+        try {
+            validatePaymentIdempotencyKey(key);
+        }
+        catch {
+            invalid();
+        }
+        records[key] = validateStoredRecord(stored);
+        if (records[key].state !== "settled")
+            pending += 1;
+    }
+    if (pending > 1)
+        invalid();
+    return { records, version: 1 };
+}

package/dist/payment-envelope-store.d.ts

@@ -0,0 +1,31 @@
+import { type NewPaymentEnvelope, type PaymentEnvelopeRecord } from "./payment-envelope-model.js";
+import { type PaymentSettlementObservation } from "./payment-settlement-observation.js";
+export type { NewPaymentEnvelope, PaymentEnvelopeRecord } from "./payment-envelope-model.js";
+export { PaymentEnvelopeStoreError } from "./payment-envelope-model.js";
+export interface PaymentEnvelopeStoreOptions {
+    lockRetryDelayMs?: number;
+    lockTimeoutMs?: number;
+    now?: () => Date;
+}
+export declare function agentPaymentStateDirectory(stateRoot: string, address: `0x${string}`): string;
+export declare function defaultPaymentStateDirectory(environment?: Readonly<Record<string, string | undefined>>, home?: string): string;
+export declare class PaymentEnvelopeStore {
+    #private;
+    constructor(address: `0x${string}`, stateDirectory: string, options?: PaymentEnvelopeStoreOptions);
+    find(idempotencyKey: string, requestFingerprint: string): Promise<PaymentEnvelopeRecord | null>;
+    findUnsettled(): Promise<{
+        idempotencyKey: string;
+        record: PaymentEnvelopeRecord;
+    } | null>;
+    findPending(): Promise<{
+        idempotencyKey: string;
+        record: PaymentEnvelopeRecord;
+    } | null>;
+    getOrCreate(idempotencyKey: string, requestFingerprint: string, factory: () => Promise<NewPaymentEnvelope>): Promise<{
+        created: boolean;
+        record: PaymentEnvelopeRecord;
+    }>;
+    markSettled(idempotencyKey: string, requestFingerprint: string): Promise<PaymentEnvelopeRecord>;
+    markObserved(idempotencyKey: string, requestFingerprint: string, value: PaymentSettlementObservation): Promise<PaymentEnvelopeRecord>;
+    removeIfPending(idempotencyKey: string, requestFingerprint: string, proveUnused: (record: PaymentEnvelopeRecord) => Promise<boolean>): Promise<boolean>;
+}

package/dist/payment-envelope-store.js

@@ -0,0 +1,210 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { assertNewPaymentEnvelopeCapacity } from "./payment-envelope-capacity.js";
+import { preparePaymentEnvelopeDirectory, readPaymentEnvelopeDocument, writePaymentEnvelopeDocument, } from "./payment-envelope-disk.js";
+import { withPaymentEnvelopeLock } from "./payment-envelope-lock.js";
+import { PaymentEnvelopeStoreError, validateNewPaymentEnvelope, validatePaymentIdempotencyKey, validateRequestFingerprint, } from "./payment-envelope-model.js";
+import { parsePaymentSettlementObservation, } from "./payment-settlement-observation.js";
+export { PaymentEnvelopeStoreError } from "./payment-envelope-model.js";
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+function invalidConfiguration(message) {
+    throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_INVALID_INPUT", message);
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        invalidConfiguration(`${name} is invalid.`);
+    return value;
+}
+export function agentPaymentStateDirectory(stateRoot, address) {
+    if (!ADDRESS.test(address))
+        invalidConfiguration("The agent address is invalid.");
+    if (!stateRoot || stateRoot.trim() !== stateRoot) {
+        invalidConfiguration("The payment state directory is invalid.");
+    }
+    return join(resolve(stateRoot), address.toLowerCase());
+}
+export function defaultPaymentStateDirectory(environment = process.env, home = homedir()) {
+    const configured = environment.TAB_STATE_DIRECTORY;
+    if (configured !== undefined) {
+        if (!configured || configured.trim() !== configured) {
+            invalidConfiguration("TAB_STATE_DIRECTORY is invalid.");
+        }
+        return resolve(configured);
+    }
+    const xdg = environment.XDG_STATE_HOME;
+    if (xdg !== undefined && (!xdg || xdg.trim() !== xdg || !isAbsolute(xdg))) {
+        invalidConfiguration("XDG_STATE_HOME is invalid.");
+    }
+    return join(xdg ?? join(home, ".local", "state"), "tab", "leash");
+}
+function clone(record) {
+    return {
+        ...record,
+        ...(record.settlementObservation
+            ? { settlementObservation: { ...record.settlementObservation } }
+            : {}),
+    };
+}
+export class PaymentEnvelopeStore {
+    #directory;
+    #lockOptions;
+    #now;
+    constructor(address, stateDirectory, options = {}) {
+        this.#directory = agentPaymentStateDirectory(stateDirectory, address);
+        this.#lockOptions = {
+            lockRetryDelayMs: positiveInteger(options.lockRetryDelayMs ?? 25, "Lock retry delay"),
+            lockTimeoutMs: positiveInteger(options.lockTimeoutMs ?? 5_000, "Lock timeout"),
+        };
+        this.#now = options.now ?? (() => new Date());
+    }
+    async #locked(task) {
+        const lockDeadline = performance.now() + this.#lockOptions.lockTimeoutMs;
+        await preparePaymentEnvelopeDirectory(this.#directory);
+        return withPaymentEnvelopeLock(this.#directory, this.#lockOptions, lockDeadline, async () => {
+            const document = await readPaymentEnvelopeDocument(this.#directory);
+            return task(document);
+        });
+    }
+    async find(idempotencyKey, requestFingerprint) {
+        const key = validatePaymentIdempotencyKey(idempotencyKey);
+        const fingerprint = validateRequestFingerprint(requestFingerprint);
+        return this.#locked(async (document) => {
+            const existing = this.#existing(document, key);
+            if (!existing)
+                return null;
+            if (existing.requestFingerprint !== fingerprint)
+                this.#conflict();
+            return clone(existing);
+        });
+    }
+    async findUnsettled() {
+        return this.#locked(async (document) => {
+            const pending = Object.entries(document.records).find(([, value]) => value.state !== "settled");
+            return pending ? { idempotencyKey: pending[0], record: clone(pending[1]) } : null;
+        });
+    }
+    findPending() {
+        return this.findUnsettled();
+    }
+    async getOrCreate(idempotencyKey, requestFingerprint, factory) {
+        const key = validatePaymentIdempotencyKey(idempotencyKey);
+        const fingerprint = validateRequestFingerprint(requestFingerprint);
+        if (typeof factory !== "function")
+            invalidConfiguration("The envelope factory is invalid.");
+        return this.#locked(async (document) => {
+            const existing = this.#existing(document, key);
+            if (existing) {
+                if (existing.requestFingerprint !== fingerprint)
+                    this.#conflict();
+                return { created: false, record: clone(existing) };
+            }
+            if (Object.values(document.records).some((candidate) => candidate.state !== "settled")) {
+                throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_PENDING", "Another payment envelope is still pending.");
+            }
+            const timestamp = this.#timestamp();
+            assertNewPaymentEnvelopeCapacity(document, key, fingerprint, timestamp);
+            const created = validateNewPaymentEnvelope(await factory());
+            const stored = {
+                createdAt: timestamp,
+                paymentSignature: created.paymentSignature,
+                receiptId: created.receiptId,
+                requestFingerprint: fingerprint,
+                state: "pending",
+                updatedAt: timestamp,
+                validBefore: created.validBefore,
+            };
+            document.records[key] = stored;
+            await writePaymentEnvelopeDocument(this.#directory, document);
+            return { created: true, record: clone(stored) };
+        });
+    }
+    async markSettled(idempotencyKey, requestFingerprint) {
+        const key = validatePaymentIdempotencyKey(idempotencyKey);
+        const fingerprint = validateRequestFingerprint(requestFingerprint);
+        return this.#locked(async (document) => {
+            const existing = this.#required(document, key, fingerprint);
+            if (existing.state === "settled")
+                return clone(existing);
+            const settled = {
+                ...existing,
+                state: "settled",
+                updatedAt: this.#timestamp(),
+            };
+            document.records[key] = settled;
+            await writePaymentEnvelopeDocument(this.#directory, document);
+            return clone(settled);
+        });
+    }
+    async markObserved(idempotencyKey, requestFingerprint, value) {
+        const key = validatePaymentIdempotencyKey(idempotencyKey);
+        const fingerprint = validateRequestFingerprint(requestFingerprint);
+        const settlementObservation = parsePaymentSettlementObservation(value);
+        if (!settlementObservation)
+            invalidConfiguration("The settlement observation is invalid.");
+        return this.#locked(async (document) => {
+            const existing = this.#required(document, key, fingerprint);
+            if (existing.state === "settled")
+                return clone(existing);
+            const observed = {
+                ...existing,
+                settlementObservation,
+                state: "observed",
+                updatedAt: this.#timestamp(),
+            };
+            document.records[key] = observed;
+            await writePaymentEnvelopeDocument(this.#directory, document);
+            return clone(observed);
+        });
+    }
+    async removeIfPending(idempotencyKey, requestFingerprint, proveUnused) {
+        const key = validatePaymentIdempotencyKey(idempotencyKey);
+        const fingerprint = validateRequestFingerprint(requestFingerprint);
+        if (typeof proveUnused !== "function")
+            invalidConfiguration("The chain proof is invalid.");
+        return this.#locked(async (document) => {
+            const existing = this.#existing(document, key);
+            if (!existing)
+                return false;
+            if (existing.requestFingerprint !== fingerprint)
+                this.#conflict();
+            if (existing.state === "settled")
+                return false;
+            let unused = false;
+            try {
+                unused = (await proveUnused(clone(existing))) === true;
+            }
+            catch {
+                // The proof callback receives the exact header; its errors must not escape unsanitized.
+            }
+            if (!unused) {
+                throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_CHAIN_STATE_UNRESOLVED", "Independent chain evidence did not prove the pending authorization unused.");
+            }
+            delete document.records[key];
+            await writePaymentEnvelopeDocument(this.#directory, document);
+            return true;
+        });
+    }
+    #required(document, key, fingerprint) {
+        const existing = this.#existing(document, key);
+        if (!existing) {
+            throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_NOT_FOUND", "The payment envelope was not found.");
+        }
+        if (existing.requestFingerprint !== fingerprint)
+            this.#conflict();
+        return existing;
+    }
+    #existing(document, key) {
+        return Object.hasOwn(document.records, key) ? document.records[key] : undefined;
+    }
+    #conflict() {
+        throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_CONFLICT", "The payment idempotency key belongs to a different request.");
+    }
+    #timestamp() {
+        const value = this.#now();
+        if (!(value instanceof Date) || !Number.isFinite(value.valueOf())) {
+            invalidConfiguration("The payment envelope clock is invalid.");
+        }
+        return value.toISOString();
+    }
+}

package/dist/payment-envelope.d.ts

@@ -0,0 +1,17 @@
+import type { PaymentPayload } from "@x402/core/types";
+import type { NewPaymentEnvelope } from "./payment-envelope-model.js";
+import type { PaymentProfile } from "./payment-profile.js";
+import type { TabRemoteSigner } from "./remote-signer.js";
+export declare class PaymentEnvelopeValidationError extends Error {
+    constructor();
+}
+export declare function newPaymentEnvelope(payload: PaymentPayload, paymentSignature: string, signer: TabRemoteSigner): NewPaymentEnvelope;
+export declare function parsePaymentEnvelope(paymentSignature: string, expectedAddress: `0x${string}`, profile: PaymentProfile): Promise<{
+    asset: `0x${string}`;
+    from: `0x${string}`;
+    network: "eip155:8453" | "eip155:42161" | "eip155:84532";
+    nonce: `0x${string}`;
+    payload: PaymentPayload;
+    signature: `0x${string}`;
+    validBefore: number;
+}>;