@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/commands/erase.js

@@ -0,0 +1,193 @@
+// `nmts erase <paths>` — erase files for good: the server's record, and this account's key to
+// them in the sealed file list. ⛔ IRREVERSIBLE, and the one act above high besides erasing the
+// account.
+//
+// ⛔ TWO THINGS ARE DESTROYED AND THIS COMMAND ALWAYS DESTROYS THE FIRST. The server row carries
+//    the wrapped key that opens the bytes; the list entry carries this account's own copy. Both
+//    go here. The BYTES on the storage network are a third thing: bought by the wallet, they stay
+//    until their term runs out (burning them is a signed transaction the browser makes); bought
+//    with credits, `--release-storage` asks the server to destroy the treasury's storage under
+//    each file first, which it does on the chain one blob at a time and reports per file.
+//
+// ⛔ THE SERVER GOES FIRST, THE LIST LAST. A row erased before the list entry leaves a file the
+//    person can see and never open; that is the same order the trash keeps, for the same reason.
+//    A release that fails leaves the file whole — nothing is erased behind a failed release.
+//
+// ⛔ THE SENTENCE IS TYPED IN EVERY MODE BUT SKIP-PERMISSIONS, where the tier gate's `--reason`
+//    and `--yes` stand for it — the same rule as `delete-account`, because it is the same tier.
+import { accountProofFor } from "../account-proof.js";
+import { request, ServerError } from "../api.js";
+import { currentMode } from "../autonomy.js";
+import { CONFIRM_SENTENCE } from "./delete-account.js";
+import { buildIndex, fullPathOf, KIND_FILE } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { readFileList } from "../manifest.js";
+import { applyToList, batchTargets } from "../manifest-write.js";
+import { BINARY_NAME } from "../product.js";
+import { promptLine, stdinIsATerminal } from "../prompt.js";
+import { openSession } from "../session.js";
+import { filesUnder } from "./trash.js";
+/** The server takes at most this many ids in one erase (`ERASE_BATCH_MAX`). */
+const BATCH = 200;
+/** The refusal a no-deposit release gets when the balance cannot cover the doubled fee. */
+const FEE_INSUFFICIENT = "DEPOSIT_FEE_INSUFFICIENT";
+export async function erase(paths, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (paths.length === 0) {
+        throw new NmtsError(`\`${BINARY_NAME} erase\` needs the path of at least one thing in the drive.`, {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} ls --all\` prints the paths as this expects them.`,
+        });
+    }
+    const typedFor = options.yes === true && currentMode() === "skip-permissions";
+    const ask = options.readLine ?? promptLine;
+    if (!typedFor && 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: erasing is confirmed by typing a sentence.`,
+        });
+    }
+    const session = await openSession(options);
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    const entries = list.manifest?.entries ?? [];
+    const index = buildIndex(entries);
+    const targets = batchTargets(entries, paths, { includeTrashed: true, nothingHappened: "Nothing was erased." });
+    const files = uniqueById(targets.flatMap((t) => (t.kind === KIND_FILE ? [t] : filesUnder(entries, t.id))));
+    const going = uniqueById([...targets, ...files]);
+    if (files.length === 0) {
+        throw new NmtsError(`Nothing named holds a file; empty folders are removed with \`${BINARY_NAME} rm\`.`, {
+            exitCode: 4,
+        });
+    }
+    say(`This erases ${files.length} file${files.length === 1 ? "" : "s"} for good. It cannot be undone, and not by the trash.`);
+    for (const f of files)
+        say(`  ${fullPathOf(index, f)}`);
+    say(``);
+    say(`  Erased:       the server's record of each file and this account's key to it, and its shares.`);
+    if (options.releaseStorage === true) {
+        say(`  Destroyed:    the storage bought with credits under each file, on the chain, before the erase.`);
+        say(`                Storage bought by the wallet is not touched — it stays until its term ends.`);
+    }
+    else {
+        say(`  Not erased:   the bytes on the storage network. They stay, unreadable, until their term ends;`);
+        say(`                \`--release-storage\` also destroys the storage bought with credits under them.`);
+    }
+    say(`  Not refunded: storage already paid for.`);
+    say(``);
+    const typed = typedFor ? CONFIRM_SENTENCE : (await ask(`Type exactly: ${CONFIRM_SENTENCE}\n> `)).trim();
+    if (typed !== CONFIRM_SENTENCE) {
+        say(`Nothing was erased.`);
+        return 1;
+    }
+    // ⛔ THE PROOF IS BUILT FOR THIS ONE RUN AND NOTHING KEEPS IT.
+    const accountProof = await accountProofFor({ code: session.code, source: session.source });
+    const releases = [];
+    if (options.releaseStorage === true) {
+        for (const f of files) {
+            const path = fullPathOf(index, f);
+            try {
+                const reply = await request(session.server, `/v1/items/${encodeURIComponent(f.id)}/release-storage`, {
+                    method: "POST",
+                    body: {},
+                    token: session.apiKey,
+                    accountProof,
+                });
+                releases.push({ path, refused: null, ...counts(reply), ...fee(reply) });
+            }
+            catch (error) {
+                // ⛔ THE ONE REFUSAL THAT STOPS THE RUN. A file with no deposit pays twice the chain fee
+                //    out of the balance, and a balance that cannot cover it means the release did not
+                //    happen — erasing behind it would destroy the account's key to bytes that are still
+                //    being served and still being paid for. Nothing is erased, and the two numbers say
+                //    exactly how far short the balance is.
+                if (error instanceof ServerError && error.code === FEE_INSUFFICIENT) {
+                    throw new NmtsError(`${path}: releasing its storage costs ${amount(error, "needed_credits")} credits and this ` +
+                        `account has ${amount(error, "balance_credits")}. It has no deposit, so the fee comes out of the balance.`, {
+                        exitCode: 4,
+                        nextStep: `Nothing was erased. Buy credits and run this again, or leave --release-storage off ` +
+                            `to erase the file and let its storage run out on its own.`,
+                    });
+                }
+                // ⚠ "Not ours to destroy" is an answer, not a failure: the storage was bought by the
+                //   wallet, and the erase goes on. A refusal of the KEY or the proof, and anything the
+                //   server could not do, stops the run before a row is touched.
+                if (error instanceof ServerError && error.status !== 401 && error.status !== 403 && error.status < 500) {
+                    releases.push({ path, released: 0, alreadyReleased: 0, failed: 0, feeCredits: 0, fromDeposit: false, refused: error.message });
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    let erased = 0;
+    for (let i = 0; i < files.length; i += BATCH) {
+        const reply = await request(session.server, "/v1/items/erase", {
+            method: "POST",
+            body: { item_ids: files.slice(i, i + BATCH).map((f) => f.id) },
+            token: session.apiKey,
+            accountProof,
+        });
+        erased += typeof reply === "object" && reply !== null && typeof Reflect.get(reply, "erased") === "number"
+            ? Number(Reflect.get(reply, "erased"))
+            : 0;
+    }
+    // ⛔ THE LIST GOES LAST, and re-decided against the list as it is on this attempt: only the
+    //    ids this run erased leave it, whatever another device wrote in between.
+    const ids = new Set(going.map((e) => e.id));
+    const result = await applyToList(session, (current) => {
+        const still = current.filter((e) => ids.has(e.id)).map((e) => e.id);
+        return still.length === 0 ? null : { op: "purge", ids: still };
+    });
+    if (options.json) {
+        say(JSON.stringify({ erased, files: files.map((f) => ({ id: f.id, path: fullPathOf(index, f) })), releases, seq: result.seq }));
+        return 0;
+    }
+    say(`Erased ${erased} file${erased === 1 ? "" : "s"}. Their entries are out of the file list.`);
+    for (const r of releases) {
+        if (r.refused !== null)
+            say(`  ${r.path}: storage not released — ${r.refused}`);
+        else if (r.failed > 0)
+            say(`  ${r.path}: ${r.released} released, ${r.failed} could not be — those bytes are still being served.`);
+        else
+            say(`  ${r.path}: storage released (${r.released} destroyed${r.alreadyReleased > 0 ? `, ${r.alreadyReleased} already gone` : ""}).`);
+        // ⛔ ONLY WHEN THE SERVER NAMED A NUMBER. Every release the new ledger charges costs at least
+        //    one credit, so a zero here is a server that did not say rather than a release that was
+        //    free — and "no credits were charged" is the wrong sentence to invent about money.
+        if (r.refused === null && r.feeCredits > 0)
+            say(`  ${r.path}: ${feeLine(r)}`);
+    }
+    return 0;
+}
+/** What the release cost and where it came from, in one clause. */
+function feeLine(r) {
+    const credits = `${r.feeCredits} credit${r.feeCredits === 1 ? "" : "s"}`;
+    return r.fromDeposit
+        ? `${credits} taken from that file's deposit — nothing came out of the balance`
+        : `${credits} taken from the balance — that file had no deposit, so the fee is doubled`;
+}
+/** The three counts a release answers with, read defensively. */
+function counts(reply) {
+    const n = (name) => {
+        const v = typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
+        return typeof v === "number" ? v : 0;
+    };
+    return { released: n("released"), alreadyReleased: n("already_released"), failed: n("failed") };
+}
+/** What it cost, read the same defensive way. An older server says neither, which reads as 0. */
+function fee(reply) {
+    const at = (name) => typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
+    const charged = at("fee_credits");
+    return {
+        feeCredits: typeof charged === "number" ? charged : 0,
+        fromDeposit: at("from_deposit") === true,
+    };
+}
+/** One credit amount out of a refusal's details, or `?` when the server did not name it. */
+function amount(error, field) {
+    const value = error.details[field];
+    return typeof value === "number" ? String(value) : "?";
+}
+function uniqueById(list) {
+    const seen = new Set();
+    return list.filter((e) => (seen.has(e.id) ? false : (seen.add(e.id), true)));
+}

package/dist/commands/expiring.d.ts

@@ -0,0 +1,19 @@
+import { type EpochClock } from "../expiry.ts";
+export interface ExpiringOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /**
+     * Read the storage network's epoch clock.
+     *
+     * ⚠ A SEAM, NOT AN OPTION: there is no flag for it and no way to supply one from a command line.
+     *   It exists because the alternative is a test that either talks to a real storage network — and
+     *   so cannot be run in an epoch change, on a halted chain, or at all offline — or does not
+     *   exercise the arithmetic that decides what a person is warned about.
+     */
+    readClock?: () => Promise<EpochClock | null>;
+    /** The instant to measure against. Passed in so one run reports one moment. */
+    now?: number;
+}
+export declare function expiring(options?: ExpiringOptions): Promise<number>;

package/dist/commands/extend.d.ts

@@ -0,0 +1,33 @@
+import { type ExtendReads, type SignExtension } from "../extend-plan.ts";
+import type { StandingTipInput } from "../standing-tip.ts";
+export interface ExtendOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** How many of the storage network's epochs to add. Default `DEFAULT_EXTEND_EPOCHS`. */
+    epochs?: string | number | undefined;
+    /** Say what it would cost and stop. ⛔ Nothing is signed and no key is touched. */
+    dryRun?: boolean;
+    /** Extend a file that is not near its deadline. Said out loud because it spends money early. */
+    yes?: boolean;
+    /**
+     * The chain reads.
+     *
+     * ⚠ A SEAM, NOT AN OPTION — no flag reaches it. See `ExtendReads`: a test that talked to a live
+     *   storage network could not run offline and could never be asked to be at its own ceiling.
+     */
+    readChain?: (network: string) => Promise<ExtendReads> | ExtendReads;
+    /**
+     * The signature.
+     *
+     * ⛔ SEPARATE FROM THE READS SO A TEST CAN PROVE THE THING THAT MATTERS: that `--dry-run` and a
+     *    missing agreement both stop before anything reaches this.
+     */
+    sign?: SignExtension;
+    /** The instant to measure against. Passed in so one run reports one moment. */
+    now?: number;
+    /** ⚠ SEAMS, NOT OPTIONS — the standing tip's own read and signature. No flag reaches them. */
+    tip?: Pick<StandingTipInput, "readDonation" | "sign">;
+}
+export declare function extend(target: string | undefined, options?: ExtendOptions): Promise<number>;

package/dist/commands/extend.js

@@ -2,13 +2,13 @@
 //
 // ⛔ THE ONLY COMMAND IN THIS TOOL THAT SIGNS ANYTHING, and the only one that spends from a
 //    WALLET. Every other purchase here is made with credits, which are a promise this service
-//    made; this one moves WAL out of the wallet the account code derives, on a public chain, and
+//    made; this one moves WAL out of the wallet the NMTS key derives, on a public chain, and
 //    nobody — NMTS included — can reverse it. That difference is said out loud, in the output,
 //    before the agreement is asked for.
 //
 // ⛔ IT PRICES BEFORE IT SPENDS, ALWAYS. The reads and the quote are free and happen first, so
 //    `--dry-run` answers with a real number and never reaches the key. Nothing below the quote can
-//    run without `requireConsent("wallet")` having passed.
+//    run without `requireWalletGrant("extend", …)` having passed.
 //
 // ⛔ THE SERVER DOES NOT EXTEND ANYTHING, and this command is shaped by that. `POST
 //    /v1/items/{id}/extended` means "record an extension the device already signed": the storage is
@@ -19,7 +19,7 @@
 // ⛔ AND A FILE THAT IS NOT RUNNING OUT IS NOT EXTENDED BY ACCIDENT. Extending early loses nothing
 //    — epochs are added to what is left — so this is not a refusal on principle; it is a refusal
 //    to spend money on a deadline nobody is near, unless somebody says so with `--yes`.
-import { requireConsent } from "../consent.js";
+import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
 import { request } from "../api.js";
 import { buildIndex, entryAt, fullPathOf, KIND_FILE, normalisePath } from "../drive-paths.js";
 import { NmtsError } from "../errors.js";
@@ -27,9 +27,11 @@ import { daysLeftInWords, daysLeftUntilEpoch, stageOf, } from "../expiry.js";
 import { asExtendPreview, chooseEpochs, headroom, soonestEnd, } from "../extend-plan.js";
 import { isRecord } from "../guards.js";
 import { readFileList } from "../manifest.js";
+import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
 import { openSession } from "../session.js";
-import { coinAmount } from "../wallet.js";
+import { coinAmount, walletAddress } from "../wallet.js";
+import { budgetFacts, describeBudget, readBudget, shortfallNextStep } from "../extend-budget.js";
 export async function extend(target, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     const now = options.now ?? Date.now();
@@ -45,6 +47,8 @@ export async function extend(target, options = {}) {
         throw new NmtsError("This account has no file list, so there is nothing to extend.", { exitCode: 4 });
     }
     const entries = list.manifest.entries;
+    // The standing share is the person's, and it is read from the same sealed list this file came from.
+    const settings = list.manifest.settings;
     const entry = entryAt(entries, normalisePath(target), {
         nothingHappened: "Nothing was signed and nothing was charged.",
     });
@@ -105,6 +109,14 @@ export async function extend(target, options = {}) {
     const frost = await reads.quote(leases, epochs);
     const cohort = Math.max(0, ...preview.targets.map((t) => t.sharedItems));
     const unreachable = preview.treasuryParts + preview.untrackedParts;
+    // What the wallet holds and what the chain would charge — read, never assumed (`extend-budget.ts`).
+    const address = await walletAddress(session.code);
+    const budget = await readBudget(reads, {
+        address,
+        objectIds: preview.targets.map((t) => t.objectId),
+        epochs,
+        priceFrost: frost,
+    });
     const facts = {
         file: path,
         itemId: entry.id,
@@ -121,6 +133,7 @@ export async function extend(target, options = {}) {
         paidFrom: "wallet",
         filesOnTheSameBlobs: cohort,
         partsThatCannotBeExtended: unreachable,
+        ...budgetFacts(budget),
     };
     if (options.dryRun === true) {
         // ⛔ NOTHING BELOW THIS BRANCH RUNS. No key is derived, no agreement is asked for, and the
@@ -130,15 +143,20 @@ export async function extend(target, options = {}) {
             return 0;
         }
         describe(say, facts, cohort, unreachable);
+        describeBudget(say, budget);
         say(``);
+        if (budget.shortfall !== null)
+            say(`  ⚠ ${budget.shortfall} As it stands, it would be refused.`);
         say(`  Nothing was signed and nothing was charged. Run the same command without --dry-run to`);
         say(`  buy it.`);
         if (stage === "later")
             say(`  It is not near its deadline, so buying it also needs --yes.`);
         return 0;
     }
-    if (!options.json)
+    if (!options.json) {
         describe(say, facts, cohort, unreachable);
+        describeBudget(say, budget);
+    }
     // ⛔ ASKED AFTER THE PRICE IS KNOWN AND BEFORE ANYTHING IS SIGNED. Extending early loses nothing,
     //    so this is not a refusal on principle — it is a refusal to spend on a deadline that is not
     //    close, unless somebody says otherwise out loud.
@@ -150,16 +168,26 @@ export async function extend(target, options = {}) {
                 `Add --yes to buy it anyway. \`${BINARY_NAME} expiring\` lists what is actually running out.`,
         });
     }
+    // ⛔ A WALLET KNOWN TO BE SHORT IS REFUSED BEFORE THE AGREEMENT IS ASKED FOR — a person should
+    //    not grant signing in order to be told there is nothing to spend (`extend-budget.ts`).
+    if (budget.shortfall !== null) {
+        throw new NmtsError(budget.shortfall, { exitCode: 4, nextStep: shortfallNextStep(budget) });
+    }
     // ⛔ THE ONE GATE THAT STANDS BETWEEN A PROGRAM AND SOMEBODY'S WALLET. Everything above this line
-    //    is a read; nothing below it can be undone.
-    requireConsent("wallet");
-    const sign = options.sign ?? (await import("../extend-sign.js")).signExtension;
+    //    is a read; nothing below it can be undone. The grant names a scope, runs out, and may carry
+    //    a ceiling — this signature is held against all three (`wallet-grant.ts`).
+    const spend = { walFrost: frost, suiMist: budget.feeMist ?? 0n };
+    requireWalletGrant("extend", spend, new Date(now));
+    const sign = options.sign ?? (await import("../wallet-sign.js")).signExtension;
     const digest = await sign({
         network: session.network,
         code: session.code,
         objectIds: preview.targets.map((t) => t.objectId),
         epochs,
     });
+    // What left the wallet is added to the grant's ledger first — the fee as estimated, since the
+    // amount actually charged is not read back here.
+    recordWalletSpend(spend);
     // From here the storage IS extended. Recording it is bookkeeping, and a failure to record must
     // never be reported as a failure to extend — that reading invites a second run, which pays again.
     let replay = false;
@@ -184,14 +212,25 @@ export async function extend(target, options = {}) {
     }
     if (options.json) {
         say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest, recorded: true, replay }));
