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

package/dist/node/relay-transport.js

@@ -0,0 +1,173 @@
+/** Contract calls for the SDK: a selected NEAR wallet signs, otherwise the relayer submits. */
+import { Annon } from '../api/annon.js';
+import { secureUrl } from '../download/download.js';
+import { AnnonError, isAnnonErrorCode, isTransient } from '../errors.js';
+import { isStorageRequired, txOutcome } from '../near/rpc.js';
+import { parseRetryAfterMs } from '../net/retry.js';
+import { protocolFeeAboveMax } from '../relay/fees.js';
+import { TransactionUncertain } from '../wallet/uncertain.js';
+import { backupPath, fail } from './adapter-checks.js';
+import { amount } from './amounts.js';
+import { AdapterError, publicError } from './errors.js';
+import { writeBackup } from './io.js';
+import { requestOptions, response } from './offers.js';
+/**
+ * Sends one contract call and waits for its final outcome. Relayer refusals keep their public
+ * code; admission limits, Base settlement and pending key releases are retried with fixed waits.
+ */
+async function relaySend(ctx, method, args, owner) {
+    const { c, d, fetcher, o, wait } = ctx;
+    if (method === 'unlock' && !c.baseRpc)
+        return fail('base_rpc_required', 'Configure baseRpc before resuming a Base purchase.', 2);
+    // The relayer gets the full request; the contract call, and so the outcome check, never
+    // carries the relayer-only fields.
+    const { baseSplit: _baseSplit, hostingReservation: _hostingReservation, ...envelope } = args;
+    const funding = envelope.args;
+    const wireArgs = method === 'fund_file_storage'
+        ? { file_id: funding.file_id, amount: funding.amount }
+        : envelope;
+    const signer = owner ?? (ctx.selected?.identity.kind === 'near' ? ctx.selected : undefined);
+    let submitted;
+    const call = async () => {
+        if (signer)
+            return signer.call({ receiverId: c.contractId, method, args: wireArgs });
+        if (!c.relayer)
+            return fail('transport_required', 'Configure a relayer URL or select a NEAR wallet for transaction calls.', 2);
+        if (!submitted) {
+            const r = await fetcher(new URL('/v1/relay', secureUrl(c.relayer)), {
+                ...requestOptions,
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(method === 'claim_key' ? { method, args } : { method, ...args }),
+                signal: AbortSignal.timeout(60000),
+            });
+            if (![200, 202].includes(r.status)) {
+                const body = (await r.json().catch(() => null));
+                const fallback = r.status === 425
+                    ? 'settlement_pending'
+                    : r.status === 429
+                        ? 'relayer_rate_limited'
+                        : r.status === 503
+                            ? 'relayer_unavailable'
+                            : 'operation_failed';
+                const code = isAnnonErrorCode(body?.error) ? body.error : fallback;
+                const delay = parseRetryAfterMs(r.headers.get('Retry-After'));
+                const safe = publicError({
+                    ...(body && isAnnonErrorCode(body.error) ? body : {}),
+                    code,
+                    ...(delay !== undefined ? { retryAfterSeconds: Math.ceil(delay / 1000) } : {}),
+                });
+                const error = Object.assign(new AdapterError(safe.code, safe.message, safe.exitCode), safe);
+                if (code === 'budget')
+                    throw error;
+                if (code === 'settlement_pending')
+                    throw Object.assign(error, { safetyDelayMs: (safe.retryAfterSeconds ?? 30) * 1000 });
+                const waitMs = delay ?? (safe.retryAfterSeconds === undefined ? 5000 : safe.retryAfterSeconds * 1000);
+                if ([429, 503].includes(r.status) && waitMs <= 60000)
+                    throw Object.assign(error, { retryAfterMs: waitMs });
+                throw error;
+            }
+            const body = (await r.json());
+            if (r.status === 202 && body.pending === true)
+                throw new AdapterError('in_flight', 'Relayer operation is pending.', 4);
+            if (typeof body.txHash !== 'string' ||
+                !body.txHash ||
+                typeof body.signer !== 'string' ||
+                !body.signer)
+                throw new Error('invalid relayer transaction response');
+            submitted = { txHash: body.txHash, signer: body.signer };
+        }
+        const tx = submitted;
+        const result = await txOutcome(c.nearRpc, tx.txHash, tx.signer, c.contractId, 'FINAL', {
+            method,
+            args: wireArgs,
+        });
+        if (result.state === 'released')
+            return result.answer;
+        if (result.state === 'done')
+            return result.value;
+        if ('reason' in result && isStorageRequired(result.reason))
+            throw new AdapterError('storage_required', 'Prepay Annon storage with the SDK storageDeposit helper, then resume the saved operation.');
+        throw new Error(`transaction ${result.state}`);
+    };
+    // Timeouts repeat only idempotent releases; explicit admission refusals have their own cap.
+    let timeouts = 0;
+    let pending = 0;
+    let admissions = 0;
+    let safetyWaits = 0;
+    for (;;) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (o.command === 'share' && submitted) {
+                if (error instanceof AnnonError && !isTransient(error))
+                    throw Object.assign(error, { txHash: submitted.txHash });
+                throw new TransactionUncertain(submitted.txHash);
+            }
+            if (error instanceof AdapterError && 'retryAfterMs' in error) {
+                if (admissions++ >= 3)
+                    throw error;
+                await wait(error.retryAfterMs);
+                continue;
+            }
+            if (method === 'unlock' &&
+                error instanceof AdapterError &&
+                error.code === 'settlement_pending') {
+                if (o.command === 'status')
+                    throw error;
+                if (o.command !== 'open' || d.agent || o.json)
+                    throw error;
+                const planned = [10000, 20000, 30000, 40000, 60000][safetyWaits++];
+                const minimum = error.safetyDelayMs ?? 0;
+                if (planned === undefined || minimum > 60000)
+                    throw error;
+                const delay = Math.max(planned, Number.isFinite(minimum) ? minimum : 0);
+                d.notify?.(`Base settlement pending; retrying unlock in ${delay / 1000} seconds.`);
+                await wait(delay);
+                continue;
+            }
+            const inFlight = error instanceof AdapterError && ['in_flight', 'duplicate'].includes(error.code);
+            const timeout = isTransient(error) || (error instanceof Error && error.name === 'TimeoutError');
+            if (!['unlock', 'reopen', 'claim_key'].includes(method) ||
+                (!inFlight && !timeout) ||
+                (inFlight ? pending++ >= 36 : timeouts++ >= 2))
+                throw error;
+            if (!o.json)
+                d.notify?.('Key release pending; retrying the saved request.');
+            await wait(inFlight ? 5000 : 1000 * 2 ** (timeouts - 1));
+        }
+    }
+}
+/** The SDK for this run, wired to the relay transport and the relayer's sponsorship policy. */
+function createSdk(ctx, rawStore, secret) {
+    const { c, d, fetcher, o } = ctx;
+    const send = (method, args, owner) => relaySend(ctx, method, args, owner);
+    const sdk = (d.sdk ?? ((options) => new Annon(options)))({
+        ...c,
+        rawStore,
+        fetch: fetcher,
+        backupSecret: secret,
+        send,
+        ...(c.relayer
+            ? {
+                sponsorship: async () => {
+                    const reply = await response(new URL('/v1/capabilities', c.relayer).href, fetcher);
+                    if (!reply.ok)
+                        throw new Error('relayer capabilities unavailable');
+                    const cap = (await reply.json());
+                    if (cap.contract !== c.contractId || cap.disabled || !cap.fee)
+                        throw new Error('invalid relayer sponsorship policy');
+                    if ((d.agent || o.json) &&
+                        o.price &&
+                        protocolFeeAboveMax(amount(o.price), cap.fee, c.maxProtocolFee))
+                        return fail('protocol_fee_above_max', 'The advertised protocol fee exceeds maxProtocolFee. Review the fee in human configuration.', 2);
+                    return { fee: cap.fee };
+                },
+            }
+            : {}),
+        writeBackup: (id, encrypted) => writeBackup(backupPath(c, id), encrypted),
+    });
+    return sdk;
+}
+export { createSdk };

