@needmoretruth/nmts-cli 0.17.2

package/dist/commands/recovery.js

@@ -0,0 +1,291 @@
+// `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 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.
+//
+// ⛔ IT NEVER OVERWRITES AND IT NEVER INSTALLS ITSELF. One file, in the directory the caller
+//    named, under the name the release published it as; a name that is taken is a refusal unless
+//    `--force` says otherwise; and the full path is printed. Nothing is copied onto a PATH
+//    directory, nothing is added to a shell profile, nothing on this machine is made to point at
+//    it. A program that quietly drops an executable somewhere the shell will find it has not saved
+//    anybody a step — it has taken a decision that was not its to take.
+//
+// ⛔ THE BYTES ARE CHECKED BEFORE THEY ARE MADE RUNNABLE. `SHA256SUMS` is fetched first, the tag
+//    the release resolved to is taken out of that request's redirects, and the executable is then
+//    asked for from THAT tag — never from "latest" a second time, which could answer from a
+//    release published in between. The file is written without an executable bit, hashed, and only
+//    then made runnable; a hash that does not match leaves nothing on the disk at all.
+//
+// ⛔ IT IS NOT AN MCP TOOL, AND MUST NOT BECOME ONE. `commands/mcp.ts` offers a model four things:
+//    who the account is, what is in it, one file out and one file in. Downloading an executable
+//    and setting its executable bit is not a step a model takes on somebody's behalf — the person
+//    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
+//   session is involved, and the command works signed out.
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { NmtsError } from "../errors.js";
+import { assetUrl, buildFromSource, CHECK_DOES_NOT_PROVE, CHECK_PROVES, executableFor, hashFromSums, publishedLabels, RECOVERY_TOOL, RECOVERY_TOOL_URL, SUMS_FILE, sumsUrl, tagFromChain, wrapText, } from "../recovery-release.js";
+/** A download that stalls is a download that failed, and this one is a few megabytes. */
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+/**
+ * How many hops one address may take.
+ *
+ * ⚠ Two are ordinary — "latest" to the tagged address, and that to wherever the bytes are served
+ *   from. More than a handful is a loop, and a loop with no cap is a command that never returns.
+ */
+const MAX_REDIRECTS = 5;
+/** `SHA256SUMS` lists five short lines. Anything approaching this is not that file. */
+const MAX_SUMS_BYTES = 1024 * 1024;
+/**
+ * A ceiling on the executable.
+ *
+ * ⛔ THE WHOLE FILE IS HELD IN MEMORY, because it has to be hashed before any of it is allowed to
+ *    become runnable. That makes "how big is it" a question this command has to answer rather than
+ *    discover: the published ones are single-digit megabytes, and this is ten times over.
+ */
+const MAX_EXECUTABLE_BYTES = 128 * 1024 * 1024;
+export async function recovery(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const source = options.source ?? RECOVERY_TOOL_URL;
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const wanted = executableFor(platform, arch);
+    if (wanted === null)
+        throw noExecutableFor(platform, arch, source);
+    // ⛔ ASKED BEFORE ANYTHING IS DOWNLOADED. A taken name is a refusal either way, and finding out
+    //    after several megabytes have crossed somebody's connection helps nobody. The reservation
+    //    that actually makes it safe is the `wx` write below — this is the fast half of it.
+    const destination = destinationFor(options.out, wanted.asset);
+    if (options.force !== true && existsSync(destination))
+        throw alreadyThere(destination, "downloaded");
+    const sums = await fetched(sumsUrl(source), MAX_SUMS_BYTES, SUMS_FILE);
+    // ⛔ THE TAG COMES OUT OF THE REQUEST THAT WAS JUST ANSWERED. Asking for "latest" a second time
+    //    would be a second question, and two questions can get two answers: a release published
+    //    between them would hand over an executable that the sums in hand do not describe, and the
+    //    mismatch would look like a corrupt download rather than what it is.
+    const tag = tagFromChain(sums.chain, SUMS_FILE);
+    if (tag === null)
+        throw unresolvedRelease(source);
+    const lookup = hashFromSums(new TextDecoder().decode(sums.bytes), wanted.asset);
+    if (!lookup.found)
+        throw noLineFor(wanted.asset, tag, lookup.why);
+    const from = assetUrl(source, tag, wanted.asset);
+    const got = await fetched(from, MAX_EXECUTABLE_BYTES, wanted.asset);
+    // ⛔ 0600 AND NOT EXECUTABLE. The bit that makes this runnable goes on further down, after the
+    //    hash matched — between here and there the file on the disk is bytes nobody has checked, and
+    //    a run interrupted in that window must not leave something a shell will start.
+    try {
+        writeFileSync(destination, got.bytes, { flag: options.force === true ? "w" : "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, "code") === "EEXIST") {
+            throw alreadyThere(destination, "written");
+        }
+        throw error;
+    }
+    const digest = createHash("sha256").update(got.bytes).digest("hex");
+    if (digest !== lookup.hash) {
+        // ⛔ NOTHING IS LEFT BEHIND. A file that failed this check is not a partial download to resume
+        //    or an artefact to inspect — it is bytes of unknown provenance under the name of a program
+        //    somebody is about to run when everything else has already gone wrong.
+        //
+        // ⚠ WITH `--force` THAT MEANS THE OLD FILE IS GONE TOO, and it is the honest outcome rather
+        //   than an oversight: `--force` said this name was the caller's to replace, and the two
+        //   things that could be left here are a file they asked to be rid of and one nothing
+        //   checked. Without `--force` this branch is only ever reached for a file this run made.
+        rmSync(destination, { force: true });
+        throw doesNotMatch(wanted.asset, tag, lookup.hash, digest);
+    }
+    // ⚠ THE HOST'S PLATFORM DECIDES, not the one being fetched for: the bit is a property of the
+    //   filesystem being written to. Windows has no executable bit and `chmod` there is a no-op at
+    //   best, so it is not asked for.
+    if (process.platform !== "win32")
+        chmodSync(destination, 0o700);
+    if (options.json === true) {
+        say(JSON.stringify({
+            program: RECOVERY_TOOL,
+            platform: wanted.label,
+            asset: wanted.asset,
+            release: tag,
+            from,
+            writtenTo: destination,
+            bytes: got.bytes.length,
+            sha256: digest,
+            // ⛔ BOTH SENTENCES REACH A READER THAT ONLY PARSES JSON. An agent handing this file to
+            //    somebody has to be able to say what was and was not established, in the same words.
+            proves: CHECK_PROVES,
+            doesNotProve: CHECK_DOES_NOT_PROVE,
+        }));
+        return 0;
+    }
+    say(`Wrote ${destination}`);
+    say(``);
+    say(`  ${RECOVERY_TOOL} for ${wanted.label}, from release ${tag}`);
+    say(`  ${from}`);
+    say(`  sha256 ${digest}`);
+    say(``);
+    for (const line of wrapText(CHECK_PROVES))
+        say(`  ${line}`);
+    for (const line of wrapText(CHECK_DOES_NOT_PROVE))
+        say(`  ${line}`);
+    say(``);
+    for (const line of wrapText(`Nothing was installed. The file is where you see it and nowhere else — no copy was put on ` +
+        `your PATH, and nothing on this machine was pointed at it. Run it with \`--help\` to see ` +
+        `what it does.`)) {
+        say(`  ${line}`);
+    }
+    return 0;
+}
+/** Where the file goes: the given file name, inside the given directory, or this directory. */
+function destinationFor(out, asset) {
+    if (out === undefined)
+        return join(process.cwd(), asset);
+    const target = isAbsolute(out) ? out : resolve(process.cwd(), out);
+    // A directory that exists means "put it in here under its published name"; anything else is the
+    // name to write. Guessing the other way round would write a file called `bin`.
+    if (existsSync(target) && statSync(target).isDirectory())
+        return join(target, asset);
+    return target;
+}
+/**
+ * Fetch one address, following redirects by hand.
+ *
+ * ⛔ BY HAND BECAUSE THE CHAIN IS THE ANSWER. `redirect: "follow"` reports only where a request
+ *    ended, and where this one ends carries no release tag — the hop that names the tag is in the
+ *    middle. Following it here is what lets the executable be asked for from the same release as
+ *    the sums, which is the whole point of checking them.
+ */
+async function fetched(from, cap, what) {
+    const chain = [from];
+    let current = from;
+    const wasSecure = new URL(from).protocol === "https:";
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+        let response;
+        try {
+            response = await fetch(current, {
+                redirect: "manual",
+                signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new NmtsError(`${what} could not be fetched: ${because(error)}`, {
+                exitCode: 1,
+                nextStep: `Nothing was written. This talks to the site the recovery program is published on, not ` +
+                    `to NMTS — check that this machine can reach it, and try again.`,
+            });
+        }
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get("location");
+            // The body of a redirect is not part of the answer; reading it releases the connection.
+            await response.arrayBuffer().catch(() => undefined);
+            if (location === null || location === "") {
+                throw new NmtsError(`${what} was redirected to nowhere (${response.status}).`, {
+                    exitCode: 1,
+                    nextStep: `Nothing was written. The release page answered in a shape this cannot follow.`,
+                });
+            }
+            const next = new URL(location, current);
+            // ⛔ A REDIRECT MAY NOT DOWNGRADE THE CONNECTION. A request that started encrypted and is
+            //    talked down to a plain one hands whoever is in the middle the executable to write.
+            if (wasSecure && next.protocol !== "https:") {
+                throw new NmtsError(`${what} was redirected off an encrypted connection.`, {
+                    exitCode: 1,
+                    nextStep: `Nothing was written. This refuses rather than fetching an executable in the clear.`,
+                });
+            }
+            current = next.toString();
+            chain.push(current);
+            continue;
+        }
+        if (!response.ok) {
+            throw new NmtsError(`${what} — the release answered ${response.status}.`, {
+                exitCode: 1,
+                nextStep: response.status === 404
+                    ? `Nothing was written. That file is not attached to the release this resolved to.`
+                    : `Nothing was written. Try again; if it keeps answering this, the release page is the ` +
+                        `place to look.`,
+            });
+        }
+        const declared = Number(response.headers.get("content-length"));
+        if (Number.isFinite(declared) && declared > cap)
+            throw tooBig(what, cap);
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        // ⚠ Asked again after the fact: the header above is a claim, and this is the measurement.
+        if (bytes.length > cap)
+            throw tooBig(what, cap);
+        return { bytes, chain };
+    }
+    throw new NmtsError(`${what} was redirected more than ${MAX_REDIRECTS} times.`, {
+        exitCode: 1,
+        nextStep: `Nothing was written.`,
+    });
+}
+function because(error) {
+    return error instanceof Error ? error.message : "no answer";
+}
+function tooBig(what, cap) {
+    return new NmtsError(`${what} is larger than ${Math.round(cap / (1024 * 1024))} MiB.`, {
+        exitCode: 4,
+        nextStep: `Nothing was written. The published executables are a few megabytes; whatever answered is ` +
+            `not one of them.`,
+    });
+}
+function alreadyThere(destination, verb) {
+    return new NmtsError(`${destination} is already there.`, {
+        exitCode: 4,
+        nextStep: `Nothing was ${verb}. Pass --out to choose another name, or --force to replace it.`,
+    });
+}
+function noExecutableFor(platform, arch, source) {
+    const lines = [
+        `Nothing was downloaded. The release publishes one for each of these, and this machine ` +
+            `matches none of them:`,
+        ``,
+        ...publishedLabels().map((label) => `  ${label}`),
+        ``,
+        `It builds from source on anything a Rust toolchain runs on:`,
+        ``,
+        ...buildFromSource(source).map((command) => `  ${command}`),
+        ``,
+        `The source, and what it does, are at ${source}.`,
+    ];
+    return new NmtsError(`No recovery program is published for ${platform} ${arch}.`, {
+        exitCode: 4,
+        nextStep: lines.join("\n"),
+    });
+}
+function unresolvedRelease(source) {
+    return new NmtsError(`The newest release did not resolve to a named one.`, {
+        exitCode: 4,
+        nextStep: `Nothing was written. This follows ${SUMS_FILE} to the release it belongs to so the ` +
+            `executable can be asked for from that same release, and the address it was handed does not ` +
+            `name one. The releases are listed at ${source}/releases.`,
+    });
+}
+function noLineFor(asset, tag, why) {
+    const detail = why === "repeated"
+        ? `${SUMS_FILE} in release ${tag} lists ${asset} more than once.`
+        : why === "malformed"
+            ? `${SUMS_FILE} in release ${tag} lists ${asset} with something that is not a SHA-256 hash.`
+            : `${SUMS_FILE} in release ${tag} has no line for ${asset}.`;
+    return new NmtsError(detail, {
+        exitCode: 4,
+        nextStep: `Nothing was downloaded. Without a line to compare against there is nothing to check the ` +
+            `bytes with, and this does not hand over an executable it did not check.`,
+    });
+}
+function doesNotMatch(asset, tag, expected, got) {
+    return new NmtsError(`${asset} is not the file release ${tag} published.`, {
+        exitCode: 4,
+        nextStep: `The downloaded file was deleted. ${SUMS_FILE} says ${expected}; what arrived hashes to ` +
+            `${got}. Run this again — a download can be cut short — and if it says the same thing twice, ` +
+            `do not run the file.`,
+    });
+}

package/dist/commands/s3.js

@@ -0,0 +1,241 @@
+// `nmts s3` — serve this account's drive to any program that speaks S3.
+//
+// ⛔ WHY THIS EXISTS. Backup programs, sync tools and agent frameworks already know how to talk to
+//    S3. They do not know how to talk to this. Rather than ask every one of them to learn, the tool
+//    speaks the protocol they already speak, on this machine, where the account code already is.
+//
+// ⛔ WHAT IT IS NOT. It is not a bridge to the internet and cannot be made into one: the address it
+//    binds is loopback and there is no option to change that (`s3/server.ts` says why). Nothing is
+//    stored: the access key it prints is made fresh every time it starts and dies with it.
+//
+// ⛔ WRITING IS BEHIND THE SPENDING AGREEMENT, AND SAYS SO WHEN IT IS NOT THERE. Uploading costs
+//    credits, and spending is one of the three things this tool asks a person about once per
+//    machine -- and a gateway cannot ask, because its caller is a program and its stdin is not a
+//    terminal. So the agreement has to exist before it starts: without it the drive is served read
+//    only and every write is refused with the sentence naming the command that grants it.
+import { createWriteStream } from "node:fs";
+import { mkdir as makeDir, rm as removeFile, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { randomUUID } from "node:crypto";
+import { isGranted } from "../consent.js";
+import { createStaging } from "../s3/staging.js";
+import { refusalFor, verdictForKey } from "../s3/same-file.js";
+import { fetchFile } from "../download.js";
+import { NmtsError } from "../errors.js";
+import { ensureFolderPath } from "./organise.js";
+import { put } from "./put.js";
+import { rm } from "./trash.js";
+import { readFileList } from "../manifest.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+import { BUCKET } from "../s3/listing.js";
+import { BIND_ADDRESS, createGateway, newCredential } from "../s3/server.js";
+/** MinIO's port, which is what most S3 tools already have in their examples. */
+export 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 const LIST_CACHE_MS = 5_000;
+function portOf(raw) {
+    if (raw === undefined)
+        return DEFAULT_PORT;
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new NmtsError(`--port needs a number between 1 and 65535, not ${raw}.`, { exitCode: 2 });
+    }
+    return port;
+}
+export async function s3(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const port = portOf(options.port);
+    const session = await openSession({ server: options.server, network: options.network });
+    const chain = resolveNetwork(session.server, session.network);
+    const credential = newCredential();
+    let cached = [];
+    let cachedAt = 0;
+    const entries = async () => {
+        if (Date.now() - cachedAt < LIST_CACHE_MS)
+            return cached;
+        const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+        cached = list.manifest === null ? [] : list.manifest.entries;
+        cachedAt = Date.now();
+        return cached;
+    };
+    /**
+     * Where the pieces of a multipart upload wait until they are one file.
+     *
+     * ⛔ ONE DIRECTORY PER RUN, 0700, REMOVED WHEN THE COMMAND STOPS. Pieces are somebody's
+     *    plaintext; leaving them in a shared temporary directory under a predictable name would put
+     *    them where any other account on the machine could read them, for as long as the upload
+     *    takes and afterwards.
+     */
+    const stagingRoot = join(tmpdir(), `nmts-s3-${randomUUID()}`);
+    /**
+     * Store one local file at a drive key, making the folders above it if they are missing.
+     *
+     * ⛔ THE SAME-FILE QUESTION IS ANSWERED HERE AND NOWHERE ELSE.
+     *    Both ways of uploading — one PUT, or pieces staged and joined — end in this
+     *    function, so a rule written here cannot disagree with itself; written in the protocol layer
+     *    it would have to be written twice, once for each, and the two would differ the first time
+     *    one of them changed. What is compared is the plaintext's SHA-256 against the one this
+     *    account sealed when the file was first stored.
+     *
+     * ⛔ IDENTICAL CONTENT IS NOT AN ERROR. Nothing is sent and nothing is charged, and the caller
+     *    is told the upload finished — because the statement it was making, "that file is at that
+     *    key", is true. Answering 409 there is what made every backup run fail on every file it had
+     *    already stored, and a sync tool writes 409 down as a failure.
+     */
+    const storeFile = async (key, path) => {
+        const at = key.lastIndexOf("/");
+        const folder = at < 0 ? undefined : key.slice(0, at);
+        const name = at < 0 ? key : key.slice(at + 1);
+        const verdict = await verdictForKey(await entries(), key, session.code, path);
+        // ⭐ Already there, byte for byte. This is the whole point: an unchanged file costs nothing to
+        //    re-offer, so a backup that runs nightly stops paying for the nights nothing changed.
+        if (verdict === "same") {
+            say(`same ${key} — already stored, nothing sent`);
+            return;
+        }
+        if (verdict !== "free")
+            throw refusalFor(verdict, key);
+        if (folder !== undefined && folder !== "")
+            await ensureFolderPath(session, folder);
+        await put(path, {
+            server: options.server,
+            network: options.network,
+            ...(folder === undefined || folder === "" ? {} : { to: folder }),
+            name,
+            write: () => undefined,
+        });
+        cachedAt = 0;
+    };
+    // ⛔ WRITING IS OFF UNLESS THIS MACHINE ALREADY AGREED TO SPENDING. A gateway cannot ask: its
+    //    caller is a program and its stdin is not a terminal. So the question is answered before it
+    //    starts, and where the answer is no every write says so and nothing is charged.
+    const writable = isGranted("spend");
+    const server = createGateway({
+        credential,
+        source: {
+            entries,
+            ...(writable
+                ? {
+                    write: {
+                        // ⛔ THE BODY IS SPOOLED TO A FILE FIRST, 0600, and deleted whatever happens. The
+                        //    upload path reserves storage, cuts parts and seals them from a file, and giving
+                        //    it a socket instead would mean either holding whole uploads in memory or
+                        //    writing a second upload path — and a second upload path is a second place for
+                        //    "what if the reservation succeeds and the part fails" to be got right.
+                        put: async (key, body, size) => {
+                            await makeDir(stagingRoot, { recursive: true, mode: 0o700 });
+                            const spool = join(stagingRoot, randomUUID());
+                            try {
+                                await pipeline(body, createWriteStream(spool, { mode: 0o600 }));
+                                const written = (await stat(spool)).size;
+                                if (written !== size) {
+                                    throw new NmtsError(`The upload said ${size} bytes and ${written} arrived. Nothing was stored.`);
+                                }
+                                await storeFile(key, spool);
+                            }
+                            finally {
+                                await removeFile(spool, { force: true });
+                            }
+                        },
+                        multipart: createStaging(stagingRoot, storeFile),
+                        trash: async (object) => {
+                            await rm([`/${object.key}`], {
+                                server: options.server,
+                                network: options.network,
+                                write: () => undefined,
+                            });
+                            cachedAt = 0;
+                        },
+                    },
+                }
+                : {}),
+            // The real reader. The gateway takes it as a function so its own tests can be driven by a
+            // real S3 client without an account, a network or anybody's credits.
+            fetch: async (object, sink) => {
+                const wrapped = object.entry.dekWrapped;
+                if (wrapped === undefined)
+                    throw new NmtsError("That entry has no key in the file list.");
+                await fetchFile({
+                    base: session.server,
+                    apiKey: session.apiKey,
+                    accountCode: session.code,
+                    itemId: object.entry.id,
+                    size: object.size,
+                    dekWrapped: wrapped,
+                    contentHashCt: object.entry.contentHashCt,
+                    chain,
+                    sink,
+                });
+            },
+        },
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", (error) => {
+            reject(error.code === "EADDRINUSE"
+                ? new NmtsError(`Port ${port} on ${BIND_ADDRESS} is already taken.`, {
+                    exitCode: 4,
+                    nextStep: `Nothing was served. Pass --port with a free number.`,
+                })
+                : error);
+        });
+        server.listen(port, BIND_ADDRESS, resolve);
+    });
+    const endpoint = `http://${BIND_ADDRESS}:${port}`;
+    if (options.json === true) {
+        say(JSON.stringify({
+            endpoint,
+            bucket: BUCKET,
+            accessKeyId: credential.accessKeyId,
+            secretAccessKey: credential.secretAccessKey,
+            readOnly: !writable,
+            listCacheMs: LIST_CACHE_MS,
+        }));
+    }
+    else {
+        say(`  This account's drive is being served at ${endpoint}, to this machine only.`);
+        say(``);
+        say(`  endpoint        ${endpoint}`);
+        say(`  bucket          ${BUCKET}`);
+        say(`  access key id   ${credential.accessKeyId}`);
+        say(`  secret key      ${credential.secretAccessKey}`);
+        say(`  region          any — the signature carries whichever one the client used`);
+        say(``);
+        say(writable
+            ? `  Listing, downloading, uploading and deleting all work. Uploading spends credits.`
+            : `  ⛔ READ ONLY — this machine has not agreed to spending, so uploads and deletes are` +
+                ` refused. \`${BINARY_NAME} consent grant spend\`, run by the person whose account this` +
+                ` is, changes that.`);
+        say(`  ⚠ A file already in the drive is not replaced: uploading over one is refused, and a`);
+        say(`     delete puts the old one in the trash for thirty days.`);
+        say(`  ⛔ These credentials were made for this run and are stored nowhere. They stop working`);
+        say(`     the moment this command does.`);
+        say(`  ⚠ A file uploaded from another device can take ${LIST_CACHE_MS / 1000}s to appear here.`);
+        say(``);
+        say(`  Press Ctrl-C to stop. \`${BINARY_NAME} s3 --json\` prints the same thing in one line.`);
+    }
+    await new Promise((resolve) => {
+        const stop = () => {
+            // Nothing half-uploaded outlives the command that was staging it.
+            void removeFile(stagingRoot, { recursive: true, force: true });
+            server.close(() => resolve());
+            // A client holding a connection open must not keep the process alive after Ctrl-C.
+            server.closeAllConnections();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        void options.until?.then(stop);
+    });
+    return 0;
+}

