@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/commands/put.js

@@ -1,6 +1,8 @@
-// `nmts put <file>` — one file in, sealed on this machine, paid for with credits.
+// `nmts put <file>` — one file in, sealed on this machine, paid for with credits — or, with
+// `--pay wallet`, paid for by the person's own wallet (`put-wallet.ts`, which this file hands off
+// to before anything is read or priced).
 //
-// ⛔ THE ONLY COMMAND IN THIS TOOL THAT SPENDS. Everything about it is arranged so that is never a
+// ⛔ THE COMMAND THAT SPENDS CREDITS. Everything about it is arranged so that is never a
 //   surprise: `--dry-run` says the price without paying it, the price is printed before the work
 //   starts, and a failure says whether the money already moved. The machinery that keeps a half
 //   finished upload from becoming money that bought nothing is in `upload.ts`.
@@ -13,14 +15,14 @@ import { identityOf } from "../account.js";
 import { requireAccountCode } from "../code-access.js";
 import { API_KEY_ENV_VAR, CODE_ENV_VAR, readCredentialsFile, resolveApiKey } from "../credentials.js";
 import { parseAsked } from "../collision.js";
-import { requireConsent } from "../consent.js";
+import { depositDefaultOf, depositLines, parseDeposit, refuseDepositWithWallet } from "../deposit.js";
 import { DERIVED, loadCrypto } from "../crypto.js";
 import { buildIndex, fullPathOf, isLive, KIND_FOLDER, normalisePath } from "../drive-paths.js";
 import { NmtsError } from "../errors.js";
 import { Progress, silentSink, stderrSink } from "../progress.js";
 import { setTrashed } from "../item-trash.js";
 import { addEntry } from "../manifest-write.js";
-import { readFileList } from "../manifest.js";
+import { paddingRuleOf, readFileList } from "../manifest.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
 import { resolveServer } from "../server.js";
@@ -29,6 +31,32 @@ import { createUploadApi } from "../upload-api.js";
 import { fileSource, partKeysOf, uploadFile } from "../upload-file.js";
 import { CREDIT_BYTES, creditsFor, measureLocal, partSizeFor, planAndPrice, UPLOAD_EPOCHS, } from "../upload-price.js";
 import { createBlobProtocol, readCurrentEpoch } from "../walrus-write.js";
