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

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,7 +44,22 @@ 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 followers = new Set();
+    const advance = (action = null) => {
+        for (const response of followers)
+            response.end(JSON.stringify({ action }));
+        followers.clear();
+    };
     const server = createServer((req, res) => {
         void (async () => {
             const headers = {
@@ -67,8 +85,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 +101,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,9 +151,17 @@ export async function startBrowserSession(o) {
                         pending = undefined;
                         armIdle();
                     }
-                    p.resolve(b.result);
+                    notify(APPROVED_LINE);
                     complete(200);
-                    send(200, '{}');
+                    if (b.follow === true) {
+                        res.writeHead(200, { ...headers, 'content-type': 'application/json' });
+                        res.flushHeaders();
+                        followers.add(res);
+                        res.on('close', () => followers.delete(res));
+                    }
+                    else
+                        send(200, '{}');
+                    p.resolve(b.result);
                 }
                 catch (error) {
                     clearTimeout(p.timer);
@@ -114,7 +169,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 +185,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)
@@ -148,8 +211,19 @@ export async function startBrowserSession(o) {
             pending.reject(new Error('session closed'));
             pending = undefined;
         }
+        const flushed = [...followers].map((response) => new Promise((resolve) => response.end(JSON.stringify({ action: null }), resolve)));
+        followers.clear();
+        const stopped = new Promise((resolve) => server.close(() => resolve()));
+        let flushTimer;
+        await Promise.race([
+            Promise.all(flushed),
+            new Promise((resolve) => {
+                flushTimer = setTimeout(resolve, 1000);
+            }),
+        ]);
+        clearTimeout(flushTimer);
         server.closeAllConnections();
-        await new Promise((resolve) => server.close(() => resolve()));
+        await stopped;
     };
     let timeout;
     const armIdle = () => {
@@ -161,6 +235,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 +260,23 @@ 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;
+            advance(entry.action);
+            notify(waitingLine(action.expiresAt - Date.now()));
         }),
     };
 }

package/dist/node/buy-commands.js

@@ -1,5 +1,5 @@
 /** Buyer commands before a purchase exists: `verify` a file and `buy` it. */
