@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/code-access.d.ts

@@ -0,0 +1,29 @@
+import { type CredentialSource } from "./credentials.ts";
+export interface OpenedCode {
+    code: string;
+    source: CredentialSource;
+}
+/**
+ * The NMTS key for this run, opening a sealed one if that is what is stored.
+ *
+ * Returns null when there is nothing to use — the caller decides whether that is an error, which
+ * differs between `whoami` (say so quietly) and `put` (refuse).
+ */
+export interface OpenOptions {
+    /**
+     * May this run stop and ask on the terminal?
+     *
+     * ⛔ FALSE FOR `nmts mcp`, AND THAT IS NOT TIDINESS. Its stdin carries the protocol: a prompt
+     *    there consumes the client's first message as a passphrase guess, and the answer it prints
+     *    lands on the wire as bytes the other end cannot parse. An MCP server that cannot open its
+     *    credential must say so and exit, not negotiate.
+     */
+    allowPrompt?: boolean;
+}
+export declare function openAccountCode(options?: OpenOptions): Promise<OpenedCode | null>;
+/**
+ * The code, or a refusal naming what to do about it. For commands that cannot proceed without it.
+ *
+ * ⛔ The message never mentions the code itself, only where one could come from.
+ */
+export declare function requireAccountCode(options?: OpenOptions): Promise<OpenedCode>;

package/dist/code-access.js

@@ -1,4 +1,4 @@
-// Getting the account code this run should actually use — including opening a sealed one.
+// Getting the NMTS key this run should actually use — including opening a sealed one.
 //
 // ⛔ WHY IT IS NOT IN `credentials.ts`. That module answers "where is the code"; this one answers
 //    "may this run have it, and can it be opened". Putting the second question in the first module
