@needmoretruth/nmts-cli 0.17.2

package/dist/commands/wallet.js

@@ -0,0 +1,122 @@
+// `nmts wallet` — which wallet this account code opens, and what the chain says is in it.
+//
+// ⛔ IT READS. Nothing in this command signs, sends, swaps or spends, and there is no option that
+//    makes it. That is why it asks for no agreement: the agreement ladder stops a program from
+//    signing with a wallet on somebody's behalf, and asking for it here — where nothing can move —
+//    would teach a person to grant the one key that matters in order to look at a number.
+//
+// ⛔ THE ADDRESS AND THE BALANCES ARE DIFFERENT KINDS OF FACT, so they fail differently. The
+//    address is computed on this machine from the account code and cannot fail for any reason
+//    outside it; the balances come from a public node that can be slow, wrong or down. `nmts
+//    wallet address` is the half that never needs a network, and it exists because "what is my
+//    address" is the question somebody asks when the network is the thing that is broken.
+//
+// ⛔ AND A BALANCE THAT COULD NOT BE READ IS PRINTED AS THAT, NEVER AS ZERO — in words for a
+//    person, as `"read": false` for a program, and as a non-zero exit code for whatever is
+//    checking only that. An empty wallet and an unanswered question look identical on a screen,
+//    and one of them is a reason to stop.
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { coinAmount, readBalances, walCoinType, walletAddress, SUI_COIN_TYPE, } from "../wallet.js";
+/** What the operand may say. Anything else is a command line to correct, not a guess to act on. */
+const MODES = ["address", "balance"];
+function modeOf(what) {
+    if (what === undefined || what === "balance")
+        return "balance";
+    if (what === "address")
+        return "address";
+    throw new NmtsError(`\`${BINARY_NAME} wallet ${what}\` is not something this command does.`, {
+        exitCode: 2,
+        nextStep: `\`${BINARY_NAME} wallet\` shows the address and the balances, and ` +
+            `\`${BINARY_NAME} wallet address\` shows the address alone, without touching a network.`,
+    });
+}
+export async function wallet(what, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const mode = modeOf(what);
+    const resolved = await requireAccountCode();
+    const address = await walletAddress(resolved.code);
+    if (mode === "address") {
+        if (options.json) {
+            // ⛔ NO `network` FIELD. There is no network in this answer — an account has one wallet and
+            //    it is called the same thing on every chain — and a field naming one would invite a
+            //    reader to believe this address was looked up somewhere.
+            say(JSON.stringify({ address }));
+            return 0;
+        }
+        say(`Address  ${address}`);
+        say(``);
+        say(`  Derived on this machine from the account code. Nothing was asked of the NMTS server or`);
+        say(`  of any chain, so this says what the wallet is called and nothing about what is in it.`);
+        say(`  The browser app derives the same address from the same code.`);
+        return 0;
+    }
+    // ⛔ THE SERVER IS RESOLVED BUT NEVER CALLED. It is here for one thing only: the live server
+    //    implies mainnet, and which chain to ask is a question this tool refuses to guess at
+    //    (`network.ts`). Reading the stored file matches `whoami` — somebody who signed in against
+    //    a development stack on testnet must not be shown a mainnet answer.
+    const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    const open = options.openChain ??
+        (async (net, addr) => (await import("../wallet-chain.js")).chainReader(net, addr));
+    const walType = walCoinType(network);
+    const balances = await readBalances(await open(network, address), walType);
+    if (options.json) {
+        say(JSON.stringify({
+            address,
+            network,
+            sui: asJson(balances.sui, SUI_COIN_TYPE),
+            wal: asJson(balances.wal, walType),
+        }));
+        return exitCodeFor(balances);
+    }
+    say(`Address  ${address}`);
+    say(`Network  ${network}`);
+    say(`SUI      ${inWords(balances.sui)}`);
+    say(`WAL      ${inWords(balances.wal)}`);
+    say(``);
+    say(`  The address is derived on this machine from the account code; the balances were read`);
+    say(`  from the ${network} chain just now, and they move without this tool.`);
+    if (!balances.sui.read || !balances.wal.read) {
+        say(`  A balance that could not be read is printed as that and never as zero, and this command`);
+        say(`  exits non-zero when it happens — so nothing driving it reads a missing number as an`);
+        say(`  empty wallet.`);
+    }
+    say(`  Nothing here signs or spends. \`${BINARY_NAME} extend\` is the one command that signs, and it`);
+    say(`  asks for a separate agreement before it does.`);
+    return exitCodeFor(balances);
+}
+/**
+ * ⛔ AN UNREAD BALANCE IS A FAILURE, even beside one that answered. A program that checks the exit
+ *    code and nothing else is the ordinary case, and telling it "fine" while half the answer is
+ *    missing is the same mistake as printing the missing half as zero.
+ */
+function exitCodeFor(balances) {
+    return balances.sui.read && balances.wal.read ? 0 : 1;
+}
+/** One balance, for a person. */
+function inWords(balance) {
+    return balance.read ? coinAmount(balance.baseUnits) : `⛔ could not be read — ${balance.why}`;
+}
+/**
+ * One balance, for a program.
+ *
+ * ⚠ `baseUnits` IS A STRING. A balance can hold more digits than a JSON number keeps, and a
+ *   silently rounded total is worse than no total. `amount` is the same value written as a person
+ *   reads it, exactly, so a caller never has to divide.
+ */
+function asJson(balance, coinType) {
+    if (!balance.read)
+        return { coinType, read: false, error: balance.why };
+    return {
+        coinType,
+        read: true,
+        baseUnits: balance.baseUnits.toString(),
+        amount: coinAmount(balance.baseUnits),
+    };
+}

