@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/commands/key.js

@@ -0,0 +1,249 @@
+// `nmts key new` — make this machine's API key from the NMTS key it already holds.
+//
+// ⛔ WHY IT EXISTS. Setting this tool up took TWO secrets and two places: the NMTS key here,
+//    and a key made at a browser — because the only door that minted one wanted a signed-in
+//    session as well as the code, and signing in goes through a human check no terminal can pass.
+//    So every automated setup began with a person at a screen, and a container that had the code
+//    still could not talk to the server. The server now has a door that takes the code alone, and
+//    this is the command that knocks on it: one secret in, one working machine out.
+//
+// ⛔ THE NMTS KEY IS NEVER AN ARGUMENT, and there is no option here that could carry one. It
+//    comes from where every other command gets it (`code-access.ts`), so a sealed store is opened
+//    the same way and an environment variable asks for the same agreement. What travels is the
+//    derived proof, which is what a sign-in sends and what `account-proof.ts` says is safe to
+//    send — never the code.
+//
+// ⛔ AND THERE IS NO MCP TOOL FOR THIS, DELIBERATELY. A key that could mint keys makes revoking
+//    one meaningless — revoke it and the program has already made three — and the whole reason
+//    the server refuses a key at these doors is that the credential which mints credentials must
+//    be the one a person holds. A tool here would hand that back through the side of the surface
+//    the server closed. Making a key is a person's act, at a command line.
+//
+// ⚠ THE KEY STRING IS PRINTED IN EXACTLY ONE PLACE. By default it is written into this machine's
+//   credentials file and never shown; `--print` puts it on the screen once, for somebody who has
+//   to paste it into another machine. Nothing else here — no confirmation, no error, no --json
+//   without --print — carries it.
+import { identityOf } from "../account.js";
+import { accountProofFor } from "../account-proof.js";
+import { request } from "../api.js";
+import { requireAccountCode } from "../code-access.js";
+import { API_KEY_ENV_VAR, credentialsPath, readCredentialsFile, writeCredentials, } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME, HOME_URL } from "../product.js";
+import { resolveServer } from "../server.js";
+/**
+ * The three permissions a key can carry, by the names the account screen uses for them.
+ *
+ * ⛔ THE BITS ARE THE SERVER'S AND THEY ARE FROZEN. `api/src/domain/api_key.rs` defines 1, 2 and 4
+ *    and the browser mirrors the same three numbers; a fourth would be a new scope, which is a
+ *    decision rather than an addition here.
+ */
+const SCOPE_BITS = {
+    read: 1,
+    write: 2,
+    spend: 4,
+};
+/**
+ * What a key gets when nobody says.
+ *
+ * ⛔ THE SAME DEFAULT THE ACCOUNT SCREEN OFFERS — read only. A default that could write or spend
+ *    would mean the narrowest thing anybody types is wider than the narrowest thing they could
+ *    have asked for, and the screen and this tool would hand out different credentials for the
+ *    same words.
+ */
+const DEFAULT_SCOPES = "read";
+/**
+ * How long a key lasts when nobody says.
+ *
+ * ⚠ A SECOND COPY OF THE SERVER'S `API_KEY_DEFAULT_TTL_SECS` (30 days), and it is a copy because
+ *   there is nowhere to read the real one from: the route that reports the account's limits needs
+ *   a key, and this is the command that does not have one yet. The server still decides the
+ *   ceiling — a longer request is clamped, not refused — so the worst a stale number here does is
+ *   ask for the wrong lifetime, which the reply then states.
+ */
+const DEFAULT_DAYS = 30;
+/**
+ * `nmts key <verb>`.
+ *
+ * ⛔ A VERB AND NOT A BARE COMMAND. Three verbs: `new` mints, `list` shows, `revoke` cuts
+ *    (`key-manage.ts` for the last two). All three present the NMTS key's proof and none is
+ *    reachable with a key — a key cannot cut another key off, and that is what makes revoking
+ *    mean something. `key` with no verb says which ones exist rather than doing one of them, so
+ *    `nmts key` never turns out to have made something.
+ */
+export async function key(verb, args) {
+    if (verb === "list") {
+        const { keyList } = await import("./key-manage.js");
+        return await keyList({ server: args.server, json: args.json });
+    }
+    if (verb === "revoke") {
+        const { keyRevoke } = await import("./key-manage.js");
+        return await keyRevoke(args.operands[1], args, { server: args.server, json: args.json });
+    }
+    if (verb !== "new") {
+        throw new NmtsError(verb === undefined ? `\`${BINARY_NAME} key\` needs a verb.` : `\`${verb}\` is not a key verb.`, {
+            exitCode: 2,
+            nextStep: `The verbs are \`${BINARY_NAME} key new\` (make an API key for this machine from the ` +
+                `NMTS key it already holds), \`${BINARY_NAME} key list\` and ` +
+                `\`${BINARY_NAME} key revoke <id|all>\`. Each needs the NMTS key on this machine; ` +
+                `a key alone cannot list or cut keys.`,
+        });
+    }
+    return await keyNew({
+        server: args.server,
+        network: args.network,
+        scopes: args.scopes,
+        days: args.days,
+        print: args.print,
+        json: args.json,
+    });
+}
+/** Turn `read,write` into the bitmask the server takes, refusing anything it does not define. */
+export function scopeMask(spelled) {
+    const names = spelled
+        .split(",")
+        .map((part) => part.trim().toLowerCase())
+        .filter((part) => part !== "");
+    if (names.length === 0) {
+        throw new NmtsError(`--scopes was given nothing to read.`, {
+            exitCode: 2,
+            nextStep: `Name one or more of: ${Object.keys(SCOPE_BITS).join(", ")}.`,
+        });
+    }
+    let mask = 0;
+    for (const name of names) {
+        const bit = SCOPE_BITS[name];
+        if (bit === undefined) {
+            // ⛔ REFUSED, NOT IGNORED. A misspelt permission that was quietly dropped would make a key
+            //    narrower than the person believes, and they would find out from a refusal days later
+            //    on a machine nobody is watching.
+            throw new NmtsError(`\`${name}\` is not a permission a key can carry.`, {
+                exitCode: 2,
+                nextStep: `The three are: read (see what is stored), write (add and remove files), spend ` +
+                    `(spend credits on storage). A program that uploads needs all three.`,
+            });
+        }
+        mask |= bit;
+    }
+    return mask;
+}
+/** The permission names a bitmask stands for, in the order they are defined. */
+export function scopeNames(mask) {
+    return Object.entries(SCOPE_BITS)
+        .filter(([, bit]) => (mask & bit) !== 0)
+        .map(([name]) => name);
+}
+function wholeDays(given) {
+    if (given === undefined)
+        return DEFAULT_DAYS;
+    if (!/^[0-9]+$/u.test(given.trim())) {
+        throw new NmtsError(`--days takes a whole number of days.`, { exitCode: 2 });
+    }
+    const days = Number(given.trim());
+    if (days < 1)
+        throw new NmtsError(`--days must be at least 1.`, { exitCode: 2 });
+    return days;
+}
+function asIssued(value) {
+    if (!isRecord(value))
+        throw new NmtsError("The server's answer was not an object.");
+    const key = value["key"];
+    const keyId = value["key_id"];
+    const scopes = value["scopes"];
+    const expiresAt = value["expires_at"];
+    if (typeof key !== "string" ||
+        typeof keyId !== "string" ||
+        typeof scopes !== "number" ||
+        typeof expiresAt !== "string") {
+        throw new NmtsError("The server described the new key in a shape this version cannot read.", {
+            // ⛔ IT NAMES NO PART OF THE ANSWER. Whatever came back may contain the key.
+            nextStep: `A key may have been made even though this could not read the reply. Check the account ` +
+                `screen at ${HOME_URL} and revoke anything you did not mean to keep, then update this ` +
+                `tool — \`npm install -g ${BINARY_NAME}\`.`,
+        });
+    }
+    return { key, keyId, scopes, expiresAt };
+}
+export async function keyNew(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const mask = scopeMask(options.scopes ?? DEFAULT_SCOPES);
+    const days = wholeDays(options.days);
+    const held = await requireAccountCode();
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    // ⛔ RESOLVED ONLY WHEN THERE IS SOMEWHERE TO WRITE IT. The network is a property of the stored
+    //    credential and nothing in this request touches the storage network, so demanding to be
+    //    told which one a development server uses — which `resolveNetwork` rightly does — would
+    //    refuse a run that was never going to record the answer.
+    const network = stored === null ? null : resolveNetwork(server, options.network ?? stored.network);
+    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 });
+    const issued = asIssued(await request(server, "/v1/account/api-keys/by-code", {
+        method: "POST",
+        body: {
+            account_id: identity.accountId,
+            auth_secret: authSecret,
+            scopes: mask,
+            lifetime_days: days,
+        },
+        // ⛔ NOT REPEATED ON A TIMEOUT. A request that reached the server and died on the way back
+        //    has already spent one of the two live keys this account may hold, and a retry would
+        //    spend the other — leaving somebody at the cap with two keys they never received.
+        retryBudgetMs: 0,
+    }));
+    // ⛔ THE STORE IS THE ONE THIS TOOL ALREADY HAS, WRITTEN THE ONE WAY IT IS WRITTEN. Whatever
+    //    shape the NMTS key is in — sealed or in the clear — is carried through untouched:
+    //    this command is about the key, and re-deciding how somebody's code is stored on the way
+    //    past is exactly what `login` refuses to do with a key.
+    const canStore = stored !== null;
+    if (stored !== null && network !== null) {
+        writeCredentials({ ...stored, server, network, apiKey: issued.key });
+    }
+    if (options.json === true) {
+        // ⛔ THE KEY IS IN THE JSON ONLY WHEN IT WAS ASKED FOR ON THE SCREEN. A machine-readable
+        //    answer goes into logs and into whatever is driving this; the default must not put a
+        //    credential there because a caller happened to want a parseable reply.
+        const showKey = options.print === true || !canStore;
+        say(JSON.stringify({
+            key_id: issued.keyId,
+            scopes: scopeNames(issued.scopes),
+            expires_at: issued.expiresAt,
+            stored: canStore,
+            ...(showKey ? { key: issued.key } : {}),
+        }));
+        return 0;
+    }
+    say(`Key ${issued.keyId} made for ${server}${network === null ? "" : ` (${network})`}.`);
+    say(`  may       ${scopeNames(issued.scopes).join(", ")}`);
+    say(`  stops     ${issued.expiresAt}`);
+    say(``);
+    if (canStore) {
+        say(`  Stored in ${credentialsPath()}, so every command on this machine now uses it.`);
+        say(`  Whatever key was there before is no longer used; revoke it at ${HOME_URL} if it is`);
+        say(`  running somewhere else.`);
+    }
+    else {
+        say(`  ⛔ NOTHING WAS STORED. This machine keeps no NMTS key file — it came from`);
+        say(`     the environment — so there is nowhere to put the key. It is printed below because`);
+        say(`     this is the only time it exists outside the server's memory.`);
+    }
+    if (options.print === true || !canStore) {
+        say(``);
+        say(`  ⚠ The key is the account's credential. Anyone who reads it can do what it may do,`);
+        say(`    until it is revoked or it stops. It is about to be on this screen and in this`);
+        say(`    terminal's scrollback.`);
+        say(``);
+        // ⛔ ALONE ON ITS OWN LINE, for the reason `whoami --reveal` says: a line with nothing else
+        //    on it is one a person can select without dragging a label into their clipboard.
+        say(issued.key);
+        say(``);
+        say(`  Put it in ${API_KEY_ENV_VAR}, or in a file named by ${API_KEY_ENV_VAR}_FILE — the`);
+        say(`  shape a container cannot leak. NMTS keeps no copy: lose it and the way back is to`);
+        say(`  revoke it and make another.`);
+    }
+    return 0;
+}