+/** Who pays, or a refusal for a payer this tool does not know. */
+export function payerOf(pay) {
+    if (pay === undefined || pay === "credits")
+        return "credits";
+    if (pay === "wallet")
+        return "wallet";
+    throw new NmtsError(`--pay takes credits or wallet, not "${pay}".`, {
+        exitCode: 2,
+        nextStep: `Nothing was sent. --pay wallet buys the storage from the wallet this NMTS key derives; without it credits pay.`,
+    });
+}
+/** The two options that only mean something when the wallet pays, refused when it does not. */
+export function refuseWalletOnlyOptions(options) {
+    if (options.epochs !== undefined) {
+        throw new NmtsError("--epochs only applies with --pay wallet: one credit buys a fixed term.", {
+            exitCode: 2,
+            nextStep: `Nothing was sent. Add --pay wallet to choose the term, or leave --epochs off to pay with credits.`,
+        });
+    }
+    if (options.storage !== undefined) {
+        throw new NmtsError("--storage only applies with --pay wallet: credits buy storage from the treasury.", {
+            exitCode: 2,
+            nextStep: `Nothing was sent. Add --pay wallet to use a storage resource this wallet holds.`,
+        });
+    }
+}
 /**
  * The folder id `--to` names, or null for the root. Refuses rather than guessing.
  *
@@ -61,6 +89,16 @@ export function folderIdFor(wanted, entries) {
     return folder.id;
 }
 export async function put(target, options = {}) {
+    // ⛔ DECIDED BEFORE ANYTHING IS READ. The wallet path prices in WAL and signs; nothing below this
+    //    line knows how to do either, and it must not learn.
+    if (payerOf(options.pay) === "wallet") {
+        refuseDepositWithWallet(options.deposit);
+        return (await import("./put-wallet.js")).putWithWallet(target, options);
+    }
+    refuseWalletOnlyOptions(options);
+    // ⛔ BEFORE THE FILE IS EVEN MEASURED. A deposit outside the range is a command line to fix, and
+    //    a typo that surfaced after the upload would have cost real money to produce.
+    const askedDeposit = parseDeposit(options.deposit);
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     if (target === undefined || target === "") {
         throw new NmtsError("Say which file to put.", {
@@ -101,7 +139,10 @@ export async function put(target, options = {}) {
     //    would have cost real money to produce a message about a typo.
     const asked = parseAsked(options.onCollision);
     const list = await readFileList(server, key.key, resolved.code, identity.accountId);
-    const rule = list.manifest?.settings?.paddingMode === "pow2" ? "pow2" : "padme";
+    const rule = paddingRuleOf(list.manifest?.settings);
+    // The flag if it was given, otherwise the account's own default. Always a number, never left to
+    // the server to pick: the price printed below names it, and a server default could differ.
+    const deposit = askedDeposit ?? depositDefaultOf(list.manifest?.settings);
     // ⛔ THE PRICE IS ARITHMETIC, NOT A MEASUREMENT: quoting it by sealing would mean reading and
     //    encrypting a very large file to answer `--dry-run`. Every part rounds up to a whole credit
     //    on its own, exactly as the server charges each reservation, so a file in several parts is
@@ -122,11 +163,14 @@ export async function put(target, options = {}) {
                 parts: plan.length,
                 partSize,
                 credits,
+                deposit,
                 epochs: UPLOAD_EPOCHS,
             }));
             return 0;
         }
         say(`${name}  ${size} bytes  →  ${credits} credit${credits === 1 ? "" : "s"}`);
+        for (const line of depositLines(deposit))
+            say(line);
         if (plan.length > 1)
             say(`  in ${plan.length} parts of up to ${partSize} bytes`);
         say(``);
@@ -137,7 +181,6 @@ export async function put(target, options = {}) {
     // ⛔ ASKED AFTER THE PRICE IS KNOWN AND BEFORE ANYTHING LEAVES. Working the price out is local
     //    and free, so doing it first costs nothing and lets the refusal name a real number instead
     //    of a warning about spending in general. `--dry-run` returns above this line and never asks.
-    requireConsent("spend");
     // ⛔ Resolved from the list read above — which happened BEFORE the money moves, so a rolled-back
     //    or forked list stops the upload rather than being discovered after it is paid for.
     const parentId = folderIdFor(options.to, list.manifest?.entries ?? []);
@@ -148,6 +191,8 @@ export async function put(target, options = {}) {
     const currentEpoch = await readCurrentEpoch(network);
     if (!options.json) {
         say(`${name}  ${size} bytes  →  ${credits} credit${credits === 1 ? "" : "s"}`);
+        for (const line of depositLines(deposit))
+            say(line);
         if (plan.length > 1) {
             say(`  in ${plan.length} parts — each one is bought separately and can be finished later`);
         }
@@ -199,6 +244,7 @@ export async function put(target, options = {}) {
             currentEpoch,
             partSize,
             padding: { rule, unitBytes: CREDIT_BYTES },
+            depositCredits: deposit,
             onStep,
         });
     }
@@ -256,6 +302,7 @@ export async function put(target, options = {}) {
             sealedBytes,
             parts: plan.length,
             credits: result.resumed ? 0 : credits,
+            deposit,
             resumed: result.resumed,
             renamed: added.name !== name,
             ...(added.replaced ? { replacedIntoTrash: added.replaced.id } : {}),

package/dist/commands/rebuild.d.ts

@@ -0,0 +1,18 @@
+import type { PairVerdict } from "../shared/lib/drive/rebuild-verify.ts";
+import type { SourceItem } from "../rebuild.ts";
+export interface RebuildOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    /** Write the rebuilt list. Without this the run reports and writes nothing. */
+    yes?: boolean;
+    /** Rebuild even though this machine has seen a file list for this account before. */
+    force?: boolean;
+    write?: (line: string) => void;
+    /**
+     * The key check, injected. Absent = the real one, which reads 72 bytes of each file's first
+     * stored part from the storage network (`rebuild-key-check.ts`).
+     */
+    verify?: (item: SourceItem) => Promise<PairVerdict>;
+}
+export declare function rebuild(options?: RebuildOptions): Promise<number>;

