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

package/dist/node/browser-login.js

@@ -3,6 +3,8 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { TransactionUncertain } from '../wallet/uncertain.js';
+import { APPROVED_LINE, cancelledError, expiredError, failureLine, isPageReport, openingLine, sendUncertain, usableHash, waitingLine, } from './approval-status.js';
+import { LOGIN_PAGE_CSS, LOGIN_PAGE_HTML } from './login-page.js';
 const equal = (a, b) => Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b));
 /**
  * The approval page talks only to this loopback server, the NEAR RPC its Wallet Selector uses
@@ -12,6 +14,7 @@ const equal = (a, b) => Buffer.byteLength(a) === Buffer.byteLength(b) && timingS
  */
 export 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 async function startBrowserSession(o) {
+    const notify = o.notify ?? ((line) => void process.stderr.write(`${line}\n`));
     let asset = o.asset;
     if (asset === undefined) {
         try {
@@ -41,6 +44,15 @@ export async function startBrowserSession(o) {
                 .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
                 .join(',')}}`
         : JSON.stringify(v);
+    /** Ends a request whose transaction may be on chain, with the CLI's own warning. */
+    const uncertain = (p, txHash) => {
+        const { line, error } = sendUncertain(p.action, txHash);
+        notify(line);
+        return error;
+    };
+    /** A transaction request whose send started, or that returned transaction evidence at all. */
+    const sent = (p) => p.sending === true ||
+        p.action.operation === 'near.signTransaction';
     let pending;
     const server = createServer((req, res) => {
         void (async () => {
@@ -67,8 +79,12 @@ export async function startBrowserSession(o) {
                     !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(200, JSON.stringify({
+                        pairingCode,
+                        action: pending?.action ?? null,
+                        sendStarted: pending?.sending === true,
+                    }));
+                if (!['/api/result', '/api/report'].includes(path) || req.method !== 'POST')
                     return void send(404, '{}');
                 let size = 0;
                 const parts = [];
@@ -79,6 +95,31 @@ export async function startBrowserSession(o) {
                     parts.push(chunk);
                 }
                 const b = JSON.parse(Buffer.concat(parts).toString());
+                if (path === '/api/report') {
+                    // A fixed reason for the current, unconsumed request. Only `cancelled` and
+                    // `send_uncertain` end it, and never as cancelled once the page started a send.
+                    const p = pending;
+                    if (!p || p.busy || b.id !== p.action.id || !isPageReport(b.reason))
+                        return void send(409, '{}');
+                    if (b.reason === 'send_started') {
+                        // One send per request: a reloaded or second page cannot start another.
+                        if (p.sending)
+                            return void send(409, '{}');
+                        p.sending = true;
+                    }
+                    else if (b.reason === 'cancelled' || b.reason === 'send_uncertain') {
+                        clearTimeout(p.timer);
+                        pending = undefined;
+                        armIdle();
+                        p.reject(p.sending || b.reason === 'send_uncertain' ? uncertain(p) : cancelledError());
+                    }
+                    else if (!p.sending && p.failure !== b.reason) {
+                        // After a send started no failure can be retried, so none is announced as one.
+                        p.failure = b.reason;
+                        notify(failureLine(b.reason, p.action.expiresAt - Date.now()));
+                    }
+                    return void send(200, '{}');
+                }
                 const key = canonical(b.result);
                 const previous = results.get(b.id);
                 if (previous && Date.now() < previous.expiresAt) {
@@ -104,6 +145,7 @@ export async function startBrowserSession(o) {
                         pending = undefined;
                         armIdle();
                     }
+                    notify(APPROVED_LINE);
                     p.resolve(b.result);
                     complete(200);
                     send(200, '{}');
@@ -114,7 +156,13 @@ export async function startBrowserSession(o) {
                         pending = undefined;
                         armIdle();
                     }
-                    p.reject(error instanceof TransactionUncertain ? error : new Error('wallet result rejected'));
+                    // After a send, a result that cannot be verified is never evidence of success or of
+                    // failure: the request ends as uncertain, with any usable hash, so it stays saved.
+                    p.reject(sent(p)
+                        ? uncertain(p, usableHash(error instanceof TransactionUncertain ? error.txHash : b?.result?.txHash))
+                        : error instanceof TransactionUncertain
+                            ? error
+                            : new Error('wallet result rejected'));
                     complete(400);
                     send(400, '{}');
                 }
@@ -124,8 +172,10 @@ export async function startBrowserSession(o) {
                 return void send(405, '{}');
             if (path === '/app.js')
                 return void send(200, asset, 'text/javascript');
+            if (path === '/app.css')
+                return void send(200, LOGIN_PAGE_CSS, 'text/css; charset=utf-8');
             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><p><label for="near-wallet">NEAR wallet</label> <select id="near-wallet"><option value="meteor-wallet">Meteor Wallet</option><option id="near-wallet-hot" value="hot-wallet">HOT Wallet (mainnet)</option></select></p><button id="approve">Review in wallet</button><p id="status"></p></body></html>', 'text/html; charset=utf-8');
+                return void send(200, LOGIN_PAGE_HTML, 'text/html; charset=utf-8');
             send(404, '{}');
         })().catch(() => {
             if (!res.headersSent)
@@ -161,6 +211,9 @@ export async function startBrowserSession(o) {
     };
     armIdle();
     const url = `${origin}/#${capability}`;
+    // The capability-free page URL: in open mode the page bootstraps the capability once.
+    if (!o.noOpen)
+        notify(openingLine(`${origin}/`));
     if (!o.noOpen)
         (o.open ??
             ((target) => {
@@ -183,21 +236,22 @@ export async function startBrowserSession(o) {
                 return;
             }
             clearTimeout(timeout);
-            const timer = setTimeout(() => {
-                if (pending?.timer === timer) {
-                    pending = undefined;
-                    armIdle();
-                }
-                reject(new Error('action expired'));
-            }, action.expiresAt - Date.now());
-            pending = {
+            const entry = {
                 action: JSON.parse(JSON.stringify(action)),
                 busy: false,
                 resolve: resolve,
                 reject,
                 verify: verify,
-                timer,
+                timer: setTimeout(() => {
+                    if (pending === entry) {
+                        pending = undefined;
+                        armIdle();
+                    }
+                    reject(entry.sending ? uncertain(entry) : expiredError(entry.failure));
+                }, action.expiresAt - Date.now()),
             };
+            pending = entry;
+            notify(waitingLine(action.expiresAt - Date.now()));
         }),
     };
 }

package/dist/node/buy-commands.js

@@ -176,6 +176,10 @@ async function buy(ctx, preparedBuy) {
                 return true;
             if (!saved)
                 return Date.now() / 1000 < claimUntil;
+            // A NEAR send that may be on chain blocks another payment until reconciled or --force,
+            // even after the purchase expired: a late transfer still moves tokens.
+            if (saved.nearSubmission?.state === 'uncertain')
+                return true;
             return (Number(saved.purchase.expires_at) > Date.now() / 1000 ||
                 (saved.purchase.route === 'base-usdc' && saved.attempts.length > 0));
         },
@@ -277,11 +281,14 @@ async function buy(ctx, preparedBuy) {
                 : bought.instructions
                     ? 'deposit_required'
                     : 'submitted',
-            ...(bought.uncertain ? { txHash: bought.uncertain.txHash } : {}),
+            // A browser send that failed after the wallet's send call has no hash to report.
+            ...(bought.uncertain?.txHash ? { 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.',
+            next: bought.uncertain
+                ? `The wallet may have sent this payment. Do not pay again. Run annon status ${bought.record.id} until it is accepted.`
+                : 'Fund the deposit if instructed, then check status and open this purchase.',
         };
     }
     catch (error) {

package/dist/node/cli.js

@@ -1,5 +1,6 @@
 import { parseArgs } from 'node:util';
 import { publicError, usage } from './errors.js';
+import { version } from './version.js';
 const common = [
     'no-open',
     'json',
@@ -57,6 +58,7 @@ const perCommand = {
     verify: [],
     status: [],
 };
+const bareInit = ['json', 'config', 'stateDir', 'backupSecretFile'];
 export function parseCli(argv) {
     try {
         const keys = [...new Set([...common, ...Object.values(perCommand).flat()])];
@@ -117,7 +119,10 @@ export function parseCli(argv) {
             else if (!values.price || !values.split)
                 throw usage();
         }
-        if (cmd === 'init' && values.agent !== true)
+        // Bare init only sets up the backup secret; signer and deployment options need --agent.
+        if (cmd === 'init' &&
+            values.agent !== true &&
+            Object.keys(values).some((k) => !bareInit.includes(k)))
             throw usage();
         if (cmd === 'recover' && !values.recovery)
             throw usage();
@@ -136,10 +141,12 @@ export function parseCli(argv) {
         throw usage();
     }
 }
+const versionFlags = ['--version', '-v'];
 const HELP = `annon <command> [options]
 shops [--search <q>] [--limit <n>] [--offset <n>]
 shop add <url> [--id <alias>]
 catalog [--shop <id>] [--search <q>] [--limit <n>] [--offset <n>]
+init [--backup-secret-file <file>] [--state-dir <dir>] [--config <file>]
 login [--wallet evm|near] [--no-open]
 init --agent --daily-budget <USDC> [--recovery <kind:id>] [--key-env <name> | --keychain-entry <name> | --new-key | --signer <https origin> (--credential-env <name> | --credential-keychain <name>)]
 share <file> --price <USDC> [--shop <id>] [--title <title>] [--description <text>] [--listing-storage <NEAR>] [--storage-budget <NEAR>]
@@ -158,9 +165,11 @@ Common: --json --config <file> --contract-id <account> --near-rpc <url> --base-r
 --network <near:mainnet> --state-dir <dir> --relayer <url> --trust-contract
 --wallet evm|solana|near --evm-key-file <file> --solana-key-file <file> --near-key-file <file>
 --near-account <account> --near-public-key <ed25519:key> --backup-secret-file <file>
-Secrets: env ANNON_EVM_PRIVATE_KEY, ANNON_SOLANA_KEYPAIR, ANNON_NEAR_CREDENTIALS,
-ANNON_BACKUP_SECRET (64 hex); or explicitly named files. See packages/annon/CLI.md.
-Exit: 0 success (buy may need deposit), 1 operation failed, 2 arguments/config, 3 trust required, 4 purchase pending.
+Backup secret: run init once; it creates ~/.config/annon/backup-secret (owner-only) and never
+overwrites. --backup-secret-file or ANNON_BACKUP_SECRET_FILE, then ANNON_BACKUP_SECRET, override it.
+Secrets: env ANNON_EVM_PRIVATE_KEY, ANNON_SOLANA_KEYPAIR, ANNON_NEAR_CREDENTIALS; or explicitly
+named files. See packages/annon/CLI.md. --version prints the installed version.
+Exit: 0 success (buy may need deposit), 1 operation failed, 2 arguments/config, 3 trust required, 4 purchase pending or uncertain.
 `;
 export async function runCli(argv, execute, write) {
     const json = argv.includes('--json') || argv.includes('--json=true');
@@ -168,6 +177,12 @@ export async function runCli(argv, execute, write) {
         write(HELP);
         return 0;
     }
+    // Answered before any config, agent policy, wallet, network or backup-secret step.
+    if (argv.some((a) => versionFlags.includes(a)) &&
+        argv.every((a) => [...versionFlags, '--json'].includes(a))) {
+        write(json ? JSON.stringify({ ok: true, result: { version } }) : version);
+        return 0;
+    }
     try {
         const input = parseCli(argv);
         const result = await execute(input);
@@ -185,11 +200,12 @@ export async function runCli(argv, execute, write) {
                     show(item);
         }
         write(JSON.stringify({ ok: true, result }, null, json ? undefined : 2));
-        return input.command === 'status' &&
-            result &&
+        // 4: not settled. A pending status, or a buy whose payment may be on chain (uncertain).
+        return result &&
             typeof result === 'object' &&
             'state' in result &&
-            result.state === 'pending'
+            ((input.command === 'status' && result.state === 'pending') ||
+                (input.command === 'buy' && result.state === 'uncertain'))
             ? 4
             : 0;
     }

package/dist/node/command-context.js

@@ -65,7 +65,7 @@ async function pendingSetup(ctx, purchaseId) {
     return {
         purchaseId,
         state: 'pending',
-        next: 'Check the payment; configure readable saved state and the matching backup secret to resume Base unlock. 1Click SUCCESS alone is not acceptance.',
+        next: 'Check the payment. To resume Base unlock, keep the saved state readable and restore its matching backup secret (or select its existing copy with ANNON_BACKUP_SECRET_FILE). 1Click SUCCESS alone is not acceptance.',
     };
 }
 /** Loads the command's wallet once; later calls reuse it. */

package/dist/node/config.d.ts

@@ -32,6 +32,8 @@ export interface Config extends DiscoveryConfig {
         bps: number;
     };
 }
+/** Human default for saved records and backups; agent and explicit settings override it. */
+export declare const defaultStateDir: () => string;
 export declare function loadConfig(o: Input, env: Environment, login?: boolean, forcedAgent?: boolean): Promise<Config>;
 export type TrustPrompt = (description: string) => Promise<boolean>;
 export declare function trustContract(c: Config, explicit: boolean, prompt?: TrustPrompt): Promise<void>;

package/dist/node/config.js

@@ -8,6 +8,8 @@ import { validateDiscoveryConfig } from '../shops/discovery.js';
 import { agentPolicy, configPath, validateSigner } from './agent.js';
 import { AdapterError } from './errors.js';
 import { resourceAllowed } from './resources.js';
+/** Human default for saved records and backups; agent and explicit settings override it. */
+export const defaultStateDir = () => join(homedir(), '.local', 'share', 'annon');
 export async function loadConfig(o, env, login = false, forcedAgent = false) {
     const pinnedAgent = await agentPolicy(o, env, forcedAgent);
     try {
@@ -41,7 +43,7 @@ export async function loadConfig(o, env, login = false, forcedAgent = false) {
             stateDir: o.stateDir ??
                 (agent ? undefined : env.ANNON_STATE_DIR) ??
                 file.stateDir ??
-                join(homedir(), '.local', 'share', 'annon'),
+                defaultStateDir(),
         };
         Object.assign(c, validateDiscoveryConfig(file));
         const workDir = (env.ANNON_AGENT === 'true' ? env.ANNON_WORK_DIR : undefined) ?? file.workDir;

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

@@ -0,0 +1,7 @@
+/**
+ * The approval page shell and its stylesheet. Both are static: the page script fills in every
+ * request value as text. The stylesheet is served from the page's own origin (`style-src 'self'`),
+ * with no inline styles, web fonts or other resources.
+ */
+export declare const LOGIN_PAGE_HTML = "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><meta name=\"color-scheme\" content=\"light\"><title>Annon wallet approval</title><link rel=\"stylesheet\" href=\"/app.css\"><script src=\"/app.js\" defer></script></head><body><main class=\"card\">\n<header class=\"brand\"><svg class=\"mark\" viewBox=\"0 0 24 28\" width=\"22\" height=\"26\" aria-hidden=\"true\"><path d=\"M2 27V12a10 10 0 0 1 20 0v15h-5V12a5 5 0 0 0-10 0v15z\"/></svg><p class=\"eyebrow\">ANNON CLI</p></header>\n<h1 id=\"title\">Waiting for the CLI</h1>\n<section class=\"pair\" aria-labelledby=\"pair-label\"><p class=\"label\" id=\"pair-label\">Pairing code</p><p id=\"pair\" class=\"code\">------</p><p class=\"hint\">Check that your terminal shows the same code.</p></section>\n<section id=\"summary\" class=\"summary\" hidden><p id=\"amount\" class=\"amount\" hidden></p><dl id=\"rows\" class=\"rows\"></dl><div id=\"message-box\" class=\"message\" hidden><p id=\"message-label\" class=\"label\"></p><pre id=\"message\"></pre></div><ul id=\"warnings\" class=\"warnings\" hidden></ul><div id=\"terms-box\" class=\"terms\" hidden><p class=\"label\">Terms from the CLI</p><p class=\"hint\">For review. Your wallet signs only the request above.</p><dl id=\"terms\" class=\"rows\"></dl></div><p id=\"note\" class=\"note\"></p></section>\n<section class=\"act\"><div id=\"wallet-field\" class=\"field\" hidden><span class=\"label\" id=\"near-wallet-label\">NEAR wallet</span><div class=\"picker\"><div id=\"near-wallet\" class=\"picker-button\" role=\"combobox\" tabindex=\"0\" aria-haspopup=\"listbox\" aria-expanded=\"false\" aria-controls=\"near-wallet-list\" aria-labelledby=\"near-wallet-label near-wallet-value\"><span id=\"near-wallet-value\">Meteor Wallet</span></div><ul id=\"near-wallet-list\" class=\"picker-list\" role=\"listbox\" aria-labelledby=\"near-wallet-label\" hidden><li id=\"near-wallet-meteor\" class=\"option\" role=\"option\" aria-selected=\"true\">Meteor Wallet<span class=\"option-note\">Extension or web popup</span></li><li id=\"near-wallet-hot\" class=\"option\" role=\"option\" aria-selected=\"false\">HOT Wallet<span class=\"option-note\">Mainnet only</span></li></ul></div></div><div class=\"buttons\"><button id=\"approve\" class=\"primary\" disabled>Review in wallet</button><button id=\"cancel\" class=\"secondary\" hidden>Cancel</button></div><p id=\"status\" class=\"status\" role=\"status\" aria-live=\"polite\"></p></section>\n<details class=\"details\"><summary>Technical details</summary><pre id=\"action\"></pre></details>\n</main></body></html>";
+export declare const LOGIN_PAGE_CSS = ":root{--paper:#FAF8F2;--alt:#F1EDE3;--ink:#111111;--soft:#2E2C28;--muted:#4A4741;--line:#D9D3C7;--red:#B3261E;--serif:Newsreader,\"Iowan Old Style\",Georgia,serif;--mono:\"IBM Plex Mono\",ui-monospace,\"SF Mono\",Menlo,monospace}\n*{box-sizing:border-box;border-radius:0}\nhtml{background:var(--paper)}\nbody{margin:0;background:var(--paper);color:var(--ink);font:16px/1.5 var(--serif);-webkit-text-size-adjust:100%}\n.card{max-width:640px;margin:0 auto;padding:40px 16px 56px}\n.brand{display:flex;align-items:center;gap:10px;margin-bottom:20px}\n.mark{fill:var(--ink);flex:none}\n.eyebrow,.label,dt,.details summary,button{font-family:var(--mono);letter-spacing:.08em;text-transform:uppercase;font-size:12px}\n.eyebrow{margin:0;color:var(--soft)}\nh1{font-weight:500;font-size:clamp(28px,6vw,36px);line-height:1.15;margin:0 0 24px;letter-spacing:-.01em}\n.label{margin:0 0 6px;color:var(--muted)}\n.hint{margin:6px 0 0;color:var(--muted);font-size:15px}\n.pair{border:1px solid var(--ink);background:var(--alt);padding:16px 20px;margin-bottom:28px}\n.code{margin:0;font:600 clamp(30px,9vw,40px)/1.1 var(--mono);letter-spacing:.18em;word-break:break-all}\n.summary{border-top:1px solid var(--line);padding-top:20px}\n.amount{margin:0 0 12px;font-size:clamp(30px,8vw,42px);line-height:1.1}\n.rows{margin:0}\n.row{display:grid;grid-template-columns:minmax(0,11em) minmax(0,1fr);gap:4px 16px;padding:9px 0;border-bottom:1px solid var(--line)}\ndt{color:var(--muted);padding-top:3px}\ndd{margin:0;color:var(--soft);overflow-wrap:anywhere}\ndd.mono{font:14px/1.5 var(--mono)}\n.message,.terms{margin-top:20px}\npre{margin:0;padding:14px 16px;background:var(--alt);border:1px solid var(--line);font:13px/1.55 var(--mono);color:var(--soft);white-space:pre-wrap;overflow-wrap:anywhere;max-height:22em;overflow:auto}\n.warnings{margin:20px 0 0;padding:12px 16px 12px 32px;border:1px solid var(--red);color:var(--red)}\n.note{margin:20px 0 0;color:var(--soft)}\n.act{margin-top:28px;border-top:1px solid var(--line);padding-top:20px}\n.field{margin:0 0 16px;display:flex;flex-wrap:wrap;align-items:center;gap:8px 16px}\n.picker{position:relative;flex:0 1 20em;min-width:0}\n.picker-button{display:flex;align-items:center;justify-content:space-between;gap:12px;background:var(--paper);color:var(--ink);border:1px solid var(--ink);padding:10px 12px;cursor:pointer;font:14px/1.4 var(--mono);user-select:none}\n.picker-button::after{content:\"\";width:0;height:0;border:5px solid transparent;border-top-color:var(--ink);border-bottom:0;flex:none}\n.picker-button[aria-expanded=\"true\"]::after{border-top:0;border-bottom:5px solid var(--ink)}\n.picker-button[aria-disabled=\"true\"]{opacity:.4;cursor:not-allowed}\n.picker-list{position:absolute;z-index:2;left:0;right:0;top:100%;margin:0;padding:0;list-style:none;background:var(--paper);border:1px solid var(--ink);border-top:0}\n.option{display:flex;justify-content:space-between;align-items:baseline;gap:12px;padding:10px 12px;cursor:pointer;font:14px/1.4 var(--mono);color:var(--soft)}\n.option+.option{border-top:1px solid var(--line)}\n.option.active{background:var(--alt);color:var(--ink)}\n.option[aria-selected=\"true\"]{color:var(--ink);font-weight:600}\n.option[aria-selected=\"true\"]::before{content:\"\";width:6px;height:6px;background:var(--ink);flex:none;align-self:center}\n.option[aria-disabled=\"true\"]{color:var(--muted);cursor:not-allowed;opacity:.6}\n.option-note{margin-left:auto;font-size:11px;font-weight:400;letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}\n.buttons{display:flex;flex-wrap:wrap;gap:12px}\nbutton{padding:14px 22px;border:1px solid var(--ink);cursor:pointer}\n.primary{background:var(--ink);color:var(--paper)}\n.secondary{background:transparent;color:var(--ink)}\nbutton:disabled{cursor:not-allowed;opacity:.4}\nbutton:focus-visible,.picker-button:focus-visible,summary:focus-visible{outline:2px solid var(--red);outline-offset:2px}\n.status{min-height:1.5em;margin:16px 0 0;color:var(--soft)}\n.status.wait{color:var(--muted)}\n.status.ok{color:var(--ink);border-left:3px solid var(--ink);padding-left:12px}\n.status.error{color:var(--red);border-left:3px solid var(--red);padding-left:12px}\n.details{margin-top:32px;border-top:1px solid var(--line);padding-top:12px}\n.details summary{cursor:pointer;color:var(--muted);padding:6px 0}\n.details pre{margin-top:10px}\n[hidden]{display:none!important}\n@media (max-width:480px){.row{grid-template-columns:1fr}.card{padding-top:28px}button{flex:1 1 100%}.picker{flex-basis:100%}}\n";

package/dist/node/login-page.js

@@ -0,0 +1,71 @@
+/**
+ * The approval page shell and its stylesheet. Both are static: the page script fills in every
+ * request value as text. The stylesheet is served from the page's own origin (`style-src 'self'`),
+ * with no inline styles, web fonts or other resources.
+ */
+/** A small arch: the Annon mark. Inline SVG, so it needs no image source. */
+const MARK = '<svg class="mark" viewBox="0 0 24 28" width="22" height="26" aria-hidden="true"><path d="M2 27V12a10 10 0 0 1 20 0v15h-5V12a5 5 0 0 0-10 0v15z"/></svg>';
+export const LOGIN_PAGE_HTML = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="light"><title>Annon wallet approval</title><link rel="stylesheet" href="/app.css"><script src="/app.js" defer></script></head><body><main class="card">
+<header class="brand">${MARK}<p class="eyebrow">ANNON CLI</p></header>
+<h1 id="title">Waiting for the CLI</h1>
+<section class="pair" aria-labelledby="pair-label"><p class="label" id="pair-label">Pairing code</p><p id="pair" class="code">------</p><p class="hint">Check that your terminal shows the same code.</p></section>
+<section id="summary" class="summary" hidden><p id="amount" class="amount" hidden></p><dl id="rows" class="rows"></dl><div id="message-box" class="message" hidden><p id="message-label" class="label"></p><pre id="message"></pre></div><ul id="warnings" class="warnings" hidden></ul><div id="terms-box" class="terms" hidden><p class="label">Terms from the CLI</p><p class="hint">For review. Your wallet signs only the request above.</p><dl id="terms" class="rows"></dl></div><p id="note" class="note"></p></section>
+<section class="act"><div id="wallet-field" class="field" hidden><span class="label" id="near-wallet-label">NEAR wallet</span><div class="picker"><div id="near-wallet" class="picker-button" role="combobox" tabindex="0" aria-haspopup="listbox" aria-expanded="false" aria-controls="near-wallet-list" aria-labelledby="near-wallet-label near-wallet-value"><span id="near-wallet-value">Meteor Wallet</span></div><ul id="near-wallet-list" class="picker-list" role="listbox" aria-labelledby="near-wallet-label" hidden><li id="near-wallet-meteor" class="option" role="option" aria-selected="true">Meteor Wallet<span class="option-note">Extension or web popup</span></li><li id="near-wallet-hot" class="option" role="option" aria-selected="false">HOT Wallet<span class="option-note">Mainnet only</span></li></ul></div></div><div class="buttons"><button id="approve" class="primary" disabled>Review in wallet</button><button id="cancel" class="secondary" hidden>Cancel</button></div><p id="status" class="status" role="status" aria-live="polite"></p></section>
+<details class="details"><summary>Technical details</summary><pre id="action"></pre></details>
+</main></body></html>`;
+export const LOGIN_PAGE_CSS = `:root{--paper:#FAF8F2;--alt:#F1EDE3;--ink:#111111;--soft:#2E2C28;--muted:#4A4741;--line:#D9D3C7;--red:#B3261E;--serif:Newsreader,"Iowan Old Style",Georgia,serif;--mono:"IBM Plex Mono",ui-monospace,"SF Mono",Menlo,monospace}
+*{box-sizing:border-box;border-radius:0}
+html{background:var(--paper)}
+body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.5 var(--serif);-webkit-text-size-adjust:100%}
+.card{max-width:640px;margin:0 auto;padding:40px 16px 56px}
+.brand{display:flex;align-items:center;gap:10px;margin-bottom:20px}
+.mark{fill:var(--ink);flex:none}
+.eyebrow,.label,dt,.details summary,button{font-family:var(--mono);letter-spacing:.08em;text-transform:uppercase;font-size:12px}
+.eyebrow{margin:0;color:var(--soft)}
+h1{font-weight:500;font-size:clamp(28px,6vw,36px);line-height:1.15;margin:0 0 24px;letter-spacing:-.01em}
+.label{margin:0 0 6px;color:var(--muted)}
+.hint{margin:6px 0 0;color:var(--muted);font-size:15px}
+.pair{border:1px solid var(--ink);background:var(--alt);padding:16px 20px;margin-bottom:28px}
+.code{margin:0;font:600 clamp(30px,9vw,40px)/1.1 var(--mono);letter-spacing:.18em;word-break:break-all}
+.summary{border-top:1px solid var(--line);padding-top:20px}
+.amount{margin:0 0 12px;font-size:clamp(30px,8vw,42px);line-height:1.1}
+.rows{margin:0}
+.row{display:grid;grid-template-columns:minmax(0,11em) minmax(0,1fr);gap:4px 16px;padding:9px 0;border-bottom:1px solid var(--line)}
+dt{color:var(--muted);padding-top:3px}
+dd{margin:0;color:var(--soft);overflow-wrap:anywhere}
+dd.mono{font:14px/1.5 var(--mono)}
+.message,.terms{margin-top:20px}
+pre{margin:0;padding:14px 16px;background:var(--alt);border:1px solid var(--line);font:13px/1.55 var(--mono);color:var(--soft);white-space:pre-wrap;overflow-wrap:anywhere;max-height:22em;overflow:auto}
+.warnings{margin:20px 0 0;padding:12px 16px 12px 32px;border:1px solid var(--red);color:var(--red)}
+.note{margin:20px 0 0;color:var(--soft)}
+.act{margin-top:28px;border-top:1px solid var(--line);padding-top:20px}
+.field{margin:0 0 16px;display:flex;flex-wrap:wrap;align-items:center;gap:8px 16px}
+.picker{position:relative;flex:0 1 20em;min-width:0}
+.picker-button{display:flex;align-items:center;justify-content:space-between;gap:12px;background:var(--paper);color:var(--ink);border:1px solid var(--ink);padding:10px 12px;cursor:pointer;font:14px/1.4 var(--mono);user-select:none}
+.picker-button::after{content:"";width:0;height:0;border:5px solid transparent;border-top-color:var(--ink);border-bottom:0;flex:none}
+.picker-button[aria-expanded="true"]::after{border-top:0;border-bottom:5px solid var(--ink)}
+.picker-button[aria-disabled="true"]{opacity:.4;cursor:not-allowed}
+.picker-list{position:absolute;z-index:2;left:0;right:0;top:100%;margin:0;padding:0;list-style:none;background:var(--paper);border:1px solid var(--ink);border-top:0}
+.option{display:flex;justify-content:space-between;align-items:baseline;gap:12px;padding:10px 12px;cursor:pointer;font:14px/1.4 var(--mono);color:var(--soft)}
+.option+.option{border-top:1px solid var(--line)}
+.option.active{background:var(--alt);color:var(--ink)}
+.option[aria-selected="true"]{color:var(--ink);font-weight:600}
+.option[aria-selected="true"]::before{content:"";width:6px;height:6px;background:var(--ink);flex:none;align-self:center}
+.option[aria-disabled="true"]{color:var(--muted);cursor:not-allowed;opacity:.6}
+.option-note{margin-left:auto;font-size:11px;font-weight:400;letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
+.buttons{display:flex;flex-wrap:wrap;gap:12px}
+button{padding:14px 22px;border:1px solid var(--ink);cursor:pointer}
+.primary{background:var(--ink);color:var(--paper)}
+.secondary{background:transparent;color:var(--ink)}
+button:disabled{cursor:not-allowed;opacity:.4}
+button:focus-visible,.picker-button:focus-visible,summary:focus-visible{outline:2px solid var(--red);outline-offset:2px}
+.status{min-height:1.5em;margin:16px 0 0;color:var(--soft)}
+.status.wait{color:var(--muted)}
+.status.ok{color:var(--ink);border-left:3px solid var(--ink);padding-left:12px}
+.status.error{color:var(--red);border-left:3px solid var(--red);padding-left:12px}
+.details{margin-top:32px;border-top:1px solid var(--line);padding-top:12px}
+.details summary{cursor:pointer;color:var(--muted);padding:6px 0}
+.details pre{margin-top:10px}
+[hidden]{display:none!important}
+@media (max-width:480px){.row{grid-template-columns:1fr}.card{padding-top:28px}button{flex:1 1 100%}.picker{flex-basis:100%}}
+`;

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

@@ -1,7 +1,7 @@
 import type { CommandSession, RequestContext } from './command-context.js';
 /**
- * `status`, first step: a purchase already accepted on chain, or the pending answer when no
- * backup secret is configured. Returns nothing when the saved record has to be checked.
+ * `status`, first step: a purchase already accepted on chain. Returns nothing when the saved
+ * record has to be checked; a missing backup secret then reports the pending setup answer.
  */
 declare function statusOnChain(ctx: RequestContext): Promise<Record<string, unknown> | undefined>;
 /** `status` from the saved purchase record: accepted, or still pending with a retry delay. */

package/dist/node/purchase-commands.js

@@ -16,11 +16,11 @@ import { resourceAllowed } from './resources.js';
 import { retryGate } from './retry-gate.js';
 import { readBackupSecret } from './wallets.js';
 /**
- * `status`, first step: a purchase already accepted on chain, or the pending answer when no
- * backup secret is configured. Returns nothing when the saved record has to be checked.
+ * `status`, first step: a purchase already accepted on chain. Returns nothing when the saved
+ * record has to be checked; a missing backup secret then reports the pending setup answer.
  */
 async function statusOnChain(ctx) {
-    const { c, d, env, o, paymentDetails, pendingSetup } = ctx;
+    const { c, d, env, o, paymentDetails } = ctx;
     if (!o.target || !isId(o.target))
         throw usage();
     if (d.agent)
@@ -35,8 +35,6 @@ async function statusOnChain(ctx) {
             next: 'open',
             ...(await paymentDetails(async () => encryptedPurchaseStore(fileStore(join(c.stateDir, 'records')), await readBackupSecret(o, env)).load(purchaseKey(o.target)))),
         };
-    if (!o.backupSecretFile && !env.ANNON_BACKUP_SECRET_FILE && !env.ANNON_BACKUP_SECRET)
-        return pendingSetup(o.target);
 }
 /** `status` from the saved purchase record: accepted, or still pending with a retry delay. */
 async function status(ctx) {
@@ -66,14 +64,20 @@ async function status(ctx) {
     }
     if (d.agent && !accepted)
         await retryGate({ ...c, purchaseId: o.target }).defer('settlement_pending', 30);
+    // A NEAR send that may be on chain: pending is not proof that it failed.
+    const uncertain = !accepted && record.nearSubmission?.state === 'uncertain';
     return {
         purchaseId: o.target,
         state: accepted ? 'accepted' : 'pending',
+        ...(uncertain ? { submission: 'uncertain' } : {}),
+        ...(uncertain && record.nearSubmission?.txHash ? { txHash: record.nearSubmission.txHash } : {}),
         ...(await paymentDetails(async () => record)),
         ...(accepted ? {} : { retryAfterSeconds: 30 }),
         next: accepted
             ? 'open'
-            : 'Check the payment and retry status. 1Click SUCCESS alone is not acceptance.',
+            : uncertain
+                ? 'The wallet may have sent this payment. Do not pay again. Retry status until it is accepted or the purchase expires.'
+                : 'Check the payment and retry status. 1Click SUCCESS alone is not acceptance.',
     };
 }
 /** `recover`: purchases found for the recovery wallet, with per-purchase public errors. */

package/dist/node/saved-state.d.ts

@@ -0,0 +1,4 @@
+import type { Input } from './cli.js';
+import type { Environment } from './wallets.js';
+/** Directory entries only: this cannot see unrelated custom directories or offline backups. */
+export declare function assertNoSavedState(o: Partial<Input>, env: Environment): Promise<void>;

package/dist/node/saved-state.js

@@ -0,0 +1,50 @@
+/** Refuses a new backup secret where saved state already depends on an older one. */
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { configPath } from './agent.js';
+import { defaultStateDir } from './config.js';
+import { AdapterError } from './errors.js';
+const savedState = () => new AdapterError('backup_secret_required', 'Saved records or backups already exist in the state directory or in ~/.local/share/annon; a new secret needs both empty. Restore their matching backup secret or select its existing file, because a new secret cannot decrypt them. To recover with a new secret instead, first move the whole old state, including ~/.local/share/annon, to a separate private archive and keep it.', 2);
+const uncheckable = () => new AdapterError('backup_secret_required', 'Annon could not check the state directory for saved records or backups (unreadable config or state). Fix it before creating a backup secret.', 2);
+async function hasEntries(dir) {
+    try {
+        return (await readdir(dir)).length > 0;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/**
+ * Human state precedence (flag, environment, config, default), read locally without the
+ * deployment checks of loadConfig. The legacy default is checked too when it differs.
+ */
+async function stateDirs(o, env) {
+    let file = {};
+    try {
+        file = JSON.parse(await readFile(configPath(o, env), 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const stateDir = o.stateDir ?? env.ANNON_STATE_DIR ?? file.stateDir ?? defaultStateDir();
+    if (typeof stateDir !== 'string' || !stateDir)
+        throw new Error('invalid state directory');
+    return new Set([resolve(stateDir), resolve(defaultStateDir())]);
+}
+/** Directory entries only: this cannot see unrelated custom directories or offline backups. */
+export async function assertNoSavedState(o, env) {
+    let found = false;
+    try {
+        for (const dir of await stateDirs(o, env))
+            for (const name of ['records', 'backups'])
+                found ||= await hasEntries(join(dir, name));
+    }
+    catch {
+        throw uncheckable();
+    }
+    if (found)
+        throw savedState();
+}

package/dist/node/version.d.ts

@@ -0,0 +1 @@
+export declare const version: string;

package/dist/node/version.js

@@ -0,0 +1,3 @@
+/** The installed package version; package.json sits two levels above both src/node and dist/node. */
+import { createRequire } from 'node:module';
+export const { version } = createRequire(import.meta.url)('../../package.json');

package/dist/node/wallets.d.ts

@@ -3,11 +3,11 @@ import type { SplitCall } from '../pay/split.js';
 import { type IdentityWallet } from '../wallet/wallet.js';
 import type { Input } from './cli.js';
 import { type Keychain } from './keychain.js';
+export { readBackupSecret } from './backup-secret.js';
 export type Environment = Record<string, string | undefined>;
 export type LocalWallet = IdentityWallet & {
     signUpload?: (intent: UploadIntent) => Promise<UploadAuth>;
     sendBase?: (call: SplitCall, rpc: string) => Promise<void>;
 };
 export declare function identity(value: string): import("../settle-near/identity.js").Identity;
-export declare function readBackupSecret(o: Partial<Input>, env: Environment): Promise<Uint8Array>;
 export declare function loadWallet(o: Partial<Input>, env: Environment, nearRpc: string, keychain?: Keychain): Promise<LocalWallet>;

package/dist/node/wallets.js

@@ -7,11 +7,12 @@ import { privateKeyToAccount } from 'viem/accounts';
 import { base } from 'viem/chains';
 import { signNearUpload } from '../browser/wallets.js';
 import { nep413Hash } from '../near/nep413.js';
-import { bytes, hex } from '../settle-near/codec.js';
+import { hex } from '../settle-near/codec.js';
 import { identityJson, parseIdentity } from '../settle-near/identity.js';
 import { nearKeyPairWallet } from '../wallet/wallet.js';
 import { AdapterError } from './errors.js';
 import { decodeKeychain, osKeychain } from './keychain.js';
+export { readBackupSecret } from './backup-secret.js';
 const credentialsError = () => new AdapterError('credentials_required', 'Select a wallet and provide its key through the documented environment variable or a named key file. Check the recovery identity matches.', 2);
 export function identity(value) {
     const at = value.indexOf(':');
@@ -24,15 +25,6 @@ async function source(file, env) {
         return env.trim();
     throw credentialsError();
 }
-export async function readBackupSecret(o, env) {
-    try {
-        const text = await source(o.backupSecretFile ?? env.ANNON_BACKUP_SECRET_FILE, env.ANNON_BACKUP_SECRET);
-        return bytes(text.startsWith('0x') ? text : `0x${text}`, 32);
-    }
-    catch {
-        throw new AdapterError('backup_secret_required', 'Provide a 32-byte random backup secret as 64 hex characters in ANNON_BACKUP_SECRET or a named backup secret file.', 2);
-    }
-}
 export async function loadWallet(o, env, nearRpc, keychain = osKeychain) {
     try {
         const selected = o.wallet ?? (o.recovery ? identity(o.recovery).kind : env.ANNON_WALLET);

package/dist/pay/purchase.d.ts

@@ -76,9 +76,10 @@ export interface PurchaseRecord extends Versioned {
     recoveryProved: boolean;
     /** Source details are the reviewed 1Click quote. */
     payment: PaymentSummary;
+    /** A NEAR send that may be on chain; `txHash` only when the wallet returned one. */
     nearSubmission?: {
         state: 'uncertain';
-        txHash: string;
+        txHash?: string;
     };
     paymentState?: 'expired' | 'canceled';
     purchase: Purchase;

package/dist/wallet/uncertain.d.ts

@@ -1,8 +1,11 @@
 import { AnnonError } from '../errors.js';
-/** Public evidence to retain whenever a submitted NEAR transaction cannot be confirmed. */
+/**
+ * Public evidence to retain whenever a submitted NEAR transaction cannot be confirmed. `txHash` is
+ * absent when a wallet may have broadcast but never returned a hash: unknown, never invented.
+ */
 export declare class TransactionUncertain extends AnnonError {
-    readonly txHash: string;
+    readonly txHash: string | undefined;
     readonly purchaseId?: string | undefined;
     readonly code = "transaction_uncertain";
-    constructor(txHash: string, purchaseId?: string | undefined);
+    constructor(txHash: string | undefined, purchaseId?: string | undefined);
 }

package/dist/wallet/uncertain.js

@@ -1,5 +1,8 @@
 import { AnnonError } from '../errors.js';
-/** Public evidence to retain whenever a submitted NEAR transaction cannot be confirmed. */
+/**
+ * Public evidence to retain whenever a submitted NEAR transaction cannot be confirmed. `txHash` is
+ * absent when a wallet may have broadcast but never returned a hash: unknown, never invented.
+ */
 export class TransactionUncertain extends AnnonError {
     txHash;
     purchaseId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defdone/annon",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Files only the buyer can open: encrypted on the client, the key released by NEAR once the payment is verified.",
   "license": "Apache-2.0",
   "homepage": "https://annon.dev",