package/dist/commands/kit.d.ts

@@ -0,0 +1,11 @@
+export interface KitOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Where to put it: a directory, or the file name to write. Default: this directory. */
+    out?: string | undefined;
+    /** Replace a file that is already there. */
+    force?: boolean;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function kit(options?: KitOptions): Promise<number>;

package/dist/commands/kit.js

@@ -1,6 +1,6 @@
 // `nmts kit` — the recovery kit: one file that is enough to get everything back.
 //
-// ⛔⛔ IT WRITES THE ACCOUNT CODE IN THE CLEAR. That is the format, decided deliberately: the point
+// ⛔⛔ IT WRITES THE NMTS KEY IN THE CLEAR. That is the format, decided deliberately: the point
 //    of the kit is that a person needs ONE thing, not two. So whoever holds this file holds the
 //    account and the wallet, and this command says exactly that at the moment it writes — not in a
 //    manual, not on a website. The moment somebody makes this file is the moment that fact
@@ -8,7 +8,7 @@
 //
 // ⛔ IT WRITES NOWHERE BUT THE PATH THE CALLER NAMED. Nothing is copied into this tool's own
 //    directory, nothing is left in a temporary file, nothing is printed to the terminal. A command
-//    that quietly kept a second copy of an account code would be the worst defect in this program.
+//    that quietly kept a second copy of an NMTS key would be the worst defect in this program.
 //
 // ⛔ AND IT NEVER REPLACES A FILE NOBODY ASKED IT TO REPLACE. A taken name is a refusal unless
 //    `--force` says otherwise — the same rule every other writing command here follows.