package/dist/node/resources.d.ts

@@ -0,0 +1,2 @@
+/** Absent means open HTTPS policy. An explicit empty list denies every resource. */
+export declare function resourceAllowed(rules: readonly string[] | undefined, resource: string): boolean;

package/dist/node/resources.js

@@ -0,0 +1,26 @@
+import { secureUrl } from '../download/download.js';
+import { sameResource } from '../download/proof.js';
+/** Absent means open HTTPS policy. An explicit empty list denies every resource. */
+export function resourceAllowed(rules, resource) {
+    try {
+        const url = secureUrl(resource);
+        if (/%2f|%5c/i.test(resource))
+            return false;
+        if (url.username || url.password)
+            return false;
+        if (rules === undefined)
+            return true;
+        return rules.some((rule) => {
+            if (!rule.endsWith('/*'))
+                return sameResource(rule, resource);
+            const prefix = secureUrl(rule.slice(0, -1));
+            return (!prefix.search &&
+                !prefix.hash &&
+                prefix.origin === url.origin &&
+                url.pathname.startsWith(prefix.pathname));
+        });
+    }
+    catch {
+        return false;
+    }
+}

package/dist/node/retry-gate.d.ts

@@ -0,0 +1,15 @@
+import { type AnnonErrorCode } from '../errors.js';
+interface Context {
+    stateDir: string;
+    network: string;
+    contractId: string;
+    purchaseId: string;
+    host?: string;
+    fileId?: string;
+}
+/** Host and deployment are operator-checked; grants and URL paths never reset a purchase wait. */
+export declare function retryGate(c: Context, now?: () => number): {
+    check(): Promise<void>;
+    defer(code: AnnonErrorCode, seconds: number): Promise<void>;
+};
+export {};

