@inversealtruism/cairn-cli 0.3.2 → 0.3.5

package/README.md

@@ -1,11 +1,13 @@
 # cairn-cli
 
-A command-line client for **Compute Substrate / Cairn** — browse the board, and **send CSD,
+A command-line client for **Compute Substrate / Cairn** - browse the board, and **send CSD,
 propose, attest, and place stones on the Wall** straight from your terminal.
 
 For the people who'd rather not put a key in a browser extension: **cairn-cli never holds your
-key.** Reads are plain HTTP. For writes it drives your **own installed `csd` wallet** — `csd`
-signs with your key (CSD_SIG_V1), and cairn-cli adds the Cairn layer on top: it computes the
+key.** Reads are plain HTTP. For writes it drives your **own installed `csd` wallet** - `csd`
+signs with your key (CSD_SIG_V1) -- https://github.com/compute-substrate/compute-substrate
+
+cairn-cli adds the Cairn layer on top: it computes the
 canonical payload hash, fetches a spendable input from the Cairn proxy (so you don't need a
 synced local node), registers your off-chain content, and gives you the board / wall / network
 views the raw `csd` CLI doesn't have. Browsing needs no `csd` binary and no keys.
@@ -44,15 +46,16 @@ cairn watch                  # live auto-refreshing board
 cairn recent                 # recent proposals and support
 cairn show   <id>            # item detail and integrity check
 cairn verify <id>            # recompute the content hash and check it
-cairn wall                   # the Wall — top stones + the reigning King
+cairn wall                   # the Wall - top stones + the reigning King
 cairn network                # live network telemetry (alias: cairn stats)
 cairn quests                 # open quests
 cairn profile <addr>         # identity + on-chain reputation
 cairn leaderboard            # top builders by reputation
+cairn tokens [address]       # CairnX token balances + .csd names (see below)
 cairn ls --json              # machine-readable output
 ```
 
-## Wallet (transacting — uses your own `csd` wallet)
+## Wallet (transacting - uses your own `csd` wallet)
 
 One-time: install Compute Substrate's `csd` CLI and create/import your key.
 
@@ -61,7 +64,7 @@ csd wallet new                          # or: csd wallet init --privkey <your ke
 cairn setup                             # checks csd + wallet, shows your address + balance
 ```
 
-Then transact — cairn-cli builds the request, `csd` signs with your key, and the tx is submitted
+Then transact - cairn-cli builds the request, `csd` signs with your key, and the tx is submitted
 through the Cairn proxy (no local node required):
 
 ```bash
@@ -75,11 +78,33 @@ cairn wall place "gm, Compute Substrate"
 Fees and amounts are in **CSD** (e.g. `--amount 1.5`, `--fee 0.05`). Minimums: 0.25 CSD to propose,
 0.05 CSD to attest. Support is a paid demand signal, not a payment to the author; fees go to miners.
 
+## CairnX (tokens + .csd names)
+
+CairnX is the token / DeFi layer that lives entirely in `cairnx:v1` records on-chain
+(traded at [cairn-substrate.com/trade](https://cairn-substrate.com/trade)). Reads hit the
+CairnX state API (`CAIRNX_API` → local service → public gateway); the one write —
+`token-send` — anchors a canonical transfer record signed by your own `csd` wallet.
+
+```bash
+cairn tokens [address]                  # token balances (locked shown) + owned .csd names
+cairn token-info CAIRN                  # supply · minted · decimals · mint mode · top-10 holders
+cairn token-send --ticker CAIRN --to 0x… --amount 1.5   # send tokens (--dry-run to preview, --yes to skip the prompt)
+cairn names [address]                   # owned .csd names
+cairn name inverse                      # one name: owner · lease · open offer
+```
+
+`token-send` amounts are **human units converted exactly** (string math, never floats):
+`--amount 1.5` on an 8-decimals token sends `150000000` base units, and `1.5` of a
+0-decimals token is an **error**, never a truncation. The transfer itself is free at the
+token layer; anchoring it on-chain costs the 0.25 CSD propose fee (printed before anything
+signs, and `--dry-run` shows the exact canonical record + hash without signing).
+
 ## Configuration (environment variables)
 
 | Variable | Default | Purpose |
 |---|---|---|
 | `CAIRN_API` | `https://cairn-substrate.com` | the board / proxy to talk to (use your own, e.g. `http://127.0.0.1:7777`) |
+| `CAIRNX_API` | local service, then the public gateway | the CairnX (token/name) state API; set it to pin one base |
 | `CAIRN_CSD` | `csd` | path to your installed `csd` binary (signs your transactions) |
 | `CAIRN_ADDR` | – | your public addr20; skips deriving it from the csd wallet |
 | `CAIRN_RPC` | – | optional csd node RPC; enables fully trustless `verify` (recompute the hash + confirm on-chain) |
@@ -91,13 +116,18 @@ Fees and amounts are in **CSD** (e.g. `--amount 1.5`, `--fee 0.05`). Minimums: 0
 - `verify` fetches an item, recomputes `sha256(canonical content)` locally, and if `CAIRN_RPC` is set,
   confirms that hash is the one committed on-chain. You trust the math, not the server.
 - `send` / `propose` / `support` / `wall place`: cairn-cli fetches a spendable input from the Cairn
