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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @defdone/annon
 
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- Add `BrowserPurchaseController.reconcile()` so a purchase that 1Click reported as failed can be checked again. Under the purchase lease it keeps the same purchase, deposit and recovery identity, checks NEAR acceptance and reads the existing deposit's 1Click status once. Accepted moves to `accepted`, `SUCCESS` to `accepting` and `REFUNDED` to `refunded`; anything else stays `failed` with the new status saved. If the saved deposit address or memo, the restored purchase's deposit and the saved polling checkpoint disagree, it refuses before any read or write. It never creates, starts or pays for a purchase.
+- Bare `annon init` creates the CLI backup secret at `~/.config/annon/backup-secret`: 32 random bytes as hex, mode 0600 from the first write, published with a hard link so it never appears half-written and never replaces an existing file. Running it again only validates the file. It refuses to create a new secret while saved records or backups exist, never prints the secret, and sends its one-time notice to stderr. `--backup-secret-file`, `ANNON_BACKUP_SECRET_FILE` and `ANNON_BACKUP_SECRET` keep their precedence; the default file is read only when none is set, and a selected source that fails never falls back. Other commands, agent mode and MCP read the default but never create it. Reading the default checks that `~/.config/annon` is a private directory you own, refuses symlinks, FIFOs and other non-regular files without blocking, and never repairs anything. Bare `init` reports an unreadable config as a setup error (exit 2). A pending `status` now uses the default file too. `annon --version` (or `-v`) prints the installed version. The quickstart replaces the manual secret recipe with `annon init` and explains backup and restore.
+- The CLI wallet approval page shows a readable summary of exactly what the wallet signs: a title per action, the pairing code to compare, amounts in USDC or NEAR, receiver, account, expiry and what signing does, with the CLI's terms shown apart and the raw request under Technical details (the NEP-413 nonce as hex). Each click opens at most one wallet window, so Meteor's web popup is no longer blocked: NEP-413 messages are signed without a sign-in, and transactions connect first and then send. After a closed, blocked or declined wallet window the page explains it and allows another try until the request expires. The terminal prints a waiting line with the expiry, the reported wallet failure and a specific final error (`cancelled`, `rejected` or `wallet_error`) instead of `operation_failed`. Once the page has called the wallet's send for a transaction, the request is never attempted again: the CLI records the send start before the wallet is called, the request ends as `transaction_uncertain` with a warning not to pay again, the saved purchase keeps that state without inventing a transaction hash, and it blocks a plain rerun of `annon buy` until it is accepted or `--force` is used. A result the CLI cannot verify after the send start also ends as uncertain, keeping a valid transaction hash when there is one. An uncertain `annon buy` exits 4, and `annon status` reports `submission: "uncertain"` with a warning not to pay again. The NEAR wallet is chosen in a styled, keyboard-accessible list instead of the browser's native menu.
+
 ## 0.1.0-alpha.1
 
 ### Patch Changes

package/CLI.md

@@ -2,7 +2,9 @@
 
 Build with `pnpm build`. The `@defdone/annon` package ships the `annon` bin;
 in this checkout run `node packages/annon/dist/node/main.js` in its place.
-Run `annon --help` for all flags. All commands return JSON; `--json` uses one compact
+Run `annon --help` for all flags and `annon --version` (or `-v`) for the installed version; with
+`--json` the version is `{ "ok": true, "result": { "version": ... } }`. It loads no config, wallet
+or secret and also works in agent mode. All commands return JSON; `--json` uses one compact
 JSON line and disables interactive prompts. Success is `{ "ok": true, "result": ... }`;
 errors are `{ "ok": false, "error": { "code": ..., "message": ... } }`.
 
@@ -53,10 +55,9 @@ On macOS, with no NEAR file or credential env value, explicitly select both
 service `near-mainnet-alice.near`, account `alice.near:ed25519:PUBLIC_KEY`.
 Other platforms use the credential JSON file or environment. No keychain enumeration occurs.
 