-        return 0;
     }
-    say(``);
-    say(`  Extended. The storage now ends at epoch ${newEndEpoch} — ${daysLeftInWords(after)}.`);
-    say(`  Transaction ${digest}`);
-    if (replay) {
-        say(`  The server had already recorded this transaction, so nothing was written twice.`);
+    else {
+        say(``);
+        say(`  Extended. The storage now ends at epoch ${newEndEpoch} — ${daysLeftInWords(after)}.`);
+        say(`  Transaction ${digest}`);
+        if (replay)
+            say(`  The server had already recorded this transaction, so nothing was written twice.`);
     }
+    // ⛔ AFTER THE PAYMENT, NEVER INSIDE IT, and it cannot change the answer above. In --json the
+    //    tip speaks on stderr: stdout carries the machine's one answer and nothing else.
+    await (await import("../standing-tip.js")).standingTipAfter({
+        server: session.server,
+        network: resolveNetwork(session.server, session.network),
+        code: session.code,
+        settings,
+        paidWalFrost: frost,
+        say: options.json === true ? (line) => void process.stderr.write(`${line}\n`) : say,
+        ...(options.tip ?? {}),
+    });
     return 0;
 }
 /** What the numbers say, for a person, in the order somebody deciding needs them. */
@@ -213,7 +252,7 @@ function describe(say, facts, cohort, unreachable) {
     say(``);
     // ⛔ REQUIRED, AND IT COMES BEFORE THE AGREEMENT. Every other purchase in this tool spends
     //    credits; this one spends assets out of a wallet, and nobody can put them back.
-    say(`  This is paid in WAL from the wallet this account code derives — not from credits, which`);
+    say(`  This is paid in WAL from the wallet this NMTS key derives — not from credits, which`);
     say(`  is what every other command in this tool spends. \`${BINARY_NAME} wallet\` shows what is in it.`);
 }
 /** Why a file has nothing to extend, said as the two different things it can be. */