-  proxy, hands it to **your** `csd` (which signs with your wallet key — for these commands the key
+  proxy, hands it to **your** `csd` (which signs with your wallet key - for these commands the key
   stays inside `csd` and never enters the cairn-cli process), then submits the signed transaction
   through the proxy and (for proposals) registers the off-chain content. Sealed claims and
   Sign-in-with-CSD live in the Cairn Wallet.
-- **L3 registry commands** (`gateway register`, `peer announce`, `identity claim`) are the one
+- **CairnX commands** (`tokens`, `token-info`, `token-send`, `names`, `name`) read the CairnX
+  state API. `token-send` builds the canonical transfer record locally (`sha256(uri)` is the
+  on-chain commitment, byte-exact-tested against the resolver's own builder), checks your
+  balance, prints the record + the 0.25 CSD anchor cost, then has `csd` sign the anchoring
+  Propose — the same no-key-in-process path as `propose`/`send`.
+- **registry commands** (`gateway register`, `peer announce`, `identity claim`) are the one
   exception: they sign a registry *binding* with `@inversealtruism/csd-registry`, so cairn-cli reads
-  your private key from `csd wallet config` and signs **in-process** (the key is never networked — only
+  your private key from `csd wallet config` and signs **in-process** (the key is never networked - only
   the signed canonical content is published). Because these load key material into the Node process,
   the `csd-registry` / `csd-codec` dependencies are **pinned to exact versions** (no caret ranges) to
   shrink the supply-chain surface. If you only ever `send`/`propose`/`support`, your key never leaves `csd`.

package/dist/cli.js

@@ -7,29 +7,128 @@ import * as csd from "./lib/csd.js";
 import { buildCommitment } from "./lib/item.js";
 import { buildGatewayRecord, buildPeerRecord, buildIdentityCommit, buildIdentityReveal } from "@inversealtruism/csd-registry";
 import { canonicalJson } from "@inversealtruism/csd-codec";
+import { cairnxGet, activeCairnxBase, buildTransferRecord, humanToBase, baseToHuman, CAIRNX_DOMAIN, CAIRNX_ANCHOR_FEE, TICKER_RE, NAME_RE } from "./lib/cairnx.js";
 import { randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
 import { c, banner, bannerAnimated, rule, badge, bar, csd as csdFmt, ok, warn, err, key as kdim, pad, spinner, sleep, isTty, anim, clearScreen, cursorHome, san } from "./lib/ui.js";
 const CSD = (n) => Number.isFinite(n) ? Math.round(n * CSD_PER_COIN) : NaN; // CSD → base units
+// ── max-fee sanity guard (UTXO-VALUE-1) ──────────────────────────────────────────────────────
+// A CSD fee is implicit (Σin − Σout) and the chain enforces NO maximum, so a hostile proxy that
+// UNDER-reports the picked UTXO's value would make `csd` compute too-small a change and the
+// difference is silently burned to the miner as fee — the user's own funds, with no on-chain
+// protection. cairn-cli has no codec to recompute the input's REAL value (the wallet's
+// verifyInputValues path), so it applies a proportionate SANITY cap on the fee instead: the fee
+// must be ≤ max(1 CSD absolute, 25% of the tx value). Every honest fee (a 0.01 CSD transfer fee,
+// a 0.25 CSD propose) passes; a typo / hostile-inflated fee is refused. `--max-fee <CSD>` overrides.
+// Returns null if the fee is acceptable, or a human error string to print and abort.
+const MAX_FEE_ABS = 100_000_000; // 1 CSD absolute floor — every honest fee is well under this
+const MAX_FEE_VALUE_FRACTION = 0.25; // …and ≤ 25% of the value moved
+function feeCap(txValue, a) {
+    if (a.flags["max-fee"] !== undefined) {
+        const m = CSD(Number(a.flags["max-fee"]));
+        if (Number.isSafeInteger(m) && m >= 0)
+            return m;
+    }
+    return Math.max(MAX_FEE_ABS, Math.floor(Math.max(0, txValue) * MAX_FEE_VALUE_FRACTION));
+}
+// Guard a value-write before it is built/signed. `txValue` = the value the user means to move
+// (recipients for a send; the fee itself for a fee-only propose/attest). Prints + returns false on abort.
+function feeSanity(fee, txValue, a) {
+    const cap = feeCap(txValue, a);
+    if (fee > cap) {
+        console.log(err(`fee ${csdToCoins(fee)} CSD looks abnormally high (cap ${csdToCoins(cap)} CSD).`) +
+            c.gray(" A proxy under-reporting your input can silently burn the difference as fee. Lower ") + c.cyan("--fee") +
+            c.gray(", or override with ") + c.cyan("--max-fee <CSD>") + c.gray(" if this is intentional."));
+        return false;
+    }
+    return true;
+}
+// Implied-fee transparency for a single-UTXO spend: the on-chain fee a hostile proxy can inflate is
+// (real input − value − change). We can only see the REPORTED input, but we can flag when the
+// reported change is implausibly small for the input (the collapsed-change signature of an
+// under-report). Non-fatal — a warning the user sees before they commit.
+function warnIfChangeCollapsed(inputValue, txValue, fee) {
+    const change = inputValue - txValue - fee;
+    if (change < 0)
+        return; // pickInput already ensures coverage; defensive
+    // a healthy spend leaves change ≫ fee unless the user genuinely picked a tight UTXO; flag the
+    // case where the implied fee dwarfs the change (what an under-reporting proxy produces).
+    if (change > 0 && fee > change * 4) {
+        console.log(warn(`heads up: change (${csdToCoins(change)} CSD) is much smaller than the fee (${csdToCoins(fee)} CSD).`) +
+            c.gray(" If your proxy under-reports this input, extra value is burned as fee — verify with your own node, or use ") + c.cyan("--max-fee") + c.gray("."));
+    }
+}
+// Pick a spendable input from the proxy, INDEPENDENTLY verify its value against CAIRN_RPC
+// (UTXO-VALUE-1 cross-source cure), and ALWAYS display the input/change so the implied fee is
+// visible on EVERY write (not just `send`). `txValue` = value moved to recipients (0 for a fee-
+// only propose/attest); `fee` = the fee. Returns the csd input triple, or null (reason printed).
+// Defense layering: (1) if an independent node is configured we cryptographically catch an
+// under-report and REFUSE; (2) otherwise the value is proxy-trusted and the only backstop is the
+// feeSanity cap + the visible change line — the user is told to set CAIRN_RPC for a real check.
+async function pickAndShow(addr, need, txValue, fee) {
+    const picked = await api.pickInput(addr, need).catch(() => null);
+    if (!picked) {
+        console.log(err("no single confirmed UTXO covers this spend") + c.gray(" — fund this address, or consolidate (a node + `csd … --auto-input` can combine inputs)."));
+        return null;
+    }
+    const [ptxid, pvoutS] = picked.input.split(":");
+    const v = await api.verifyInputValue(addr, ptxid, Number(pvoutS), picked.value).catch(() => ({ checked: false }));
+    if (v.checked && v.ok === false) {
+        if (v.missing)
+            console.log(err("the picked input is NOT in your independent node's UTXO set (CAIRN_RPC).") + c.gray(" The proxy may be misreporting your coins — refusing to spend. Check your node is synced, or unset CAIRN_RPC to override."));
+        else
+            console.log(err(`input value MISMATCH — proxy says ${csdToCoins(picked.value)} CSD, your node says ${csdToCoins(v.value ?? 0)} CSD.`) + c.gray(" A proxy under-reporting your input would burn the difference as fee — refusing to spend."));
+        return null;
+    }
+    const verified = v.checked && v.ok === true;
+    const inputValue = verified ? Number(v.value) : picked.value;
+    const tag = verified ? c.green(" ✓ verified vs your node")
+        : (CAIRN_RPC ? c.gray(" (independent value check unavailable)") : c.gray(" (set CAIRN_RPC to your own node to independently verify this value)"));
+    console.log(`${kdim("input")}   ${csdToCoins(inputValue)} CSD ${c.gray("(one UTXO)")}${tag}   ${kdim("change")} ${csdToCoins(Math.max(0, inputValue - txValue - fee))} CSD ${c.gray("back to you")}`);
+    warnIfChangeCollapsed(inputValue, txValue, fee);
+    return picked.input;
+}
 // Resolve the user's PUBLIC address (to fetch inputs from the proxy). Never reads the key
 // unless we must derive it locally from the user's own csd wallet config (then we cache
-// only the public address). Order: --address → CAIRN_ADDR → cached → derive via csd.
+// only the public address). Order: --address → CAIRN_ADDR (both EXPLICIT user intent for this
+// invocation) → the csd wallet's real change address → cached config.address (LAST, and never
+// above the wallet — see below).
+//
+// F13/R18: the cached config.address is attacker-tamperable (a poisoned
+// ~/.config/cairn-cli/config.json would otherwise redirect `cairn address` output, so a funder
+// piping it pays the attacker). So when csd is available we re-derive the wallet's REAL change
+// address and treat THAT as authoritative; if it disagrees with the cached value we refuse and
+// rewrite the cache. The cache is only used as a fallback when csd can't tell us the truth.
 async function resolveAddr(a) {
-    const flag = a.flags.address ? String(a.flags.address) : (CAIRN_ADDR || loadLocalConfig().address);
-    if (flag && /^0x[0-9a-fA-F]{40}$/.test(flag))
-        return flag;
+    // explicit, per-invocation choice — the user can deliberately target any address
+    const explicit = a.flags.address ? String(a.flags.address) : CAIRN_ADDR;
+    if (explicit && /^0x[0-9a-fA-F]{40}$/.test(explicit))
+        return explicit;
+    const cached = loadLocalConfig().address;
     const cfg = await csd.walletConfig();
-    // Prefer the address csd already exposes (change addr) — avoids re-deriving from the
-    // privkey, which would put the key on the `csd` argv (visible via /proc on a shared host).
+    // Best case: the wallet exposes its change address directly — authoritative AND needs no key
+    // (no argv exposure). The cache is then only an anti-poison cross-check (F13/R18): if a tampered
+    // config disagrees, say so loudly and use the wallet's address.
     if (cfg?.default_change_addr20 && /^0x[0-9a-fA-F]{40}$/.test(String(cfg.default_change_addr20))) {
-        const addr = String(cfg.default_change_addr20);
-        saveLocalConfig({ address: addr });
-        return addr;
-    }
+        const real = String(cfg.default_change_addr20);
+        if (cached && cached.toLowerCase() !== real.toLowerCase())
+            console.log(warn(`cached address ${c.cyan(san(cached))} does NOT match your csd wallet ${c.cyan(real)}`) + c.gray(" — using the wallet's address and refreshing the cache (a tampered config can't redirect you)."));
+        saveLocalConfig({ address: real });
+        return real;
+    }
+    // No change address configured. Audit H-2: re-deriving from the privkey on EVERY call runs
+    // `csd wallet recover --privkey <KEY>`, putting the key on the argv (readable via /proc on a
+    // shared host). Avoid that — prefer a previously-cached address; only DERIVE when we have
+    // nothing else (then cache it + warn once, and nudge the user to set a change address so the
+    // key is never needed again, which also restores the F13 anti-poison cross-check above).
+    if (cached && /^0x[0-9a-fA-F]{40}$/.test(cached))
+        return cached;
     if (cfg?.default_privkey) {
-        const addr = await csd.deriveAddr(cfg.default_privkey);
-        if (addr) {
-            saveLocalConfig({ address: addr });
-            return addr;
+        const real = await csd.deriveAddr(cfg.default_privkey);
+        if (real && /^0x[0-9a-fA-F]{40}$/.test(real)) {
+            console.log(warn("derived your address from the wallet key once.") + c.gray(" " + csd.keyExposureWarning));
+            saveLocalConfig({ address: real });
+            return real;
         }
     }
     return null;
@@ -39,9 +138,13 @@ async function resolveAddr(a) {
 // proxy ourselves. We do NOT trust csd's own auto-submit: it targets csd's configured node,
 // which may be a different node than the one the Cairn board (and its miner) read — so a tx
 // could sit in the wrong mempool and never get mined into the board's view. Always submit via
-// the proxy (the board's miner-connected node). A repeat that comes back "already present /
-// known" for OUR txid is success (the tx is in that node's mempool); a true double-spend
-// "conflict" is the only ambiguous case, so we confirm via a tx lookup before claiming ok.
+// the proxy (the board's miner-connected node).
+//
+// Success is EVIDENCE-BASED, never message-based: a hostile proxy (or a real double-spend)
+// can return an "already present / conflict" string for a tx that is NOT actually ours, so we
+// never treat any error message as success. A clean submit ack is good; otherwise we ask the
+// node directly whether OUR exact txid is on-chain (api.confirmTxMined), and only claim success
+// when the node confirms it. If we can't confirm, we surface the real node message.
 async function signAndSubmit(csdArgs) {
     const r = await csd.run(csdArgs);
     if (!r.ok)
@@ -57,17 +160,40 @@ async function signAndSubmit(csdArgs) {
     const sub = await api.submitTx(out.tx).catch((e) => ({ ok: false, err: e.message }));
     if (sub.ok)
         return { ok: true, txid: sub.txid || txid };
-    // A benign "already present / mempool conflict" for OUR txid means the tx is already in a
-    // mempool (e.g. csd's own auto-submit reached this same node first, or a re-run) — success.
-    // For a single-key wallet this is safe: only the key owner can produce a conflicting spend
-    // of their own UTXO, so a conflict on our freshly-built tx is our own prior submit, not a
-    // third party. (The narrow exception — two DIFFERENT local spends of one UTXO fired at once
-    // — is on the user.) The node can't be queried for mempool membership (its /tx indexes only
-    // mined txs), so we rely on the matching txid + benign message.
-    if (txid && /already|present|known|in mempool|conflict/i.test(String(sub.err ?? "")))
+    // Submit was NOT acked. Don't trust the error STRING — a forged "already present" can hide a
+    // rejected/conflicting tx. Confirm against the chain: only if the node reports OUR exact txid
+    // as mined is this our own prior submit (a genuine "already in"); otherwise the conflict is a
+    // DIFFERENT spend (a real double-spend / hostile reply) and we surface it as a failure.
+    if (txid && await api.confirmTxMined(txid))
         return { ok: true, txid };
     return { ok: false, error: sub.err || "submit rejected by node", txid };
 }
+// Freshness gate (R12): before building any value tx, consult the proxy's chain-view status so
+// we never sign against a FROZEN or forked tip (the proxy may be failing over to an honest-but-
+// stale or wedged node). Fail CLOSED on a stale tip; fail OPEN (warn only) if the freshness
+// surface is unreachable — that matches the rest of the CLI's 'cannot reach' UX and an old node
+// without /api/rpc/status must still be usable. `--force-stale` lets an operator override.
+async function freshTip(a) {
+    let s;
+    try {
+        s = await api.rpcStatus();
+    }
+    catch {
+        console.log(warn("could not check chain freshness (status surface unreachable) — proceeding"));
+        return true;
+    }
+    const secs = Number(s?.secondsSinceAdvance ?? 0);
+    const threshold = Number(s?.staleSecsThreshold ?? 600);
+    const stale = s?.stale === true || (Number.isFinite(secs) && Number.isFinite(threshold) && threshold > 0 && secs > threshold);
+    if (!stale)
+        return true;
+    if (a.flags["force-stale"]) {
+        console.log(warn(`chain tip looks STALE (${secs}s since last advance) — proceeding anyway (--force-stale)`));
+        return true;
+    }
+    console.log(err(`chain tip looks STALE — last advanced ${secs}s ago (threshold ${threshold}s).`) + c.gray(" The node may be frozen or failing over to a stale view; refusing to build a tx. Retry shortly, or override with ") + c.cyan("--force-stale") + c.gray("."));
+    return false;
+}
 // Guard: a write needs `csd` installed + a configured wallet (or an explicit --address + csd key).
 async function requireCsd() {
     if (!(await csd.available())) {
@@ -103,11 +229,19 @@ function parse(argv) {
     }
     return { _, flags, multi };
 }
-// Do two URLs point at the same host? (used to refuse a "trustless" verify claim when the
-// node RPC and the board API are the same operator). Unparseable → treat as same (safe).
+// Do two URLs point at the same MACHINE? (used to refuse a "trustless" verify claim when the
+// node RPC and the board API are the same operator). Compares hostname only — NOT host — so a
+// same-box node:8789 + board:7777 are correctly judged same-machine (a port difference does not
+// make two endpoints independent), and canonicalizes the loopback aliases (127.0.0.1 / localhost
+// / ::1) so they all compare equal. Unparseable → treat as same (the SAFE default: never claim
+// trustless independence we can't establish).
+function canonHost(h) {
+    const x = h.toLowerCase().replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+    return (x === "localhost" || x === "127.0.0.1" || x === "::1" || x === "0.0.0.0") ? "localhost" : x;
+}
 function sameHost(a, b) {
     try {
-        return new URL(a).host.toLowerCase() === new URL(b).host.toLowerCase();
+        return canonHost(new URL(a).hostname) === canonHost(new URL(b).hostname);
     }
     catch {
         return true;
@@ -271,7 +405,12 @@ async function cmdSetup() {
     banner();
     rule("setup — cairn over your csd wallet");
     const has = await csd.available();
-    console.log(`  ${kdim("csd binary")}  ${has ? ok("found (" + csd.CSD_BIN + ")") : err("not found — install Compute Substrate's csd CLI, or set CAIRN_CSD to its path")}`);
+    // H-1: show the RESOLVED absolute path of the binary that will SIGN, so the user can verify it
+    // (and see the refusal if it was resolved from an untrusted location).
+    const bin = csd.csdPathInfo();
+    console.log(`  ${kdim("csd binary")}  ${has ? ok("found") + c.gray("  " + (bin.path ?? "")) + (bin.explicit ? c.gray("  (CAIRN_CSD)") : c.gray("  (resolved)")) : err(bin.error || "not found — install Compute Substrate's csd CLI, or set CAIRN_CSD to its absolute path")}`);
+    if (bin.warning)
+        console.log(`  ${kdim("")}            ${warn(bin.warning)}`);
     if (!has) {
         console.log(c.gray("\n  cairn signs nothing itself — it drives your csd wallet. Install csd, then re-run ") + c.cyan("cairn setup") + c.gray("."));
         return;
@@ -346,30 +485,61 @@ async function cmdSend(a) {
     for (const o of outs)
         console.log(`${kdim("to")}      ${c.cyan(o.to)} ${c.gray("→ " + csdToCoins(o.value) + " CSD")}`);
     console.log(`${kdim("fee")}     ${csdToCoins(fee)} CSD   ${kdim("total")} ${csdToCoins(total + fee)} CSD`);
+    // max-fee sanity: an absurd fee (typo, or a hostile proxy under-reporting the input → burned
+    // change) is refused BEFORE we build/sign. --dry-run still SHOWS the abnormal-fee warning (so the
+    // user sees it without spending) but never aborts the preview. --max-fee overrides a deliberate fee.
+    const feeOk = feeSanity(fee, total, a);
     if (a.flags["dry-run"]) {
         console.log(c.gray("\n[dry-run] not sent"));
         return;
     }
-    const sp = spinner("fetching input → csd signs → submit");
-    const picked = await api.pickInput(addr, total + fee).catch(() => null);
-    if (!picked) {
-        sp.stop();
-        console.log(err("no single confirmed UTXO covers amount + fee") + c.gray(" — fund this address, or consolidate (a node + `csd … --auto-input` can combine inputs)"));
+    if (!feeOk)
+        return;
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(addr, total + fee, total, fee);
+    if (!input)
         return;
-    }
-    sp.stop();
-    // transparency: show the input value + change so a hostile proxy under-reporting the input
-    // (which would silently inflate the burned fee) is visible before we sign. Change goes to
-    // your own address; the proxy can never redirect it.
-    console.log(`${kdim("input")}   ${csdToCoins(picked.value)} CSD ${c.gray("(one UTXO)")}   ${kdim("change")} ${csdToCoins(Math.max(0, picked.value - total - fee))} CSD ${c.gray("back to you")}`);
     const sp2 = spinner("csd signs → submit");
     const args = ["spend"];
     for (const o of outs)
         args.push("--output", `${o.to}:${o.value}`);
-    args.push("--change", addr, "--fee", String(fee), "--input", picked.input);
+    args.push("--change", addr, "--fee", String(fee), "--input", input);
     const r = await signAndSubmit(args);
     sp2.stop();
-    console.log(r.ok ? ok(`sent  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)") : err(r.error || "failed"));
+    if (!r.ok) {
+        console.log(err(r.error || "failed"));
+        return;
+    }
+    console.log(ok(`sent  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)"));
+    await confirmMined(r.txid, "transfer", !!a.flags.wait);
+}
+// Post-submit feedback for value writes (send/support). The txid is already proven submitted by the
+// evidence-based signAndSubmit; mining is a separate ~120s event, so by DEFAULT we DON'T block on it —
+// we report submitted + how to track it (matching token-send). Pass `--wait` to block until OUR exact
+// txid is mined (the old behavior; useful in scripts that chain on confirmation). Non-fatal either way.
+async function confirmMined(txid, label, wait) {
+    if (!wait) {
+        console.log(c.gray(`  ${label} submitted — usually mines within ~2 min; track with `) + c.cyan(`cairn show ${txid.slice(0, 10)}…`));
+        return;
+    }
+    const sp = spinner("waiting for the tx to mine (--wait)");
+    const mined = await api.confirmTxMined(txid).catch(() => false);
+    // H-7: the proxy can string-echo a "mined" reply. Only assert "confirmed on-chain" when an
+    // INDEPENDENT node (CAIRN_RPC) agrees; otherwise soften/flag so the user isn't given a false
+    // settlement guarantee they might release goods against.
+    const indep = mined ? await api.chainTxMined(txid).catch(() => null) : null;
+    sp.stop();
+    if (!mined) {
+        console.log(warn(`${label} submitted — not mined yet; re-check with `) + c.cyan(`cairn show`) + warn(" once a block lands"));
+        return;
+    }
+    if (indep === true)
+        console.log(ok(`${label} confirmed on-chain`) + c.gray("  (verified against your independent node)"));
+    else if (indep === false)
+        console.log(err(`${label}: the proxy reports it mined but your node (CAIRN_RPC) does NOT — treat as UNCONFIRMED.`) + c.gray(" A hostile proxy can forge a 'mined' reply; trust your own node."));
+    else
+        console.log(warn(`${label}: proxy reports mined`) + c.gray("  — set CAIRN_RPC to your own node to confirm independently (a proxy can forge this signal)."));
 }
 async function cmdPropose(a) {
     const domain = String(a.flags.domain ?? "");
@@ -411,19 +581,21 @@ async function cmdPropose(a) {
         console.log(`${kdim("title")}    ${c.white(title)}`);
         console.log(`${kdim("hash")}     ${c.magenta(payloadHash)} ${c.gray("· uri " + uri)}`);
         console.log(`${kdim("fee")}      ${csdToCoins(fee)} CSD   ${kdim("from")} ${c.cyan(addr)}`);
+        feeSanity(fee, fee, a); // show the abnormal-fee warning in the preview (non-aborting on dry-run)
         console.log(c.gray("\n[dry-run] not signed or submitted"));
         return;
     }
-    const sp = spinner("fetching input → csd signs → submit");
-    const picked = await api.pickInput(addr, fee).catch(() => null);
-    if (!picked) {
-        sp.stop();
-        console.log(err("no confirmed UTXO above the fee") + c.gray(" — fund " + addr));
+    if (!feeSanity(fee, fee, a))
+        return;
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(addr, fee, 0, fee);
+    if (!input)
         return;
-    }
     const tip = await api.tipHeight().catch(() => 0);
     const days = Math.max(1, parseInt(String(a.flags["expires-days"] ?? 30)) || 30);
-    const r = await signAndSubmit(["propose", "--domain", domain, "--payload-hash", payloadHash, "--uri", uri, "--expires-epoch", String(Math.floor(tip / 30) + days * 24), "--fee", String(fee), "--change", addr, "--input", picked.input]);
+    const sp = spinner("csd signs → submit");
+    const r = await signAndSubmit(["propose", "--domain", domain, "--payload-hash", payloadHash, "--uri", uri, "--expires-epoch", String(Math.floor(tip / 30) + days * 24), "--fee", String(fee), "--change", addr, "--input", input]);
     sp.stop();
     if (!r.ok) {
         console.log(err(r.error || "failed"));
@@ -472,19 +644,27 @@ async function cmdSupport(a) {
     if (a.flags["dry-run"]) {
         console.log(`${kdim("support")}  ${c.cyan(id)}`);
         console.log(`${kdim("fee")}      ${csdToCoins(fee)} CSD ${c.gray("· score " + score + " · confidence " + confidence)}   ${kdim("from")} ${c.cyan(addr)}`);
+        feeSanity(fee, fee, a); // show the abnormal-fee warning in the preview (the attest weight IS the fee)
         console.log(c.gray("\n[dry-run] not signed or submitted"));
         return;
     }
-    const sp = spinner("fetching input → csd signs → submit");
-    const picked = await api.pickInput(addr, fee).catch(() => null);
-    if (!picked) {
-        sp.stop();
-        console.log(err("no confirmed UTXO above the fee") + c.gray(" — fund " + addr));
+    // an attest's fee IS the deliberate weight/stake; only guard against an absurd typo above the cap.
+    if (!feeSanity(fee, fee, a))
         return;
-    }
-    const r = await signAndSubmit(["attest", "--proposal-id", id, "--score", String(score), "--confidence", String(confidence), "--fee", String(fee), "--change", addr, "--input", picked.input]);
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(addr, fee, 0, fee);
+    if (!input)
+        return;
+    const sp = spinner("csd signs → submit");
+    const r = await signAndSubmit(["attest", "--proposal-id", id, "--score", String(score), "--confidence", String(confidence), "--fee", String(fee), "--change", addr, "--input", input]);
     sp.stop();
-    console.log(r.ok ? ok(`supported  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)") : err(r.error || "failed"));
+    if (!r.ok) {
+        console.log(err(r.error || "failed"));
+        return;
+    }
+    console.log(ok(`supported  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)"));
+    await confirmMined(r.txid, "support", !!a.flags.wait);
 }
 async function cmdWall(a) {
     if (a._[1] === "place") {
@@ -631,12 +811,19 @@ async function help() {
     console.log(c.bold("  wallet") + c.gray("  (signs with your installed csd wallet — cairn never holds your key)"));
     cmd("setup", "", "check csd + wallet, show your address (alias: doctor)");
     cmd("address", "", "your address + balance (alias: whoami, balance)");
-    cmd("send", "--to <0x…40> --amount <CSD>", "transfer CSD (+ --output <a>:<CSD> ×N, --fee <CSD>, --dry-run)");
+    cmd("send", "--to <0x…40> --amount <CSD>", "transfer CSD (+ --output <a>:<CSD> ×N, --fee <CSD>, --max-fee <CSD>, --dry-run)");
     cmd("propose", "--domain <d> --title <t> --body <b>", "post an item (alias: post; + --fee, --expires-days, --dry-run)");
     cmd("support", "<id> --fee <CSD>", "back an item (+ --score, --confidence, --dry-run)");
+    console.log("");
+    console.log(c.bold("  cairnx") + c.gray("  (tokens + .csd names on the CairnX layer)"));
+    cmd("tokens", "[address]", "token balances + .csd names (default: your address)");
+    cmd("token-info", "<TICKER>", "supply · minted · mint mode · top-10 holders (alias: token)");
+    cmd("token-send", "--ticker T --to 0x…40 --amount <n>", "send tokens (anchors a 0.25 CSD transfer record; --dry-run, --yes)");
+    cmd("names", "[address]", "owned .csd names");
+    cmd("name", "<name>", "one name: owner · lease · open offer");
     console.log(c.gray("\n  lenses (--sort): " + Object.keys(LENS).join(" · ")));
     console.log(c.gray(`  api: ${CAIRN_API}  ·  1 CSD = ${CSD_PER_COIN} base · propose ≥ ${csdToCoins(MIN_FEE_PROPOSE)} · attest ≥ ${csdToCoins(MIN_FEE_ATTEST)} CSD`));
-    console.log(c.gray("  config: CAIRN_API (board) · CAIRN_CSD (csd binary) · CAIRN_ADDR (your addr) · CAIRN_RPC (trustless verify) · CAIRN_TOKEN (operator)"));
+    console.log(c.gray("  config: CAIRN_API (board) · CAIRNX_API (token layer) · CAIRN_CSD (csd binary) · CAIRN_ADDR (your addr) · CAIRN_RPC (trustless verify) · CAIRN_TOKEN (operator)"));
     console.log(c.gray("  display: honors NO_COLOR · --no-color · --no-anim · TERM=dumb (color/animation auto-off when piped)"));
     console.log(c.gray("  writes are signed by your own ") + c.cyan("csd") + c.gray(" wallet (csd wallet new / init); cairn supplies the input + Cairn content. Sealed claims + Sign-in: use the Cairn Wallet."));
 }
@@ -667,6 +854,12 @@ async function main() {
         case "propose":
         case "post": return cmdPropose(a);
         case "support": return cmdSupport(a);
+        case "tokens": return cmdTokens(a);
+        case "token-info":
+        case "token": return cmdTokenInfo(a);
+        case "token-send": return cmdTokenSend(a);
+        case "names": return cmdNames(a);
+        case "name": return cmdName(a);
         case "gateway": return cmdGateway(a);
         case "peer": return cmdPeer(a);
         case "identity": return cmdIdentity(a);
@@ -677,16 +870,18 @@ async function main() {
 // Anchor a built registry record: Propose{domain, payloadHash} signed by the csd wallet,
 // then publish the EXACT canonical bytes to the content origin (self-certified on arrival).
 async function anchorRecord(rec, addr, fee, days, label) {
-    const uri = "csd:" + rec.domain.replace(/[^a-z]/gi, "").slice(0, 6) + ":v1:" + rec.payloadHash.slice(2, 14);
-    const sp = spinner("fetching input → csd signs → submit");
-    const picked = await api.pickInput(addr, fee).catch(() => null);
-    if (!picked) {
-        sp.stop();
-        console.log(err("no confirmed UTXO above the fee") + c.gray(" — fund " + addr));
+    // max-fee sanity: a fixed-floor record anchor should never burn more than the 1 CSD abs cap.
+    if (fee > MAX_FEE_ABS) {
+        console.log(err(`fee ${csdToCoins(fee)} CSD looks abnormally high for a ${label} record (cap ${csdToCoins(MAX_FEE_ABS)} CSD).`) + c.gray(" Lower ") + c.cyan("--fee") + c.gray("."));
         return false;
     }
+    const uri = "csd:" + rec.domain.replace(/[^a-z]/gi, "").slice(0, 6) + ":v1:" + rec.payloadHash.slice(2, 14);
+    const input = await pickAndShow(addr, fee, 0, fee);
+    if (!input)
+        return false;
     const tip = await api.tipHeight().catch(() => 0);
-    const r = await signAndSubmit(["propose", "--domain", rec.domain, "--payload-hash", rec.payloadHash, "--uri", uri, "--expires-epoch", String(Math.floor(tip / 30) + days * 24), "--fee", String(fee), "--change", addr, "--input", picked.input]);
+    const sp = spinner("csd signs → submit");
+    const r = await signAndSubmit(["propose", "--domain", rec.domain, "--payload-hash", rec.payloadHash, "--uri", uri, "--expires-epoch", String(Math.floor(tip / 30) + days * 24), "--fee", String(fee), "--change", addr, "--input", input]);
     sp.stop();
     if (!r.ok) {
         console.log(err(r.error || "failed"));
@@ -806,4 +1001,233 @@ async function cmdIdentity(a) {
     if (okc)
         console.log(c.gray("\n  save this salt — reveal NEXT epoch (~1h):  ") + c.cyan(`cairn identity claim ${handle} --reveal --salt ${salt}`));
 }
+// ── CairnX: tokens + .csd names (reads via the CairnX state API; the one write —
+//    token-send — anchors a canonical transfer record as a cairnx:v1 Propose) ──
+// Display: base units → human, with thousands grouping. decimals===undefined (a ticker the
+// API doesn't know) falls back to raw base units rather than guessing a scale.
+const group = (s) => s.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+function tokAmt(base, decimals) {
+    if (decimals === undefined)
+        return `${group(String(base))} (base units)`;
+    const [i, f] = baseToHuman(String(base), decimals).split(".");
+    return group(i) + (f ? "." + f : "");
+}
+// The address a CairnX read targets: positional arg → --address/CAIRN_ADDR/csd wallet.
+async function resolveCairnxAddr(a, positional) {
+    if (positional !== undefined) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(positional)) {
+            console.log(err(`bad address: ${san(positional)}`));
+            return null;
+        }
+        return positional.toLowerCase();
+    }
+    const addr = await resolveAddr(a);
+    if (!addr)
+        console.log(err("no address — pass one (cairn tokens 0x…), or --address, or run ") + c.cyan("cairn setup"));
+    return addr ? addr.toLowerCase() : null;
+}
+// ticker → decimals map from /tokens (best-effort: an unreachable list degrades to raw units).
+async function tokenDecimals() {
+    const list = await cairnxGet("/tokens").catch(() => []);
+    const map = {};
+    for (const t of Array.isArray(list) ? list : [])
+        if (typeof t?.ticker === "string" && Number.isInteger(t?.decimals))
+            map[t.ticker] = t.decimals;
+    return map;
+}
+async function cmdTokens(a) {
+    const addr = await resolveCairnxAddr(a, a._[1]);
+    if (!addr)
+        return;
+    const [acct, dec] = await Promise.all([cairnxGet(`/address/${encodeURIComponent(addr)}`), tokenDecimals()]);
+    if (a.flags.json) {
+        console.log(JSON.stringify(acct, null, 2));
+        return;
+    }
+    banner();
+    rule(`cairnx · ${addr.slice(0, 10)}… · ${String(activeCairnxBase() ?? "").replace(/^https?:\/\//, "")}`);
+    const bals = Object.entries(acct.balances ?? {});
+    if (!bals.length)
+        console.log(c.gray("  no token balances"));
+    for (const [ticker, b] of bals) {
+        const locked = BigInt(String(b.locked ?? "0"));
+        console.log(`  ${c.cyan(pad(san(ticker), 14))} ${c.white(tokAmt(String(b.available ?? "0"), dec[ticker]))}${locked > 0n ? c.gray(` · ${tokAmt(String(b.locked), dec[ticker])} locked in open offers`) : ""}`);
+    }
+    const names = acct.names ?? [];
+    console.log(`\n  ${kdim(".csd names")} ${names.length ? names.map((n) => c.green(san(n))).join(c.gray(" · ")) : c.gray("none")}`);
+}
+async function cmdTokenInfo(a) {
+    const ticker = String(a._[1] ?? "").toUpperCase();
+    if (!TICKER_RE.test(ticker)) {
+        console.log(warn("usage: ") + c.cyan("cairn token-info <TICKER>"));
+        return;
+    }
+    const t = await cairnxGet(`/token/${encodeURIComponent(ticker)}`).catch((e) => { console.log(e.status === 404 ? err(`unknown token ${ticker}`) : err(e.message)); return null; });
+    if (!t)
+        return;
+    banner();
+    rule(`token · ${san(t.ticker)}`);
+    const row = (k, v) => console.log(`  ${kdim(pad(k, 11))} ${v}`);
+    row("name", c.white(san(t.name ?? t.ticker)));
+    row("decimals", c.white(String(t.decimals)));
+    row("supply", `${c.white(tokAmt(String(t.supply), t.decimals))} ${c.gray("max")}`);
+    const minted = BigInt(String(t.minted ?? "0")), supply = BigInt(String(t.supply ?? "0"));
+    row("minted", `${c.white(tokAmt(String(t.minted), t.decimals))}${supply > 0n ? c.gray(` · ${Number((minted * 10000n) / supply) / 100}% of supply`) : ""}`);
+    row("mint", t.mint === "open" ? c.green("open") + c.gray(` · up to ${tokAmt(String(t.mintLimit ?? "0"), t.decimals)} per mint`) : c.gray("issuer-only"));
+    row("deployer", c.gray(san(t.deployer)));
+    row("deployed", c.gray(`height ${Number(t.height)} · id ${san(String(t.deployId ?? "")).slice(0, 22)}…`));
+    // top-10 holders by total (available + locked) — the same reading the explorer shows
+    const holders = Object.entries(t.holders ?? {}).map(([h, b]) => ({ h, total: BigInt(String(b.available ?? "0")) + BigInt(String(b.locked ?? "0")) }))
+        .filter((x) => x.total > 0n).sort((x, y) => (y.total > x.total ? 1 : y.total < x.total ? -1 : 0));
+    console.log(`\n  ${kdim("holders")}    ${c.white(String(holders.length))}${holders.length > 10 ? c.gray(" · top 10") : ""}`);
+    const max = holders[0]?.total ?? 1n;
+    for (const { h, total } of holders.slice(0, 10)) {
+        const pct = minted > 0n ? Number((total * 10000n) / minted) / 100 : 0;
+        console.log(`  ${bar(Number((total * 1000n) / max), 1000)}  ${c.gray(san(h).slice(0, 12) + "…")} ${c.white(tokAmt(total.toString(), t.decimals))} ${c.gray(`· ${pct}%`)}`);
+    }
+}
+// y/N gate for the one CairnX write. Non-interactive runs behave like the CLI's other
+// writes (no prompt — use --dry-run to preview); --yes skips the prompt when interactive.
+async function confirmSend(q) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return true;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ans = await new Promise((res) => rl.question(q, res));
+    rl.close();
+    return /^y(es)?$/i.test(ans.trim());
+}
+async function cmdTokenSend(a) {
+    const ticker = String(a.flags.ticker ?? "").toUpperCase();
+    const to = String(a.flags.to ?? "");
+    const amountStr = String(a.flags.amount ?? "");
+    if (!ticker || !a.flags.to || a.flags.amount === undefined) {
+        console.log(warn("usage: ") + c.cyan("cairn token-send --ticker CAIRN --to 0x…40 --amount 1.5 [--dry-run] [--yes]"));
+        return;
+    }
+    if (!TICKER_RE.test(ticker)) {
+        console.log(err(`bad ticker: ${san(ticker)}`));
+        return;
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(to)) {
+        console.log(err(`bad recipient: ${san(to)}`));
+        return;
+    }
+    // decimals are AUTHORITATIVE from the token's deploy record — never guessed
+    const t = await cairnxGet(`/token/${encodeURIComponent(ticker)}`).catch((e) => { console.log(e.status === 404 ? err(`unknown token ${ticker}`) : err(e.message)); return null; });
+    if (!t)
+        return;
+    let amount;
+    try {
+        amount = humanToBase(amountStr, Number(t.decimals));
+    }
+    catch (e) {
+        console.log(err(e.message));
+        return;
+    }
+    if (amount <= 0n) {
+        console.log(err("amount must be > 0"));
+        return;
+    }
+    const from = await resolveAddr(a);
+    if (!from) {
+        console.log(err("could not resolve your address — pass --address or run ") + c.cyan("cairn setup"));
+        return;
+    }
+    // balance check against the same state the resolver will apply the transfer to
+    const acct = await cairnxGet(`/address/${encodeURIComponent(from.toLowerCase())}`);
+    const avail = BigInt(String(acct.balances?.[ticker]?.available ?? "0"));
+    if (avail < amount) {
+        console.log(err(`insufficient ${ticker}: balance ${tokAmt(avail.toString(), t.decimals)}, tried to send ${tokAmt(amount.toString(), t.decimals)}${BigInt(String(acct.balances?.[ticker]?.locked ?? "0")) > 0n ? ` (${tokAmt(String(acct.balances[ticker].locked), t.decimals)} more is locked in open offers)` : ""}`));
+        return;
+    }
+    let built;
+    try {
+        built = buildTransferRecord({ ticker, to, amount });
+    }
+    catch (e) {
+        console.log(err(e.message));
+        return;
+    }
+    // clear-print exactly what will be anchored before anything signs
+    console.log(`${kdim("send")}    ${c.white(tokAmt(amount.toString(), t.decimals))} ${c.cyan(ticker)} ${c.gray(`(${amount} base units · ${t.decimals} decimals)`)}`);
+    console.log(`${kdim("to")}      ${c.cyan(to.toLowerCase())}`);
+    console.log(`${kdim("from")}    ${c.cyan(from.toLowerCase())} ${c.gray(`· ${ticker} balance ${tokAmt(avail.toString(), t.decimals)}`)}`);
+    console.log(`${kdim("record")}  ${c.white(built.uri)}`);
+    console.log(`${kdim("hash")}    ${c.magenta(built.payloadHash)}`);
+    console.log(`${kdim("anchor")}  ${c.gray(`Propose on ${CAIRNX_DOMAIN} — costs `)}${c.white(csdToCoins(CAIRNX_ANCHOR_FEE) + " CSD")}${c.gray(" (the chain fee; the tokens themselves move by record)")}`);
+    if (a.flags["dry-run"]) {
+        console.log(c.gray("\n[dry-run] not signed or submitted"));
+        return;
+    }
+    if (!(await requireCsd()))
+        return;
+    if (!a.flags.yes && !(await confirmSend(`\nsend ${tokAmt(amount.toString(), t.decimals)} ${ticker} for ${csdToCoins(CAIRNX_ANCHOR_FEE)} CSD? [y/N] `))) {
+        console.log(c.gray("aborted"));
+        return;
+    }
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(from, CAIRNX_ANCHOR_FEE, 0, CAIRNX_ANCHOR_FEE);
+    if (!input)
+        return;
+    const tip = await api.tipHeight().catch(() => 0);
+    const sp3 = spinner("csd signs → submit");
+    const r = await signAndSubmit(["propose", "--domain", CAIRNX_DOMAIN, "--payload-hash", built.payloadHash, "--uri", built.uri, "--expires-epoch", String(Math.floor(tip / 30) + 24), "--fee", String(CAIRNX_ANCHOR_FEE), "--change", from, "--input", input]);
+    sp3.stop();
+    console.log(r.ok ? ok(`transfer anchored  ${c.cyan(r.txid)}`) + c.gray("  (tokens move when it mines — check `cairn tokens`)") : err(r.error || "failed"));
+}
+async function cmdNames(a) {
+    const addr = await resolveCairnxAddr(a, a._[1]);
+    if (!addr)
+        return;
+    const acct = await cairnxGet(`/address/${encodeURIComponent(addr)}`);
+    const names = acct.names ?? [];
+    if (a.flags.json) {
+        console.log(JSON.stringify(names, null, 2));
+        return;
+    }
+    banner();
+    rule(`.csd names · ${addr.slice(0, 10)}…`);
+    if (!names.length) {
+        console.log(c.gray("  no names owned — claim one on " + (activeCairnxBase()?.includes("127.0.0.1") ? "the /trade marketplace" : "https://cairn-substrate.com/trade")));
+        return;
+    }
+    for (const n of names)
+        console.log(`  ${c.green(san(n))}`);
+    console.log(c.gray(`\n  ${names.length} name${names.length === 1 ? "" : "s"} · cairn name <name> for detail`));
+}
+async function cmdName(a) {
+    const n = String(a._[1] ?? "").toLowerCase();
+    if (!n || !NAME_RE.test(n)) {
+        console.log(warn("usage: ") + c.cyan("cairn name <name>") + c.gray("  (lowercase, 3–32 chars [a-z0-9-])"));
+        return;
+    }
+    const r = await cairnxGet(`/name/${encodeURIComponent(n)}`).catch((e) => { console.log(e.status === 404 ? err(`unregistered name "${n}"`) + c.gray(" — claimable via commit-reveal on /trade") : err(e.message)); return null; });
+    if (!r)
+        return;
+    banner();
+    rule(`name · ${san(r.name ?? n)}`);
+    const row = (k, v) => console.log(`  ${kdim(pad(k, 10))} ${v}`);
+    row("owner", c.cyan(san(r.owner)));
+    row("claimed", c.gray(`height ${Number(r.height)}${Number(r.effectiveHeight) !== Number(r.height) ? ` · effective ${Number(r.effectiveHeight)}` : ""} · claim ${san(String(r.claimId ?? "")).slice(0, 22)}…`));
+    // lease: the API reports paidThroughEpoch once the v1.5 lease model is live; the ETA is
+    // computed from the chain tip (1 epoch = 30 blocks · 120s target ⇒ ~1h per epoch).
+    if (r.paidThroughEpoch != null) {
+        const tip = await api.tipHeight().catch(() => 0);
+        const blocksLeft = (Number(r.paidThroughEpoch) + 1) * 30 - tip;
+        const eta = !tip ? "" : blocksLeft <= 0 ? " · " + "EXPIRED" : ` · expires in ~${blocksLeft >= 720 ? (blocksLeft / 720).toFixed(1) + " days" : Math.max(1, Math.round(blocksLeft / 30)) + "h"}`;
+        row("lease", `${c.white("paid through epoch " + Number(r.paidThroughEpoch))}${blocksLeft <= 0 && tip ? "  " + err("EXPIRED") : c.gray(eta)}`);
+    }
+    else
+        row("lease", c.gray("— (no lease data from this API)"));
+    if (r.locked)
+        row("locked", c.gray("yes — a sale/transfer is in flight"));
+    if (r.offer) {
+        const want = r.offer.want ?? {};
+        const price = want.value !== undefined ? `${csdToCoins(Number(want.value))} CSD` : `${san(String(want.amount))} ${san(String(want.ticker))}`;
+        row("offer", `${c.green("FOR SALE")} ${c.white("· " + price)} ${c.gray(`· seller ${san(String(r.offer.seller ?? r.owner)).slice(0, 12)}… · offer ${san(String(r.offer.id ?? "")).slice(0, 18)}…${r.offer.taker ? " · reserved for a taker" : ""}`)}`);
+    }
+    else
+        row("offer", c.gray("no open offer"));
+}
 main().catch((e) => { console.error(err(String(e?.message ?? e))); process.exit(1); });

package/dist/lib/api.js

@@ -64,11 +64,73 @@ export async function pickInput(addr, minValue) {
     const x = cand[0] ?? (j.utxos ?? []).find(ok);
     return x ? { input: `${x.txid}:${Number(x.vout)}:${Number(x.value)}`, value: Number(x.value) } : null;
 }
+// UTXO-VALUE-1 cross-source check. cairn-cli has no codec to recompute an input's REAL value, so
+// a hostile/MITM'd CAIRN_API that UNDER-reports a UTXO's value would make `csd` compute too-small
+// a change and silently burn the difference as fee. If the user has configured an INDEPENDENT node
+// (CAIRN_RPC, a different host than the proxy), confirm the picked outpoint's value against its
+// authoritative UTXO set and refuse on a mismatch. Returns:
+//   { checked:false }                          — no independent RPC configured / unreachable (caller warns + relies on the fee cap)
+//   { checked:true, ok:true,  value }          — independent node agrees (display the verified value)
+//   { checked:true, ok:false, value }          — DISAGREEMENT (hostile proxy) → caller refuses
+//   { checked:true, ok:false, missing:true }   — outpoint absent on the independent node → suspicious, caller refuses
+export async function verifyInputValue(addr, txid, vout, claimedValue) {
+    if (!CAIRN_RPC)
+        return { checked: false };
+    if (!/^0x[0-9a-fA-F]{40}$/.test(addr) || !HEX64.test(txid))
+        return { checked: false };
+    let j;
+    try {
+        const r = await fetch(`${CAIRN_RPC}/utxos/${encodeURIComponent(addr)}`, { redirect: "error", signal: AbortSignal.timeout(6000) });
+        if (!r.ok)
+            return { checked: false };
+        j = await r.json();
+    }
+    catch {
+        return { checked: false };
+    }
+    const list = j.utxos ?? j.outputs ?? [];
+    const norm = (t) => String(t).toLowerCase().replace(/^0x/, "");
+    const hit = list.find((u) => norm(u.txid) === norm(txid) && Number(u.vout) === vout);
+    if (!hit)
+        return { checked: true, ok: false, missing: true };
+    const v = Number(hit.value);
+    return { checked: true, ok: Number.isSafeInteger(v) && v === claimedValue, value: v };
+}
 export async function confirmedBalance(addr) {
     const j = await req(`/api/rpc/utxos-all/${encodeURIComponent(addr)}`);
     return { balance: Number(j.confirmed_balance ?? 0), utxos: (j.utxos ?? []).length };
 }
 export async function tipHeight() { return Number((await req("/api/rpc/tip")).height ?? 0); }
+// Chain-view freshness of the proxy's backend node: { stale, secondsSinceAdvance, staleSecsThreshold, height }.
+// Used to refuse building a tx against a frozen/forked tip. Throws if the surface is unreachable
+// (caller treats that as a soft warning, never a hard block — matches the 'cannot reach' UX).
+export async function rpcStatus() {
+    return req("/api/rpc/status");
+}
+// Look up a tx by id on the node. Mined txs resolve to { ok:true, txid, block_hash, height };
+// an unknown id resolves to { ok:false, err:"not found" }. (The node's /tx indexes MINED txs;
+// a mempool-only tx returns not-found, so a not-found is "no proof yet", never "rejected".)
+export async function txStatus(txid) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(txid))
+        return { ok: false }; // never splice an unshaped id into the URL
+    const j = await req(`/api/rpc/tx/${encodeURIComponent(txid)}`).catch(() => null);
+    return j ?? { ok: false };
+}
+// Has the node confirmed OUR exact txid (mined into the chain)? Polls a few times because a
+// freshly-submitted tx is mempool-only until a block lands. Returns true ONLY on an exact
+// txid match the node reports as known — evidence the user's own tx (not a different conflict)
+// is on-chain. (Non-fatal on an unreachable node: simply never confirms.) The poll budget is
+// overridable via CAIRN_CONFIRM_ATTEMPTS / CAIRN_CONFIRM_INTERVAL_MS (used by the test suite).
+export async function confirmTxMined(txid, attempts = Number(process.env.CAIRN_CONFIRM_ATTEMPTS) || 4, intervalMs = Number(process.env.CAIRN_CONFIRM_INTERVAL_MS) || 7000) {
+    for (let i = 0; i < attempts; i++) {
+        const s = await txStatus(txid).catch(() => null);
+        if (s?.ok && typeof s.txid === "string" && s.txid.toLowerCase() === txid.toLowerCase())
+            return true;
+        if (i < attempts - 1)
+            await new Promise((res) => setTimeout(res, intervalMs));
+    }
+    return false;
+}
 // Submit a node-JSON tx through the proxy (for `csd spend`, which builds+signs but doesn't
 // reliably submit to a proxy URL). Returns the node's response.
 export async function submitTx(txNodeJson) { return req("/api/rpc/tx/submit", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ tx: txNodeJson }) }); }
@@ -99,6 +161,28 @@ export async function registerRawContent(bytes, txid, attempts = 20) {
     }
     return false;
 }
+// Independent confirmation (audit H-7): is this txid mined according to CAIRN_RPC, a node on a
+// DIFFERENT host than the proxy? `confirmTxMined` above polls the proxy's own /api/rpc/tx, which a
+// hostile/MITM'd CAIRN_API can string-echo to forge a "mined" reply. This cross-checks an
+// independent node. Returns true (independent node confirms OUR exact txid mined), false (it does
+// not), or null (no independent RPC configured / unreachable → "unverifiable", never a hard claim).
+export async function chainTxMined(txid) {
+    if (!CAIRN_RPC)
+        return null;
+    if (!/^0x[0-9a-fA-F]{64}$/.test(txid))
+        return null;
+    try {
+        const r = await fetch(`${CAIRN_RPC}/tx/${encodeURIComponent(txid)}`, { redirect: "error", signal: AbortSignal.timeout(6000) });
+        if (!r.ok)
+            return null;
+        const j = await r.json();
+        const t = String(j.txid ?? j.tx?.txid ?? "").toLowerCase().replace(/^0x/, "");
+        return j.ok === true && t === txid.toLowerCase().replace(/^0x/, "");
+    }
+    catch {
+        return null;
+    }
+}
 // optional: query a raw csd node RPC (for trustless verify)
 export async function chainProposal(id) {
     if (!CAIRN_RPC)

package/dist/lib/cairnx.js

@@ -0,0 +1,108 @@
+// CairnX — the token + .csd-name layer that lives entirely in CSD Propose records on the
+// `cairnx:v1` domain. This file is the CLI's complete CairnX surface:
+//   • a READ client for the CairnX state API (resolution order: $CAIRNX_API → the local
+//     service → the public gateway, GET-only) with automatic fallback on network failure
+//   • the canonical TRANSFER record builder — hand-rolled on the repo's own
+//     stableStringify/sha256 (byte-exact-tested against cairnx-core's ground truth) so the
+//     CLI takes NO dependency on the private cairnx repo.
+//     TODO: swap to @inversealtruism/cairnx-core once it is published to npm.
+//   • exact human↔base-unit amount math as STRING/BigInt arithmetic — floats never touch
+//     token amounts (no "1.1 * 1e8 = 110000000.00000001" class of bug, no silent truncation).
+import { stableStringify, sha256Hex } from "./item.js";
+export const CAIRNX_DOMAIN = "cairnx:v1";
+export const CAIRNX_ANCHOR_FEE = 25_000_000; // 0.25 CSD — the consensus min Propose fee that anchors a record
+export const MAX_AMOUNT = (1n << 96n) - 1n; // CONVENTION.md: token amounts are ≤ 96-bit
+const MAX_RECORD_BYTES = 512; // consensus MAX_URI_BYTES — the record must fit in `uri`
+// Validation shapes (mirrors CONVENTION.md §4 — kept in sync by the byte-exact fixtures).
+export const TICKER_RE = /^[A-Z][A-Z0-9]{2,11}$/;
+export const NAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/; // a claimable .csd name
+const ADDR_RE = /^0x[0-9a-f]{40}$/; // records carry LOWERCASE addresses
+export function buildTransferRecord(p) {
+    const to = String(p.to).toLowerCase();
+    if (!TICKER_RE.test(p.ticker))
+        throw new Error(`bad ticker "${p.ticker}" — want 3–12 chars [A-Z0-9], starting with a letter`);
+    if (!ADDR_RE.test(to))
+        throw new Error(`bad recipient "${p.to}" — want a 0x… 20-byte address`);
+    if (p.amount <= 0n)
+        throw new Error("amount must be > 0");
+    if (p.amount > MAX_AMOUNT)
+        throw new Error("amount exceeds the 96-bit token-amount limit");
+    const record = { amount: p.amount.toString(), t: "transfer", ticker: p.ticker, to, v: 1 };
+    const uri = stableStringify(record);
+    if (Buffer.byteLength(uri, "utf8") > MAX_RECORD_BYTES)
+        throw new Error("record exceeds 512 bytes"); // unreachable for a transfer, kept as a guard
+    return { record, uri, payloadHash: sha256Hex(uri) };
+}
+// ── exact amount math (strings + BigInt only) ─────────────────────────────────────────────
+// "1.5" with decimals 8 → 150000000n. Fails LOUDLY instead of truncating: "1.5" on a
+// 0-decimals token is an error, not 1. Trailing fractional zeros are exact and accepted
+// ("1.50" @ 1 decimal → 15n).
+export function humanToBase(human, decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 8)
+        throw new Error(`bad token decimals ${decimals}`);
+    const s = String(human).trim();
+    if (s.length === 0 || s.length > 40)
+        throw new Error(`bad amount "${human}"`); // MAX_AMOUNT is 29 digits; cap before BigInt
+    const m = /^([0-9]+)?(?:\.([0-9]+))?$/.exec(s);
+    if (!m || (m[1] === undefined && m[2] === undefined))
+        throw new Error(`bad amount "${human}" — use plain digits like 1 or 1.25`);
+    const frac = (m[2] ?? "").replace(/0+$/, ""); // trailing zeros are exactly representable — drop them
+    if (frac.length > decimals)
+        throw new Error(`amount "${human}" has more decimal places than this token allows (${decimals})`);
+    const base = BigInt(m[1] ?? "0") * 10n ** BigInt(decimals) + BigInt(frac.padEnd(decimals, "0") || "0");
+    if (base > MAX_AMOUNT)
+        throw new Error(`amount "${human}" exceeds the 96-bit token-amount limit`);
+    return base;
+}
+// 150000000n @ 8 → "1.5" (exact inverse of humanToBase; no grouping — display adds that).
+export function baseToHuman(base, decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 8)
+        throw new Error(`bad token decimals ${decimals}`);
+    const v = typeof base === "bigint" ? base : BigInt(String(base));
+    if (v < 0n)
+        throw new Error("negative token amount");
+    const s = v.toString().padStart(decimals + 1, "0");
+    const int = decimals ? s.slice(0, -decimals) : s;
+    const fr = decimals ? s.slice(-decimals).replace(/0+$/, "") : "";
+    return fr ? `${int}.${fr}` : int;
+}
+// ── read API client (GET-only; never sees a key) ──────────────────────────────────────────
+// Base resolution order: $CAIRNX_API (explicit choice — used exclusively), else the local
+// CairnX service, else the public gateway. Read at call time (not import) so tests can vary it.
+export function defaultBases() {
+    const env = (process.env.CAIRNX_API ?? "").trim().replace(/\/+$/, "");
+    if (env)
+        return [env];
+    return ["http://127.0.0.1:8794/cairnx", "https://cairn-substrate.com/trade/api/cairnx"];
+}
+// Remember the first base that answered (per base-list) so one command's N requests don't
+// re-probe a dead localhost N times.
+let active = null;
+export const activeCairnxBase = () => active?.base ?? null;
+export async function cairnxGet(path, bases = defaultBases()) {
+    const key = bases.join(" ");
+    const order = active?.key === key && bases.includes(active.base)
+        ? [active.base, ...bases.filter((b) => b !== active.base)] : bases;
+    let lastErr = null;
+    for (const base of order) {
+        let res;
+        try {
+            res = await fetch(`${base}${path}`, { signal: AbortSignal.timeout(8000) }); // GET-only, no credentials — redirects are safe to follow
+        }
+        catch (e) {
+            lastErr = e;
+            continue;
+        } // network failure → try the next base
+        // A reachable base's answer is authoritative — an HTTP 404 here is a real "not found",
+        // never a reason to fall through to a different (possibly divergent) view of state.
+        active = { key, base };
+        if (!res.ok) {
+            const j = await res.json().catch(() => null);
+            const e = new Error(j?.error ? String(j.error) : `CairnX API ${path} → HTTP ${res.status}`);
+            e.status = res.status;
+            throw e;
+        }
+        return res.json();
+    }
+    throw new Error(`cannot reach a CairnX API (tried ${bases.join(", ")}) — set CAIRNX_API (${lastErr?.message ?? lastErr})`);
+}

package/dist/lib/config.js

@@ -1,7 +1,7 @@
 // cairn-cli configuration (env-overridable).
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
 export const CAIRN_API = (process.env.CAIRN_API ?? "https://cairn-substrate.com").replace(/\/+$/, "");
 export const CAIRN_TOKEN = process.env.CAIRN_TOKEN ?? ""; // optional operator write token (falls back to local csd wallet)
 export const CAIRN_RPC = process.env.CAIRN_RPC ?? ""; // optional: a csd node RPC, enables trustless verify
@@ -13,7 +13,9 @@ export const MIN_FEE_ATTEST = 5_000_000; // 0.05 CSD
 export function csdToCoins(base) {
     return (base / CSD_PER_COIN).toLocaleString(undefined, { maximumFractionDigits: 4 });
 }
-// small local config: caches ONLY the user's public address (never a key).
+// small local config: caches ONLY the user's public address (never a key). Written with
+// owner-only perms (dir 0700, file 0600) so another local user can't poison the cached address
+// to redirect `cairn address` output (F13/R18 — the wallet is still the source of truth).
 const CFG_PATH = process.env.CAIRN_CLI_CONFIG ?? join(homedir(), ".config", "cairn-cli", "config.json");
 export function loadLocalConfig() { try {
     return JSON.parse(readFileSync(CFG_PATH, "utf8"));
@@ -23,8 +25,9 @@ catch {
 } }
 export function saveLocalConfig(patch) {
     try {
-        mkdirSync(dirname(CFG_PATH), { recursive: true });
-        writeFileSync(CFG_PATH, JSON.stringify({ ...loadLocalConfig(), ...patch }, null, 2) + "\n");
+        mkdirSync(dirname(CFG_PATH), { recursive: true, mode: 0o700 });
+        writeFileSync(CFG_PATH, JSON.stringify({ ...loadLocalConfig(), ...patch }, null, 2) + "\n", { mode: 0o600 });
+        chmodSync(CFG_PATH, 0o600); // tighten even if the file pre-existed (writeFileSync mode is create-only)
     }
     catch { /* best-effort */ }
 }

package/dist/lib/csd.js

@@ -1,19 +1,130 @@
 // Thin wrapper around the user's INSTALLED `csd` CLI. cairn-cli never holds a private
 // key: for any write it shells out to `csd`, which signs with the user's own csd wallet
 // config key (CSD_SIG_V1). We only orchestrate — supply the input (fetched from the Cairn
-// proxy, so no local node is required) + the Cairn payload — and `csd` does the signing
-// and submit. Binary resolution: CAIRN_CSD env → `csd` on PATH → the substrate default.
+// proxy, so no local node is required) + the Cairn payload — and `csd` does the signing.
+//
+// SECURITY (audit H-1): which `csd` binary signs is a trust decision. A bare `csd` resolved
+// by $PATH order lets a malicious binary planted earlier on PATH (dev env, npm postinstall,
+// shared host) capture the wallet key the instant cairn shells out. So:
+//   • CAIRN_CSD, if set, is the user's EXPLICIT choice — honored, but MUST be absolute.
+//   • Otherwise we resolve `csd` from a list of CANONICAL absolute locations FIRST (not PATH
+//     order), fall back to a PATH search only if none exists, REFUSE a binary in a world-
+//     writable / transient / cwd location, and SURFACE the resolved absolute path so the user
+//     can see which binary signs.
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { statSync, realpathSync } from "node:fs";
+import { isAbsolute, join, dirname, delimiter } from "node:path";
 const pexec = promisify(execFile);
+// Back-compat hint (the configured name/path); real resolution is resolveCsdBin().
 export const CSD_BIN = process.env.CAIRN_CSD || "csd";
+// Canonical absolute install locations, checked in order BEFORE any $PATH search so a binary
+// planted earlier on PATH cannot win.
+const HOME = process.env.HOME || "";
+const CANONICAL = [
+    "/usr/local/bin/csd", "/usr/bin/csd", "/opt/substrate_miner/bin/csd",
+    ...(HOME ? [join(HOME, ".cargo/bin/csd"), join(HOME, ".local/bin/csd")] : []),
+];
+// Is this resolved path attacker-plantable? Returns a human reason, or null if it looks safe.
+function insecureReason(abs) {
+    let st;
+    try {
+        st = statSync(abs);
+    }
+    catch {
+        return "does not exist";
+    }
+    if (!st.isFile())
+        return "is not a regular file";
+    if (st.mode & 0o002)
+        return "is world-writable";
+    const dir = dirname(abs);
+    try {
+        const dst = statSync(dir);
+        if ((dst.mode & 0o002) && !(dst.mode & 0o1000))
+            return `is in a world-writable directory (${dir})`;
+    }
+    catch { /* dir unreadable — fall through */ }
+    if (dir === process.cwd())
+        return "is in the current working directory (a cwd hijack vector)";
+    if (dir.startsWith("/tmp") || dir.startsWith("/var/tmp") || dir.startsWith("/dev/shm"))
+        return `is in a transient directory (${dir})`;
+    return null;
+}
+function pathSearch(name) {
+    for (const d of (process.env.PATH || "").split(delimiter).filter(Boolean)) {
+        const p = join(d, name);
+        try {
+            const st = statSync(p);
+            if (st.isFile() && (st.mode & 0o111))
+                return p;
+        }
+        catch { /* keep looking */ }
+    }
+    return null;
+}
+let _resolved = null;
+// Resolve (and cache) the trusted `csd` path. See header for the policy.
+export function resolveCsdBin() {
+    if (_resolved)
+        return _resolved;
+    const env = process.env.CAIRN_CSD;
+    if (env) {
+        // Explicit user choice. Require absolute (a relative explicit path is still PATH/cwd-hijackable);
+        // honor it even in an unusual location (the user told us exactly which binary to trust), but warn
+        // if world-writable. We do NOT refuse here — the test harness and power users point CAIRN_CSD at
+        // bespoke absolute paths deliberately.
+        if (!isAbsolute(env))
+            return (_resolved = { path: null, explicit: true, error: `CAIRN_CSD must be an ABSOLUTE path (got "${env}") — a relative csd binary is a key-theft risk` });
+        let abs = env;
+        try {
+            abs = realpathSync(env);
+        }
+        catch { /* may legitimately not exist yet — surfaced at run/available */ }
+        let warning;
+        try {
+            if (statSync(abs).mode & 0o002)
+                warning = `CAIRN_CSD (${abs}) is world-writable — anyone could replace it with a key-stealing binary`;
+        }
+        catch { /* */ }
+        return (_resolved = { path: abs, explicit: true, warning });
+    }
+    // Implicit resolution: canonical locations first (defeats PATH-order hijack), then PATH.
+    for (const cand of CANONICAL) {
+        try {
+            const st = statSync(cand);
+            if (st.isFile() && (st.mode & 0o111) && !insecureReason(cand))
+                return (_resolved = { path: realpathSync(cand), explicit: false });
+        }
+        catch { /* next */ }
+    }
+    const found = pathSearch("csd");
+    if (!found)
+        return (_resolved = { path: null, explicit: false, error: "`csd` not found in any trusted location or on PATH — install it, or set CAIRN_CSD to its absolute path" });
+    let abs;
+    try {
+        abs = realpathSync(found);
+    }
+    catch {
+        return (_resolved = { path: null, explicit: false, error: `csd at ${found} could not be resolved` });
+    }
+    const bad = insecureReason(abs);
+    if (bad)
+        return (_resolved = { path: null, explicit: false, error: `refusing to run csd at ${abs} — it ${bad}. A malicious csd there could steal your wallet key. Move it to a trusted location (e.g. /usr/local/bin) or set CAIRN_CSD to a trusted absolute path.` });
+    return (_resolved = { path: abs, explicit: false });
+}
+// For display (the `setup` command shows the user exactly which binary will sign).
+export function csdPathInfo() { return resolveCsdBin(); }
 function extractTxid(s) {
     const m = s.match(/txid["':\s]+0x([0-9a-fA-F]{64})/) || s.match(/0x[0-9a-fA-F]{64}/);
     return m ? (m[1] ? "0x" + m[1] : m[0]) : undefined;
 }
 export async function run(args) {
+    const bin = resolveCsdBin();
+    if (!bin.path)
+        return { ok: false, stdout: "", stderr: bin.error || "csd unavailable" };
     try {
-        const { stdout, stderr } = await pexec(CSD_BIN, args, { timeout: 30000 });
+        const { stdout, stderr } = await pexec(bin.path, args, { timeout: 30000 });
         return { ok: true, stdout, stderr, txid: extractTxid(stdout + stderr) };
     }
     catch (e) {
@@ -21,9 +132,10 @@ export async function run(args) {
         return { ok: false, stdout: e.stdout ?? "", stderr: e.stderr ?? String(e.message ?? e), txid: extractTxid(out) };
     }
 }
-// Is `csd` installed + runnable?
-export async function available() { try {
-    await pexec(CSD_BIN, ["--version"], { timeout: 5000 });
+// Is `csd` installed + runnable (at the trusted path)?
+export async function available() { const bin = resolveCsdBin(); if (!bin.path)
+    return false; try {
+    await pexec(bin.path, ["--version"], { timeout: 5000 });
     return true;
 }
 catch {
@@ -37,5 +149,10 @@ export async function walletConfig() { const r = await run(["wallet", "config"])
 catch {
     return null;
 } }
-// Derive the public addr20 from a privkey via `csd wallet recover` (local; key never networked).
+// Derive the public addr20 from a privkey via `csd wallet recover`.
+// SECURITY (audit H-2): this puts --privkey on the csd argv, briefly readable via /proc on a
+// shared host. It is a LAST resort — resolveAddr() only calls it when the wallet has no
+// default_change_addr20 AND we have no cached address, and the result is cached so it happens at
+// most once. Callers surface keyExposureWarning and recommend setting a change address.
 export async function deriveAddr(priv) { const r = await run(["wallet", "recover", "--privkey", priv]); const m = r.stdout.match(/addr20:\s*(0x[0-9a-fA-F]{40})/i); return m ? m[1] : null; }
+export const keyExposureWarning = "deriving your address from the wallet key briefly exposes it on the `csd` command line (readable via /proc on a shared host). Set a change address once — `csd wallet init --privkey <key>` — so cairn never needs the key again.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inversealtruism/cairn-cli",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "CLI for Compute Substrate / Cairn — browse the board/wall/network, and send CSD, propose, attest, and place stones non-custodially by driving your own installed `csd` wallet (cairn never holds your key; works node-less via the Cairn proxy).",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc",
     "dev": "tsx src/cli.ts",
-    "test": "npm run build && node test/security.mjs && node test/e2e.mjs",
+    "test": "npm run build && node test/security.mjs && node test/cairnx.mjs && node test/e2e.mjs",
     "prepare": "npm run clean && tsc",
     "prepublishOnly": "npm run clean && tsc"
   },