@needmoretruth/nmts-cli 0.17.2

package/dist/commands/rebuild.js

@@ -0,0 +1,160 @@
+// `nmts rebuild` — building a file list for an account that has none.
+//
+// ⛔ IT IS ITS OWN COMMAND, AND IT ASKS. Rebuilding WRITES: it seals a new file list and puts it on
+//    the server, and from then on that account's names are placeholders on every device. Doing
+//    that as a side effect of `ls` would mean somebody who pointed this tool at the wrong account
+//    — a mistyped variable, a second code on the same machine — would come back to an account that
+//    had been rebuilt without anybody deciding to. So it is a verb somebody types, and a run
+//    without `--yes` reports exactly what would happen and changes nothing.
+//
+// ⛔ AND IT IS NOT A ONCE-PER-MACHINE AGREEMENT. Those fit a capability — this machine may spend,
+//    this machine may hold the code unsealed. What is being decided here is not "may this tool
+//    ever rebuild" but "is THIS account, today, the one whose list is missing", and an answer
+//    given once for every future account on this machine is not an answer to that question.
+//
+// ⛔ TWO THINGS STOP IT FROM WRITING OVER A LIST, and they fail differently on purpose:
+//      · it reads the list first, and an account that has one is refused before the account is
+//        listed at all;
+//      · the write itself declares `base_seq: null`, which the server accepts only while no list
+//        exists — so a list that appears while this runs comes back as a refusal rather than as a
+//        replacement.
+//
+// ⚠ 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 { NmtsError } from "../errors.js";
+import { createFirstList } from "../manifest-create.js";
+import { readFileList } from "../manifest.js";
+import { BINARY_NAME } from "../product.js";
+import { rebuildFromServer } from "../rebuild.js";
+import { openSession } from "../session.js";
+import { TRASH_RETENTION_DAYS } from "../trash-sweep.js";
+/** The machine-readable answer, printed once on whichever path the run takes. */
+function summary(built, wrote, extra = {}) {
+    return JSON.stringify({
+        entries: built.entries.length,
+        live: built.live,
+        trashed: built.trashed,
+        keyless: built.keyless,
+        unaccounted: built.unaccounted,
+        namesRecovered: false,
+        foldersRecovered: false,
+        wrote,
+        ...extra,
+    });
+}
+export async function rebuild(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const session = await openSession(options);
+    const current = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (current.manifest !== null) {
+        throw new NmtsError(`This account already has a file list (version ${current.seq ?? 0}).`, {
+            exitCode: 4,
+            nextStep: `Nothing was changed. Rebuilding is for an account whose list is missing; over an existing ` +
+                `one it would replace real names with placeholders. Run \`${BINARY_NAME} ls\` to see what ` +
+                `the list holds.`,
+        });
+    }
+    if (!current.firstTimeOnThisMachine && options.force !== true) {
+        throw new NmtsError(`This machine has seen a file list for this account, and the server now says there is none.`, {
+            exitCode: 4,
+            nextStep: `Nothing was changed. A list that was there and is not is different from one that never ` +
+                `existed: it is also what being shown an emptied account would look like. Open the account ` +
+                `in a browser and check before rebuilding. If the list really was lost, ` +
+                `\`${BINARY_NAME} rebuild --yes --force\` goes ahead.`,
+        });
+    }
+    // ⚠ A LARGE ACCOUNT IS TWO WHOLE LISTINGS, a hundred rows at a time, and a person watching a
+    //   command that says nothing for a minute concludes it has hung. Every thousandth row is often
+    //   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...`);
+        },
+    });
+    if (built.entries.length === 0) {
+        if (options.json) {
+            say(summary(built, false));
+            return 0;
+        }
+        say(`This account has no file list, and the server holds no stored files for it either.`);
+        say(`There is nothing to rebuild from. Nothing was changed.`);
+        return 0;
+    }
+    if (options.yes !== true) {
+        if (options.json) {
+            say(summary(built, false));
+            return 5;
+        }
+        describe(say, built);
+        say(``);
+        say(`Nothing was changed. To go ahead:  ${BINARY_NAME} rebuild --yes`);
+        say(`⛔ If a program is reading this on somebody's behalf: show it to them and let them decide.`);
+        return 5;
+    }
+    const written = await createFirstList(session, built.entries);
+    if (options.json) {
+        say(summary(built, true, { seq: written.seq }));
+        return 0;
+    }
+    say(`Wrote file list version ${written.seq}: ${built.entries.length} ` +
+        `entr${built.entries.length === 1 ? "y" : "ies"} (${built.live} live, ${built.trashed} in the trash).`);
+    say(``);
+    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.`);
+    reportGaps(say, built);
+    return 0;
+}
+/** What a rebuild would do, in the words somebody is about to decide on. */
+function describe(say, built) {
+    say(`This account has no file list, and the server still holds ${built.entries.length} ` +
+        `stored file${built.entries.length === 1 ? "" : "s"} for it. The files are there; what is ` +
+        `missing is the list that names them.`);
+    say(``);
+    say(`A rebuild would recover:`);
+    say(`  · ${built.live} live and ${built.trashed} in the trash — the trash keeps its remaining days`);
+    say(`  · every file's key, without which its bytes could never be opened again`);
+    say(`  · the sealed content hash, so a later download still checks itself`);
+    say(`  · each file's real dates and its size`);
+    say(``);
+    say(`It cannot recover:`);
+    say(`  · names — each file gets a placeholder such as \`recovered-a1b2c3d4\`, for you to type over`);
+    say(`  · folders and where each file sat — the rebuilt drive is flat`);
+    say(`  · stars, labels, share receipts and account settings`);
+    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.`);
+    reportGaps(say, built);
+}
+/** The parts of the account this rebuild could not account for. Printed on both paths. */
+function reportGaps(say, built) {
+    if (built.keyless > 0) {
+        say(``);
+        say(`  ⚠ ${built.keyless} of them carr${built.keyless === 1 ? "ies" : "y"} no key on the server.` +
+            ` ${built.keyless === 1 ? "It appears" : "They appear"} in the list and`);
+        say(`    nothing can open ${built.keyless === 1 ? "it" : "them"} — the entry is still what says the file was there.`);
+    }
+    if (built.unaccounted === null) {
+        say(``);
+        say(`  ⚠ The check that compares this against everything the server holds could not be`);
+        say(`    finished, so this cannot say whether any row was left out.`);
+        return;
+    }
+    if (built.unaccounted > 0) {
+        say(``);
+        say(`  ⚠ ${built.unaccounted} row${built.unaccounted === 1 ? "" : "s"} the server holds ` +
+            `${built.unaccounted === 1 ? "is" : "are"} not in this rebuild.`);
+        say(`    The trash listing ends at ${TRASH_RETENTION_DAYS} days, so anything thrown away longer ago than that`);
+        say(`    is in no listing this can read, and its key is not recoverable here. The bytes stay`);
+        say(`    on the storage network until the term already paid for runs out.`);
+    }
+}

package/dist/commands/receive.js

@@ -0,0 +1,125 @@
+// `nmts receive <id>` — download a file somebody shared with this account.
+//
+// ⛔ THE LENGTH COMES FROM THE SENDER, NOT FROM THE SERVER. The number the server holds is
+//    bytes-on-the-network: larger than the file by a fixed amount per stored piece, and larger
+//    again when the sender rounded the stored size up to hide the true one. Only the sender knows
+//    the real length, and they sealed it beside the name. Taking the server's number instead
+//    produces a file with padding written into the end of it, and the hash check then refuses a
+//    download that was otherwise perfect.
+//
+// ⛔ AND THE HASH IS THE SENDER'S TOO, sealed under the file's own key. The recipient holds that
+//    key and nothing else of the sender's, which is exactly why the check works at all: a storage
+//    network that returned different bytes cannot produce a matching hash without the key.
+import { resolve } from "node:path";
+import { request } from "../api.js";
+import { loadCrypto } from "../crypto.js";
+import { fetchWithKey } from "../download.js";
+import { fileSink, stdoutSink } from "../download-sink.js";
+import { NmtsError } from "../errors.js";
+import { destinationFor } from "../safe-path.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+import { openReceived, openSharedDigest, shareKeysOf } from "../share.js";
+import { processStdout, STDOUT_TARGET } from "../stdout.js";
+export async function receive(id, options = {}) {
+    const toStdout = options.out === "-";
+    const say = options.write ?? ((line) => (toStdout ? process.stderr : process.stdout).write(`${line}\n`));
+    if (id === undefined || id === "") {
+        throw new NmtsError("Say which share to receive.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} receive <id>\` — the id \`${BINARY_NAME} shares\` prints.`,
+        });
+    }
+    const session = await openSession({ server: options.server, network: options.network });
+    const chain = resolveNetwork(session.server, session.network);
+    const crypt = await loadCrypto();
+    const keys = shareKeysOf(crypt, session.code);
+    try {
+        // ⛔ THE ROW IS FOUND IN THE LISTING, not asked for by id. The listing is what carries the
+        //    sender's published identity, and without that identity the envelope cannot be
+        //    authenticated — an unauthenticated open is not one worth doing.
+        const answer = await request(session.server, "/v1/shares/received", {
+            token: session.apiKey,
+        });
+        const rows = typeof answer === "object" && answer !== null ? Reflect.get(answer, "shares") : null;
+        if (!Array.isArray(rows))
+            throw new NmtsError("The server did not list any shares.");
+        const row = rows.find((candidate) => typeof candidate === "object" && candidate !== null && Reflect.get(candidate, "id") === id);
+        if (row === undefined) {
+            throw new NmtsError(`Nothing shared with this account has the id "${id}".`, {
+                exitCode: 4,
+                nextStep: `Nothing was written. \`${BINARY_NAME} shares\` lists what is there.`,
+            });
+        }
+        const opened = openReceived(crypt, keys, row);
+        if (opened.dek === null || opened.name === null) {
+            throw new NmtsError(`That share ${opened.problem ?? "did not open"}.`, {
+                exitCode: 1,
+                nextStep: "Nothing was written. The sender can withdraw it and share the file again.",
+            });
+        }
+        if (opened.size === null) {
+            // ⛔ NOT A GUESS. Without the sender's number there is nothing to trim the stored bytes back
+            //    to, and taking the stored length would write padding into the end of the file.
+            opened.dek.fill(0);
+            throw new NmtsError("The sender did not record this file's real length.", {
+                exitCode: 1,
+                nextStep: "Nothing was written. It was shared by an older client; ask them to share it again from " +
+                    "a current one, which seals the length beside the name.",
+            });
+        }
+        const expected = openSharedDigest(crypt, opened.dek, opened.digestCt);
+        if (expected === null) {
+            opened.dek.fill(0);
+            throw new NmtsError("This share's content hash did not open with the file's own key.", {
+                exitCode: 1,
+                nextStep: "Nothing was written. There would be nothing to check the bytes against.",
+            });
+        }
+        const destination = toStdout
+            ? null
+            : options.out !== undefined
+                ? resolve(options.out)
+                : options.intoDir !== undefined
+                    ? destinationFor(options.intoDir, opened.name)
+                    : resolve(opened.name);
+        // ⛔ `--force` has nothing to overwrite on the stdout branch and is ignored there on purpose.
+        //    On the disk branch the file streams into a temporary name beside the destination and is
+        //    renamed into place only once the sender's digest matches, so a share that turns out to be
+        //    wrong — or a transfer that stops half way — leaves nothing under the name it was given.
+        const sink = destination === null
+            ? stdoutSink(options.stdout ?? processStdout())
+            : fileSink(destination, { force: options.force === true });
+        const fetched = await fetchWithKey({
+            base: session.server,
+            apiKey: session.apiKey,
+            descriptorPath: `/v1/shares/${encodeURIComponent(id)}/parts?for=download`,
+            size: opened.size,
+            dek: opened.dek,
+            expected,
+            chain,
+            sink,
+        });
+        if (!fetched.delivered)
+            return 0;
+        if (options.json) {
+            say(JSON.stringify({
+                id,
+                name: opened.name,
+                bytes: fetched.byteCount,
+                from: opened.sender,
+                parts: fetched.partCount,
+                out: destination ?? STDOUT_TARGET,
+            }));
+            return 0;
+        }
+        say(`${opened.name}  ${fetched.byteCount} bytes`);
+        say(`  from ${opened.sender ?? ""}`);
+        say(`  checked against the hash the sender sealed with it`);
+        return 0;
+    }
+    finally {
+        keys.wipe();
+    }
+}

