@defdone/annon 0.0.0-stage → 0.1.0-alpha.0

package/dist/node/browser-login.js

@@ -0,0 +1,212 @@
+import { execFile } from 'node:child_process';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { TransactionUncertain } from '../wallet/uncertain.js';
+const equal = (a, b) => Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+export async function startBrowserSession(o) {
+    let asset = o.asset;
+    if (asset === undefined) {
+        try {
+            asset = await readFile(new URL('../browser/login-bundle.js', import.meta.url), 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            try {
+                asset = await readFile(new URL('../../dist/browser/login-bundle.js', import.meta.url), 'utf8');
+            }
+            catch {
+                throw new Error('Browser login requires the bundle. Run pnpm --filter @defdone/annon build first.');
+            }
+        }
+    }
+    const capability = randomBytes(32).toString('base64url'), pairingCode = randomBytes(3).toString('hex').toUpperCase();
+    let origin = '', closed = false;
+    let bootstrapped = false;
+    // Keep in-flight and completed outcomes so popup/opener races verify only once.
+    const results = new Map();
+    const canonical = (v) => v && typeof v === 'object'
+        ? Array.isArray(v)
+            ? `[${v.map(canonical)}]`
+            : `{${Object.keys(v)
+                .sort()
+                .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
+                .join(',')}}`
+        : JSON.stringify(v);
+    let pending;
+    const server = createServer((req, res) => {
+        void (async () => {
+            const headers = {
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+                'x-content-type-options': 'nosniff',
+                'content-security-policy': "default-src 'none'; script-src 'self'; connect-src 'self' https:; style-src 'self'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+            };
+            const send = (status, body, type = 'application/json') => res.writeHead(status, { ...headers, 'content-type': type }).end(body);
+            if (closed || req.headers.host !== new URL(origin).host)
+                return void send(403, '{}');
+            const path = req.url;
+            if (path === '/api/bootstrap' && req.method === 'POST') {
+                if (o.noOpen || bootstrapped)
+                    return void send(404, '{}');
+                if (req.headers.origin !== origin)
+                    return void send(403, '{}');
+                bootstrapped = true;
+                return void send(200, JSON.stringify({ capability }));
+            }
+            if (path?.startsWith('/api/')) {
+                if (req.headers.origin !== origin ||
+                    !equal(req.headers.authorization ?? '', `Bearer ${capability}`))
+                    return void send(403, '{}');
+                if (path === '/api/action' && ['GET', 'POST'].includes(req.method ?? ''))
+                    return void send(200, JSON.stringify({ pairingCode, action: pending?.action ?? null }));
+                if (path !== '/api/result' || req.method !== 'POST')
+                    return void send(404, '{}');
+                let size = 0;
+                const parts = [];
+                for await (const chunk of req) {
+                    size += chunk.length;
+                    if (size > 131072)
+                        return void send(413, '{}');
+                    parts.push(chunk);
+                }
+                const b = JSON.parse(Buffer.concat(parts).toString());
+                const key = canonical(b.result);
+                const previous = results.get(b.id);
+                if (previous && Date.now() < previous.expiresAt) {
+                    if (previous.key !== key)
+                        return void send(409, '{}');
+                    return void send(await previous.outcome, '{}');
+                }
+                const p = pending;
+                if (!p || p.busy || b.id !== p.action.id || Date.now() >= p.action.expiresAt)
+                    return void send(409, '{}');
+                p.busy = true; // consumed before async verification, including forged results
+                let complete = () => { };
+                const outcome = new Promise((resolve) => {
+                    complete = resolve;
+                });
+                results.set(b.id, { key, expiresAt: p.action.expiresAt, outcome });
+                try {
+                    await p.verify(b.result);
+                    if (closed || pending !== p || Date.now() >= p.action.expiresAt)
+                        throw new Error('expired');
+                    clearTimeout(p.timer);
+                    if (pending === p) {
+                        pending = undefined;
+                        armIdle();
+                    }
+                    p.resolve(b.result);
+                    complete(200);
+                    send(200, '{}');
+                }
+                catch (error) {
+                    clearTimeout(p.timer);
+                    if (pending === p) {
+                        pending = undefined;
+                        armIdle();
+                    }
+                    p.reject(error instanceof TransactionUncertain ? error : new Error('wallet result rejected'));
+                    complete(400);
+                    send(400, '{}');
+                }
+                return;
+            }
+            if (req.method !== 'GET')
+                return void send(405, '{}');
+            if (path === '/app.js')
+                return void send(200, asset, 'text/javascript');
+            if (path === '/' || path === '/callback')
+                return void send(200, '<!doctype html><html><head><meta charset="utf-8"><title>Annon wallet approval</title><script src="/app.js" defer></script></head><body><h1>Annon wallet approval</h1><p id="pair"></p><pre id="action"></pre><button id="approve">Review in wallet</button><p id="status"></p></body></html>', 'text/html; charset=utf-8');
+            send(404, '{}');
+        })().catch(() => {
+            if (!res.headersSent)
+                res.writeHead(400, { 'cache-control': 'no-store' }).end();
+        });
+    });
+    server.on('upgrade', (_req, socket) => socket.destroy());
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    origin = `http://127.0.0.1:${server.address().port}`;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(timeout);
+        if (pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('session closed'));
+            pending = undefined;
+        }
+        server.closeAllConnections();
+        await new Promise((resolve) => server.close(() => resolve()));
+    };
+    let timeout;
+    const armIdle = () => {
+        clearTimeout(timeout);
+        if (!closed && !pending)
+            timeout = setTimeout(() => {
+                void close();
+            }, o.timeoutMs ?? 300000);
+    };
+    armIdle();
+    const url = `${origin}/#${capability}`;
+    if (!o.noOpen)
+        (o.open ??
+            ((target) => {
+                execFile(process.platform === 'darwin'
+                    ? 'open'
+                    : process.platform === 'win32'
+                        ? 'explorer.exe'
+                        : 'xdg-open', [target], { env: browserOpenerEnv(process.env) }, () => { });
+            }))(`${origin}/`);
+    return {
+        url,
+        pairingCode,
+        close,
+        request: (action, verify) => new Promise((resolve, reject) => {
+            for (const [id, r] of results)
+                if (Date.now() >= r.expiresAt)
+                    results.delete(id);
+            if (closed || pending || results.has(action.id) || action.expiresAt <= Date.now()) {
+                reject(new Error('session closed, busy or expired'));
+                return;
+            }
+            clearTimeout(timeout);
+            const timer = setTimeout(() => {
+                if (pending?.timer === timer) {
+                    pending = undefined;
+                    armIdle();
+                }
+                reject(new Error('action expired'));
+            }, action.expiresAt - Date.now());
+            pending = {
+                action: JSON.parse(JSON.stringify(action)),
+                busy: false,
+                resolve: resolve,
+                reject,
+                verify: verify,
+                timer,
+            };
+        }),
+    };
+}
+/** Only desktop routing and executable lookup reach the browser opener. */
+export function browserOpenerEnv(env) {
+    return Object.fromEntries([
+        'PATH',
+        'HOME',
+        'DISPLAY',
+        'BROWSER',
+        'XDG_CURRENT_DESKTOP',
+        'DESKTOP_SESSION',
+        'LANG',
+        'WAYLAND_DISPLAY',
+        'XDG_RUNTIME_DIR',
+        'DBUS_SESSION_BUS_ADDRESS',
+        'SystemRoot',
+    ].flatMap((key) => (env[key] === undefined ? [] : [[key, env[key]]])));
+}