@@ -59,7 +59,7 @@ export async function kit(options = {}) {
     if (options.force !== true && existsSync(destination))
         throw alreadyThere(destination);
     try {
-        // ⛔ 0600, AND IT IS NOT A FORMALITY HERE. This file is the account code. On a filesystem that
+        // ⛔ 0600, AND IT IS NOT A FORMALITY HERE. This file is the NMTS key. On a filesystem that
         //    cannot keep the mode, this is still the only protection there is to ask for.
         writeFileSync(destination, file.content, {
             flag: options.force === true ? "w" : "wx",
@@ -84,7 +84,7 @@ export async function kit(options = {}) {
             // ⛔ THE SENTENCE REACHES A READER THAT ONLY PARSES JSON. An agent that hands this file to
             //    somebody has to be able to say what it is, in the same words.
             carries: ["account-code", "recovery-list"],
-            warning: "This file contains the account code in the clear. Anyone who holds it holds the " +
+            warning: "This file contains the NMTS key in the clear. Anyone who holds it holds the " +
                 "account and the wallet.",
             missingFromSource: built.missingFromSource,
         }));
@@ -92,9 +92,9 @@ export async function kit(options = {}) {
     }
     say(`Wrote ${destination}`);
     say(``);
-    say(`  ⛔ This file contains your account code in the clear, together with the recovery list`);
+    say(`  ⛔ This file contains your NMTS key in the clear, together with the recovery list`);
     say(`     for ${built.fileCount} file(s). Anyone who holds it holds this account: every file in`);
-    say(`     it, and the wallet that pays for storage. One account code opens both.`);
+    say(`     it, and the wallet that pays for storage. One NMTS key opens both.`);
     say(``);
     say(`  It was written only where you see it, with permissions 0600, and nowhere else.`);
     say(`  Do not keep it in a folder that syncs or backs up on its own, and do not send it to`);
@@ -130,7 +130,7 @@ function destinationFor(out, filename) {
 function alreadyThere(destination) {
     return new NmtsError(`${destination} is already there.`, {
         exitCode: 4,
-        nextStep: `Nothing was written, and no account code was put anywhere. Pass --out to choose another ` +
+        nextStep: `Nothing was written, and no NMTS key was put anywhere. Pass --out to choose another ` +
             `name, or --force to replace it.`,
     });
 }

package/dist/commands/listfile.d.ts

@@ -0,0 +1,13 @@
+export interface ListFileOptions {
+    /**
+     * Where to write it: a directory, a file name, or `-` for standard output. Default: this
+     * directory, under the name the file describes itself with.
+     */
+    out?: string | undefined;
+    /** Replace a file that is already there. */
+    force?: boolean;
+    write?: (line: string) => void;
+    /** Where the document goes when `--out -` asked for it. */
+    writeDocument?: (text: string) => void;
+}
+export declare function listfile(options?: ListFileOptions): Promise<number>;

package/dist/commands/listfile.js

@@ -12,7 +12,7 @@
 //    which is a fact it can state exactly rather than a promise about the account.
 //
 // ⛔ WHAT THE FILE IS NOT. It is not a recovery on its own. The storage network's addresses are not
-//    in it — those live in the recovery list a browser writes — and neither is the account code,
+//    in it — those live in the recovery list a browser writes — and neither is the NMTS key,
 //    deliberately: this file plus the code IS the account, and keeping both together turns one
 //    theft into a total loss. Both facts are printed, and both are inside the file for whoever
 //    finds it later without this text.
@@ -22,6 +22,7 @@ import { identityOf } from "../account.js";
 import { requireAccountCode } from "../code-access.js";
 import { NmtsError } from "../errors.js";
 import { buildFileListFile } from "../list-file.js";
+import { keptChunks } from "../manifest-chunk-flow.js";
 import { readKeptList } from "../manifest.js";
 import { BINARY_NAME } from "../product.js";
 export async function listfile(options = {}) {
@@ -40,15 +41,21 @@ export async function listfile(options = {}) {
             exitCode: 4,
             nextStep: `Nothing was written. Run \`${BINARY_NAME} ls\` once while this machine can reach the ` +
                 `server: every read of the list keeps its sealed bytes here, and this command writes that ` +
-                `copy out. A copy cannot be made from the account code alone — the list itself is what is ` +
+                `copy out. A copy cannot be made from the NMTS key alone — the list itself is what is ` +
                 `being copied.`,
         });
     }
+    // ⛔ THE PARTS TRAVEL WITH THE INDEX. At format version 2 the kept bytes are an index that names
+    //    chunks; this machine holds those chunks by name beside it, and a copy of the index without
+    //    them is a copy of nothing anybody can use. Null means the kept bytes are a single-blob list,
+    //    which carries its entries itself.
+    const chunks = await keptChunks(resolved.code, identity.accountId, kept.ct);
     const file = buildFileListFile({
         accountId: identity.accountId,
         seq: kept.seq,
         savedAt: kept.savedAt,
         sealed: kept.ct,
+        ...(chunks === null ? {} : { chunks }),
     });
     if (toStdout) {
         emit(file.content);
@@ -95,11 +102,11 @@ function destinationFor(out, filename) {
 function saidWhatItIs(say, seq, savedAt, filename) {
     say(``);
     say(`  File list version ${seq}, as this machine last read it (${savedAt}).`);
-    say(`  It holds the names, folders and file keys of this account, sealed with the account code.`);
+    say(`  It holds the names, folders and file keys of this account, sealed with the NMTS key.`);
     say(``);
     say(`  ⛔ It is not a recovery on its own. It carries no storage-network addresses — those are in`);
-    say(`     the recovery list saved from the account screen — and it does not contain the account`);
-    say(`     code. Keep it somewhere other than the code: together they are the whole account.`);
+    say(`     the recovery list saved from the account screen — and it does not contain the NMTS`);
+    say(`     key. Keep it somewhere other than your NMTS key: together they are the whole account.`);
     say(`  ⚠ A copy goes stale. Run this again after uploading: of two copies, the one whose`);
     say(`    filename carries the higher number supersedes the other (this one is ${filename}).`);
 }

package/dist/commands/login.d.ts

@@ -0,0 +1,18 @@
+export interface LoginOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Store the code in the clear rather than sealed. Behind `unsafe-code-storage`. */
+    plain?: boolean | undefined;
+    /** Store nothing; print the environment variable to set. Behind `plain-env`. */
+    env?: boolean | undefined;
+    /** Injected in tests so the terminal is not involved. */
+    readCode?: (() => Promise<string>) | undefined;
+    /** Injected in tests. Called twice for a new passphrase — the second is the confirmation. */
+    readPassphrase?: ((prompt: string) => Promise<string>) | undefined;
+    /** Injected in tests so the terminal is not involved. An empty answer means "not now". */
+    readApiKey?: (() => Promise<string>) | undefined;
+    /** Injected in tests. Answers the question that replaces a key already on this machine. */
+    confirmKeyReplace?: (() => Promise<string>) | undefined;
+    write?: (line: string) => void;
+}
+export declare function login(options?: LoginOptions): Promise<number>;

package/dist/commands/login.js

@@ -1,4 +1,4 @@
-// `nmts login` — keep an account code on this machine, in one of three shapes.
+// `nmts login` — keep an NMTS key on this machine, in one of three shapes.
 //
 // ⚠ IT DOES NOT CHECK THE CODE WITH THE SERVER, AND IT SAYS SO. The code never goes to the server
 //    at all — it is what opens the files, and nothing on the far end has ever seen it — so there
@@ -53,7 +53,7 @@ export async function login(options = {}) {
     if (options.plain === true && options.env === true) {
         throw new NmtsError("--plain and --env ask for two different things.", {
             exitCode: 2,
-            nextStep: "--plain writes the code to this machine; --env writes nothing and prints it.",
+            nextStep: "--plain writes the NMTS key to this machine; --env writes nothing and prints it.",
         });
     }
     if (existing === null)
@@ -120,12 +120,12 @@ async function readTheCode(options) {
             ? fromFile
             : fromEnv !== undefined && fromEnv.length > 0
                 ? fromEnv
-                : await promptSecret(`Account code (not shown as you type): `, CODE_ENV_VAR);
+                : await promptSecret(`NMTS key (not shown as you type): `, CODE_ENV_VAR);
     if (code.length === 0) {
-        throw new NmtsError("No account code was given.", {
+        throw new NmtsError("No NMTS key was given.", {
             exitCode: 2,
             nextStep: stdinIsATerminal()
-                ? `Run \`${BINARY_NAME} login\` again and paste the code.`
+                ? `Run \`${BINARY_NAME} login\` again and enter your NMTS key.`
                 : `Set ${CODE_ENV_VAR} in the environment.`,
         });
     }
@@ -138,14 +138,14 @@ async function storeSealed(code, server, network, apiKey, options, say) {
     writeCredentials({ lockedCode, server, network, ...(apiKey ? { apiKey } : {}) });
     say(`Sealed for ${server} (${network}) in ${credentialsPath()}`);
     say(``);
-    say(`  What is on disk is not the account code. Opening it needs the passphrase, so a copy of`);
+    say(`  What is on disk is not the NMTS key. Opening it needs the passphrase, so a copy of`);
     say(`  this file — in a backup, a synced folder, a container image, a stolen disk — is worth`);
     say(`  nothing on its own.`);
     say(``);
-    say(`  ⚠ It does NOT protect the code from anything running as you on this machine while you`);
+    say(`  ⚠ It does NOT protect your NMTS key from anything running as you on this machine while you`);
     say(`    are using the tool. Whatever supplies the passphrase can be read the same way.`);
     say(``);
-    say(`  Every command that needs the code will ask for the passphrase, or read it from`);
+    say(`  Every command that needs your NMTS key will ask for the passphrase, or read it from`);
     say(`  ${PASSPHRASE_ENV_VAR}. Opening it costs a fraction of a second and 64 MiB of memory each`);
     say(`  time, on purpose: that is what makes guessing the passphrase expensive.`);
     return 0;
@@ -173,7 +173,7 @@ function storePlain(code, server, network, apiKey, say) {
     if (!private_) {
         say(``);
         say(`  ⛔ This machine did not keep the mode that was asked for, so anybody who can reach that`);
-        say(`     path can read the code. \`${BINARY_NAME} login\` without --plain seals it instead,`);
+        say(`     path can read your NMTS key. \`${BINARY_NAME} login\` without --plain seals it instead,`);
         say(`     and ${CODE_ENV_VAR}_FILE names a file this tool never copies.`);
     }
     return 0;
@@ -181,7 +181,7 @@ function storePlain(code, server, network, apiKey, say) {
 /**
  * Write nothing; print what to set.
  *
- * ⛔ THIS PRINTS THE ACCOUNT CODE, which every other part of this tool refuses to do. It is the
+ * ⛔ THIS PRINTS THE NMTS KEY, which every other part of this tool refuses to do. It is the
  *    one command whose entire purpose is to hand it back, it says so, and it is behind an
  *    agreement that names how an environment variable leaks.
  */
@@ -200,11 +200,11 @@ function printEnvForm(code, say) {
     say(``);
     say(`  Nothing was written to this machine. Paste that where your program's environment is set.`);
     say(``);
-    say(`  ⚠ The code is now on this screen, and probably in this terminal's scrollback. An`);
+    say(`  ⚠ Your NMTS key is now on this screen, and probably in this terminal's scrollback. An`);
     say(`    environment variable is readable by anything running as you, by every child process,`);
     say(`    and — inside a container — by anybody who can run \`docker inspect\`.`);
     say(``);
-    say(`  ${CODE_ENV_VAR}_FILE names a FILE holding the code instead, and has none of those.`);
+    say(`  ${CODE_ENV_VAR}_FILE names a FILE holding the NMTS key instead, and has none of those.`);
     return 0;
 }
 /**
@@ -219,14 +219,14 @@ function printEnvForm(code, say) {
  */
 function sayCheckSymbol(say, keyWasAccepted) {
     say(``);
-    say(`  The code is well-formed — its own check symbol matches. That was verified here, offline.`);
+    say(`  The NMTS key is well-formed — its own check symbol matches. That was verified here, offline.`);
     if (!keyWasAccepted) {
         say(`  Whether the account EXISTS has not been checked: signing in goes through a human check`);
         say(`  this tool cannot pass yet, so that will first show up on a command that needs the server.`);
         return;
     }
-    say(`  ⚠ Whether it is the code for the account the KEY belongs to has not been checked, and`);
-    say(`    cannot be: the code never goes to the server, so nothing can compare the two. A code`);
+    say(`  ⚠ Whether it is the NMTS key for the account the API KEY belongs to has not been checked, and`);
+    say(`    cannot be: an NMTS key never goes to the server, so nothing can compare the two. One`);
     say(`    from a different account looks like an account with nothing in it.`);
 }
 /**
@@ -248,7 +248,7 @@ function sayAboutTheKey(outcome, server, say) {
             say(`No API key is stored, and every command that talks to the server needs one.`);
             say(``);
             say(`  Make one on the account screen at ${HOME_URL}, then run \`${BINARY_NAME} login\` again`);
-            say(`  with it in ${API_KEY_ENV_VAR} — or paste it when this asks. It is checked with the`);
+            say(`  with it in ${API_KEY_ENV_VAR} — or enter it when this asks. It is checked with the`);
             say(`  server before it is written down.`);
             say(``);
             say(`  ${API_KEY_FILE_ENV_VAR} names a FILE holding the key instead, which is the shape a`);
@@ -277,7 +277,7 @@ function sayAboutTheKey(outcome, server, say) {
             say(`⚠ A different API key is in ${keySourceName(outcome.from)}. It was NOT stored.`);
             say(``);
             say(`  The key already on this machine is left as it is. Replacing one is something to say`);
-            say(`  out loud, not something a run about the account code does on the way past — every`);
+            say(`  out loud, not something a run about the NMTS key does on the way past — every`);
             say(`  agent using the old one would stop working at a moment nobody would connect to this.`);
             say(``);
             say(`  While that variable is set, every command uses what it holds anyway: the environment`);
@@ -303,7 +303,7 @@ async function newPassphrase(options) {
         return fromEnv;
     }
     if (ask === undefined && !stdinIsATerminal()) {
-        throw new NmtsError("Sealing the account code needs a passphrase, and there is no terminal.", {
+        throw new NmtsError("Sealing the NMTS key needs a passphrase, and there is no terminal.", {
             exitCode: 2,
             nextStep: [
                 `One of these:`,
@@ -314,7 +314,7 @@ async function newPassphrase(options) {
         });
     }
     const prompt = ask ?? ((q) => promptSecret(q, PASSPHRASE_ENV_VAR));
-    const first = await prompt(`New passphrase for the stored code (not shown as you type): `);
+    const first = await prompt(`New passphrase for the stored NMTS key (not shown as you type): `);
     if (first.length < MIN_PASSPHRASE)
         throw tooShort();
     const again = await prompt(`Type it again: `);

package/dist/commands/logout.d.ts

@@ -0,0 +1 @@
+export declare function logout(write?: (line: string) => void): number;

package/dist/commands/logout.js

@@ -1,4 +1,4 @@
-// `nmts logout` — remove the stored account code from this machine.
+// `nmts logout` — remove the stored NMTS key from this machine.
 //
 // ⚠ WHAT IT DOES NOT DO. It removes a file. It does not end any session on the server, and it
 //    cannot reach a copy of the code that has already been read by something else on this machine.

package/dist/commands/losses.d.ts

@@ -0,0 +1,12 @@
+export interface LossesOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Machine-readable output. The list arm prints the server's own object, unchanged. */
+    json?: boolean;
+    write?: (line: string) => void;
+    /** Ask the chain about ONE listed object now, instead of listing. */
+    recheck?: string | undefined;
+    /** Take ONE line off this account's own drive, instead of listing. */
+    dismiss?: string | undefined;
+}
+export declare function losses(options?: LossesOptions): Promise<number>;