-Sell, buy, open, recover and stop also require a user-held random 32-byte backup secret,
-encoded as 64 lowercase hex characters in `ANNON_BACKUP_SECRET`, or in the file named by
-`--backup-secret-file` / `ANNON_BACKUP_SECRET_FILE`. Create it with a cryptographic random
-generator and keep it outside the repository. It is never derived from a wallet signature.
+Sell, buy, open, recover and stop also require a random 32-byte backup secret. It encrypts the
+local purchase, recovery and sell records and the portable backups. It is never derived from a
+wallet signature or key. See [Backup secret](#backup-secret).
 `verify` and accepted/read-only `status` need neither a wallet nor this secret. A pending Base `status` with saved state and a backup secret may send `unlock` through the configured relayer or NEAR wallet. Status can update encrypted local state and backups: expired/canceled Base payments are marked with `paymentState`, preserving the purchase, attempts and recovery key. It never deletes the purchase record.
 
 State directories are created with mode 0700 and records/outputs with 0600. Keep existing
@@ -64,8 +65,99 @@ state directories private. Purchases and recovery grants are encrypted by the SD
 encrypted backups are under `stateDir/backups`. Public headers and resource URLs are saved
 separately for later downloading. Preserve state after timeouts. Losing local state does not
 lose recovery rights: the same recovery wallet can create a fresh grant on a new device with
-a new backup secret. Keys, signed payment payloads and decrypted file contents are never
-returned in CLI/MCP results. Plaintext is written only to the explicitly named output.
+a new backup secret ([Loss](#backup-secret) explains when `init` creates one). Keys, signed payment
+payloads and decrypted file contents are never returned in CLI/MCP results. Plaintext is written only to the explicitly named output.
+
+### Backup secret
+
+Run `annon init` once, before buying, selling or enabling agent mode. It creates
+`~/.config/annon/backup-secret`: 32 random bytes as 64 lowercase hex characters and a newline,
+mode 0600, in a directory created with mode 0700. The file is written to an exclusive temporary
+file and published with a hard link, so it never appears half-written and an existing file is
+never replaced. Running `init` again only validates the file and reports `"created": false`. An
+unsafe default is refused and never repaired: a symlink, FIFO or other non-regular file, a file not
+owned by you or with group or other permission bits, malformed content, or an `~/.config/annon`
+that is a symlink, is not owned by you, or is writable by group or others. An existing 0755
+directory is fine. Every command that reads the default applies the same checks.
+
+The location is fixed. `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `--config`,
+`ANNON_CONFIG` and `--state-dir` do not move it. For another private location, name an existing file with the explicit inputs below.
+
+Sources, in order, as before this file existed:
+
+1. `--backup-secret-file` (or, when the flag is absent, `ANNON_BACKUP_SECRET_FILE`), a file with the
+   64 hex characters.
+2. `ANNON_BACKUP_SECRET`, the hex value itself. Prefer a file: environment values are inherited by
+   child processes.
+3. The default file, only when neither is set.
+
+An empty value counts as unset, as before: an empty `--backup-secret-file` selects no file even when
+`ANNON_BACKUP_SECRET_FILE` is set, and moves on to `ANNON_BACKUP_SECRET`. Hex must be lowercase in
+every source; an optional `0x` prefix and surrounding whitespace are accepted. A selected source that is missing,
+unreadable or malformed fails with `backup_secret_required` (exit 2); there is no fallback to a
+later source, the default file or a new secret. `annon init` with an explicit source only validates
+it and never writes, creates or changes that file. Commands other than `init` read the secret but
+never create it, and agent mode and MCP never create it. Bare `init` accepts only `--json`,
+`--config`, `--state-dir` and `--backup-secret-file`; signer options need `--agent`.
+
+Output: stdout carries the usual single JSON result, for example
+`{"ok":true,"result":{"configured":true,"backupSecret":{"source":"default-file","path":"/home/me/.config/annon/backup-secret","created":true}}}`.
+`source` is `default-file`, `flag-file`, `env-file` or `env`; `path` is shown for files only. The
+one-time creation notice goes to stderr, also with `--json`. The secret itself is never printed, in
+results, errors or notices.
+
+**Back it up.** The secret is not part of the encrypted backups in `stateDir/backups`; copy the file
+itself, separately, to private encrypted storage. Never `cat` it or paste it into a terminal. This
+copies without displaying it and refuses an existing destination:
+
+```sh
+node --input-type=module -e '
+  import { constants } from "node:fs";
+  import { copyFile } from "node:fs/promises";
+  await copyFile(process.argv[1], process.argv[2], constants.COPYFILE_EXCL);
+' "$HOME/.config/annon/backup-secret" /mounted-private-encrypted-backup/annon-backup-secret
+```
+
+The copy keeps mode 0600 when the destination supports POSIX permissions; check it. A secret manager
+that imports files is also fine.
+
+**Restore.** On a new machine, put the saved file in a private directory (directory mode 0700, file
+mode 0600), copy the encrypted record backups separately, and select the file. Do not run `init`
+first:
+
+```sh
+export ANNON_BACKUP_SECRET_FILE=/absolute/private/restored-annon-backup-secret
+annon open /absolute/private/purchase-backup.json --url https://host.example/file --output restored-file
+```
+
+Opening one known backup proves the restore. To restore to the default location instead, create
+`~/.config/annon` with mode 0700 and copy in the other direction, still refusing an existing file:
+
+```sh
+mkdir -p -m 700 "$HOME/.config/annon"
+node --input-type=module -e '
+  import { constants } from "node:fs";
+  import { copyFile } from "node:fs/promises";
+  await copyFile(process.argv[1], process.argv[2], constants.COPYFILE_EXCL);
+' /mounted-private-encrypted-backup/annon-backup-secret "$HOME/.config/annon/backup-secret"
+```
+
+**Loss.** If the secret disappears, commands fail with `backup_secret_required` and a pending
+`status` stays pending; nothing recreates it. Restore the same bytes. Bare `init` creates a new
+secret only when both checked state locations are empty: the effective state directory and the
+default `~/.local/share/annon`, each in `records` and `backups`. If every copy is lost and you want
+to recover with a new secret, first move the whole old state, including `~/.local/share/annon`, to
+a separate private archive and keep it. Then use an empty state directory, run `init`, and run
+`recover` with the same recovery wallet. That creates a fresh grant and new records; it cannot
+decrypt the archived records or resume pending sell jobs. An operator can instead provision a
+separate secret file and select it with `ANNON_BACKUP_SECRET_FILE`. Use one secret per state
+directory.
+
+**Agents.** `init --agent` does not create or reference a backup secret. Run bare `init` before it,
+or give the agent an operator-managed file with an absolute `ANNON_BACKUP_SECRET_FILE` in the
+launcher. A launcher that sets `ANNON_BACKUP_SECRET_FILE` must point it at a file that exists; a
+missing file fails without falling back to the default. Once agent mode is active, `init` is
+refused, so provision or restore the secret outside the running agent.
 
 ## Commands
 
@@ -161,9 +253,23 @@ blindly retried. Raw upstream errors are intentionally suppressed to avoid leaki
 | --- | --- |
 | 0 | Command completed; buy may still require a deposit or settlement |
 | 1 | Operation failed; inspect final status and retained encrypted state before retrying |
-| 2 | Invalid arguments, configuration, wallet source or missing local input |
-| 3 | First-use contract trust required or declined |
-| 4 | `status` reports pending; acceptance has not been observed (not proof of payment failure) |
+| 2 | Invalid arguments, configuration, wallet source or missing local input; `purchase_open` when a saved purchase of the file, including an uncertain NEAR send, still blocks a new one |
+| 3 | First-use contract trust required or declined; browser approval cancelled (`cancelled`), expired (`cancelled`, or `rejected` or `wallet_error` after the last wallet failure the page reported) or declined by the wallet |
+| 4 | Not settled, and not proof of failure: `status` reports pending; `buy` returned `state: "uncertain"` (its payment may be on chain; the JSON result is unchanged and names the saved purchase); or `transaction_uncertain`: a transaction may have been sent and is not confirmed |
+
+In browser approval, once the CLI has acknowledged the page's send start, the request can only end
+as a verified transaction or as `transaction_uncertain`: a wallet failure, a cancel, the expiry, or a
+result the CLI cannot verify (an RPC rejection, malformed evidence) never counts as "not sent". The
+purchase is saved with that uncertainty, with the transaction hash only when the wallet returned a
+valid one. `annon buy` then exits 4 with `state: "uncertain"`, and `annon status <purchase id>`
+answers `submission: "uncertain"` until the purchase is accepted. Do not pay again.
+
+A plain `annon buy` of the same file is refused with `purchase_open` while that uncertainty is
+saved, also after the purchase expired: a late transfer still moves tokens, and the contract then
+owes a refund that is paid out later rather than returned at once. Neither a pending status, an
+expired purchase nor an empty wallet history proves that nothing was sent. `--force` overrides the
+guard; use it only after you have reconciled the original attempt, for example by finding its
+final transaction or its refund, because otherwise you may pay twice.
 
 ## SDK seller resume and CKD configuration
 

package/README.md

@@ -203,6 +203,7 @@ const { meta, data } = await controller.open({ onProgress: renderDownload });
   before an expired key is replaced. Portable receipts carry those archives too.
 - The local random backup secret is persisted in IndexedDB for reload recovery. It protects
   encrypted storage from accidental disclosure and shares the embedding page's trust boundary.
+  This is the browser's secret; the CLI keeps its own in a file ([CLI.md](CLI.md#backup-secret)).
 - Export with `controller.exportReceipt(portableSecret)`, using a separate random 32-byte
   `newBackupSecret()` that you keep separately. Import with
   `storage.importReceipt(file, portableSecret)`. Import restores the header, resource URL and
@@ -295,6 +296,9 @@ shop-provided data: on each shop's `info` from `listShops`, and as `rules` with
 
 ## CLI browser wallet login
 
+Run `annon init` once first. It creates the CLI backup secret file that encrypts local records
+([CLI.md](CLI.md#backup-secret)); login neither creates nor exports it.
+
 ```sh
 annon login --wallet evm
 annon login --wallet near --network near:testnet
@@ -308,21 +312,44 @@ in the wallet.
 | Wallet | How | Signing supported |
 | --- | --- | --- |
 | EVM | Injected EIP-1193 wallet on Base | `personal_sign` for the SDK's authorization texts, `eth_signTypedData_v4` for the exact EIP-3009/x402 payload |
-| NEAR | Meteor Wallet (extension or web popup; mainnet and testnet) or HOT Wallet (mainnet only) through Wallet Selector, picked on the page; account-only sign-in (no `contractId`, no method list) | NEP-413 and `signAndSendTransaction`, including the required deposit `"1"` on `ft_transfer_call` |
+| NEAR | Meteor Wallet (extension or web popup; mainnet and testnet) or HOT Wallet (mainnet only) through Wallet Selector, picked on the page. NEP-413 messages are signed directly, with the account chosen in the wallet and no sign-in. Transactions take two clicks: an account-only sign-in (no `contractId`, no method list), then the transaction | NEP-413 and `signAndSendTransaction`, including the required deposit `"1"` on `ft_transfer_call` |
 
 Browser and remote EVM split-deployment transactions and browser and remote Solana signing are not
 included; the local-key adapters remain available for those workflows.
 
 **The local page.** The listener binds `127.0.0.1` on an OS-assigned port before opening the browser.
 Match the short pairing code with the terminal, and review the action, amount, recipients, file and
-chain on the page before approving in the wallet.
+chain on the page before approving in the wallet. The page shows a summary built only from the
+request the wallet signs (amounts in USDC or NEAR, receiver, account, expiry), the CLI's payment or
+listing terms apart from it with a warning if their price differs, and the raw request under
+Technical details. While a request waits, the terminal prints its expiry on stderr.
+
+- Each click opens at most one wallet window, inside that click, so the browser's pop-up blocker
+  allows it. If the wallet window closes, is blocked or declines before anything is sent, the page
+  says so and you can try again, with the same or another wallet, until the request expires.
+  Nothing is retried for you.
+- Once the page has called the wallet's send for a transaction, that request is never attempted
+  again, whatever the wallet answers, because it may already have broadcast. The request ends as
+  `transaction_uncertain` and the terminal says: "The wallet may have sent the transaction. Do not
+  pay again. Run annon status <purchase id> to check it." The page records the send start with
+  the CLI before it calls the wallet, so a reloaded page or the request's expiry cannot turn it
+  into a retryable failure, and a result the CLI cannot verify after that point also ends as
+  uncertain. `annon buy` exits 4, `annon status` reports `submission: "uncertain"`, and the saved
+  purchase blocks a plain `annon buy` of the same file (`purchase_open`). `--force` overrides it
+  only after you have reconciled the first attempt (see CLI.md).
+- The page reports only a fixed reason name (`window_closed`, `popup_blocked`, `rejected`,
+  `wallet_error`, `refused`, `send_uncertain`, `send_started` or `cancelled`) to the CLI, which
+  prints its own line for it. Cancel ends the request at once; an expired request fails with the
+  last reported reason, for example `rejected` or `wallet_error`, instead of a generic error. A
+  report never completes a request.
 
 - Host (including port), Origin and an unpredictable RAM-only capability are checked on action and
   result API calls.
 - In open mode, a same-origin POST bootstraps the capability once into the opened page, then the
   bootstrap route closes. With `--no-open`, bootstrap is disabled and the capability exists only in
   the printed URL fragment. It is never passed to the browser launcher in argv.
-- Bundled scripts, a restrictive CSP, no framing, `no-store` and `no-referrer` are enforced. The page
+- Bundled scripts and a stylesheet from the page's own origin (no inline styles, fonts or other
+  resources), a restrictive CSP, no framing, `no-store` and `no-referrer` are enforced. The page
   connects only to itself, the Wallet Selector's NEAR RPC (`free.rpc.fastnear.com` on mainnet,
   `test.rpc.fastnear.com` on testnet, fixed in the page and independent of your configured RPC) and
   HOT's relay `h4n.app`, and frames only `hot-labs.org`.
@@ -405,8 +432,11 @@ Order matters, because agent mode refuses `init`, `login` and per-call trust or
 2. Write the deployment, `maxPrice`, `workDir` and, after reviewing the contract,
    `trustContract: true` (or trust it once with a human command and `--trust-contract`). Do not set
    `agent: true` yourself.
-3. Run one `annon init --agent ...` from the examples above. It saves the signer, the daily budget
-   and `agent: true`.
+3. Run bare `annon init` to create the backup secret, or give the launcher an absolute
+   `ANNON_BACKUP_SECRET_FILE` you manage ([CLI.md](CLI.md#backup-secret)). Agent mode never creates
+   one.
+4. Run one `annon init --agent ...` from the examples above. It saves the signer, the daily budget
+   and `agent: true`. It does not create or reference a backup secret.
 
 - Agents never prompt. Missing trust, price cap or daily budget causes a refusal.
 - `allowedResources` is optional. Without it, any secure resource URL is allowed within the
@@ -447,7 +477,8 @@ Before a human payment the CLI confirms the current price, split recipients and
 and file, token and network. Browser mode shows these exact terms with each signing request for
 approval in the page and the wallet. Local and remote human signing require an explicit terminal
 confirmation. Purchase and recovery secrets still need the independent backup secret described in
-CLI.md; login does not derive one from a signature.
+[CLI.md](CLI.md#backup-secret) and created by `annon init`; login does not derive one from a
+signature.
 
 ## Remote signer, HTTP JSON v1
 
@@ -501,9 +532,10 @@ RPC. A returned transaction hash alone never proves success.
 - Definite mismatches and failed finalized transactions are rejected without saving the hash as
   `nearSubmission` evidence. Only RPC unavailability or a non-final status keeps the outcome
   uncertain.
-- If submission or finalized verification is ambiguous, the CLI returns `state: "uncertain"`,
-  `purchaseId` and `txHash`, and keeps `nearSubmission: {state:"uncertain",txHash}` in the encrypted
-  purchase backup. Check status for that saved purchase before buying again.
+- If submission or finalized verification is ambiguous, the CLI returns `state: "uncertain"` and
+  `purchaseId`, and keeps `nearSubmission: {state:"uncertain"}` in the encrypted purchase backup.
+  Both carry `txHash` only when the wallet returned a valid one. `annon buy` exits 4. Check status
+  for that saved purchase before buying again.
 - Signing errors with a known hash also expose safe hash and purchase evidence, with exit code 4.
 
 **Reference handler.** `node/signer-mock` exports `signerMock`, an authenticated HTTP

package/dist/api/annon-types.d.ts

@@ -100,9 +100,10 @@ export interface Bought {
     route: BuyRoute;
     record: PurchaseRecord;
     instructions?: Deposit;
+    /** `txHash` is absent when the wallet may have sent the transaction without returning one. */
     uncertain?: {
         purchaseId: string;
-        txHash: string;
+        txHash?: string;
     };
     payment?: string;
 }

package/dist/api/annon.js

@@ -869,11 +869,18 @@ export class Annon {
                 const next = {
                     ...record,
                     revision: record.revision + 1,
-                    nearSubmission: { state: 'uncertain', txHash: error.txHash },
+                    nearSubmission: {
+                        state: 'uncertain',
+                        ...(error.txHash ? { txHash: error.txHash } : {}),
+                    },
                 };
                 if (!(await store.compareAndSet(purchaseKey(id), record, next)))
                     throw new TransactionUncertain(error.txHash, id);
-                return { route, record: next, uncertain: { purchaseId: id, txHash: error.txHash } };
+                return {
+                    route,
+                    record: next,
+                    uncertain: { purchaseId: id, ...(error.txHash ? { txHash: error.txHash } : {}) },
+                };
             }
             return { route, record };
         }

package/dist/browser/index.d.ts

@@ -18,6 +18,6 @@ export { type CatalogEntry, type CatalogQuery, type ConfiguredShop, canonicalMan
 export { TransactionUncertain } from '../wallet/uncertain.js';
 export { type EvmWallet, FileFundingRefused, type IdentityWallet, type NearWallet, } from '../wallet/wallet.js';
 export { BROWSER_DOWNLOAD_LIMIT, type BrowserDownloadOptions, type BrowserDownloadProgress, browserDownload, } from './download.js';
-export { type BrowserOpenOptions, BrowserPurchaseController, type BrowserPurchaseRecord, type BrowserPurchaseState, type BrowserPurchaseStorage, browserAnnon, browserPurchaseStorage, type ControllerOptions, PurchaseLeaseBusy, type PurchaseProgress, type PurchaseSdk, type PurchaseTermsReview, } from './purchases.js';
+export { type BrowserOpenOptions, BrowserPurchaseController, type BrowserPurchaseRecord, type BrowserPurchaseState, type BrowserPurchaseStorage, browserAnnon, browserPurchaseStorage, type ControllerOptions, PurchaseLeaseBusy, type PurchaseProgress, type PurchaseSdk, type PurchaseTermsReview, type ReconcileOptions, type ReconcileResult, } from './purchases.js';
 export { type BrowserSaleIndex, type BrowserSellerOptions, browserSellerSpool, browserSellerStorage, createBrowserSeller, type SaleHandle, type SaleView, type SellDraft, type SellerConnection, type SellerFacade, type SellProgress, type SellQuote, type SellStep, type SellTerms, } from './selling.js';
 export { type BrowserNearProvider, type BrowserNearTransaction, BrowserWalletError, type BrowserWalletErrorCode, browserEvmWallet, browserNearWallet, browserSolanaWallet, type InjectedEvmProvider, type InjectedSolanaKey, type InjectedSolanaProvider, signNearUpload, } from './wallets.js';