package/dist/commands/get.d.ts

@@ -0,0 +1,18 @@
+import { type ByteDestination } from "../stdout.ts";
+export interface GetOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /**
+     * Where to write it. Defaults to the file's own name, in the working directory.
+     *
+     * `-` means stdout: nothing is written and the bytes go to whatever is reading this program.
+     */
+    out?: string | undefined;
+    /** Overwrite an existing file. Off by default, and saying so is the point. */
+    force?: boolean;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** Where the file's own bytes go when `out` is `-`. Injectable so a test can read them. */
+    stdout?: ByteDestination;
+}
+export declare function get(target: string | undefined, options?: GetOptions): Promise<number>;

package/dist/commands/key-manage.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedArgs } from "../args.ts";
+export interface KeyManageOptions {
+    server?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** Injected in tests: answers the tier gate's y/N. */
+    readLine?: ((question: string) => Promise<string>) | undefined;
+}
+export declare function keyList(options?: KeyManageOptions): Promise<number>;
+/** `nmts key revoke <id|all>`: the refusals, the tier gate's question, then the proof and the cut. */
+export declare function keyRevoke(target: string | undefined, args: ParsedArgs, options?: KeyManageOptions): Promise<number>;

package/dist/commands/key-manage.js

@@ -0,0 +1,162 @@
+// `nmts key list` and `nmts key revoke <id|all>` — the account's keys, seen and cut from a
+// terminal that holds the NMTS key.
+//
+// ⛔ THE CODE, NEVER THE KEY. Both doors here are sessionless and take the NMTS key's derived
+//    proof, exactly as `key new` does (`key.ts`). A key is refused by the server on purpose: a key
+//    that could list keys hands whoever stole it the owner's whole automation inventory, and a
+//    key that could revoke keys could switch every other program off while staying alive. So the
+//    credential this command presents is the one thing a key cannot forge, and the server judges
+//    it the way it judges a sign-in — same lockout, same cost to guess.
+//
+// ⛔ REVOKING IS A MEDIUM ACT (`risk.ts` "key.revoke"): the tier gate asks a person once in mode
+//    default and lets an auto mode through with --yes, because whatever used that key stops the
+//    moment it is cut and there is no way to bring it back — only to make another.
+import { identityOf } from "../account.js";
+import { accountProofFor } from "../account-proof.js";
+import { request, ServerError } from "../api.js";
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { gate } from "../gate.js";
+import { isRecord } from "../guards.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { scopeNames } from "./key.js";
+function asKeys(value) {
+    if (!isRecord(value) || !Array.isArray(value["keys"])) {
+        throw new NmtsError("The server listed the keys in a shape this version cannot read.", {
+            nextStep: `Update this tool — \`npm install -g ${BINARY_NAME}\` — or read them in a browser.`,
+        });
+    }
+    const out = [];
+    for (const row of value["keys"]) {
+        if (!isRecord(row))
+            continue;
+        const id = row["key_id"];
+        const scopes = row["scopes"];
+        const created = row["created_at"];
+        const expires = row["expires_at"];
+        if (typeof id !== "string" || typeof scopes !== "number" || typeof created !== "string")
+            continue;
+        out.push({
+            key_id: id,
+            scopes,
+            created_at: created,
+            expires_at: typeof expires === "string" ? expires : created,
+            last_used_at: typeof row["last_used_at"] === "string" ? row["last_used_at"] : null,
+            revoked_at: typeof row["revoked_at"] === "string" ? row["revoked_at"] : null,
+            uses: typeof row["uses"] === "number" ? row["uses"] : 0,
+        });
+    }
+    return out;
+}
+/** The account named and proven, the way `key new` names and proves it. */
+async function provenAccount() {
+    const held = await requireAccountCode();
+    const identity = await identityOf(held.code);
+    const authSecret = await accountProofFor({ code: held.code, source: held.source });
+    return { account_id: identity.accountId, auth_secret: authSecret };
+}
+export async function keyList(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    const proof = await provenAccount();
+    const keys = asKeys(await request(server, "/v1/account/api-keys/list-by-code", {
+        method: "POST",
+        body: proof,
+        retryBudgetMs: 0,
+    }));
+    // The key string on this machine carries its id after the prefix (`nmts_ak1_<id>_<secret>`),
+    // so the row that is "this one" is known without the secret ever being compared or printed.
+    const mine = stored?.apiKey ?? "";
+    if (options.json === true) {
+        say(JSON.stringify({
+            keys: keys.map((k) => ({
+                key_id: k.key_id,
+                scopes: scopeNames(k.scopes),
+                created_at: k.created_at,
+                expires_at: k.expires_at,
+                last_used_at: k.last_used_at,
+                revoked_at: k.revoked_at,
+                uses: k.uses,
+                this_machine: mine.includes(k.key_id),
+            })),
+        }));
+        return 0;
+    }
+    if (keys.length === 0) {
+        say(`This account has no API keys.`);
+        say(``);
+        say(`  \`${BINARY_NAME} key new\` makes one for this machine from the NMTS key it holds.`);
+        return 0;
+    }
+    const live = keys.filter((k) => k.revoked_at === null);
+    for (const k of keys) {
+        say(`${k.key_id}${mine.includes(k.key_id) ? "  ← this machine" : ""}`);
+        say(`  may         ${scopeNames(k.scopes).join(", ")}`);
+        say(`  made        ${k.created_at}`);
+        if (k.revoked_at !== null) {
+            say(`  revoked     ${k.revoked_at}`);
+        }
+        else {
+            say(`  stops       ${k.expires_at}`);
+        }
+        say(`  last used   ${k.last_used_at ?? "never"}  (${k.uses} ${k.uses === 1 ? "use" : "uses"})`);
+    }
+    say(``);
+    say(`  ${live.length} live of ${keys.length}. The key strings are not here: NMTS keeps no copy of them.`);
+    say(`  \`${BINARY_NAME} key revoke <id>\` (or \`all\`) cuts one — whatever uses it stops at once.`);
+    return 0;
+}
+/** `nmts key revoke <id|all>`: the refusals, the tier gate's question, then the proof and the cut. */
+export async function keyRevoke(target, args, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const wanted = (target ?? "").trim();
+    if (wanted === "") {
+        throw new NmtsError(`\`${BINARY_NAME} key revoke\` needs a key id, or \`all\`.`, {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} key list\` shows the ids.`,
+        });
+    }
+    await gate("key.revoke", args, { write: say, readLine: options.readLine });
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    const proof = await provenAccount();
+    const all = wanted === "all";
+    let answered;
+    try {
+        answered = await request(server, "/v1/account/api-keys/revoke-by-code", {
+            method: "POST",
+            body: all ? proof : { ...proof, key_id: wanted },
+            retryBudgetMs: 0,
+        });
+    }
+    catch (error) {
+        if (error instanceof ServerError && error.status === 404) {
+            throw new NmtsError(`No live key ${wanted} on this account.`, {
+                exitCode: 1,
+                nextStep: `\`${BINARY_NAME} key list\` shows the ids that exist and which are already revoked.`,
+            });
+        }
+        throw error;
+    }
+    const revoked = isRecord(answered) && typeof answered["revoked"] === "number" ? answered["revoked"] : null;
+    if (options.json === true) {
+        say(JSON.stringify({ revoked: revoked ?? (all ? null : 1) }));
+        return 0;
+    }
+    if (all) {
+        say(revoked === null ? `Revoked every key.` : `Revoked ${revoked} key${revoked === 1 ? "" : "s"}.`);
+    }
+    else {
+        say(`Revoked key ${wanted}.`);
+    }
+    const mine = stored?.apiKey ?? "";
+    if (all || mine.includes(wanted)) {
+        say(``);
+        say(`  The key stored on this machine was among them, so commands that need a key will be`);
+        say(`  refused until \`${BINARY_NAME} key new\` makes another.`);
+    }
+    return 0;
+}

package/dist/commands/key.d.ts

@@ -0,0 +1,28 @@
+import type { ParsedArgs } from "../args.ts";
+export interface KeyOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Comma-separated permission names: read, write, spend. */
+    scopes?: string | undefined;
+    /** How many days the key should last. The server clamps at its own ceiling. */
+    days?: string | undefined;
+    /** Put the key string on the screen as well. A person's act — see the header. */
+    print?: boolean;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+/**
+ * `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 declare function key(verb: string | undefined, args: ParsedArgs): Promise<number>;
+/** Turn `read,write` into the bitmask the server takes, refusing anything it does not define. */
+export declare function scopeMask(spelled: string): number;
+/** The permission names a bitmask stands for, in the order they are defined. */
+export declare function scopeNames(mask: number): string[];
+export declare function keyNew(options?: KeyOptions): Promise<number>;