package/dist/commands/recovery-list.js

@@ -0,0 +1,104 @@
+// `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
+//    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.
+//
+// ⛔ THE ACCOUNT CODE 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.
+//
+// ⛔ NO PARTIAL LIST, EVER. If any page, name or key does not reconcile, nothing is written and the
+//    reason is printed. A list quietly missing files tells somebody they are covered when they are
+//    not, and they find out on the one day it cannot be repaired.
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { NmtsError } from "../errors.js";
+import { assembleRecoveryList, recordRecoveryList } from "../recovery-assemble.js";
+export async function recoveryList(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const assembled = await assembleRecoveryList({
+        server: options.server,
+        network: options.network,
+    });
+    const { built, file, seq } = assembled;
+    // ⛔ ASKED BEFORE THE ATTEMPT AND ENFORCED BY THE WRITE ITSELF. The `wx` flag below is what
+    //    actually reserves the name; this only turns the common case into a sentence rather than a
+    //    system error.
+    const destination = destinationFor(options.out, file.filename);
+    if (options.force !== true && existsSync(destination))
+        throw alreadyThere(destination);
+    try {
+        // ⛔ 0600. These bytes are one account's whole storage index, sealed — and a mode is cheaper to
+        //    get right than an explanation of why it did not matter.
+        writeFileSync(destination, file.content, {
+            flag: options.force === true ? "w" : "wx",
+            mode: 0o600,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, "code") === "EEXIST") {
+            throw alreadyThere(destination);
+        }
+        throw error;
+    }
+    await recordRecoveryList(assembled, destination);
+    if (options.json === true) {
+        say(JSON.stringify({
+            writtenTo: destination,
+            seq,
+            nrm: built.doc.v,
+            files: built.fileCount,
+            bytes: built.totalBytes,
+            capturedAt: assembled.capturedAt,
+            // ⛔ REACHES A READER THAT ONLY PARSES JSON. An agent has to be able to say the account is
+            //    not fully covered without a person reading the lines below.
+            missingFromSource: built.missingFromSource,
+        }));
+        return 0;
+    }
+    say(`Wrote ${destination}`);
+    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(``);
+    say(`  Recorded with the server: version ${seq}, kept on this machine (no storage-network`);
+    say(`  copy), read from the account at ${assembled.capturedAt}.`);
+    if (built.missingFromSource.length > 0) {
+        say(``);
+        say(`  ⚠ ${built.missingFromSource.length} file(s) in your file list are not in the account's`);
+        say(`    stored files, so they are not in this list. An upload that never finished looks like`);
+        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(`     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.`);
+    return 0;
+}
+/** Where the file goes: the given file name, inside the given directory, or this directory. */
+function destinationFor(out, filename) {
+    if (out === undefined)
+        return join(process.cwd(), filename);
+    const target = isAbsolute(out) ? out : resolve(process.cwd(), out);
+    // A directory that exists means "put it in here under its own name"; anything else is the name
+    // to write. Guessing the other way round would rename the artefact whose filename is how a
+    // person tells two copies apart.
+    if (existsSync(target) && statSync(target).isDirectory())
+        return join(target, filename);
+    return target;
+}
+function alreadyThere(destination) {
+    return new NmtsError(`${destination} is already there.`, {
+        exitCode: 4,
+        nextStep: `Nothing was written. Pass --out to choose another name, or --force to replace it.`,
+    });
+}