package/dist/node/budget.d.ts

@@ -0,0 +1,24 @@
+import { AnnonError } from '../errors.js';
+import type { Store, Versioned } from '../pay/store.js';
+export declare class BudgetError extends AnnonError {
+    constructor(message?: string);
+}
+export interface BudgetRecord extends Versioned {
+    day: number;
+    hour: number;
+    daily: string;
+    hourly: string;
+    reconciled?: string[];
+}
+/** Reserve in UTC windows; refund once after a definite refusal or retain verified final spend. */
+export declare function reserveSpend(store: Store<BudgetRecord>, scope: string, amount: bigint, limits: {
+    daily: bigint;
+    hourly?: bigint;
+}, now?: number, reservationId?: string): Promise<(retained?: bigint) => Promise<void>>;
+export interface SpendReservation {
+    id?: string;
+    amount: string;
+    at: number;
+}
+/** Idempotent across keeper restarts; old UTC windows are never refunded into new ones. */
+export declare function reconcileSpend(store: Store<BudgetRecord>, scope: string, reservation: SpendReservation, retained: bigint): Promise<void>;

package/dist/node/budget.js

@@ -0,0 +1,59 @@
+import { AnnonError } from '../errors.js';
+export class BudgetError extends AnnonError {
+    constructor(message) {
+        super('budget_exceeded', message);
+        this.name = 'BudgetError';
+    }
+}
+/** Reserve in UTC windows; refund once after a definite refusal or retain verified final spend. */
+export async function reserveSpend(store, scope, amount, limits, now = Date.now(), reservationId) {
+    if (amount < 0n || limits.daily < 0n || (limits.hourly !== undefined && limits.hourly < 0n))
+        throw new TypeError('invalid spend limit');
+    const day = Math.floor(now / 86400000), hour = Math.floor(now / 3600000);
+    for (;;) {
+        const old = await store.load(scope);
+        if (old && (old.day > day || old.hour > hour))
+            throw new BudgetError('Clock moved backwards; spending is paused.');
+        const daily = BigInt(old?.day === day ? old.daily : '0') + amount;
+        const hourly = BigInt(old?.hour === hour ? old.hourly : '0') + amount;
+        if (daily > limits.daily || (limits.hourly !== undefined && hourly > limits.hourly))
+            throw new BudgetError('The persisted spending budget is exhausted.');
+        if (await store.compareAndSet(scope, old, {
+            id: scope,
+            revision: (old?.revision ?? -1) + 1,
+            day,
+            hour,
+            daily: String(daily),
+            hourly: String(hourly),
+            ...(old?.day === day && old.reconciled ? { reconciled: old.reconciled } : {}),
+        }))
+            break;
+    }
+    let released;
+    return (retained = 0n) => (released ??= reconcileSpend(store, scope, { amount: String(amount), at: now, ...(reservationId ? { id: reservationId } : {}) }, retained));
+}
+/** Idempotent across keeper restarts; old UTC windows are never refunded into new ones. */
+export async function reconcileSpend(store, scope, reservation, retained) {
+    const amount = BigInt(reservation.amount);
+    if (retained < 0n)
+        throw new TypeError('invalid retained spend');
+    const refund = amount > retained ? amount - retained : 0n;
+    const day = Math.floor(reservation.at / 86400000), hour = Math.floor(reservation.at / 3600000);
+    for (;;) {
+        const old = await store.load(scope);
+        if (!old || old.day !== day || (reservation.id && old.reconciled?.includes(reservation.id)))
+            return;
+        const daily = BigInt(old.daily) - refund;
+        const hourly = BigInt(old.hourly) - (old.hour === hour ? refund : 0n);
+        if (daily < 0n || hourly < 0n)
+            throw new Error('invalid budget refund');
+        if (await store.compareAndSet(scope, old, {
+            ...old,
+            revision: old.revision + 1,
+            daily: String(daily),
+            hourly: String(hourly),
+            ...(reservation.id ? { reconciled: [...(old.reconciled ?? []), reservation.id] } : {}),
+        }))
+            return;
+    }
+}