package/dist/commands/rebuild.js

@@ -19,12 +19,21 @@
 //        exists — so a list that appears while this runs comes back as a refusal rather than as a
 //        replacement.
 //
+// ⛔ AND IT DOES NOT SEAL A PAIRING IT HAS NOT CHECKED. Every key the server hands back is tried
+//    against its own row's first sealed part before the list is written; a key that does not open
+//    its file is left off the entry and reported by id. Only an account where NOT ONE key opened
+//    is a failure — that is a wrong key set, and going ahead would seal a list that opens nothing.
+//    One file whose aggregator was down is not that, and refusing the whole rebuild over it would
+//    leave somebody with no list at all.
+//
 // ⚠ A THIRD CASE IS NOT A MISSING LIST AT ALL: this machine has a record of a list for this
 //   account and the server now says there is none. That is a list that WENT missing — the shape a
 //   server would take to make a device throw away its real names — so it stops, and `--force` is
 //   how somebody who knows their list was genuinely lost goes ahead anyway.
+import { loadCrypto } from "../crypto.js";
 import { NmtsError } from "../errors.js";
 import { createFirstList } from "../manifest-create.js";
+import { accountKeyCheck } from "../rebuild-key-check.js";
 import { readFileList } from "../manifest.js";
 import { BINARY_NAME } from "../product.js";
 import { rebuildFromServer } from "../rebuild.js";