package/dist/commands/settings.js

@@ -0,0 +1,28 @@
+// The three commands that only read or write a setting on this machine.
+//
+// ⛔ THEY ARE TOGETHER BECAUSE THEY ARE THE SAME KIND OF THING, not to save lines in `main.ts`.
+//    None of them touch the network, an account, or a file in the drive: each one prints what this
+//    machine is set to, or records a new answer. Keeping the dispatch for them in one place means
+//    the next setting has an obvious home, rather than another case in the middle of the commands
+//    that move money.
+//
+// ⚠ What each setting MEANS is not here — it is beside the setting itself (`consent.ts`,
+//   `autonomy.ts`, `collision.ts`), so a caller that needs the rule does not have to load a
+//   command to get it.
+/** Is this one of the settings commands? */
+export function isSettingsCommand(command) {
+    return command === "consent" || command === "mode" || command === "on-collision";
+}
+/** Run it. Only call this when `isSettingsCommand` said yes. */
+export async function runSettings(command, args) {
+    if (command === "consent") {
+        const { consent } = await import("./consent.js");
+        return consent(args.operands[0], args.operands[1], { json: args.json });
+    }
+    if (command === "mode") {
+        const { mode } = await import("./mode.js");
+        return mode(args.operands[0], { json: args.json, accepted: args.iAcceptTheRisk });
+    }
+    const { onCollision } = await import("./on-collision.js");
+    return onCollision(args.operands[0], { json: args.json });
+}