@@ -47,7 +47,7 @@ async function readPassphrase(allowPrompt) {
     if (fromEnv !== undefined && fromEnv.length > 0)
         return fromEnv;
     if (!allowPrompt || !stdinIsATerminal()) {
-        throw new NmtsError(`The stored account code is sealed with a passphrase.`, {
+        throw new NmtsError(`The stored NMTS key is sealed with a passphrase.`, {
             exitCode: 3,
             nextStep: [
                 allowPrompt
@@ -61,7 +61,7 @@ async function readPassphrase(allowPrompt) {
             ].join("\n"),
         });
     }
-    return promptSecret(`Passphrase for the stored account code: `, PASSPHRASE_ENV_VAR);
+    return promptSecret(`Passphrase for the stored NMTS key: `, PASSPHRASE_ENV_VAR);
 }
 /**
  * The code, or a refusal naming what to do about it. For commands that cannot proceed without it.

package/dist/code-vault.d.ts

@@ -0,0 +1,38 @@
+import { NmtsError } from "./errors.ts";
+/** What gets written. Every field is needed to open it again; none of them is a secret. */
+export interface LockedCode {
+    /** Format version of THIS file, not of the NMTS crypto format. */
+    v: 1;
+    kdf: "scrypt";
+    n: number;
+    r: number;
+    p: number;
+    /** base64 */
+    salt: string;
+    /** base64 */
+    nonce: string;
+    /** base64, ciphertext followed by the 16-byte tag. */
+    ct: string;
+}
+/** Thrown when the passphrase does not open the file. ⛔ Never says how close it was. */
+export declare class WrongPassphraseError extends NmtsError {
+    constructor();
+}
+/** Seal the code under a passphrase. The result is safe to write to a file. */
+export declare function lockCode(code: string, passphrase: string): LockedCode;
+/**
+ * Open a sealed code.
+ *
+ * ⛔ The tag is checked before a single byte is returned — that is what `final()` does for GCM, and
+ *    it is why a wrong passphrase cannot yield a plausible-looking wrong code.
+ */
+export declare function unlockCode(locked: LockedCode, passphrase: string): string;
+/** Shape check for something read off disk. ⛔ A parser, not an assertion: the file is input. */
+export declare function isLockedCode(value: unknown): value is LockedCode;
+/**
+ * Are these two passphrases the same? Used only to catch a typo when one is being set.
+ *
+ * ⚠ Constant-time because it costs nothing to be. Neither value is secret to this process, but a
+ *   comparison that short-circuits is a habit worth not having near a passphrase.
+ */
+export declare function samePassphrase(a: string, b: string): boolean;

package/dist/code-vault.js

@@ -1,6 +1,6 @@
-// Locking the account code with a passphrase, so what is on disk is not the code.
+// Locking the NMTS key with a passphrase, so what is on disk is not the code.
 //
-// WHY THIS EXISTS. `nmts login` used to write the account code in the clear at mode 600, which is
+// WHY THIS EXISTS. `nmts login` used to write the NMTS key in the clear at mode 600, which is
 //   what `gh`, `aws` and `docker login` do. Mode 600 answers exactly one question — "can another
 //   user on this machine read it" — and answers nothing about a backup, a copied home directory,
 //   a synced folder, a container image layer, or a disk pulled out of a laptop. A passphrase
@@ -15,7 +15,7 @@
 //    the code is "safe".
 //
 // ⛔ NODE BUILT-INS ONLY. `scrypt` and AES-256-GCM are in `node:crypto`; a password-hashing
-//    dependency would put somebody else's code on the path the account code travels, for a
+//    dependency would put somebody else's code on the path the NMTS key travels, for a
 //    function the platform already ships. This is local storage, not the NMTS crypto format —
 //    NCF-3 governs what leaves this machine, and nothing here does.
 import { createCipheriv, createDecipheriv, randomBytes, scryptSync, timingSafeEqual, } from "node:crypto";
@@ -78,10 +78,10 @@ const TAG_BYTES = 16;
 /** Thrown when the passphrase does not open the file. ⛔ Never says how close it was. */
 export class WrongPassphraseError extends NmtsError {
     constructor() {
-        super("That passphrase does not open the stored account code.", {
+        super("That passphrase does not open the stored NMTS key.", {
             exitCode: 3,
             nextStep: "Try again. If the passphrase is lost, the stored copy cannot be recovered — sign in " +
-                "again with the account code itself.",
+                "again with the NMTS key itself.",
         });
         this.name = "WrongPassphraseError";
     }
@@ -105,10 +105,10 @@ function refuseCost(locked) {
     const { n, r, p } = locked;
     const whole = (v) => Number.isInteger(v) && v >= 1;
     const refuse = () => {
-        throw new NmtsError("The stored account code names a key-derivation cost this version refuses.", {
+        throw new NmtsError("The stored NMTS key names a key-derivation cost this version refuses.", {
             exitCode: 1,
             nextStep: "The file has been edited, or was written by a newer version of this tool. Sign in again " +
-                "with the account code itself.",
+                "with the NMTS key itself.",
         });
     };
     if (!whole(n) || !whole(r) || !whole(p))
@@ -136,7 +136,7 @@ function deriveKey(passphrase, salt, n, r, p) {
         return scryptSync(Buffer.from(passphrase, "utf8"), salt, KEY_BYTES, { N: n, r, p, maxmem: MAXMEM });
     }
     catch (error) {
-        throw new NmtsError("The stored account code asks for a key derivation this machine refused.", {
+        throw new NmtsError("The stored NMTS key asks for a key derivation this machine refused.", {
             exitCode: 1,
             nextStep: `Cause: ${error instanceof Error ? error.message : String(error)}`,
         });

package/dist/collision.d.ts

@@ -0,0 +1,67 @@
+import { type Autonomy } from "./autonomy.ts";
+/** What to do with a name that is already in use. Mirrors the browser's two buttons. */
+export type OnCollision = "rename" | "overwrite";
+export declare const COLLISION_CHOICES: readonly OnCollision[];
+/** What each choice does, in the words the tool prints. One line each. */
+export declare const COLLISION_MEANS: Readonly<Record<OnCollision, string>>;
+/**
+ * What a run asked for on the command line, or undefined for "use this machine's setting".
+ *
+ * ⛔ AN UNKNOWN WORD IS REFUSED, NOT ROUNDED DOWN. Silently reading `--on-collision overwite` as
+ *    the safe answer would look like it worked, and the person would find out from the drive.
+ */
+export declare function parseAsked(typed: string | undefined): OnCollision | undefined;
+/** What is written down when nobody has chosen. */
+export declare const DEFAULT_COLLISION: OnCollision;
+/**
+ * What this machine is set to.
+ *
+ * ⛔ Unreadable counts as `rename`, for the same reason autonomy unreadable counts as off: the
+ *    fail-safe direction for "I do not know" is the one that destroys nothing.
+ */
+export declare function currentChoice(): OnCollision;
+/** Has anybody answered on this machine? Used to know whether setup still has to ask. */
+export declare function hasChosen(): boolean;
+/** Write the choice down, with the date and the version that asked. */
+export declare function setChoice(choice: OnCollision, version: string, now: Date): void;
+/** Forget the answer, so setup asks again. */
+export declare function forgetChoice(): void;
+/** What decided, so the tool can say so rather than acting silently. */
+export interface Decision {
+    readonly choice: OnCollision;
+    /**
+     * What settled it.
+     *
+     * `setting` — what a person answered at setup, or the default when nobody has.
+     * `asked-for` — an agent asked for this run to overwrite, and a mode allows it.
+     * `agent-refused` — an agent asked to overwrite while no mode is on, so it renames instead.
+     */
+    readonly by: "setting" | "asked-for" | "agent-refused";
+}
+/**
+ * What to do with this collision, and what settled it.
+ *
+ * ⛔ A STORED ANSWER IS A PERSON'S ANSWER AND IS NOT SECOND-GUESSED. Setup asks while somebody is
+ *    definitely there; overriding that later because autonomy happens to be off would mean the
+ *    tool ignoring the one answer it actually has from a person.
+ *
+ * ⛔ WHAT THE MODES GATE IS THE OTHER THING: an agent deciding, for THIS run, to overwrite when
+ *    nobody said so. That is the case the owner ruled on -- without a mode the agent picks rename
+ *    -- and it is enforced here rather than written in the instructions and hoped for.
+ *
+ * ⛔ THE OVERRIDE IS ONE-WAY. A mode can let `overwrite` through; nothing here turns a `rename`
+ *    into an `overwrite`.
+ */
+export declare function decide(
+/** What this run asked for, if anything. `undefined` means "use what this machine is set to". */
+askedFor?: OnCollision, setting?: OnCollision, mode?: Autonomy): Decision;
+/** How the two answers are numbered where setup asks. Kept here so the question and the reading agree. */
+export declare const ANSWER_NUMBER: Readonly<Record<OnCollision, string>>;
+/**
+ * What somebody typed at the setup question.
+ *
+ * ⛔ ONLY THE EXACT NUMBER FOR OVERWRITE COUNTS, and everything else is the safe answer. A typo, an
+ *    empty line, a closed pipe, a stray space, `y`, `yes` — none of them mean "delete my files".
+ *    The answer that destroys something has to be typed on purpose.
+ */
+export declare function readAnswer(typed: string): OnCollision;

package/dist/collision.js

@@ -115,7 +115,7 @@ askedFor, setting = currentChoice(), mode = currentMode()) {
         return { choice: setting, by: "setting" };
     if (askedFor === "rename")
         return { choice: "rename", by: "asked-for" };
-    if (mode === "off")
+    if (mode === "default")
         return { choice: "rename", by: "agent-refused" };
     return { choice: "overwrite", by: "asked-for" };
 }

package/dist/commands/accept-terms.d.ts

@@ -0,0 +1,11 @@
+export interface AcceptTermsOptions {
+    server?: string | undefined;
+    write?: ((line: string) => void) | undefined;
+    /** Injected in tests: answers the two typed lines, in order. */
+    readLine?: ((question: string) => Promise<string>) | undefined;
+    /** `--accept-terms <version>`: the version the person said they accept, relayed by an agent. */
+    terms?: string | undefined;
+    /** `--accept-privacy <version>`: the version the person said they have read. */
+    privacy?: string | undefined;
+}
+export declare function acceptTerms(options?: AcceptTermsOptions): Promise<number>;

package/dist/commands/accept-terms.js

@@ -0,0 +1,106 @@
+// `nmts accept-terms` — a PERSON accepts the documents in force, from the terminal.
+//
+// ⛔ WHY IT EXISTS (2026-09-06). When a new version of the Terms takes effect the server
+//    refuses this account's uploads and shares until the new version is accepted (Terms 15.5). An
+//    account driven from a terminal holds an API key and the NMTS key and never a session,
+//    and a key is not allowed to accept — a key accepting would be a program consenting on
+//    somebody's behalf. Until this command the only way out was a browser. Now the same record is
+//    written from here, proved the way a browser sign-in is proved: by the NMTS key.
+//
+// ⛔ IT IS A PERSON'S ACT, AND THREE THINGS KEEP IT ONE. It is refused in mode auto and under
+//    --skip-permissions before the code is even opened. It needs a terminal to type into — there is
+//    no `--terms <v>` flag, because a flag is what an agent would pass. And the two versions are
+//    TYPED, not confirmed with a key press: typing the version string is what the browser's screen
+//    asks for too, and it is the smallest act that cannot be done without having looked.
+//
+// ⛔ TWO ANSWERS, NOT ONE, for the same reason the browser has two controls. Consent to the Terms is
+//    a contract; the Privacy Policy is not consented to — its own §7.3 rests the processing on
+//    contract and legitimate interests — so the second line acknowledges READING it. The call to the
+//    server is the same pair the screen sends.
+//
+// ⛔ WHAT LEAVES THIS MACHINE is the account id, the sign-in proof (`account-proof.ts` says what
+//    that is and why it decrypts nothing) and the two typed versions. The NMTS key does not.
+import { accountProofFor } from "../account-proof.js";
+import { identityOf } from "../account.js";
+import { request } from "../api.js";
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile, resolveApiKey } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { BINARY_NAME, HOME_URL } from "../product.js";
+import { promptLine, stdinIsATerminal } from "../prompt.js";
+import { resolveServer } from "../server.js";
+export async function acceptTerms(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    // The tier gate has already refused or asked by mode. The two versions are typed here by a
+    // person at a terminal, or — when an agent relays the person's acceptance — named on the
+    // command line: `--accept-terms <version> --accept-privacy <version>`.
+    const relayed = options.terms !== undefined && options.privacy !== undefined;
+    const ask = options.readLine ?? promptLine;
+    if (!relayed && options.readLine === undefined && !stdinIsATerminal()) {
+        throw new NmtsError("There is no terminal to type into (stdin is not a TTY).", {
+            exitCode: 3,
+            nextStep: `Run this where a person can type the two versions, or — after they have said so — ` +
+                `\`${BINARY_NAME} accept-terms --accept-terms <version> --accept-privacy <version> --yes\`.`,
+        });
+    }
+    const held = await requireAccountCode();
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    // The key is only for READING where the account stands; the acceptance itself needs none — an
+    // account whose key cannot even be minted until it accepts (`key new` is refused too) still has
+    // this way in.
+    const key = resolveApiKey();
+    const standing = key === null ? null : await standingOf(server, key.key);
+    if (standing !== null && !standing.owed) {
+        say(`This account has already accepted the documents in force ` +
+            `(Terms of Service ${standing.terms} · Privacy Policy ${standing.privacy}). Nothing to do.`);
+        return 0;
+    }
+    if (standing === null) {
+        say(`No API key on this machine, so where this account stands could not be read.`);
+        say(`Each document prints its version at the top.`);
+    }
+    else {
+        say(`In force: Terms of Service ${standing.terms} · Privacy Policy ${standing.privacy}.`);
+        say(`This account has not accepted this pair, so uploads and shares are refused until it does.`);
+    }
+    say(`Read them first: \`${BINARY_NAME} terms\` · \`${BINARY_NAME} privacy\` · what changed: ` +
+        `\`${BINARY_NAME} notices\` (or ${HOME_URL}/notices).`);
+    say(``);
+    const terms = (options.terms ?? (await ask(`Type the Terms of Service version you have read and accept: `))).trim();
+    const privacy = (options.privacy ?? (await ask(`Type the Privacy Policy version you have read: `))).trim();
+    if (terms === "" || privacy === "") {
+        say(`Nothing was accepted.`);
+        return 1;
+    }
+    const identity = await identityOf(held.code);
+    // ⛔ THE PROOF IS BUILT FOR THIS ONE REQUEST AND NOTHING KEEPS IT. `accountProofFor` also asks
+    //    for the agreement that covers sending it when the code came from an environment variable.
+    const authSecret = await accountProofFor({ code: held.code, source: held.source });
+    await request(server, "/v1/account/accept-terms/by-code", {
+        method: "POST",
+        body: {
+            account_id: identity.accountId,
+            auth_secret: authSecret,
+            terms_version: terms,
+            privacy_version: privacy,
+        },
+    });
+    say(`Recorded: this account accepts the Terms of Service ${terms} and has read the Privacy Policy ${privacy}.`);
+    say(`Uploads and shares are open again.`);
+    return 0;
+}
+async function standingOf(server, apiKey) {
+    const answer = await request(server, "/v1/account/summary", { token: apiKey });
+    const terms = isRecord(answer) ? answer["terms"] : undefined;
+    if (!isRecord(terms))
+        throw new NmtsError("The server described the account in a shape this version cannot read.");
+    const required = terms["required_terms_version"];
+    const privacy = terms["required_privacy_version"];
+    // No pair in force means the gate is off and nothing is owed — the same reading `balance` makes.
+    if (typeof required !== "string" || typeof privacy !== "string") {
+        return { owed: false, terms: "none", privacy: "none" };
+    }
+    return { owed: terms["acceptance_required"] === true, terms: required, privacy };
+}

package/dist/commands/balance.d.ts

@@ -0,0 +1,7 @@
+export interface BalanceOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function balance(options?: BalanceOptions): Promise<number>;

package/dist/commands/balance.js

@@ -48,6 +48,14 @@ function asSummary(value) {
             soonest_expiry: typeof expiry === "string" ? expiry : null,
             file_cap: num(credits["file_cap"], "credits.file_cap"),
             daily_cap: num(credits["daily_cap"], "credits.daily_cap"),
+            // Deposits arrived with the server that returns them; an older server simply has none.
+            held: typeof credits["held"] === "number" ? credits["held"] : 0,
+            deposits: typeof credits["deposits_held"] === "number" ? credits["deposits_held"] : 0,
+            // ⛔ THE SERVER'S TWO NUMBERS, or none. A build that filled these in from a constant of its
+            //    own would print what it believes rather than what the ledger will do, which is exactly
+            //    the mistake the two ceilings above are read this way to avoid.
+            deposit_max: typeof credits["deposit_max"] === "number" ? credits["deposit_max"] : 0,
+            deposit_default: typeof credits["deposit_default"] === "number" ? credits["deposit_default"] : 0,
         },
         quota: { granted: num(quota["granted"], "quota.granted"), used: num(quota["used"], "quota.used") },
         storage: {
@@ -55,8 +63,33 @@ function asSummary(value) {
             earliest_expiry_epoch: typeof epoch === "number" ? epoch : null,
         },
         terms: { acceptance_required: isRecord(terms) && terms["acceptance_required"] === true },
+        ai_account: value["ai_account"] === true,
+        deposits: depositRows(credits["deposits"]),
     };
 }
+/**
+ * The per-file deposit rows, when the answer carries them.
+ *
+ * ⛔ ABSENCE IS NOT ZERO ROWS DRESSED UP. The narrow read this command makes answers with the two
+ *    totals and no list, so nothing is printed rather than a list claiming this account has no
+ *    deposits. A row this version cannot read is dropped for the same reason: a file whose
+ *    set-aside is a string is a file this build cannot say anything true about.
+ */
+function depositRows(value) {
+    if (!Array.isArray(value))
+        return [];
+    const rows = [];
+    for (const row of value) {
+        if (!isRecord(row))
+            continue;
+        const set = row["deposit_credits"];
+        const spent = row["spent_credits"];
+        if (typeof set !== "number" || typeof spent !== "number")
+            continue;
+        rows.push({ deposit_credits: set, spent_credits: spent });
+    }
+    return rows;
+}
 function plural(n, one, many) {
     return `${n} ${n === 1 ? one : many}`;
 }
@@ -69,6 +102,13 @@ export async function balance(options = {}) {
         return 0;
     }
     const { credits, quota, storage } = summary;
+    // ⛔ FIRST, AND NOT UNDER THE NUMBERS. Whoever is reading has to know WHICH account these
+    //    figures belong to before they mean anything: an AI account has its own key, its own wallet
+    //    and its own empty drive, so "nothing here" is the ordinary answer rather than a loss.
+    if (summary.ai_account) {
+        say(`AI account (not the main account)`);
+        say(``);
+    }
     say(`credits    ${plural(credits.remaining, "credit", "credits")}`);
     // ⛔ SAID AS BYTES TOO, because "one credit" means nothing until you know what it buys. It is the
     //    same number, not a second one — the server derives it from the same ledger read.
@@ -79,6 +119,19 @@ export async function balance(options = {}) {
         say(`           soonest to lapse unused: ${credits.soonest_expiry}`);
     }
     say(`ceilings   ${credits.file_cap} per file · ${credits.daily_cap} per day`);
+    if (credits.held > 0) {
+        // Tied up, not spent: each credit-paid file puts a deposit down, returned when its period ends.
+        say(`deposits   ${plural(credits.held, "credit", "credits")} held on ${plural(credits.deposits, "stored file", "stored files")} — back when the storage period ends`);
+        // ⚠ Per file, and what has already gone out of it. A deposit is spent a fee at a time, so
+        //   "set aside" and "spent" are two different numbers about the same file.
+        for (const row of summary.deposits) {
+            say(`           ${row.deposit_credits} set aside · ${row.spent_credits} spent`);
+        }
+    }
+    if (credits.deposit_max > 0) {
+        say(`           an upload sets ${credits.deposit_default} aside by default — ` +
+            `0 to ${credits.deposit_max}, \`${BINARY_NAME} deposit\` or --deposit for one upload`);
+    }
     say(`holding    ${humanSize(quota.used)} across ${plural(storage.parts, "stored piece", "stored pieces")}`);
     if (storage.earliest_expiry_epoch !== null) {
         say(`           the earliest lease ends at storage period ${storage.earliest_expiry_epoch} — ` +
@@ -87,7 +140,7 @@ export async function balance(options = {}) {
     if (summary.terms.acceptance_required) {
         say(``);
         say(`⛔ New terms are in force and this account has not accepted them.`);
-        say(`   A person has to read and accept them in a browser; nothing here can do it.`);
+        say(`   A person reads and accepts them — \`${BINARY_NAME} accept-terms\` here, or in a browser.`);
     }
     return 0;
 }

package/dist/commands/create-code-file.d.ts

@@ -0,0 +1,24 @@
+import { NmtsError } from "../errors.ts";
+/**
+ * Where the code goes, or `null` for the screen.
+ *
+ * ⛔ `-` IS REFUSED, WHICH IS THE OPPOSITE OF WHAT IT MEANS EVERYWHERE ELSE IN THIS TOOL. In
+ *    `get` and `listfile` it means "hand the bytes to whatever is reading stdout", and that is
+ *    right for a file somebody already has. Here it would mean putting the only copy of an
+ *    NMTS key into the same stream a program is parsing — which is the one place this command
+ *    exists to keep it out of.
+ */
+export declare function codeFileTarget(out: string | undefined): string | null;
+/**
+ * Write the code where the caller pointed, readable by nobody else.
+ *
+ * ⚠ `wx` FAILS IF THE NAME APPEARED SINCE THE CHECK ABOVE, which is the point of using it rather
+ *   than trusting that check: between the two, something else may have written there.
+ *
+ * ⚠ ON WINDOWS THE MODE IS IGNORED and the file inherits the folder's permissions — the same
+ *   limit `credentials.ts` documents, and claiming otherwise would be claiming a guarantee the
+ *   platform does not give.
+ */
+export declare function writeCodeFile(path: string, code: string): void;
+/** `--json` without `--out`: there is nowhere for the code to go that is not the output. */
+export declare function jsonNeedsAFile(): NmtsError;

package/dist/commands/create-code-file.js

@@ -0,0 +1,93 @@
+// Where a new NMTS key goes when it is not printed, and the rules around that file.
+//
+// ⛔ IT LEFT `create.ts` BECAUSE THERE ARE TWO PATHS ONTO IT NOW (2026-09-05). `create` makes an
+//    account either with a verified API key or through a registration address a person opens, and
+//    both make the same code and owe it the same treatment: written before anything is asked of
+//    the server, never overwritten, never sent to stdout. A second copy of these three rules is a
+//    second place for one of them to be relaxed.
+//
+// ⛔ AND THE FILE IS WRITTEN BEFORE THE ACCOUNT IS ASKED FOR. A full disk, a bad path or a name
+//    already taken must fail while there is still nothing to lose; discovering it AFTER the server
+//    has created the account would mean an account exists whose only key we are about to drop.
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { NmtsError } from "../errors.js";
+import { STDOUT_TARGET } from "../stdout.js";
+/**
+ * Where the code goes, or `null` for the screen.
+ *
+ * ⛔ `-` IS REFUSED, WHICH IS THE OPPOSITE OF WHAT IT MEANS EVERYWHERE ELSE IN THIS TOOL. In
+ *    `get` and `listfile` it means "hand the bytes to whatever is reading stdout", and that is
+ *    right for a file somebody already has. Here it would mean putting the only copy of an
+ *    NMTS key into the same stream a program is parsing — which is the one place this command
+ *    exists to keep it out of.
+ */
+export function codeFileTarget(out) {
+    if (out === undefined || out === "")
+        return null;
+    if (out === STDOUT_TARGET) {
+        throw new NmtsError("The new NMTS key will not be sent to stdout.", {
+            exitCode: 2,
+            nextStep: `Nothing was created. stdout is what a program reads and a log keeps, and this is the ` +
+                `only copy of your NMTS key. Name a file — \`--out ./account-code.txt\` — or leave --out off ` +
+                `and read it off the screen.`,
+        });
+    }
+    const path = isAbsolute(out) ? out : resolve(process.cwd(), out);
+    let existing = null;
+    try {
+        existing = statSync(path);
+    }
+    catch {
+        // Not there is exactly what this wants.
+    }
+    if (existing !== null) {
+        // ⛔ NO `--force` HERE, DELIBERATELY. Everywhere else in this tool --force replaces a file
+        //    that can be fetched again. The file this would replace may be the only copy of ANOTHER
+        //    account's code, and overwriting it destroys that account with no way back.
+        throw new NmtsError(`${path} is already there.`, {
+            exitCode: 4,
+            nextStep: existing.isDirectory()
+                ? `--out names the FILE the NMTS key goes into, not a directory.`
+                : `Nothing was created. That file is not replaced, whatever --force says: it may hold ` +
+                    `the only copy of another account's NMTS key. Name one that does not exist.`,
+        });
+    }
+    return path;
+}
+/**
+ * Write the code where the caller pointed, readable by nobody else.
+ *
+ * ⚠ `wx` FAILS IF THE NAME APPEARED SINCE THE CHECK ABOVE, which is the point of using it rather
+ *   than trusting that check: between the two, something else may have written there.
+ *
+ * ⚠ ON WINDOWS THE MODE IS IGNORED and the file inherits the folder's permissions — the same
+ *   limit `credentials.ts` documents, and claiming otherwise would be claiming a guarantee the
+ *   platform does not give.
+ */
+export function writeCodeFile(path, code) {
+    const dir = resolve(path, "..");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        writeFileSync(path, `${code}\n`, { mode: 0o600, flag: "wx" });
+    }
+    catch (error) {
+        // ⛔ THE CAUSE IS NAMED BUT THE CODE IS NOT. `writeFileSync`'s errno line carries the path and
+        //    never the contents, so it is safe to pass on; the code itself appears in no message here.
+        throw new NmtsError(`The NMTS key could not be written to ${path}.`, {
+            exitCode: 1,
+            nextStep: `Nothing was created — the file is written before the account is asked for, so that a ` +
+                `failure here costs nothing. Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+/** `--json` without `--out`: there is nowhere for the code to go that is not the output. */
+export function jsonNeedsAFile() {
+    return new NmtsError("--json needs --out, because the NMTS key will not go into the output.", {
+        exitCode: 2,
+        nextStep: `Nothing was created. Machine-readable output is read by a program and kept by a log, and ` +
+            `your NMTS key is the only key this account will ever have. \`--out ./account-code.txt\` writes ` +
+            `it to a file only you can read; the JSON then names that file. Without --json the NMTS key is ` +
+            `printed on the screen for a person to keep.`,
+    });
+}

package/dist/commands/create-link.d.ts

@@ -0,0 +1,10 @@
+export interface CreateLinkOptions {
+    server: string;
+    network: string;
+    out?: string | undefined;
+    json?: boolean;
+    /** Print the address and stop, instead of waiting for somebody to use it. */
+    noWait?: boolean | undefined;
+    write?: ((line: string) => void) | undefined;
+}
+export declare function createThroughLink(options: CreateLinkOptions): Promise<number>;