-import { mkdir, readdir, readFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { inspect, inspectHeader, MAX_HEADER, parseHeader } from '../envelope/pay2.js';
 import { AnnonError } from '../errors.js';
@@ -17,6 +17,7 @@ import { offer, resourceHeader, response } from './offers.js';
 import { originFor } from './origin.js';
 import { humanPaymentTerms, quotedSource, savedPayment, validatePaymentToken, } from './payment-terms.js';
 import { claimPurchase } from './purchase-guard.js';
+import { rememberPurchase, savedRecordIds } from './purchase-ref.js';
 import { resourceAllowed } from './resources.js';
 /** `verify`: a local file's header and body, or a remote file's header, against its listing. */
 async function verifyFile(ctx) {
@@ -155,13 +156,10 @@ async function buy(ctx, preparedBuy) {
     const guardDir = join(c.stateDir, 'purchase-guards');
     await mkdir(guardDir, { recursive: true, mode: 0o700 });
     const known = [];
-    for (const name of await readdir(storeDir)) {
-        if (!/^[0-9a-f]{64}\.json$/.test(name))
+    for (const id of await savedRecordIds(storeDir)) {
+        if (!isId(id))
             continue;
-        const envelope = JSON.parse(await readFile(join(storeDir, name), 'utf8'));
-        if (!isId(envelope.id))
-            continue;
-        const saved = await sdk.store.load(purchaseKey(envelope.id));
+        const saved = await sdk.store.load(purchaseKey(id));
         if (saved?.purchase.file_id === found.fileId &&
             saved.purchase.contract === c.contractId &&
             saved.terms.network === (saved.purchase.route === 'base-usdc' ? 'eip155:8453' : c.network))
@@ -176,6 +174,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));
         },
@@ -212,6 +214,7 @@ async function buy(ctx, preparedBuy) {
                 if (renewalError)
                     throw renewalError;
                 await guard.saved(record.id);
+                await rememberPurchase(c, record.id);
             },
             recovery: buyer,
             ...(baseSponsorship ? { baseSponsorship } : {}),
@@ -277,11 +280,16 @@ 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.`
+                : bought.instructions
+                    ? 'Fund the deposit as instructed, then check status and open this purchase.'
+                    : `Payment sent. Run annon status ${bought.record.id}, then annon open ${bought.record.id} --output <file>.`,
         };
     }
     catch (error) {

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

@@ -0,0 +1,18 @@
+import type { Input } from './cli.js';
+export interface BuyFollow {
+    notify?: (message: string) => void;
+    /** Pause between status checks; resolves early when `signal` aborts. */
+    wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Aborting stops the waiting only. The saved purchase is left as it is. */
+    signal?: AbortSignal;
+    /** Asked once the purchase is accepted and no `--open` path was given. */
+    savePath?: () => Promise<string | undefined>;
+    onWaiting?: (waiting: boolean) => void;
+}
+type Execute = (input: Input) => Promise<unknown>;
+/**
+ * Runs one command. A `buy` is followed when the caller is a person (`follow`) or asked for
+ * `--open`; a deposit route returns its instructions without waiting.
+ */
+export declare function buyFlow(input: Input, execute: Execute, follow: boolean, o?: BuyFollow): Promise<unknown>;
+export {};

package/dist/node/buy-flow.js

@@ -0,0 +1,89 @@
+import { commonInput } from './cli-flags.js';
+import { publicError } from './errors.js';
+import { newOutput } from './io.js';
+const CHECKS = 60;
+const INTERVAL_MS = 3000;
+const pause = (ms, signal) => new Promise((resolve) => {
+    const done = () => {
+        clearTimeout(timer);
+        resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+});
+/** Status checks until the purchase is accepted, the checks run out or the wait is cancelled. */
+async function accepted(execute, input, id, o) {
+    o.onWaiting?.(true);
+    try {
+        for (let check = 0; check < CHECKS && !o.signal?.aborted; check++) {
+            if (check > 0)
+                await (o.wait ?? pause)(INTERVAL_MS, o.signal);
+            if (o.signal?.aborted)
+                break;
+            const status = (await execute({
+                ...commonInput(input),
+                command: 'status',
+                target: id,
+            }));
+            if (status.state === 'accepted')
+                return true;
+        }
+        return false;
+    }
+    finally {
+        o.onWaiting?.(false);
+    }
+}
+/**
+ * Runs one command. A `buy` is followed when the caller is a person (`follow`) or asked for
+ * `--open`; a deposit route returns its instructions without waiting.
+ */
+export async function buyFlow(input, execute, follow, o = {}) {
+    if (input.command !== 'buy' || (!follow && input.open === undefined))
+        return execute(input);
+    // Refuse a taken output name before any payment step.
+    if (input.open !== undefined)
+        await newOutput(input.open);
+    const bought = (await execute(input));
+    const id = bought.purchaseId;
+    if (typeof id !== 'string' || !['submitted', 'uncertain'].includes(String(bought.state)))
+        return bought;
+    o.notify?.(bought.state === 'uncertain'
+        ? 'The wallet may have sent this payment. Do not pay again. Checking NEAR...'
+        : 'Payment sent. Waiting for NEAR to accept...');
+    // From here the payment exists: a later failure is reported next to the purchase, never instead.
+    const pending = (statusError) => ({
+        ...bought,
+        settlement: 'pending',
+        ...(statusError ? { statusError } : {}),
+        next: `Not accepted yet. Do not pay again. Run annon status ${id} until it is accepted, then annon open ${id} --output <file>.`,
+    });
+    try {
+        if (!(await accepted(execute, input, id, o)))
+            return pending();
+    }
+    catch (error) {
+        return pending(publicError(error));
+    }
+    const settled = { ...bought, state: 'accepted', next: `annon open ${id} --output <file>` };
+    const output = input.open ?? (await o.savePath?.());
+    if (!output)
+        return settled;
+    try {
+        const opened = (await execute({
+            ...commonInput(input),
+            command: 'open',
+            target: id,
+            output,
+        }));
+        return {
+            ...bought,
+            state: 'opened',
+            opened: { output: opened.output, bytes: opened.bytes },
+            next: 'The file is saved.',
+        };
+    }
+    catch (error) {
+        return { ...settled, openError: publicError(error) };
+    }
+}

package/dist/node/cli-flags.d.ts

@@ -0,0 +1,10 @@
+/** The flag tables of the CLI: what every command accepts, for parsing, completion and follow-ups. */
+import type { Command, Input } from './cli.js';
+export declare const common: string[];
+export declare const perCommand: Record<Command, string[]>;
+export declare const camel: (flag: string) => string;
+export declare const commandNames: Command[];
+/** Every flag a command accepts, as typed on the command line. */
+export declare const commandFlags: (command: Command) => string[];
+/** The deployment, wallet and output options of one command, for a follow-up command it starts. */
+export declare const commonInput: (input: Input) => Partial<Input>;

package/dist/node/cli-flags.js

@@ -0,0 +1,68 @@
+export const common = [
+    'no-open',
+    'json',
+    'config',
+    'contract-id',
+    'near-rpc',
+    'base-rpc',
+    'network',
+    'state-dir',
+    'relayer',
+    'trust-contract',
+    'wallet',
+    'evm-key-file',
+    'solana-key-file',
+    'near-key-file',
+    'near-account',
+    'near-public-key',
+    'backup-secret-file',
+];
+export const perCommand = {
+    shops: ['search', 'limit', 'offset'],
+    shop: ['id'],
+    catalog: ['shop', 'search', 'limit', 'offset'],
+    fund: [],
+    budget: [],
+    login: [],
+    init: [
+        'signer',
+        'credential-env',
+        'credential-keychain',
+        'agent',
+        'recovery',
+        'key-env',
+        'keychain-entry',
+        'new-key',
+        'daily-budget',
+    ],
+    share: ['resume', 'price', 'shop', 'title', 'description', 'storage-budget', 'listing-storage'],
+    sell: ['resume', 'price', 'split', 'base', 'moderator', 'output', 'storage-budget'],
+    buy: [
+        'force',
+        'origin',
+        'route',
+        'from-chain',
+        'from-asset',
+        'refund-to',
+        'recovery',
+        'max-price',
+        'moderator',
+        'url',
+        'open',
+        'shop',
+        'search',
+    ],
+    open: ['purchase', 'file', 'url', 'output'],
+    recover: ['recovery', 'purchase'],
+    stop: [],
+    verify: [],
+    status: [],
+};
+export const camel = (flag) => flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+export const commandNames = Object.keys(perCommand);
+/** Every flag a command accepts, as typed on the command line. */
+export const commandFlags = (command) => [...perCommand[command], ...common].map((flag) => `--${flag}`);
+/** The deployment, wallet and output options of one command, for a follow-up command it starts. */
+export const commonInput = (input) => Object.fromEntries(common
+    .map((flag) => [camel(flag), input[camel(flag)]])
+    .filter(([, v]) => v !== undefined));

package/dist/node/cli.d.ts

@@ -1,4 +1,5 @@
 import type { BuyRoute } from '../routes.js';
+import { type BuyFollow } from './buy-flow.js';
 export type Command = 'shops' | 'shop' | 'catalog' | 'fund' | 'budget' | 'share' | 'sell' | 'buy' | 'open' | 'recover' | 'stop' | 'verify' | 'status' | 'login' | 'init';
 export interface Input {
     command: Command;
@@ -55,6 +56,13 @@ export interface Input {
     file?: string;
     url?: string;
     output?: string;
+    /** `buy --open <path>`: wait for acceptance, then write the opened file there. */
+    open?: string;
 }
 export declare function parseCli(argv: string[]): Input;
-export declare function runCli(argv: string[], execute: (input: Input) => Promise<unknown>, write: (text: string) => void): Promise<number>;
+/** How one command line is presented and followed up; the defaults are the script contract. */
+export interface RunOptions extends BuyFollow {
+    /** Readable text in place of the JSON envelope. `--json` always wins. */
+    human?: boolean;
+}
+export declare function runCli(argv: string[], execute: (input: Input) => Promise<unknown>, write: (text: string) => void, options?: RunOptions): Promise<number>;