package/dist/node/buy-commands.d.ts

@@ -0,0 +1,24 @@
+import type { CommandSession, RequestContext } from './command-context.js';
+type PreparedBuy = Awaited<ReturnType<typeof prepareBuy>>;
+/** `verify`: a local file's header and body, or a remote file's header, against its listing. */
+declare function verifyFile(ctx: RequestContext): Promise<Record<string, unknown>>;
+/**
+ * `buy`, checks that run before the backup secret is read: agent policy, the price cap, the
+ * offer and its header against the registered listing.
+ */
+declare function prepareBuy(ctx: RequestContext): Promise<{
+    found: {
+        pr: import("../pay/x402.js").PaymentRequired;
+        url: string;
+        header: Uint8Array<ArrayBufferLike>;
+        fileId: string;
+    };
+    f: import("../near/rpc.js").FileInfo;
+    maxPrice: bigint;
+}>;
+/**
+ * `buy`: confirms the exact terms, holds the per-file purchase guard and the agent budget, then
+ * lets the SDK pay.
+ */
+declare function buy(ctx: CommandSession, preparedBuy: PreparedBuy | undefined): Promise<Record<string, unknown>>;
+export { buy, prepareBuy, verifyFile };

package/dist/node/buy-commands.js

@@ -0,0 +1,301 @@
+/** Buyer commands before a purchase exists: `verify` a file and `buy` it. */
+import { mkdir, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inspect, inspectHeader, MAX_HEADER, parseHeader } from '../envelope/pay2.js';
+import { AnnonError } from '../errors.js';
+import { fileStorageBalance, getConfig, getPurchase } from '../near/rpc.js';
+import { OneClick } from '../oneclick/oneclick.js';
+import { purchaseKey } from '../pay/purchase.js';
+import { fileStore } from '../pay/store-node.js';
+import { checkBaseSponsorship } from '../relay/capabilities.js';
+import { hex } from '../settle-near/codec.js';
+import { backupPath, fail, isId } from './adapter-checks.js';
+import { amount } from './amounts.js';
+import { reserveSpend } from './budget.js';
+import { AdapterError, usage } from './errors.js';
+import { offer, resourceHeader, response } from './offers.js';
+import { originFor } from './origin.js';
+import { humanPaymentTerms, quotedSource, savedPayment, validatePaymentToken, } from './payment-terms.js';
+import { claimPurchase } from './purchase-guard.js';
+import { resourceAllowed } from './resources.js';
+/** `verify`: a local file's header and body, or a remote file's header, against its listing. */
+async function verifyFile(ctx) {
+    const { c, fetcher, o, readListing } = ctx;
+    if (!o.target)
+        throw usage();
+    const remote = /^https?:/.test(o.target);
+    const data = remote
+        ? await resourceHeader(o.target, c, fetcher)
+        : new Uint8Array(await readFile(o.target));
+    const parsed = parseHeader(new Uint8Array(data.subarray(0, MAX_HEADER)));
+    const fileId = hex(parsed.fileId);
+    const { listing } = await readListing(fileId);
+    const result = await (remote
+        ? inspectHeader(data, listing, c.contractId)
+        : inspect(data, listing, c.contractId));
+    if (!result.usable)
+        return fail('no_usable_stanza', 'The file has no key stanza for the trusted contract.');
+    return {
+        fileId,
+        verified: true,
+        checked: remote ? 'header' : 'header-and-body',
+        contractId: c.contractId,
+    };
+}
+/**
+ * `buy`, checks that run before the backup secret is read: agent policy, the price cap, the
+ * offer and its header against the registered listing.
+ */
+async function prepareBuy(ctx) {
+    const { c, d, fetcher, o, readListing } = ctx;
+    if (!o.target)
+        throw usage();
+    if (d.agent && !/^https?:/.test(o.target))
+        return fail('resource_not_allowed', 'Agent purchases require a secure resource URL; offer files are refused.', 2);
+    const cap = o.maxPrice ?? c.maxPrice;
+    if (!cap)
+        return fail('max_price_required', 'Set --max-price, ANNON_MAX_PRICE or maxPrice in human configuration before buying.', 2);
+    const maxPrice = BigInt(amount(cap));
+    if (c.maxPrice && maxPrice > BigInt(amount(c.maxPrice)))
+        return fail('price_above_max', 'The requested cap exceeds the configured maximum.', 2);
+    const resource = /^https?:/.test(o.target) ? o.target : o.url;
+    if (d.agent && (!resource || !resourceAllowed(c.allowedResources, resource)))
+        return fail('resource_not_allowed', 'The resource URL is outside the configured agent policy.', 2);
+    if (d.agent && (o.refundTo || o.fromChain || o.fromAsset))
+        return fail('origin_not_allowed', 'Use a human-configured origin name.', 2);
+    const found = await offer(o.target, c, fetcher, undefined, o.url);
+    const { f, listing } = await readListing(found.fileId);
+    await inspectHeader(found.header, listing, c.contractId);
+    if (o.route === 'base' && !f.terms.base)
+        throw new AnnonError('route_unavailable');
+    return { found, f, maxPrice };
+}
+/**
+ * `buy`: confirms the exact terms, holds the per-file purchase guard and the agent budget, then
+ * lets the SDK pay.
+ */
+async function buy(ctx, preparedBuy) {
+    const { c, d, env, fetcher, o, resources, sdk, storeDir, wallet } = ctx;
+    if (!preparedBuy)
+        throw usage();
+    const { found, f, maxPrice } = preparedBuy;
+    const buyer = await wallet();
+    const route = o.route ??
+        (o.fromChain || o.origin ? '1click' : buyer.identity.kind === 'near' ? 'near' : 'base');
+    if (d.agent && route === '1click' && !o.origin)
+        return fail('origin_not_allowed', 'Use a human-configured origin name.', 2);
+    if (route === 'near' && buyer.identity.kind !== 'near')
+        return fail('near_wallet_required', 'The direct NEAR route requires a NEAR wallet; use 1click for another chain.', 2);
+    if (route === 'base' && !f.terms.base)
+        throw new AdapterError(o.route ? 'route_unavailable' : 'origin_required', 'This file has no direct Base route. Use --route 1click --from-chain base to pay from Base.', 2);
+    if (route === 'base' && (buyer.identity.kind !== 'evm' || !('signTypedData' in buyer)))
+        return fail('base_wallet_required', 'The Base route requires an EVM payment wallet.', 2);
+    if (route === 'base' && !c.baseRpc)
+        return fail('base_rpc_required', 'Configure baseRpc before a Base purchase.', 2);
+    const origin = route === '1click' ? await originFor(o, env, buyer, fetcher, c) : undefined;
+    const before = await resources.load(found.fileId);
+    if (!(await resources.compareAndSet(found.fileId, before, {
+        id: found.fileId,
+        revision: (before?.revision ?? -1) + 1,
+        contractId: c.contractId,
+        url: found.url,
+        header: hex(found.header),
+    })))
+        throw new Error('resource conflict');
+    const price = route === 'base' ? f.terms.base?.price : f.terms.near.price;
+    if (!price || BigInt(price) > maxPrice)
+        return fail('price_above_max', 'The registered price exceeds maxPrice.');
+    const paymentConfig = await getConfig(c.nearRpc, c.contractId);
+    const paymentTerms = {
+        file: found.fileId,
+        resource: found.url,
+        network: route === 'base' ? 'eip155:8453' : c.network,
+        route,
+        price,
+        recipients: f.terms.near.recipients,
+        remainder: f.terms.near.remainder,
+        baseRecipient: f.terms.base?.pay_to,
+        token: route === 'base' ? f.terms.base?.usdc : f.terms.near.token,
+    };
+    if (paymentConfig.network !== c.network)
+        return fail('network_mismatch', 'The contract network differs from the configured network.', 2);
+    validatePaymentToken(paymentTerms, paymentConfig);
+    const baseSponsorship = route === 'base'
+        ? await checkBaseSponsorship({
+            deployment: {
+                network: c.network,
+                contractId: c.contractId,
+                nearUsdc: paymentConfig.nearUsdc,
+                baseUsdc: paymentConfig.usdc,
+            },
+            file: f,
+            baseRpc: c.baseRpc,
+            relayer: c.relayer ?? '',
+            fetch: fetcher,
+        })
+        : undefined;
+    if (route !== 'base') {
+        const budget = await fileStorageBalance(c.nearRpc, c.contractId, f.terms.file_id);
+        if (budget.available < budget.admissionRequirement)
+            return fail('file_storage_low', 'This file needs more purchase storage funding before a NEAR or 1Click payment.', 2);
+    }
+    if (origin && !d.agent && !d.browserApprovals && !o.json && !d.prompt)
+        return fail('confirmation_required', 'Review and confirm the exact payment terms before paying.', 3);
+    const confirmPayment = async (source) => {
+        const review = { ...paymentTerms, ...(source ? { source } : {}) };
+        d.paymentTerms?.(review);
+        if (!d.agent && !d.browserApprovals) {
+            d.notify?.(o.json ? JSON.stringify(review) : humanPaymentTerms(review, paymentConfig));
+            if (!(await (o.json ? undefined : d.prompt)?.('Type yes to pay: ')))
+                return fail('confirmation_required', 'Review and confirm the exact payment terms before paying.', 3);
+        }
+    };
+    if (d.agent && c.dailyBudget === undefined)
+        return fail('budget_required', 'Configure a daily budget before buying.', 2);
+    const guardDir = join(c.stateDir, 'purchase-guards');
+    await mkdir(guardDir, { recursive: true, mode: 0o700 });
+    const known = [];
+    for (const name of await readdir(storeDir)) {
+        if (!/^[0-9a-f]{64}\.json$/.test(name))
+            continue;
+        const envelope = JSON.parse(await readFile(join(storeDir, name), 'utf8'));
+        if (!isId(envelope.id))
+            continue;
+        const saved = await sdk.store.load(purchaseKey(envelope.id));
+        if (saved?.purchase.file_id === found.fileId &&
+            saved.purchase.contract === c.contractId &&
+            saved.terms.network === (saved.purchase.route === 'base-usdc' ? 'eip155:8453' : c.network))
+            known.push(saved.id);
+    }
+    const guard = await claimPurchase(fileStore(guardDir), JSON.stringify([c.network, c.contractId, found.fileId]), {
+        known,
+        ...(o.force === undefined ? {} : { force: o.force }),
+        live: async (id, claimUntil) => {
+            const saved = await sdk.store.load(purchaseKey(id));
+            if (await (d.purchase ?? getPurchase)(c.nearRpc, c.contractId, id))
+                return true;
+            if (!saved)
+                return Date.now() / 1000 < claimUntil;
+            return (Number(saved.purchase.expires_at) > Date.now() / 1000 ||
+                (saved.purchase.route === 'base-usdc' && saved.attempts.length > 0));
+        },
+    });
+    let renewalError;
+    const heartbeat = setInterval(() => {
+        void guard.renew().catch((error) => {
+            renewalError = error;
+        });
+    }, 30000);
+    let refundBudget;
+    const reserve = async (spend) => {
+        if (!d.agent)
+            return;
+        if (c.dailyBudget === undefined)
+            return fail('budget_required', 'Configure a daily budget before buying.', 2);
+        const budgetDir = join(c.stateDir, 'budgets');
+        await mkdir(budgetDir, { recursive: true, mode: 0o700 });
+        refundBudget = await reserveSpend(fileStore(budgetDir), 'agent:USDC', spend, {
+            daily: c.dailyBudget === '0' ? 0n : BigInt(amount(c.dailyBudget)),
+        });
+    };
+    let completed = false;
+    try {
+        if (!origin || (o.json && !d.browserApprovals))
+            await confirmPayment();
+        if (!origin)
+            await reserve(BigInt(price));
+        let source;
+        const bought = await sdk.buy({
+            fileId: found.fileId,
+            header: found.header,
+            beforeSave: async (record) => {
+                if (renewalError)
+                    throw renewalError;
+                await guard.saved(record.id);
+            },
+            recovery: buyer,
+            ...(baseSponsorship ? { baseSponsorship } : {}),
+            route,
+            refund: buyer.identity,
+            ...(route === '1click' ? {} : { payer: buyer }),
+            maxPrice,
+            moderators: o.moderator ? [o.moderator] : (c.moderators ?? []),
+            paymentRequired: found.pr,
+            url: found.url,
+            ...(origin
+                ? {
+                    origin,
+                    oneClick: new OneClick({ fetch: fetcher }),
+                    onQuote: async (quote) => {
+                        source = quotedSource(quote, origin.sourceAsset);
+                        let spend = BigInt(price);
+                        if (d.agent) {
+                            const sourceAmount = BigInt(source.amount);
+                            if (origin.maxSourceAmount !== undefined &&
+                                sourceAmount > BigInt(origin.maxSourceAmount))
+                                return fail('price_above_max', 'The quoted source amount exceeds the configured origin cap.', 2);
+                            if (source.symbol === 'USDC' && source.decimals !== undefined) {
+                                const scale = 10n ** BigInt(source.decimals);
+                                spend = (sourceAmount * 1000000n + scale - 1n) / scale;
+                                if (spend > maxPrice)
+                                    return fail('price_above_max', 'The quoted source USDC amount exceeds maxPrice.', 2);
+                            }
+                            else if (!origin.maxSourceAmount)
+                                return fail('origin_not_allowed', 'Configure maxSourceAmount in source base units for this origin before buying.', 2);
+                        }
+                        await reserve(spend);
+                        await confirmPayment(source);
+                    },
+                }
+                : {}),
+            submitBase: async (payment) => {
+                const r = await response(found.url, fetcher, { 'PAYMENT-SIGNATURE': payment });
+                await r.body?.cancel();
+                if (![200, 206, 402, 503].includes(r.status))
+                    throw new AdapterError('host_payment_failed', `Payment submission failed: host HTTP ${r.status}. Keep the saved purchase and check status before retrying.`);
+            },
+        });
+        await guard.saved(bought.record.id);
+        completed = true;
+        let payment;
+        try {
+            payment = savedPayment(bought.record, source);
+            const next = { ...bought.record, revision: bought.record.revision + 1, payment };
+            await sdk.store.compareAndSet(purchaseKey(next.id), bought.record, next);
+        }
+        catch {
+            // Keep the completed purchase when saving source details fails.
+        }
+        // Raw purchase records and signed payment payloads never cross the adapter boundary.
+        return {
+            purchaseId: bought.record.id,
+            fileId: found.fileId,
+            route: bought.route,
+            ...(payment ? { payment } : {}),
+            state: bought.uncertain
+                ? 'uncertain'
+                : bought.instructions
+                    ? 'deposit_required'
+                    : 'submitted',
+            ...(bought.uncertain ? { txHash: bought.uncertain.txHash } : {}),
+            backup: backupPath(c, bought.record.id),
+            ...(bought.instructions ? { instructions: bought.instructions } : {}),
+            ...(source ? { source } : {}),
+            next: 'Fund the deposit if instructed, then check status and open this purchase.',
+        };
+    }
+    catch (error) {
+        // Only failures before the SDK returns can release a 1Click reservation.
+        if (origin && !completed)
+            await refundBudget?.().catch(() => { });
+        throw error;
+    }
+    finally {
+        clearInterval(heartbeat);
+        if (completed)
+            await guard.release().catch(() => { });
+        else
+            await guard.release();
+    }
+}
+export { buy, prepareBuy, verifyFile };