package/dist/commands/whoami.js

@@ -0,0 +1,33 @@
+// `nmts whoami` — which account the code on this machine belongs to.
+//
+// ⚠ IT ANSWERS OFFLINE, AND IT SAYS WHAT IT DID NOT DO. Everything printed is derived from the
+//    code on this machine; nothing is asked of a server. So it proves the code is well-formed and
+//    which account it is, and it proves nothing about whether that account exists, has credits, or
+//    is signed in. Printing an account id without saying that would read as "connected".
+import { identityOf } from "../account.js";
+import { requireAccountCode } from "../code-access.js";
+import { CODE_ENV_VAR, readCredentialsFile } from "../credentials.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveNetwork } from "../network.js";
+import { resolveServer } from "../server.js";
+export async function whoami(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const resolved = await requireAccountCode();
+    const identity = await identityOf(resolved.code);
+    // ⛔ BOTH STORED SHAPES, and an adversarial review is why. This read `source === "file"` only,
+    //    which was right while the file always held the code in the clear — and became wrong the
+    //    day `login` started sealing by default. Somebody who ran `login --server … --network
+    //    testnet` was then told, silently, that their account was on the live server and mainnet.
+    const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    say(`Account id   ${identity.accountId}`);
+    say(`Public code  ${identity.publicCode}`);
+    say(`Code from    ${resolved.source === "env" ? `${CODE_ENV_VAR} (not stored)` : "this machine"}`);
+    say(`Server       ${server}`);
+    say(`Network      ${network}`);
+    say(``);
+    say(`  Derived on this machine. Nothing was asked of the server, so this does not say whether`);
+    say(`  the account exists there, has credits, or is signed in.`);
+    return 0;
+}

package/dist/consent.js

