@defdone/annon 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/browser/purchases.d.ts

@@ -7,7 +7,9 @@ import { type PurchaseRecord } from '../pay/purchase.js';
 import { type Store } from '../pay/store.js';
 import type { IdentityWallet } from '../wallet/wallet.js';
 import { type BrowserDownloadOptions } from './download.js';
+import { type ReconcileOptions, type ReconcileResult } from './reconcile.js';
 import type { BrowserPurchaseRecord, BrowserPurchaseState } from './record.js';
+export type { ReconcileOptions, ReconcileResult } from './reconcile.js';
 export type { BrowserPurchaseRecord, BrowserPurchaseState } from './record.js';
 export type PurchaseSdk = Pick<Annon, 'buy' | 'accept' | 'open' | 'recover' | 'proveRecovery'>;
 export interface BrowserPurchaseStorage {
@@ -91,6 +93,8 @@ export declare class BrowserPurchaseController {
     poll(options?: Omit<PollOptions, 'checkpoint' | 'memo' | 'onProgress'> & {
         oneClick?: Pick<OneClick, 'poll'>;
     }): Promise<void>;
+    /** Check a failed purchase again under its lease. Never creates, starts or pays. */
+    reconcile(options?: ReconcileOptions): Promise<ReconcileResult>;
     recover(wallet: IdentityWallet): Promise<void>;
     /** Open supplied ciphertext, or download with the saved grant. Returns plaintext only in memory. */
     open(input?: Uint8Array | BrowserOpenOptions): ReturnType<Annon['open']>;

package/dist/browser/purchases.js

@@ -9,6 +9,7 @@ import { purchaseKey } from '../pay/purchase.js';
 import { checkNext, indexedDbStore, } from '../pay/store.js';
 import { bytes, hex } from '../settle-near/codec.js';
 import { BROWSER_DOWNLOAD_LIMIT, browserDownload, downloadProgress, } from './download.js';
+import { checkReconcilable, reconcileFailed, } from './reconcile.js';
 const INDEX = 'annon/browser/index';
 const conflict = () => new AnnonError('store_conflict', 'browser purchase store conflict; reload the saved purchase');
 const entryKey = (id) => `annon/browser/entry/${id}`;
@@ -663,6 +664,19 @@ export class BrowserPurchaseController {
                 await session.change({ state: 'accepted' });
         });
     }