@@ -37,6 +46,8 @@ function summary(built, wrote, extra = {}) {
         live: built.live,
         trashed: built.trashed,
         keyless: built.keyless,
+        verified: built.verified,
+        unverified: built.unverified.map((u) => ({ id: u.id, reason: u.reason })),
         unaccounted: built.unaccounted,
         namesRecovered: false,
         foldersRecovered: false,
@@ -70,16 +81,45 @@ export async function rebuild(options = {}) {
     //   enough to show movement and rare enough not to bury what comes after it. The machine-readable
     //   run stays silent: its output is one object, and a progress line on that stream would break it.
     let announced = 0;
-    const built = await rebuildFromServer({
-        server: session.server,
-        apiKey: session.apiKey,
-        onProgress: (read) => {
-            if (options.json === true || read < announced + 1000)
-                return;
-            announced = read;
-            say(`  read ${read} stored files so far...`);
-        },
-    });
+    // ⛔ THE CHECKER HOLDS THIS ACCOUNT'S DATA KEY until `done()`, so every path out of the read —
+    //    including a refusal from the listing — has to reach it.
+    let checker = null;
+    let verify = options.verify;
+    if (verify === undefined) {
+        const real = accountKeyCheck({
+            server: session.server,
+            apiKey: session.apiKey,
+            accountCode: session.code,
+            chain: session.network,
+            crypt: await loadCrypto(),
+        });
+        checker = real;
+        verify = (item) => real.check(item);
+    }
+    let built;
+    try {
+        let checkedAnnounced = 0;
+        built = await rebuildFromServer({
+            server: session.server,
+            apiKey: session.apiKey,
+            verify,
+            onProgress: (read) => {
+                if (options.json === true || read < announced + 1000)
+                    return;
+                announced = read;
+                say(`  read ${read} stored files so far...`);
+            },
+            onVerifyProgress: (checked, total) => {
+                if (options.json === true || checked < checkedAnnounced + 1000)
+                    return;
+                checkedAnnounced = checked;
+                say(`  checked ${checked} of ${total} keys against their own files...`);
+            },
+        });
+    }
+    finally {
+        checker?.done();
+    }
     if (built.entries.length === 0) {
         if (options.json) {
             say(summary(built, false));
@@ -89,6 +129,17 @@ export async function rebuild(options = {}) {
         say(`There is nothing to rebuild from. Nothing was changed.`);
         return 0;
     }
+    // ⛔ NOT ONE KEY OPENED ITS OWN FILE, and at least one row had a key to try. That is not a bad
+    //    afternoon on the network — it is a key set that belongs to something else, and sealing it
+    //    would put a list on the server whose every entry names bytes it cannot open.
+    if (built.verified === 0 && built.keyless < built.entries.length) {
+        throw new NmtsError(`Not one of this account's keys opened the file it was filed beside.`, {
+            exitCode: 4,
+            nextStep: `Nothing was changed. Either this is not this account's NMTS key, or the storage network could ` +
+                `not be reached at all — ${describeReasons(built)}. A list sealed from these pairs would ` +
+                `name every file and open none of them.`,
+        });
+    }
     if (options.yes !== true) {
         if (options.json) {
             say(summary(built, false));
@@ -111,6 +162,7 @@ export async function rebuild(options = {}) {
     say(`  Every file is at the top of the drive under a placeholder name — the server had no name,`);
     say(`  no folder and no placement to give back.`);
     say(`  \`${BINARY_NAME} ls\` shows them; \`${BINARY_NAME} rename\` and \`${BINARY_NAME} mv\` put them back.`);
+    reportKeys(say, built);
     reportGaps(say, built);
     return 0;
 }
@@ -133,8 +185,54 @@ function describe(say, built) {
     say(``);
     say(`  None of that is a fault: the server was built not to know it. It keeps a row per stored`);
     say(`  file and the key that opens it, and nothing about what the file is called.`);
+    reportKeys(say, built);
     reportGaps(say, built);
 }
+/**
+ * Which keys were shown to open their own file, and which were not.
+ *
+ * ⛔ THE UNVERIFIED ONES ARE NAMED, one line each. A count alone would say "some of your files came
+ *    back without a key" and leave nobody able to act on it; the id is what `nmts ls` shows and
+ *    what a second run can be compared against.
+ */
+function reportKeys(say, built) {
+    const checked = built.entries.length - built.keyless;
+    if (checked === 0)
+        return;
+    say(``);
+    const notVerified = countUnverified(built);
+    say(`  Keys checked against their own files: ${built.verified} verified, ${notVerified} not.`);
+    if (notVerified === 0)
+        return;
+    say(`  A file whose key was not verified keeps its entry and no key — nothing else on this side`);
+    say(`  can say that key belongs to that file, and a wrong pairing would be sealed for good.`);
+    for (const one of built.unverified) {
+        if (one.reason === "no-key")
+            continue;
+        say(`    ${one.id}  ${WHY[one.reason]}`);
+    }
+}
+/** How many pairs were left unverified, not counting rows that never had a key to check. */
+function countUnverified(built) {
+    return built.unverified.filter((u) => u.reason !== "no-key").length;
+}
+/** One plain line per reason a pair was not shown to belong together. */
+const WHY = {
+    "no-key": "the server holds no key for it",
+    "no-parts": "the server names no stored bytes for it",
+    unreadable: "its stored bytes could not be read, so the key could not be tried",
+    "wrong-key": "this key does not open this file",
+};
+/** The reasons behind a wholly unverified account, most common first, for the refusal's next step. */
+function describeReasons(built) {
+    const counts = new Map();
+    for (const one of built.unverified)
+        counts.set(one.reason, (counts.get(one.reason) ?? 0) + 1);
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([reason, n]) => `${n} × ${WHY[reason]}`)
+        .join(", ");
+}
 /** The parts of the account this rebuild could not account for. Printed on both paths. */
 function reportGaps(say, built) {
     if (built.keyless > 0) {

package/dist/commands/receive.d.ts

@@ -0,0 +1,24 @@
+import { type ByteDestination } from "../stdout.ts";
+export interface ReceiveOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Where to write it. Defaults to the name the sender gave it, in the working directory. */
+    out?: string | undefined;
+    /**
+     * A DIRECTORY to write into, keeping the sender's name — for callers that must not let a name
+     * from somewhere else choose a path.
+     *
+     * ⛔ IT IS NOT `out` WITH A SLASH. `out` is a full path the caller picked; this one says "the
+     *    name is theirs, the place is mine", and the name is reduced to its last segment and checked
+     *    against this directory before anything opens. A sender who calls their file
+     *    `../../.ssh/authorized_keys` has picked a legal name for a file and must not thereby pick a
+     *    path on somebody else's disk. Ignored when `out` is given.
+     */
+    intoDir?: string | undefined;
+    force?: boolean;
+    /** Where the bytes go when `--out -` was given. Injected so a test can read them. */
+    stdout?: ByteDestination;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function receive(id: string | undefined, options?: ReceiveOptions): Promise<number>;

package/dist/commands/recovery-dispatch.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "../args.ts";
+export declare function runRecovery(command: string, args: ParsedArgs): Promise<number>;

package/dist/commands/recovery-dispatch.js

@@ -0,0 +1,34 @@
+// The recovery verbs (recovery · recovery-list · kit), dispatched here rather than in `main.ts`.
+//
+// ⛔ WHY A SECOND SWITCH. `main.ts` is measured (`check:size`) and had no room for `nmts support`;
+//    this block shares a file and an option shape, so it moved as one piece with its comments.
+export async function runRecovery(command, args) {
+    switch (command) {
+        case "recovery": {
+            const { recovery } = await import("./recovery.js");
+            return await recovery({ out: args.out, force: args.force, json: args.json });
+        }
+        case "recovery-list": {
+            const { recoveryList } = await import("./recovery-list.js");
+            return await recoveryList({
+                server: args.server,
+                network: args.network,
+                out: args.out,
+                force: args.force,
+                json: args.json,
+            });
+        }
+        case "kit": {
+            const { kit } = await import("./kit.js");
+            return await kit({
+                server: args.server,
+                network: args.network,
+                out: args.out,
+                force: args.force,
+                json: args.json,
+            });
+        }
+        default:
+            throw new Error(`not a recovery verb: ${command}`);
+    }
+}

package/dist/commands/recovery-list.d.ts

@@ -0,0 +1,11 @@
+export interface RecoveryListOptions {
+    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. Off by default, and saying so is the point. */
+    force?: boolean;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function recoveryList(options?: RecoveryListOptions): Promise<number>;

package/dist/commands/recovery-list.js

@@ -1,16 +1,16 @@
 // `nmts recovery-list` — writing the account's recovery list out as a file.
 //
-// ⛔ WHY IT EXISTS. The recovery list is the answer to "NMTS is gone and I still have my account
-//    code": it holds, encrypted, where every file's bytes are on the public storage network, and
+// ⛔ WHY IT EXISTS. The recovery list is the answer to "NMTS is gone and I still have my NMTS
+//    key": it holds, encrypted, where every file's bytes are on the public storage network, and
 //    the key that opens each of them. The account screen has always been able to write one. An
 //    account used only from a terminal could not, so the artefact that exists for the day this
 //    service is not there did not exist for those accounts at all.
 //
 // ⛔ IT IS NOT THE FILE-LIST COPY, AND NEITHER REPLACES THE OTHER. `nmts listfile` writes the names
 //    and keys this machine has seen; this one writes the storage addresses, which that file has
-//    none of. Keep both, and keep both somewhere other than the account code.
+//    none of. Keep both, and keep both somewhere other than the NMTS key.
 //
-// ⛔ THE ACCOUNT CODE IS NOT IN THE FILE. This file plus the code is the account, so keeping them
+// ⛔ THE NMTS KEY IS NOT IN THE FILE. This file plus the code is the account, so keeping them
 //    together turns one theft into a total loss. The artefact that deliberately carries both is
 //    `nmts kit`, and it says so about itself.
 //
@@ -67,7 +67,7 @@ export async function recoveryList(options = {}) {
     say(``);
     say(`  Recovery list ${seq} — ${built.fileCount} files, ${built.totalBytes} bytes described.`);
     say(`  It holds where each file's bytes are on the storage network, and the key that opens`);
-    say(`  each one, sealed with the account code.`);
+    say(`  each one, sealed with the NMTS key.`);
     say(``);
     say(`  Recorded with the server: version ${seq}, kept on this machine (no storage-network`);
     say(`  copy), read from the account at ${assembled.capturedAt}.`);
@@ -78,7 +78,7 @@ export async function recoveryList(options = {}) {
         say(`    this. Nothing here is covered for them.`);
     }
     say(``);
-    say(`  ⛔ It does not contain the account code. Keep it somewhere other than the code: together`);
+    say(`  ⛔ It does not contain the NMTS key. Keep it somewhere other than your NMTS key: together`);
     say(`     they are the whole account.`);
     say(`  ⚠ A list goes stale. Run this again after uploading: of two files, the one whose filename`);
     say(`    carries the higher number supersedes the other.`);

package/dist/commands/recovery.d.ts

@@ -0,0 +1,25 @@
+export interface RecoveryOptions {
+    /** Where to put it: a directory, or the file name to write. Default: the working directory. */
+    out?: string | undefined;
+    /** Replace a file that is already there. Off by default, and saying so is the point. */
+    force?: boolean;
+    json?: boolean;
+    write?: (line: string) => void;
+    /**
+     * Where the program is published.
+     *
+     * ⚠ Overridable so a test can drive the whole download against a server on this machine. There
+     *   is no command-line option for it: this is not somewhere a person should be talked into
+     *   pointing an executable download.
+     */
+    source?: string | undefined;
+    /**
+     * What machine to fetch for.
+     *
+     * ⚠ Overridable so the refusal a machine with no published executable gets can be tested on a
+     *   machine that has one. Defaults to what this process is running on.
+     */
+    platform?: string;
+    arch?: string;
+}
+export declare function recovery(options?: RecoveryOptions): Promise<number>;

package/dist/commands/recovery.js

@@ -1,7 +1,7 @@
 // `nmts recovery` — fetching the standalone recovery program, checked, into a file you name.
 //
 // ⛔ WHY IT EXISTS. The recovery program is the answer to "NMTS is gone and I still have my
-//    account code": it reads files back off the public storage network on its own, talking to no
+//    NMTS key": it reads files back off the public storage network on its own, talking to no
 //    NMTS server. Until its release workflow existed, getting it meant installing a Rust toolchain
 //    and building it — a fair ask of somebody auditing it, an unfair one of somebody who has just
 //    lost access to their files, and an impossible one for an agent working in a terminal.
@@ -25,7 +25,7 @@
 //    who runs this has to be the person who decided to have it.
 //
 // ⚠ WHAT IT ASKS OF THE NETWORK IS NOT THE NMTS API. It talks to the source-hosting site the
-//   recovery program is published on, and to nothing else; no account code, no API key and no
+//   recovery program is published on, and to nothing else; no NMTS key, no API key and no
 //   session is involved, and the command works signed out.
 import { createHash } from "node:crypto";
 import { chmodSync, existsSync, rmSync, statSync, writeFileSync } from "node:fs";

package/dist/commands/rollback.d.ts

@@ -0,0 +1,9 @@
+export interface RollbackOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    /** Go ahead and write it back. Without this the run reports and changes nothing. */
+    yes?: boolean;
+    write?: (line: string) => void;
+}
+export declare function rollback(options?: RollbackOptions): Promise<number>;

package/dist/commands/rollback.js

@@ -0,0 +1,118 @@
+// `nmts rollback` — putting the version of the file list that came before back as the current one.
+//
+// ⛔ IT EXISTS FOR ONE SITUATION: the current list will not open, or opens as something that is
+//    not this account's drive. A list that cannot be opened presents a full account as an empty
+//    one, and the natural response to an empty account is to upload everything a second time. The
+//    server retains the version each write replaced for exactly that day.
+//
+// ⛔ IT DOES NOT READ THE CURRENT LIST, AND THAT IS THE POINT. Every other command here opens the
+//    sealed blob before it does anything; this one moves bytes the server is holding from one
+//    place to another. A rollback that refused because the current list would not open would
+//    refuse in the only case it is for.
+//    ⚠ It does open the OLDER one, far enough to read the names of the chunks it is made of and no
+//      further (`namedChunks`). Bytes that will not open answer "no chunks", which is exactly the
+//      request this command has always made — so nothing it used to handle is refused now.
+//
+// ⛔ WHAT IT COSTS: the newer version's additions leave the list. The BYTES are untouched — the
+//    server still holds every row, the storage is still bought, and `nmts rebuild` finds files no
+//    list names — but a name, a folder and the key that opens a file live in the list and nowhere
+//    else, so a file added after the version being restored comes back nameless or not at all.
+//
+// ⛔ SO IT IS A PERSON'S ACT, IN EVERY MODE. This is not a decision about spending or about risk
+//    that a person can hand to an agent in advance: it is a judgement that the drive somebody can
+//    see is wrong, and nothing an unattended program reads can tell it that. There is no MCP tool
+//    either, so this is the only door and it is shut from both sides.
+import { request } from "../api.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { namedChunks } from "../manifest-chunk-flow.js";
+import { recordWrittenList } from "../manifest.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+function asVersion(value) {
+    if (!isRecord(value)) {
+        throw new NmtsError("The server's answer was not an object.", {
+            nextStep: "Nothing was changed.",
+        });
+    }
+    if (value["state"] === "absent")
+        return { state: "absent" };
+    if (value["state"] === "present" && typeof value["seq"] === "number" && typeof value["ct"] === "string") {
+        return { state: "present", seq: value["seq"], ct: value["ct"] };
+    }
+    throw new NmtsError("The server answered with a file list this version cannot read.", {
+        nextStep: "Nothing was changed. A newer version of this tool may understand it.",
+    });
+}
+/** The one refusal for "there is nothing to go back to", whichever half of the pair is missing. */
+function nothingRetained() {
+    return new NmtsError("The server holds no previous version of the file list.", {
+        exitCode: 4,
+        nextStep: `Nothing was changed. \`${BINARY_NAME} rebuild\` builds a list from the server's rows when ` +
+            `there is no list to go back to.`,
+    });
+}
+export async function rollback(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const session = await openSession({ server: options.server, network: options.network });
+    const previous = asVersion(await request(session.server, "/v1/manifest/previous", { token: session.apiKey }));
+    if (previous.state === "absent")
+        throw nothingRetained();
+    const current = asVersion(await request(session.server, "/v1/manifest", { token: session.apiKey }));
+    // A current list with nothing before it is the same answer in different words: there is no
+    // version this one replaced, so there is nothing to put back.
+    if (current.state === "absent")
+        throw nothingRetained();
+    if (options.yes !== true) {
+        // ⛔ THE UNCONFIRMED ANSWER SAYS WHAT WOULD HAPPEN IN ITS OWN WORDS, never in the words the
+        //    finished act uses. A caller that read `restored_seq` off a run that changed nothing would
+        //    report a rollback that never happened.
+        if (options.json === true) {
+            say(JSON.stringify({ previous_seq: previous.seq, current_seq: current.seq, changed: false }));
+            return 5;
+        }
+        say(`Version ${previous.seq} of the file list would go back as the current one, over version ` +
+            `${current.seq}.`);
+        say(``);
+        say(`⛔ What version ${current.seq} added is out of the list afterwards: a file's name, the`);
+        say(`   folder it sits in and the key that opens it live in the list and nowhere else. The`);
+        say(`   bytes are not touched — the storage stays bought — and \`${BINARY_NAME} rebuild\` finds`);
+        say(`   files the list does not name.`);
+        say(``);
+        say(`Nothing was changed. To go ahead:  ${BINARY_NAME} rollback --yes`);
+        say(`⛔ If a program is reading this on somebody's behalf: show it to them and let them decide.`);
+        return 5;
+    }
+    // ⛔ THE OLDER INDEX'S CHUNKS ARE NAMED AGAIN, and nothing is uploaded. At format version 2 the
+    //    entries live in chunks the index names by hash; the server frees a chunk no current or
+    //    retained index names, so a write that named none would put back an index whose contents it
+    //    had just thrown away. The chunks themselves are already there — the server kept what the
+    //    retained version names — which is why this is a list of names and not an upload.
+    const refs = await namedChunks(session.code, previous.ct);
+    // ⛔ THE SAME COMPARE-AND-SWAP EVERY OTHER WRITE USES, and it is not retried. A conflict here
+    //    means somebody wrote the list while this ran, so what would be replaced is no longer the
+    //    version this run showed the person — and re-applying it would roll back a version they
+    //    never saw.
+    const answer = await request(session.server, "/v1/manifest", {
+        method: "PUT",
+        token: session.apiKey,
+        body: { base_seq: current.seq, ct: previous.ct, refs },
+    });
+    const seq = isRecord(answer) ? answer["seq"] : undefined;
+    if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 1) {
+        throw new NmtsError("The file list was written but the server did not say which version it is now.", {
+            nextStep: `The older list is back. Run \`${BINARY_NAME} ls\` to see it.`,
+        });
+    }
+    // This machine's own copy follows the server, so the next command does not treat what is now
+    // being served as a list going backwards behind its back.
+    await recordWrittenList(session.accountId, seq, previous.ct);
+    if (options.json === true) {
+        say(JSON.stringify({ restored_seq: previous.seq, replaced_seq: current.seq }));
+        return 0;
+    }
+    say(`Put version ${previous.seq} of the file list back as the current one, over version ` +
+        `${current.seq}. What version ${current.seq} added is out of the list now; the bytes are ` +
+        `still stored, and \`${BINARY_NAME} rebuild\` finds files the list does not name.`);
+    return 0;
+}

package/dist/commands/s3.d.ts

@@ -0,0 +1,23 @@
+/** MinIO's port, which is what most S3 tools already have in their examples. */
+export declare const DEFAULT_PORT = 9000;
+/**
+ * How long a file list may be reused before it is fetched again.
+ *
+ * ⛔ THERE IS A CACHE BECAUSE A SYNC IS THOUSANDS OF REQUESTS. Reading the list per request would
+ *    mean a server round trip and a decryption for each one, so a listing of a large drive would
+ *    take minutes and cost the account's rate budget. ⚠ It also means a file uploaded from another
+ *    device can be up to this long in appearing here, which is the trade and is written in the
+ *    tool's own words when it starts.
+ */
+export declare const LIST_CACHE_MS = 5000;
+export interface S3Options {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Which port to listen on. Loopback either way. */
+    port?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** Resolves when the caller wants the gateway to stop. Tests pass one; a person presses Ctrl-C. */
+    until?: Promise<void>;
+}
+export declare function s3(options?: S3Options): Promise<number>;