@@ -0,0 +1,200 @@
+// What this machine's owner has agreed to, and the few things worth asking about.
+//
+// ⛔ THE DEFAULT IS SAFE AND NOTHING IS UNREACHABLE. A tool that simply refuses to do a risky
+//    thing does not prevent the risky thing — it gets forked, or worked around with a shell
+//    script, and then it happens with no warning at all and no record that anybody chose it. So
+//    every capability is here; what changes is whether it happens by accident.
+//
+// ⛔ FIVE KEYS, NOT TWENTY. A tool that asks about everything trains the person to say yes
+//    without reading, and then the one question that mattered is the one they clicked through.
+//    The bar for a key existing is one of: it cannot be undone · it costs money · it puts the
+//    account code somewhere that is not this tool's sealed file. Anything else happens without
+//    asking, and the count is written here so that adding a sixth has to be a decision.
+//    ⚠ The fifth was added for sharing, which is the first thing this tool can do that hands
+//      something to a person who is not the account holder — and the only one whose undo does not
+//      undo what already happened.
+//
+// ⛔ ONCE PER MACHINE, NOT ONCE PER RUN. The record is on disk, so an agent working through fifty
+//    files is asked nothing after the first time — which is the whole point of writing it down.
+//
+// ⚠ WHAT THIS CANNOT DO. Nothing here can tell whether a person or a program typed the grant
+//    command; no command-line tool can. What it CAN do is make the risk impossible to miss, put
+//    the decision in one obvious place, and keep a dated record of it. The instruction that an
+//    agent must not grant these on somebody's behalf is in AGENTS.md, and it is a rule rather
+//    than a mechanism. Saying otherwise would be claiming a protection that is not there.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, modesAreEnforced } from "./credentials.js";
+import { NmtsError } from "./errors.js";
+import { BINARY_NAME, SUPPORT_EMAIL } from "./product.js";
+export const CONSENTS = {
+    /**
+     * Spending the account's credits.
+     *
+     * Asked once because the price of every single upload is printed anyway — what this covers is
+     * the person understanding that this tool can spend at all, which is not obvious from a command
+     * called `put`.
+     */
+    spend: {
+        what: "Spend this account's credits on storage.",
+        risk: "Credits are consumed and are not refundable. Storage is bought on a public network and " +
+            "cannot be un-bought. The price of each upload is printed before it happens, and daily " +
+            "ceilings apply on the server whatever this machine asks for.",
+        limit: "This does not cover anything spent from a wallet. That is a separate agreement, and this " +
+            "one does not grant it.",
+    },
+    /**
+     * Writing the account code down UNSEALED — in the clear, in this tool's own file.
+     *
+     * ⛔ THE DEFAULT IS THE SEALED FORM, and this key is what unlocks the other one (owner,
+     *    2026-08-23: support storing it, but only behind encryption unless somebody agrees to a
+     *    disclaimer). It covers both the ordinary case, where mode 600 is the only protection and
+     *    every program running as you can read it, and the worse one, where the filesystem cannot
+     *    keep the mode either — a Windows share, some container mounts, a network drive. `login`
+     *    prints which of the two this machine is before it asks.
+     *
+     * ⚠ IT WAS NARROWER UNTIL 2026-08-23, covering only the filesystem case. Nothing had shipped
+     *   under the old meaning — the tool is not published — so no grant anywhere means less than
+     *   the words above. If it ever does, this needs a new key rather than a wider one: a grant
+     *   means what it said on the day it was given.
+     */
+    "unsafe-code-storage": {
+        what: "Store the account code in the clear, unsealed, in this tool's own file.",
+        risk: "The account code opens every file in this account and derives its wallet. Written in the " +
+            "clear it is readable by anything running as you — every agent, every script, every " +
+            "backup that copies your home directory, every image layer built from it. Where the " +
+            "filesystem cannot keep a file private, it is readable by others as well.",
+        limit: "There is no recovery from a leaked code: it cannot be changed while it still opens the " +
+            "files it opened. The alternatives are the sealed form, which is what `login` does by " +
+            "default, and a secret file the code is read from and never copied into.",
+    },
+    /**
+     * Reading the code out of a plain environment variable, or printing one to be set.
+     *
+     * ⛔ IT IS A DIFFERENT PLACE, NOT A SMALLER VERSION OF THE FILE (owner, 2026-08-23: an agent
+     *    must be able to choose this, with the person's agreement). An environment variable leaks
+     *    through channels a file does not: `docker inspect` prints the whole environment of a
+     *    container, `/proc/<pid>/environ` is readable by the same user for as long as the process
+     *    lives, every child process inherits it, and CI systems echo it into logs. A variable that
+     *    names a FILE — `NMTS_ACCOUNT_CODE_FILE` — has none of those, which is why it needs no
+     *    agreement.
+     */
+    "plain-env": {
+        what: "Use the account code from a plain environment variable, or print one to be set.",
+        risk: "An environment variable is not private to the program that reads it. `docker inspect` " +
+            "prints the entire environment of a container, anything running as you can read " +
+            "/proc/<pid>/environ while the process lives, every child process inherits it, and " +
+            "continuous-integration systems commonly write it into logs.",
+        limit: "This covers this tool reading it and printing it. It cannot cover where you put it " +
+            "afterwards, and it does not make the variable private. Naming a file instead — " +
+            "NMTS_ACCOUNT_CODE_FILE — avoids all of the above and asks for nothing.",
+    },
+    /**
+     * Signing a chain transaction with the wallet the account code derives.
+     *
+     * Separate from `spend` because it is a different pot of money: credits are a promise this
+     * service made, and a wallet holds assets nobody can restore.
+     */
+    /**
+     * Handing a file to another account.
+     *
+     * ⛔ IT IS HERE BECAUSE THE UNDO DOES NOT UNDO IT. Every other irreversible thing in this tool
+     *    costs money or moves the account code; this one gives somebody else a copy of a file, and
+     *    taking the share back afterwards stops future downloads and reaches nothing already
+     *    fetched. That gap is not a flaw to be fixed later — it is what handing somebody a file
+     *    means — so it is said before the first share rather than after it.
+     */
+    share: {
+        what: "Give another account the key to one of this account's files.",
+        risk: "Whoever holds that address can then download the file. Withdrawing the share stops further " +
+            "downloads and cannot reach a copy they already have. The address is typed by you and is " +
+            "not checked against a person — a share sent to the wrong address is sent.",
+        limit: "This does not cover uploading, spending, or anything to do with a wallet. It covers giving " +
+            "away files this account already holds.",
+    },
+    wallet: {
+        what: "Use the wallet this account code derives, and sign transactions with it.",
+        risk: "A signed transaction moves real assets and cannot be reversed by anybody, including NMTS. " +
+            "A mistake here is permanent.",
+        limit: "Only what this tool signs. Handing the account code to another program gives that program " +
+            "the same wallet, and nothing here can see that happen.",
+    },
+};
+/**
+ * ⛔ DERIVED FROM THE TABLE, so a key added above cannot be missing from the checks below.
+ *    Written as `Object.keys` of the table rather than a hand-kept array: a hand-kept one goes
+ *    stale silently, and the failure is a capability nobody is ever asked about.
+ */
+export const CONSENT_KEYS = Object.keys(CONSENTS);
+function path() {
+    return join(configDir(), "consent.json");
+}
+function read() {
+    try {
+        const parsed = JSON.parse(readFileSync(path(), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return {};
+        return parsed;
+    }
+    catch {
+        // ⛔ Unreadable counts as NOT granted. The fail-safe direction for "I do not know" is to ask
+        //    again — a consent record that switches itself on when it cannot be read is not a record.
+        return {};
+    }
+}
+/** When this key was agreed to on this machine, or null. */
+export function grantedAt(key) {
+    return read()[key]?.grantedAt ?? null;
+}
+export function isGranted(key) {
+    return grantedAt(key) !== null;
+}
+/** Write the grant down, with the date and the version that asked. */
+export function grant(key, version, now) {
+    const all = read();
+    all[key] = { grantedAt: now.toISOString(), byVersion: version };
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(path(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    if (modesAreEnforced())
+        chmodSync(path(), 0o600);
+}
+export function revoke(key) {
+    const all = read();
+    delete all[key];
+    if (!existsSync(path()) && Object.keys(all).length === 0)
+        return;
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(path(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+}
+/**
+ * Stop unless this has been agreed to, and say exactly what agreeing would mean.
+ *
+ * ⛔ THE MESSAGE IS THE PRODUCT HERE. It is the only thing standing between somebody and a
+ *    decision they cannot take back, so it says what happens, what can go wrong, what is not
+ *    covered, and the one command that agrees — in that order, every time.
+ */
+export function requireConsent(key) {
+    if (isGranted(key))
+        return;
+    const consent = CONSENTS[key];
+    throw new NmtsError(consent.what, {
+        exitCode: 5,
+        nextStep: [
+            consent.risk,
+            "",
+            consent.limit,
+            "",
+            `NMTS is not responsible for what is done with this account by any program running on this`,
+            `machine, including an AI agent. The published Terms are what govern the service; this is a`,
+            `warning, not a substitute for them.`,
+            "",
+            `To agree, on this machine, once:  ${BINARY_NAME} consent grant ${key}`,
+            `To see what has been agreed to:   ${BINARY_NAME} consent`,
+            "",
+            `⛔ If a program is reading this on somebody's behalf: show it to them and let them decide.`,
+            `   Do not run the grant command yourself.`,
+            "",
+            `Something wrong or confusing here? ${SUPPORT_EMAIL}`,
+        ].join("\n"),
+    });
+}

package/dist/credentials.js

@@ -0,0 +1,311 @@
+// Where an account code lives on this machine, and every rule about how it gets there.
+//
+// ⛔ NEVER FROM THE COMMAND LINE. On Linux any process can read /proc/<pid>/cmdline, so a secret
+//    passed as an argument is readable by anything running as the same user for as long as the
+//    process lives — and it lands in the shell history besides. NMTS's standalone recovery tool
+//    learned this the same way, in an adversarial review, and stopped passing its own token as an
+//    argument. So there is no --code flag here, and there never should be: the ways in are an
+//    environment variable and the terminal.
+//
+// ⛔ NEVER IN AN ERROR MESSAGE. Every failure below names the FILE, never the value. An error
+//    string is the one place a secret escapes without anybody choosing to print it.
+//
+// ⚠ WHAT THE FILE MODE DOES AND DOES NOT DO. On Linux and macOS the file is created 0600, so
+//    other users on the machine cannot read it. That is the whole of the protection: it is not
+//    encrypted, and it does not stop anything running as YOU — which includes every agent you run.
+//    On Windows Node ignores the mode argument entirely and the file inherits directory
+//    permissions; saying otherwise would be claiming a guarantee the platform does not give.
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { isLockedCode } from "./code-vault.js";
+import { NmtsError } from "./errors.js";
+/** The environment variable an agent sets instead of running `login`. */
+export const CODE_ENV_VAR = "NMTS_ACCOUNT_CODE";
+/** The API key, same rules: read fresh, never an argument, never printed. */
+export const API_KEY_ENV_VAR = "NMTS_API_KEY";
+/**
+ * Opens a passphrase-locked stored code without a terminal.
+ *
+ * ⚠ A passphrase in an environment variable protects the FILE, not this run: anything that can
+ *   read this variable can read the code the moment the tool decodes it. What it still buys is
+ *   real — a copied home directory, a backup, an image layer and a stolen disk all yield nothing
+ *   — and it is the only shape that works where no person is present to type.
+ */
+export const PASSPHRASE_ENV_VAR = "NMTS_PASSPHRASE";
+/**
+ * Names a FILE holding the account code, rather than holding it directly.
+ *
+ * ⛔ THE ONLY SAFE WAY TO GIVE A CONTAINER A SECRET. See `readSecretFile`.
+ */
+export const CODE_FILE_ENV_VAR = "NMTS_ACCOUNT_CODE_FILE";
+/** Names a file holding the API key. Same reason. */
+export const API_KEY_FILE_ENV_VAR = "NMTS_API_KEY_FILE";
+/** Directory holding everything this tool keeps. 0700 where the platform honours it. */
+export function configDir() {
+    const override = process.env["NMTS_CONFIG_DIR"];
+    return override && override.length > 0 ? override : join(homedir(), ".nmts");
+}
+export function credentialsPath() {
+    return join(configDir(), "credentials.json");
+}
+/** True on platforms where Node applies a POSIX file mode. */
+export function modesAreEnforced() {
+    return process.platform !== "win32";
+}
+/**
+ * Can this machine actually keep a file private, where the account code would go?
+ *
+ * ⛔ IT MEASURES RATHER THAN ASSUMES. "Not Windows" is not the same question: a container with a
+ *    bind mount from a Windows host, a network drive, an exFAT stick and several FUSE filesystems
+ *    all accept `chmod` and then ignore it. The mode comes back as whatever the filesystem felt
+ *    like, and the tool would have written the account code into a file anybody can read while
+ *    believing it had locked it.
+ *
+ * So: write a file, ask for 0600, read the mode back, and delete it. The probe is empty, its name
+ * is not the credentials name, and it is removed whatever happens.
+ *
+ * Returns false on Windows without probing — the platform has no POSIX mode to check, and
+ * answering "yes" from a successful no-op would be the worst of the three possible answers.
+ */
+export function codeStorageIsPrivate() {
+    if (!modesAreEnforced())
+        return false;
+    const dir = configDir();
+    const probe = join(dir, `.mode-probe.${process.pid}.tmp`);
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(probe, "", { mode: 0o600, flag: "wx" });
+        chmodSync(probe, 0o600);
+        return (statSync(probe).mode & 0o077) === 0;
+    }
+    catch {
+        // ⛔ Could not tell counts as NOT private. The fail-safe direction for "I do not know" is to
+        //    warn: a wrong warning costs one command, a wrong silence costs the account.
+        return false;
+    }
+    finally {
+        try {
+            rmSync(probe, { force: true });
+        }
+        catch {
+            // An undeleted empty probe file is harmless; failing the login over it would not be.
+        }
+    }
+}
+/**
+ * Write credentials, replacing any existing file, without ever leaving a readable window.
+ *
+ * The write goes to a fresh file created with `wx` (fails if the name exists, so nothing already
+ * on disk is opened) and is then renamed over the target. A rename within the same directory is
+ * atomic, so a reader either sees the old file or the new one and never a half-written one.
+ */
+export function writeCredentials(creds) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (modesAreEnforced())
+        chmodSync(dir, 0o700);
+    const target = credentialsPath();
+    const scratch = join(dir, `.credentials.${process.pid}.${Date.now()}.tmp`);
+    // ⛔ THE SCRATCH FILE NEVER OUTLIVES A FAILURE. It holds exactly what the target would — the
+    //    account code, in the clear when that is the shape being written — and `logout` removes
+    //    only `credentials.json`, so one left behind by a full disk or a failed rename would sit
+    //    there unreferenced and unnoticed. The rename is the last thing that happens; anything that
+    //    stops before it leaves nothing.
+    let renamed = false;
+    try {
+        writeFileSync(scratch, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        if (modesAreEnforced())
+            chmodSync(scratch, 0o600);
+        renameSync(scratch, target);
+        renamed = true;
+    }
+    finally {
+        if (!renamed) {
+            try {
+                rmSync(scratch, { force: true });
+            }
+            catch {
+                // Nothing more can be done about it here, and throwing from a `finally` would replace the
+                // real failure with this one.
+            }
+        }
+    }
+}
+/** Raised when the file exists but this machine is not keeping it private. */
+export class CredentialsTooOpenError extends Error {
+    // ⛔ Explicit fields, not constructor parameter properties: Node runs these files by ERASING the
+    //    types, and a parameter property is not erasable — it has to emit an assignment. `tsc`
+    //    refuses it here too (`erasableSyntaxOnly`), so the rule is machine-held, not remembered.
+    path;
+    mode;
+    constructor(path, mode) {
+        super(`${path} can be read by other users on this machine (mode ${mode.toString(8)}). ` +
+            `Run: chmod 600 ${path}`);
+        this.name = "CredentialsTooOpenError";
+        this.path = path;
+        this.mode = mode;
+    }
+}
+/**
+ * Read credentials from disk, refusing a file other users can read.
+ *
+ * ⛔ The refusal is the point. A credentials file that went world-readable — copied with `cp -r`,
+ *    restored from an archive, written by an older version — is a leak that nothing else in the
+ *    system would ever mention. Reading it anyway and carrying on is how that stays quiet.
+ */
+export function readCredentialsFile() {
+    const path = credentialsPath();
+    let raw;
+    try {
+        if (modesAreEnforced()) {
+            const mode = statSync(path).mode & 0o777;
+            if ((mode & 0o077) !== 0)
+                throw new CredentialsTooOpenError(path, mode);
+        }
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof CredentialsTooOpenError)
+            throw error;
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+    // ⛔ THE PARSER'S OWN MESSAGE NEVER ESCAPES. V8 quotes about thirty characters of the input in
+    //    `Unexpected token …`, and the input here is the file the account code is in — an
+    //    adversarial review printed nine symbols of a real code to stderr from a single lost quote.
+    //    `errors.ts` prints an unknown error's message verbatim, so the only place to stop it is
+    //    here, before it becomes an error at all.
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw unusable(path, "is not readable as JSON");
+    }
+    if (!isCredentials(parsed))
+        throw unusable(path, "is not a credentials file this version understands");
+    return parsed;
+}
+/**
+ * The one refusal for a file this version cannot use, in the one wording.
+ *
+ * ⛔ IT NAMES THE PATH AND NOTHING ELSE. Not the contents, not the parser's complaint, not which
+ *    field was wrong — the file is the account code's file, and every one of those quotes it.
+ *
+ * ⚠ AND IT IS AN `NmtsError` WITH A WAY OUT. It used to be a bare `Error`, which meant the
+ *    generic exit code and no next step: `whoami`, `ls`, `get` and `put` all died at 1 saying
+ *    only that the file was not understood, and the only command that could fix it — `logout` —
+ *    was the one nobody was told to run.
+ */
+function unusable(path, what) {
+    return new NmtsError(`${path} ${what}.`, {
+        exitCode: 3,
+        nextStep: `Nothing was read from it. \`nmts logout\` removes it, and \`nmts login\` writes a fresh ` +
+            `one. If that file is the only copy of the account code, take the code out of it by hand ` +
+            `first — this tool will not open it.`,
+    });
+}
+function isNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function isCredentials(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    const plain = typeof v["accountCode"] === "string" && v["accountCode"].length > 0;
+    const locked = isLockedCode(v["lockedCode"]);
+    // ⛔ Exactly one. Neither means there is no code to use; both means somebody merged two files.
+    if (plain === locked)
+        return false;
+    if (typeof v["server"] !== "string" || v["server"].length === 0)
+        return false;
+    if ("apiKey" in v && typeof v["apiKey"] !== "string")
+        return false;
+    if ("network" in v && typeof v["network"] !== "string")
+        return false;
+    return true;
+}
+/**
+ * The account code this run should use, and where it came from.
+ *
+ * The environment variable wins over the file so an agent can be handed a code for one run without
+ * writing anything to disk — which is the safer shape when the machine is shared or ephemeral.
+ */
+export function resolveAccountCode() {
+    const fromEnv = process.env[CODE_ENV_VAR];
+    if (fromEnv !== undefined && fromEnv.length > 0)
+        return { code: fromEnv, source: "env" };
+    const fromSecret = readSecretFile(CODE_FILE_ENV_VAR);
+    if (fromSecret !== null)
+        return { code: fromSecret, source: "secret-file" };
+    const file = readCredentialsFile();
+    if (file?.accountCode !== undefined)
+        return { code: file.accountCode, source: "file" };
+    if (file?.lockedCode !== undefined)
+        return { locked: file.lockedCode, source: "file-locked" };
+    return null;
+}
+/**
+ * Read a secret out of the file an environment variable NAMES.
+ *
+ * ⛔ THIS IS HOW A SECRET GETS INTO A CONTAINER. An environment variable holding the value itself
+ *    is readable by anybody who can inspect the container — `docker inspect` prints the whole
+ *    environment, and so does the API behind it. A variable holding a PATH gives that reader a
+ *    filename and nothing else, while the value rides in on a `--secret` mount, a tmpfs, or a
+ *    bind-mounted file whose permissions the host controls. It is the convention the official
+ *    database images use, for the same reason.
+ *
+ * Trailing whitespace and a trailing newline are removed: writing a secret to a file with `echo`
+ * appends one, and refusing a code because of it would be a puzzle with no clue.
+ */
+export function readSecretFile(variable) {
+    const path = process.env[variable];
+    if (path === undefined || path.length === 0)
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        // ⛔ Named, not swallowed. A variable that points at nothing is a mistake somebody made on
+        //    purpose — falling through to "not signed in" would send them looking at the wrong thing.
+        throw new NmtsError(`${variable} names ${path}, which could not be read.`, {
+            exitCode: 3,
+            nextStep: `Check the path and its permissions. Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        throw new NmtsError(`${variable} names ${path}, which is empty.`, { exitCode: 3 });
+    }
+    return value;
+}
+/**
+ * The API key this run should use, and where it came from.
+ *
+ * ⚠ SEPARATE FROM THE ACCOUNT CODE ON PURPOSE, and the two can come from different places. The
+ *   code is what opens the files; the key is only what makes the server answer without a human
+ *   check. Somebody may keep the code in the environment for one run while the key stays on the
+ *   machine, or the other way round, and neither combination is unusual enough to refuse.
+ */
+export function resolveApiKey() {
+    const fromEnv = process.env[API_KEY_ENV_VAR];
+    if (fromEnv !== undefined && fromEnv.length > 0)
+        return { key: fromEnv, source: "env" };
+    const fromSecret = readSecretFile(API_KEY_FILE_ENV_VAR);
+    if (fromSecret !== null)
+        return { key: fromSecret, source: "secret-file" };
+    const file = readCredentialsFile();
+    if (file?.apiKey !== undefined && file.apiKey.length > 0)
+        return { key: file.apiKey, source: "file" };
+    return null;
+}
+/** Scratch location used only by tests that need a directory outside the real home. */
+export function testConfigDir(name) {
+    return join(tmpdir(), `nmts-agents-test-${name}-${process.pid}`);
+}