+    /** Check a failed purchase again under its lease. Never creates, starts or pays. */
+    async reconcile(options = {}) {
+        const before = await this.read();
+        const busy = this.busy(before);
+        if (busy)
+            throw busy;
+        checkReconcilable(before);
+        return this.withLease((session) => reconcileFailed(session, {
+            accept: (record) => this.options.sdk.accept(record),
+            restorePurchase: (record) => this.storage.restorePurchase(record),
+            loadCanonical: (id) => encryptedPurchaseStore(this.storage.rawStore, this.storage.backupSecret).load(purchaseKey(id)),
+        }, options));
+    }
     async recover(wallet) {
         return this.withLease(async (session) => {
             let saved = session.record;

package/dist/browser/reconcile.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Check a failed browser purchase again. It keeps the saved purchase, its 1Click deposit and its
+ * recovery identity, and it never creates, starts or pays: it reads NEAR acceptance and, for 1Click,
+ * the existing deposit's status once.
+ */
+import { OneClick, type SwapStatus } from '../oneclick/oneclick.js';
+import type { PurchaseRecord } from '../pay/purchase.js';
+import type { BrowserPurchaseRecord, BrowserPurchaseState } from './record.js';
+export interface ReconcileOptions {
+    /** Only the single status read is used; tests and custom endpoints pass their own client. */
+    oneClick?: Pick<OneClick, 'status'>;
+    signal?: AbortSignal;
+}
+export interface ReconcileResult {
+    state: BrowserPurchaseState;
+    /** The 1Click status read by this check, when there was one. */
+    swapStatus?: SwapStatus['status'];
+}
+export interface ReconcileSession {
+    record: BrowserPurchaseRecord;
+    change(patch: Partial<BrowserPurchaseRecord>): Promise<BrowserPurchaseRecord>;
+}
+export interface ReconcileDeps {
+    accept(record: PurchaseRecord): Promise<boolean>;
+    restorePurchase(record: PurchaseRecord): Promise<PurchaseRecord>;
+    /** The canonical saved purchase, read only: no restore, no backup. */
+    loadCanonical(id: string): Promise<PurchaseRecord | null>;
+}
+/**
+ * Throws unless the record is a failed purchase with a saved commitment whose quote and polling
+ * checkpoint name the same deposit. Reads nothing and writes nothing.
+ */
+export declare function checkReconcilable(record: BrowserPurchaseRecord): PurchaseRecord;
+/**
+ * A 1Click check must read the deposit this purchase was saved with. The restored purchase may be a
+ * newer revision of the same commitment, but its deposit address and memo, and those of any saved
+ * polling checkpoint, must be the saved ones. Anything else is refused before any read or write.
+ */
+export declare function checkSameDeposit(saved: BrowserPurchaseRecord, restored: PurchaseRecord): void;
+/** Runs inside the purchase lease. A failed read leaves the saved state and checkpoint as they were. */
+export declare function reconcileFailed(session: ReconcileSession, deps: ReconcileDeps, options?: ReconcileOptions): Promise<ReconcileResult>;

package/dist/browser/reconcile.js

@@ -0,0 +1,77 @@
+/**
+ * Check a failed browser purchase again. It keeps the saved purchase, its 1Click deposit and its
+ * recovery identity, and it never creates, starts or pays: it reads NEAR acceptance and, for 1Click,
+ * the existing deposit's status once.
+ */
+import { OneClick, } from '../oneclick/oneclick.js';
+/**
+ * Throws unless the record is a failed purchase with a saved commitment whose quote and polling
+ * checkpoint name the same deposit. Reads nothing and writes nothing.
+ */
+export function checkReconcilable(record) {
+    if (record.state !== 'failed' || !record.purchase)
+        throw new Error('only a failed saved purchase can be checked again');
+    checkSameDeposit(record, record.purchase);
+    return record.purchase;
+}
+const depositOf = (record) => record?.quote?.deposit;
+/**
+ * A 1Click check must read the deposit this purchase was saved with. The restored purchase may be a
+ * newer revision of the same commitment, but its deposit address and memo, and those of any saved
+ * polling checkpoint, must be the saved ones. Anything else is refused before any read or write.
+ */
+export function checkSameDeposit(saved, restored) {
+    if (saved.route !== '1click')
+        return;
+    const expected = depositOf(saved.purchase);
+    const actual = depositOf(restored);
+    const point = saved.checkpoint;
+    if (expected?.address !== actual?.address ||
+        expected?.memo !== actual?.memo ||
+        (point && (point.address !== expected?.address || point.memo !== expected?.memo)))
+        throw new Error('saved purchase changed deposit; check it with support');
+}
+const settled = {
+    SUCCESS: 'accepting',
+    REFUNDED: 'refunded',
+};
+function nextCheckpoint(previous, address, memo, status) {
+    const base = previous && previous.address === address && previous.memo === memo
+        ? previous
+        : { address, ...(memo === undefined ? {} : { memo }), attempts: 0, errors: 0 };
+    const { nextPollAt: _wait, ...kept } = base;
+    return { ...kept, attempts: kept.attempts + 1, errors: 0, lastStatus: status };
+}
+/** Runs inside the purchase lease. A failed read leaves the saved state and checkpoint as they were. */
+export async function reconcileFailed(session, deps, options = {}) {
+    let saved = session.record;
+    const committed = checkReconcilable(saved);
+    // Validate the canonical copy before restoring, which may write it and its backup.
+    if (saved.route === '1click') {
+        const canonical = await deps.loadCanonical(committed.id);
+        if (canonical)
+            checkSameDeposit(saved, canonical);
+    }
+    const restored = await deps.restorePurchase(committed);
+    if (restored.id !== saved.purchase?.id)
+        throw new Error('saved purchase changed identity');
+    checkSameDeposit(saved, restored);
+    if (JSON.stringify(restored) !== JSON.stringify(saved.purchase))
+        saved = await session.change({ purchase: restored });
+    if (await deps.accept(restored)) {
+        saved = await session.change({ state: 'accepted' });
+        return { state: saved.state };
+    }
+    const deposit = depositOf(restored);
+    if (saved.route !== '1click' || !deposit)
+        return { state: saved.state };
+    const status = await (options.oneClick ?? new OneClick()).status(deposit.address, {
+        ...(deposit.memo === undefined ? {} : { memo: deposit.memo }),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    saved = await session.change({
+        checkpoint: nextCheckpoint(saved.checkpoint, deposit.address, deposit.memo, status),
+        state: settled[status.status] ?? 'failed',
+    });
+    return { state: saved.state, swapStatus: status.status };
+}

package/dist/node/adapter.js

@@ -3,6 +3,7 @@ import { createCoreAdapter } from './core-adapter.js';
 // core-adapter.js loads first: it imports the SDK modules in the order this file did, so they initialize as before.
 import { identityJson, parseIdentity } from '../settle-near/identity.js';
 import { agentPolicy, configPath, initAgent, savePublicConfig } from './agent.js';
+import { initBackupSecret, initPolicy } from './backup-secret-init.js';
 import { startBrowserSession } from './browser-login.js';
 import { loadConfig } from './config.js';
 import { AdapterError } from './errors.js';
@@ -18,11 +19,13 @@ export function createAdapter(env = process.env, d = {}) {
     return async (o) => {
         if (o.command !== 'init' && (o.signer || o.credentialEnv || o.credentialKeychain))
             throw new AdapterError('signer_init_only', 'Signer and credential references can only be set by init.', 2);
-        const agent = await agentPolicy(o, env, d.agent);
+        const agent = await (o.command === 'init' && !o.agent ? initPolicy : agentPolicy)(o, env, d.agent);
         if (isDiscovery(o))
             return discoverShops(o, env, agent, d.fetch);
         if (o.command === 'init')
-            return initAgent(o, env, d.keychain ?? osKeychain);
+            return o.agent
+                ? initAgent(o, env, d.keychain ?? osKeychain)
+                : initBackupSecret(o, env, d.notify);
         const c = await loadConfig(o, env, o.command === 'login', d.agent);
         if (agent || c.agent)
             o = await confinePaths(o, c.workDir);
@@ -56,7 +59,6 @@ export function createAdapter(env = process.env, d = {}) {
                         message: challenge,
                         recipient: c.contractId || 'annon-cli',
                         nonce: [...crypto.getRandomValues(new Uint8Array(32))],
-                        callbackUrl: new URL('/callback', s.url).href,
                     });
                 let identity;
                 await s.request(q, async (r) => {

package/dist/node/approval-status.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Terminal lines and final errors for a browser approval. The page reports only a fixed reason
+ * name (browser/login-status.ts); every line printed here is written by the CLI, never by the page
+ * or a wallet.
+ */
+import { type WalletFailure } from '../browser/login-status.js';
+import { TransactionUncertain } from '../wallet/uncertain.js';
+import { AdapterError } from './errors.js';
+/**
+ * What the page may report: a failed wallet attempt, a cancel, or that it is about to call the
+ * wallet's send (after which the request can only end as sent or uncertain).
+ */
+export type PageReport = WalletFailure | 'cancelled' | 'send_started';
+export declare const isPageReport: (v: unknown) => v is PageReport;
+export declare const openingLine: (url: string) => string;
+export declare const waitingLine: (ms: number) => string;
+export declare const APPROVED_LINE = "Approved in the browser.";
+export declare const failureLine: (reason: WalletFailure, ms: number) => string;
+/** The command's error when the person cancels on the page. */
+export declare const cancelledError: () => AdapterError;
+/** The command's error when a request expires, naming the last wallet failure the page reported. */
+export declare function expiredError(last?: WalletFailure): AdapterError;
+/** The purchase a NEAR USDC payment request pays for, when its transfer message names one. */
+export declare function requestPurchase(action: unknown): string | undefined;
+/** A NEAR transaction hash as wallets return it: base58 of 32 bytes. Anything else is not evidence. */
+export declare function usableHash(v: unknown): string | undefined;
+/**
+ * The line and error when a send may have reached the chain, keeping a usable hash when the
+ * wallet returned one. The CLI never pays again by itself.
+ */
+export declare function sendUncertain(action: unknown, txHash?: string): {
+    line: string;
+    error: TransactionUncertain;
+};

package/dist/node/approval-status.js

@@ -0,0 +1,71 @@
+/**
+ * Terminal lines and final errors for a browser approval. The page reports only a fixed reason
+ * name (browser/login-status.ts); every line printed here is written by the CLI, never by the page
+ * or a wallet.
+ */
+import { base58 } from '@scure/base';
+import { clock, record } from '../browser/login-format.js';
+import { isWalletFailure } from '../browser/login-status.js';
+import { parsePurchaseMessage, purchaseId } from '../settle-near/purchase.js';
+import { TransactionUncertain } from '../wallet/uncertain.js';
+import { AdapterError } from './errors.js';
+export const isPageReport = (v) => v === 'cancelled' || v === 'send_started' || isWalletFailure(v);
+export const openingLine = (url) => `Opening your browser. If it does not open, visit ${url}`;
+export const waitingLine = (ms) => `Waiting for approval in the browser. Expires in ${clock(ms)}.`;
+export const APPROVED_LINE = 'Approved in the browser.';
+const FAILED = {
+    window_closed: 'The wallet window closed before signing.',
+    popup_blocked: 'The browser blocked the wallet window. Allow pop-ups for the 127.0.0.1 page.',
+    rejected: 'The wallet declined the request.',
+    wallet_error: 'The wallet could not complete the request.',
+    refused: 'The page refused the wallet, account or chain for this request.',
+    send_uncertain: 'The wallet may have sent the transaction.',
+};
+export const failureLine = (reason, ms) => `${FAILED[reason]} You can try again on the page for ${clock(ms)}.`;
+/** The command's error when the person cancels on the page. */
+export const cancelledError = () => new AdapterError('cancelled', 'You cancelled the approval in the browser.', 3);
+/** The command's error when a request expires, naming the last wallet failure the page reported. */
+export function expiredError(last) {
+    const again = 'Run the command again.';
+    if (!last)
+        return new AdapterError('cancelled', `The browser approval expired before the wallet signed. ${again}`, 3);
+    const code = last === 'rejected' ? 'rejected' : last === 'window_closed' ? 'cancelled' : 'wallet_error';
+    return new AdapterError(code, `${FAILED[last]} The browser approval then expired. ${again}`, 3);
+}
+/** The purchase a NEAR USDC payment request pays for, when its transfer message names one. */
+export function requestPurchase(action) {
+    const p = record(record(action).payload);
+    const msg = record(p.args).msg;
+    if (p.method !== 'ft_transfer_call' || typeof msg !== 'string')
+        return undefined;
+    try {
+        return purchaseId(parsePurchaseMessage(msg));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A NEAR transaction hash as wallets return it: base58 of 32 bytes. Anything else is not evidence. */
+export function usableHash(v) {
+    if (typeof v !== 'string' || !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(v))
+        return undefined;
+    try {
+        return base58.decode(v).length === 32 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The line and error when a send may have reached the chain, keeping a usable hash when the
+ * wallet returned one. The CLI never pays again by itself.
+ */
+export function sendUncertain(action, txHash) {
+    const purchase = requestPurchase(action);
+    return {
+        line: `The wallet may have sent the transaction. Do not pay again. ${purchase
+            ? `Run annon status ${purchase} to check it.`
+            : 'Check the transaction in your wallet before you run the command again.'}`,
+        error: new TransactionUncertain(txHash, purchase),
+    };
+}

package/dist/node/backup-secret-init.d.ts

@@ -0,0 +1,9 @@
+import type { Input } from './cli.js';
+import type { Environment } from './wallets.js';
+/**
+ * The agent-policy check for bare init. A config that cannot be read must stop setup with a
+ * setup error, not a generic failure; policy refusals stay as they are.
+ */
+export declare function initPolicy(o: Input, env: Environment, forced?: boolean): Promise<boolean>;
+/** Never writes an explicit source; creates the default only when no secret exists at all. */
+export declare function initBackupSecret(o: Partial<Input>, env: Environment, notify?: (message: string) => void): Promise<Record<string, unknown>>;

package/dist/node/backup-secret-init.js

@@ -0,0 +1,103 @@
+/** `annon init` without --agent: validate the selected backup secret or create the default. */
+import { randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, mkdir, open, unlink } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { newBackupSecret } from '../pay/backup.js';
+import { hex } from '../settle-near/codec.js';
+import { agentPolicy } from './agent.js';
+import { checkAppDirectory, defaultBackupSecretPath, findBackupSecret, readDefaultSecret, unsafeDefault, } from './backup-secret.js';
+import { AdapterError } from './errors.js';
+import { assertNoSavedState } from './saved-state.js';
+import { syncDir } from './sync-dir.js';
+const setupError = (message) => new AdapterError('backup_secret_required', message, 2);
+/**
+ * Writes the secret to an exclusive owner-only temporary file, then publishes it with link(),
+ * which never replaces an existing path (rename() would). Returns false when another
+ * invocation already published one; its file is validated and the generated bytes are dropped.
+ */
+async function createDefaultSecret(path) {
+    const dir = dirname(path);
+    // Missing parents are created 0700; an existing directory is only checked, never changed.
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await checkAppDirectory(dir);
+    const temp = join(dir, `.${basename(path)}.${randomBytes(8).toString('hex')}.tmp`);
+    const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    let published;
+    try {
+        const secret = newBackupSecret();
+        try {
+            await handle.writeFile(`${hex(secret).slice(2)}\n`);
+            await handle.sync();
+        }
+        finally {
+            secret.fill(0);
+            await handle.close();
+        }
+        published = await link(temp, path).then(() => true, (error) => {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        });
+    }
+    finally {
+        await unlink(temp).catch(() => { });
+    }
+    if (!published) {
+        if (!(await readDefaultSecret(path)))
+            throw unsafeDefault();
+        return false;
+    }
+    try {
+        await syncDir(dir);
+    }
+    catch {
+        // The published file stays: deleting a secret is never cleanup. A rerun validates it.
+        throw setupError('The backup secret file was created but its directory could not be synced. Rerun annon init to validate it.');
+    }
+    return true;
+}
+const printable = (path) => (/\p{Cc}/u.test(path) ? JSON.stringify(path) : path);
+const notice = (path) => [
+    `Created a plaintext backup-secret file with owner-only permissions: ${printable(path)}`,
+    'Back up this file separately in protected storage. Losing it loses access to local saved purchase and sell records and backup files. Wallet-based purchase recovery through the contract still works.',
+    'Copy the file without displaying its contents. To restore it, select the copied file with ANNON_BACKUP_SECRET_FILE.',
+].join('\n');
+const result = (source, path, created) => ({
+    configured: true,
+    backupSecret: { source, ...(path ? { path } : {}), created },
+});
+/**
+ * The agent-policy check for bare init. A config that cannot be read must stop setup with a
+ * setup error, not a generic failure; policy refusals stay as they are.
+ */
+export async function initPolicy(o, env, forced) {
+    try {
+        return await agentPolicy(o, env, forced);
+    }
+    catch (error) {
+        if (error instanceof AdapterError)
+            throw error;
+        throw setupError('The Annon config could not be read to check agent policy. Fix or restore it before running annon init.');
+    }
+}
+/** Never writes an explicit source; creates the default only when no secret exists at all. */
+export async function initBackupSecret(o, env, notify) {
+    const found = await findBackupSecret(o, env);
+    if (found)
+        return result(found.source, found.path, false);
+    await assertNoSavedState(o, env);
+    const path = defaultBackupSecretPath();
+    let created;
+    try {
+        created = await createDefaultSecret(path);
+    }
+    catch (error) {
+        if (error instanceof AdapterError)
+            throw error;
+        throw setupError('The backup secret file could not be created. Nothing else was tried; fix ~/.config/annon and rerun annon init.');
+    }
+    if (created)
+        notify?.(notice(path));
+    return result('default-file', path, created);
+}

package/dist/node/backup-secret.d.ts

@@ -0,0 +1,35 @@
+import type { Input } from './cli.js';
+import { AdapterError } from './errors.js';
+import type { Environment } from './wallets.js';
+export type BackupSecretSource = 'flag-file' | 'env-file' | 'env' | 'default-file';
+export interface ResolvedSecret {
+    secret: Uint8Array;
+    source: BackupSecretSource;
+    /** Set for file sources only; never the value of ANNON_BACKUP_SECRET. */
+    path?: string;
+}
+/** Fixed home, like the config anchor: neither XDG nor --config/--state-dir move it. */
+export declare const defaultBackupSecretPath: () => string;
+export declare const unsafeDefault: () => AdapterError;
+/** Trimmed lowercase hex with an optional 0x prefix, exactly 32 bytes. */
+export declare function parseSecret(text: string): Uint8Array;
+/**
+ * Read-only check of the application directory that holds the managed default; false when it
+ * does not exist. An existing 0755 directory is fine. The user's home ancestry is trusted.
+ */
+export declare function checkAppDirectory(dir: string): Promise<boolean>;
+/**
+ * Reads the managed default inside a private application directory, without following a
+ * symlink or blocking on a FIFO, and checks the opened file itself. Returns undefined only
+ * when nothing exists at the path.
+ */
+export declare function readDefaultSecret(path?: string): Promise<Uint8Array<ArrayBufferLike> | undefined>;
+/**
+ * Today's explicit precedence first: the file selector (flag ?? environment), then
+ * ANNON_BACKUP_SECRET; empty values select nothing. A selected source that fails is final.
+ * Only with no explicit source is the default file read. Nothing here ever creates a secret.
+ * Returns undefined only when no source is selected and no default file exists.
+ */
+export declare function findBackupSecret(o: Partial<Input>, env: Environment): Promise<ResolvedSecret | undefined>;
+/** The secret a command needs; missing input fails before any side effect that uses it. */
+export declare function readBackupSecret(o: Partial<Input>, env: Environment): Promise<Uint8Array>;

package/dist/node/backup-secret.js

@@ -0,0 +1,104 @@
+/** Where the CLI backup secret comes from: an explicit source, else the managed default file. */
+import { constants } from 'node:fs';
+import { lstat, open, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { bytes } from '../settle-near/codec.js';
+import { AdapterError } from './errors.js';
+/** Fixed home, like the config anchor: neither XDG nor --config/--state-dir move it. */
+export const defaultBackupSecretPath = () => join(homedir(), '.config', 'annon', 'backup-secret');
+const secretError = (message) => new AdapterError('backup_secret_required', message, 2);
+const missingSecret = () => secretError('No backup secret is available. For first-time human setup, run `annon init` before enabling agent mode. If you have saved records or backups, restore their matching secret instead. Unattended callers must ask their operator to provision it.');
+const invalidExplicit = () => secretError('The selected backup secret source could not be read as a 32-byte secret (64 hex characters). Fix that source; Annon does not fall back to another one.');
+export const unsafeDefault = () => secretError('The backup secret file at ~/.config/annon/backup-secret is unreadable, malformed or not private (owner-only regular file required). Fix or restore it; Annon never repairs or replaces it.');
+/** Trimmed lowercase hex with an optional 0x prefix, exactly 32 bytes. */
+export function parseSecret(text) {
+    const value = text.trim();
+    return bytes(value.startsWith('0x') ? value : `0x${value}`, 32);
+}
+const unsafeDirectory = () => secretError('~/.config/annon must be a directory you own, not a symlink, that group and others cannot write. Fix it; Annon does not change existing directories.');
+/**
+ * Read-only check of the application directory that holds the managed default; false when it
+ * does not exist. An existing 0755 directory is fine. The user's home ancestry is trusted.
+ */
+export async function checkAppDirectory(dir) {
+    let s;
+    try {
+        s = await lstat(dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw unsafeDirectory();
+    }
+    if (!s.isDirectory() || s.uid !== process.getuid?.() || (s.mode & 0o022) !== 0)
+        throw unsafeDirectory();
+    return true;
+}
+/**
+ * Reads the managed default inside a private application directory, without following a
+ * symlink or blocking on a FIFO, and checks the opened file itself. Returns undefined only
+ * when nothing exists at the path.
+ */
+export async function readDefaultSecret(path = defaultBackupSecretPath()) {
+    if (!(await checkAppDirectory(dirname(path))))
+        return undefined;
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw unsafeDefault();
+    }
+    try {
+        const s = await handle.stat();
+        if (!s.isFile() ||
+            s.uid !== process.getuid?.() ||
+            (s.mode & 0o077) !== 0 ||
+            (s.mode & 0o400) === 0 ||
+            s.size > 256)
+            throw new Error('unsafe');
+        return parseSecret(await handle.readFile('utf8'));
+    }
+    catch {
+        throw unsafeDefault();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Today's explicit precedence first: the file selector (flag ?? environment), then
+ * ANNON_BACKUP_SECRET; empty values select nothing. A selected source that fails is final.
+ * Only with no explicit source is the default file read. Nothing here ever creates a secret.
+ * Returns undefined only when no source is selected and no default file exists.
+ */
+export async function findBackupSecret(o, env) {
+    const file = o.backupSecretFile ?? env.ANNON_BACKUP_SECRET_FILE;
+    if (file || env.ANNON_BACKUP_SECRET) {
+        try {
+            if (file)
+                return {
+                    secret: parseSecret(await readFile(file, 'utf8')),
+                    source: o.backupSecretFile ? 'flag-file' : 'env-file',
+                    path: resolve(file),
+                };
+            return { secret: parseSecret(env.ANNON_BACKUP_SECRET), source: 'env' };
+        }
+        catch {
+            throw invalidExplicit();
+        }
+    }
+    const path = defaultBackupSecretPath();
+    const secret = await readDefaultSecret(path);
+    return secret && { secret, source: 'default-file', path };
+}
+/** The secret a command needs; missing input fails before any side effect that uses it. */
+export async function readBackupSecret(o, env) {
+    const found = await findBackupSecret(o, env);
+    if (!found)
+        throw missingSecret();
+    return found.secret;
+}

package/dist/node/browser-login.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The approval page talks only to this loopback server, the NEAR RPC its Wallet Selector uses
+ * (fixed per network in browser/login.ts, independent of the CLI's configured RPC) and HOT
+ * Wallet's relay; it frames only the HOT widget. EVM wallets are reached through the injected
+ * provider, which needs no connection from the page.
+ */
+export declare const LOGIN_PAGE_CSP = "default-src 'none'; script-src 'self'; connect-src 'self' https://free.rpc.fastnear.com https://test.rpc.fastnear.com https://h4n.app; frame-src https://hot-labs.org; style-src 'self'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
 export interface BrowserSession {
     url: string;
     pairingCode: string;
@@ -13,6 +20,8 @@ export declare function startBrowserSession(o: {
     open?: (url: string) => void;
     asset?: string;
     timeoutMs?: number;
+    /** Human progress lines; stderr by default, never stdout. */
+    notify?: (line: string) => void;
 }): Promise<BrowserSession>;
 /** Only desktop routing and executable lookup reach the browser opener. */
 export declare function browserOpenerEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;