package/dist/node/retry-gate.js

@@ -0,0 +1,53 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isAnnonErrorCode } from '../errors.js';
+import { fileStore } from '../pay/store-node.js';
+import { AdapterError } from './errors.js';
+/** Host and deployment are operator-checked; grants and URL paths never reset a purchase wait. */
+export function retryGate(c, now = () => Date.now() / 1000) {
+    const dir = join(c.stateDir, 'retry-gates');
+    const store = fileStore(dir);
+    const id = JSON.stringify([
+        c.network,
+        c.contractId,
+        c.host ?? null,
+        c.purchaseId,
+        c.fileId ?? null,
+    ]);
+    return {
+        async check() {
+            const saved = await store.load(id);
+            if (!saved)
+                return;
+            if (!isAnnonErrorCode(saved.code) ||
+                !Number.isFinite(saved.nextAllowedAt) ||
+                saved.nextAllowedAt < 0)
+                throw new AdapterError('invalid_record', 'Invalid saved retry gate.', 2);
+            const remaining = Math.ceil(saved.nextAllowedAt - now());
+            if (remaining > 0)
+                throw Object.assign(new AdapterError(saved.code, 'Wait before retrying this saved purchase.', 4), {
+                    retryAfterSeconds: remaining,
+                    purchaseId: c.purchaseId,
+                    ...(c.fileId ? { fileId: c.fileId } : {}),
+                });
+        },
+        async defer(code, seconds) {
+            if (!Number.isFinite(seconds) || seconds < 0 || !Number.isSafeInteger(Math.ceil(seconds)))
+                return;
+            const nextAllowedAt = now() + Math.ceil(seconds);
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            for (;;) {
+                const before = await store.load(id);
+                if (before && before.nextAllowedAt >= nextAllowedAt)
+                    return;
+                if (await store.compareAndSet(id, before, {
+                    id,
+                    revision: (before?.revision ?? -1) + 1,
+                    nextAllowedAt,
+                    code,
+                }))
+                    return;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { CommandSession } from './command-context.js';
+import type { selectedShopRules } from './shops.js';
+/**
+ * `share`: hosts the file with the selected shop and registers it; in a human session the seller
+ * approves the sale terms first. `--resume` continues a saved hosted sale.
+ */
+declare function share(ctx: CommandSession, hostedOrigin: string | undefined, shopRules: Awaited<ReturnType<typeof selectedShopRules>>): Promise<Record<string, unknown>>;
+/** `sell`: writes the encrypted .pay2 file and registers its split; `--resume` continues one. */
+declare function sell(ctx: CommandSession): Promise<Record<string, unknown>>;
+/** `stop`: the registered seller stops new sales of a file. */
+declare function stop(ctx: CommandSession): Promise<Record<string, unknown>>;
+export { sell, share, stop };

package/dist/node/seller-commands.js

@@ -0,0 +1,207 @@
+/** Seller commands: `share` through a hosted shop, `sell` a local file, `stop` a listing. */
+import { basename, join } from 'node:path';
+import { identityJson } from '../settle-near/identity.js';
+import { fail, isId } from './adapter-checks.js';
+import { amount, nearAmount } from './amounts.js';
+import { AdapterError, usage } from './errors.js';
+import { fileSource, newOutput, withSpool, writeStream } from './io.js';
+import { identity } from './wallets.js';
+/**
+ * `share`: hosts the file with the selected shop and registers it; in a human session the seller
+ * approves the sale terms first. `--resume` continues a saved hosted sale.
+ */
+async function share(ctx, hostedOrigin, shopRules) {
+    const { c, d, o, sdk, wallet } = ctx;
+    if (!o.target || !hostedOrigin || !sdk.share || !sdk.resumeShare)
+        throw usage();
+    const seller = await wallet();
+    const hosting = {
+        origin: hostedOrigin,
+        ...(seller.signUpload ? { signUpload: seller.signUpload } : {}),
+        spool: (stream, use) => withSpool(join(c.stateDir, 'hosted'), stream, use),
+    };
+    const data = await fileSource(o.target);
+    if (o.resume) {
+        if (!isId(o.resume) ||
+            [o.price, o.title, o.description, o.storageBudget, o.listingStorage].some((v) => v !== undefined))
+            throw usage();
+        return {
+            ...(await sdk.resumeShare({ fileId: o.resume, data, seller, hosting })),
+            ...shopRules,
+        };
+    }
+    if (!o.price)
+        throw usage();
+    const near = seller.identity.kind === 'near';
+    if (near &&
+        (d.agent || o.json) &&
+        (!(d.agent ? c.listingStorage : (o.listingStorage ?? c.listingStorage)) ||
+            !(d.agent ? c.storageBudget : (o.storageBudget ?? c.storageBudget))))
+        throw new AdapterError('storage_required', 'Configure listingStorage and storageBudget, or provide --listing-storage and --storage-budget in a human CLI session, before noninteractive NEAR sharing.', 2);
+    const listingStorage = near
+        ? nearAmount(d.agent ? (c.listingStorage ?? '0.01') : (o.listingStorage ?? c.listingStorage ?? '0.01'))
+        : undefined;
+    const storageBudget = near
+        ? nearAmount(d.agent ? (c.storageBudget ?? '0.05') : (o.storageBudget ?? c.storageBudget ?? '0.05'))
+        : undefined;
+    if (!near && (o.listingStorage || o.storageBudget))
+        throw usage();
+    return {
+        ...shopRules,
+        ...(await sdk.share({
+            data,
+            name: basename(o.target),
+            mime: 'application/octet-stream',
+            seller,
+            price: amount(o.price),
+            hosting,
+            ...(o.title !== undefined ? { title: o.title } : {}),
+            ...(o.description !== undefined ? { description: o.description } : {}),
+            ...(listingStorage !== undefined ? { listingStorage } : {}),
+            ...(storageBudget !== undefined ? { storageBudget } : {}),
+            onSplit: async (split, fee, aboveMaximum) => {
+                if (aboveMaximum && (d.agent || o.json))
+                    throw new AdapterError('protocol_fee_above_max', 'Review maxProtocolFee in human configuration.', 2);
+                const terms = {
+                    seller: seller.identity,
+                    host: hostedOrigin,
+                    contract: c.contractId,
+                    price: split.price,
+                    split,
+                    fee: fee ?? null,
+                    listingStorage: listingStorage?.toString() ?? null,
+                    purchaseStorage: storageBudget?.toString() ?? null,
+                    registerDeposit: '0',
+                };
+                d.paymentTerms?.(terms);
+                if (!d.agent &&
+                    !o.json &&
+                    !(await d.prompt?.(`${JSON.stringify(terms)}\nType yes to share: `)))
+                    throw new AdapterError('sale_not_approved', 'Sale terms were not approved.', 3);
+            },
+            // The configured secret is separate from the durable backup files.
+            confirmBackup: async () => { },
+        })),
+    };
+}
+/** `sell`: writes the encrypted .pay2 file and registers its split; `--resume` continues one. */
+async function sell(ctx) {
+    const { c, d, o, sdk, wallet } = ctx;
+    if (!o.target)
+        throw usage();
+    const seller = await wallet();
+    const output = o.output ?? `${o.target}.pay2`;
+    await newOutput(output);
+    const publish = async (file) => {
+        await writeStream(output, file.file);
+    };
+    if (o.resume) {
+        if (!isId(o.resume) || o.price || o.split || o.base || o.moderator || o.storageBudget)
+            throw usage();
+        const result = await sdk.resumeSell({
+            fileId: o.resume,
+            data: await fileSource(o.target),
+            seller,
+            publish,
+        });
+        return {
+            fileId: result.terms.file_id,
+            file: output,
+            terms: result.terms,
+            ...(result.baseSplit ? { baseSplit: result.baseSplit } : {}),
+        };
+    }
+    if (!o.price || !o.split)
+        throw usage();
+    if (o.base && !c.baseRpc)
+        return fail('base_rpc_required', 'Configure baseRpc before creating a Base listing.', 2);
+    const recipients = o.split.split(',').map((entry) => {
+        const at = entry.lastIndexOf(':');
+        return { identity: identity(entry.slice(0, at)), bps: Number(entry.slice(at + 1)) };
+    });
+    if (!recipients.length ||
+        recipients.length > 8 ||
+        recipients.some((r) => !Number.isInteger(r.bps) || r.bps <= 0 || r.bps > 10000) ||
+        recipients.reduce((n, r) => n + r.bps, 0) !== 10000 ||
+        new Set(recipients.map((r) => identityJson(r.identity))).size !== recipients.length)
+        throw usage();
+    const remainder = recipients[0]?.identity;
+    if (!remainder)
+        throw usage();
+    if (o.base && (!seller.sendBase || recipients.some((r) => r.identity.kind !== 'evm')))
+        return fail('base_wallet_required', 'Base listings require an EVM wallet and EVM split recipients.', 2);
+    const storageBudget = d.agent ? c.storageBudget : (o.storageBudget ?? c.storageBudget);
+    const selfNear = seller.identity.kind === 'near';
+    if (o.storageBudget && !selfNear)
+        return fail('invalid_arguments', '--storage-budget requires a self-registered NEAR sell.', 2);
+    if (selfNear && !storageBudget)
+        d.notify?.('This self-registered file has no purchase storage budget. Fund it before NEAR or 1Click purchases.');
+    const result = await sdk.sell({
+        data: await fileSource(o.target),
+        name: basename(o.target),
+        mime: 'application/octet-stream',
+        seller,
+        near: { price: amount(o.price), recipients, remainder },
+        ...((!c.relayer || seller.identity.kind === 'near') &&
+            (d.agent ? c.storageBudget : (o.storageBudget ?? c.storageBudget))
+            ? {
+                storageBudget: nearAmount((d.agent ? c.storageBudget : (o.storageBudget ?? c.storageBudget))),
+            }
+            : {}),
+        onSplit: async (split, fee, aboveMaximum) => {
+            if (aboveMaximum && (d.agent || o.json))
+                return fail('protocol_fee_above_max', 'The advertised protocol fee exceeds maxProtocolFee. Review the fee in human configuration.', 2);
+            if (!c.relayer || seller.identity.kind === 'near')
+                return;
+            const description = [
+                'Sponsored sale split:',
+                ...(fee
+                    ? [
+                        `Protocol fee: ${fee.fixed} USDC base units + ${fee.bps} bps.`,
+                        ...(aboveMaximum ? ['This exceeds maxProtocolFee.'] : []),
+                    ]
+                    : []),
+                ...split.recipients.map((r, i) => `${identityJson(r.identity)}: ${(r.bps / 100).toFixed(2)}%${i === split.remainder ? ' (rounding remainder)' : ''}`),
+            ].join('\n');
+            if (!d.agent && !o.json) {
+                d.notify?.(description);
+                if (!(await d.prompt?.(`${description}\nType yes to register: `)))
+                    return fail('sale_not_approved', 'Sale split was not approved.', 3);
+            }
+        },
+        ...(o.base
+            ? {
+                base: {
+                    price: amount(o.price),
+                    sendTransaction: async (call) => {
+                        await seller.sendBase?.(call, c.baseRpc);
+                    },
+                },
+            }
+            : {}),
+        ...(o.moderator ? { moderator: o.moderator } : {}),
+        publish,
+    });
+    return {
+        fileId: result.terms.file_id,
+        file: output,
+        terms: result.terms,
+        ...(result.baseSplit ? { baseSplit: result.baseSplit } : {}),
+        ...(selfNear && !storageBudget
+            ? {
+                warnings: [
+                    'This file has no purchase storage budget. Fund it before NEAR or 1Click purchases.',
+                ],
+            }
+            : {}),
+    };
+}
+/** `stop`: the registered seller stops new sales of a file. */
+async function stop(ctx) {
+    const { o, sdk, wallet } = ctx;
+    if (!o.target || !isId(o.target))
+        throw usage();
+    await sdk.stop({ fileId: o.target, seller: await wallet() });
+    return { fileId: o.target, stopped: true };
+}
+export { sell, share, stop };

package/dist/node/sharing.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from './config.js';
+/** Hosting comes only from a selected, locally approved deployment profile. */
+export declare function shareHost(config: Config, id: string | undefined, fetcher: typeof fetch): Promise<string>;

package/dist/node/sharing.js

@@ -0,0 +1,28 @@
+import { AnnonError } from '../errors.js';
+import { readShop } from '../shops/discovery.js';
+/** Hosting comes only from a selected, locally approved deployment profile. */
+export async function shareHost(config, id, fetcher) {
+    const selected = id ?? config.defaultShop;
+    const shop = config.shops?.find((s) => s.id === selected || s.manifest === selected);
+    if (!shop)
+        throw new AnnonError('invalid_config');
+    const endpoint = (a, b) => {
+        try {
+            return new URL(a).href === new URL(b).href;
+        }
+        catch {
+            return false;
+        }
+    };
+    const p = shop.profile;
+    if (!p)
+        throw new AnnonError('trust_required');
+    if (p.contract !== config.contractId ||
+        p.network !== config.network ||
+        !endpoint(p.nearRpc, config.nearRpc) ||
+        (p.baseRpc ? !endpoint(p.baseRpc, config.baseRpc) : config.baseRpc !== '') ||
+        p.relayer !== config.relayer)
+        throw new AnnonError('config_conflict');
+    const checked = await readShop(shop, fetcher);
+    return checked.info.host;
+}

package/dist/node/shops.d.ts

@@ -0,0 +1,17 @@
+import { type DiscoveryConfig } from '../shops/discovery.js';
+import type { Input } from './cli.js';
+import type { Environment } from './wallets.js';
+export declare const isDiscovery: (input: Input) => boolean;
+/** Discovery deliberately does not load deployment, signing or spending configuration. */
+export declare function discoverShops(input: Input, env: Environment, agent: boolean, fetcher?: typeof fetch): Promise<Record<string, unknown>>;
+/** Descriptive text retains its canonical shop provenance. */
+export declare function selectedShopRules(config: DiscoveryConfig, id: string | undefined, fetcher: typeof fetch): Promise<{
+    shop?: never;
+    rules?: never;
+} | {
+    shop: {
+        manifest: string;
+        name: string;
+    };
+    rules: import("../shops/discovery.js").ShopRules;
+}>;

package/dist/node/shops.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { AnnonError } from '../errors.js';
+import { canonicalManifestUrl, catalog, listShops, readShop, validateDiscoveryConfig, } from '../shops/discovery.js';
+import { configPath } from './agent.js';
+export const isDiscovery = (input) => ['shops', 'shop', 'catalog'].includes(input.command);
+async function readConfig(path) {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error();
+        return value;
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return {};
+        throw new AnnonError('invalid_config', undefined, { cause });
+    }
+}
+/** Discovery deliberately does not load deployment, signing or spending configuration. */
+export async function discoverShops(input, env, agent, fetcher = globalThis.fetch) {
+    if (input.command === 'shop' && agent)
+        throw new AnnonError('human_only');
+    const path = configPath(input, env);
+    const raw = await readConfig(path);
+    const config = validateDiscoveryConfig(raw);
+    const query = {
+        ...(input.search !== undefined ? { search: input.search } : {}),
+        ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        ...(input.offset !== undefined ? { offset: input.offset } : {}),
+    };
+    if (input.command === 'shops')
+        return { ...(await listShops(config, query, fetcher)) };
+    if (input.command === 'catalog')
+        return {
+            ...(await catalog(config, { ...query, ...(input.shop !== undefined ? { shop: input.shop } : {}) }, fetcher)),
+        };
+    if (input.command !== 'shop' || !input.target)
+        throw new AnnonError('invalid_arguments');
+    const manifest = canonicalManifestUrl(input.target);
+    const shops = config.shops ?? [];
+    const existing = shops.find((s) => s.manifest === manifest);
+    if ((input.id !== undefined && shops.some((s) => s.id === input.id && s.manifest !== manifest)) ||
+        (existing?.id !== undefined && input.id !== undefined && existing.id !== input.id))
+        throw new AnnonError('config_conflict');
+    const added = { ...existing, manifest, ...(input.id !== undefined ? { id: input.id } : {}) };
+    const next = existing ? shops.map((s) => (s === existing ? added : s)) : [...shops, added];
+    validateDiscoveryConfig({ ...config, shops: next });
+    await readShop(added, fetcher);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(tmp, JSON.stringify({ ...raw, shops: next }, null, 2), {
+        mode: 0o600,
+        flag: 'wx',
+    });
+    await rename(tmp, path);
+    return {
+        manifest,
+        ...(added.id !== undefined ? { id: added.id } : {}),
+        trusted: added.profile !== undefined,
+    };
+}
+/** Descriptive text retains its canonical shop provenance. */
+export async function selectedShopRules(config, id, fetcher) {
+    const selected = id ?? config.defaultShop;
+    const local = config.shops?.find((s) => s.id === selected || s.manifest === selected);
+    if (!local)
+        return {};
+    const shop = await readShop(local, fetcher);
+    return shop.info.rules
+        ? { shop: { manifest: shop.manifest, name: shop.info.name }, rules: shop.info.rules }
+        : {};
+}

package/dist/node/signer-mock.d.ts

@@ -0,0 +1,11 @@
+/** Reference in-memory adapter for tests/provider integrations; inject signing and policy. */
+import { type Operation, type SigningRequest, type SigningResult } from './signing.js';
+export declare function signerMock(o: {
+    credential: string;
+    account: string;
+    chain: string;
+    operations: Operation[];
+    approve: (q: SigningRequest) => Promise<SigningResult | 'pending' | 'rejected'>;
+}): ((request: Request) => Promise<Response>) & {
+    decide(id: string, result: SigningResult | "rejected"): void;
+};