@needmoretruth/nmts-cli 0.17.2

package/dist/recovery-map-file.js

@@ -0,0 +1,114 @@
+// The FILE a person keeps — a self-describing wrapper around one sealed recovery list.
+//
+// ⛔ ONE FORMAT, NOT TWO. `format`, `version` and the `.nmtsmap` extension are what a reader
+//    matches on, and somebody recovering an account may hold copies written by a browser and by
+//    this command months apart. The shape below is RECOVERY-MANIFEST.md §5 and the standalone
+//    program's `recovery/src/mapfile.rs` reads it; a second spelling of the same artefact would
+//    mean whoever helps them has two formats to work out instead of one, at the worst moment.
+//
+// ⛔ WHY A WRAPPER AND NOT THE BARE ENVELOPE. On the storage network the list is the raw envelope
+//    and its address says what it is. A file in somebody's Downloads folder has no such context —
+//    years later it has to explain itself. `sealed` is byte-for-byte the SAME envelope a
+//    storage-network copy would hold, so one reader reads either.
+//
+// ⛔ NOTHING SECRET IN THE HEADER, AND THAT INCLUDES SIZES. No file name, no count, no total. A
+//    leaked wrapper must not say what is inside it, or even how much.
+//
+// ⛔ THE ACCOUNT CODE IS NOT IN IT. This file plus the code is the account; the artefact that DOES
+//    carry both is the recovery kit, and it says so about itself in every language it is written.
+//
+// ⚠ WHAT DIFFERS FROM THE BROWSER'S COPY, and none of it is a format difference:
+//    · The finder's note is English only. §5 says v2 carries both languages, and the reason is
+//      sound — which language the finder reads is not something the moment of saving can know. The
+//      Korean half lives in the site's message bundles, which this package does not import, and
+//      `cli/src/list-file.ts` set the precedent for the sibling artefact: ship the English and say
+//      so rather than invent a translation. The four English sentences below ARE the site's, word
+//      for word, so the two artefacts do not describe themselves differently. ⚠ A reader never
+//      reads `note` at all (`recovery/src/mapfile.rs` ignores it), so nothing refuses this file.
+//    · `about.app_version` names THIS PROGRAM rather than the site release — the field's own
+//      contract, and how a person holding two copies tells which program wrote each.
+//    · `min_tool` is written from the table below, which is restated because it is a claim about a
+//      THIRD program's versions and cannot be derived from anything here.
+import { artifactAbout } from "./artifact-about.js";
+/** Wrapper format identifier, checked on read before anything is attempted. */
+export const MAP_FILE_FORMAT = "nmts-recovery-map";
+/**
+ * Wrapper version — the SHELL's version, independent of the NRM version inside.
+ *
+ * ⛔ NOT RAISED FOR ANYTHING THIS TOOL ADDS. `MAX_WRAPPER_VERSION` in the standalone program is a
+ *    CEILING: a shell numbered higher than a build knows is refused outright, unread. So a bump is
+ *    a wall in front of every reader already in somebody's hands, never a courtesy.
+ */
+export const MAP_FILE_VERSION = 2;
+/** Filename extension. Deliberately not the file-list copy's: the two must not be confusable. */
+export const MAP_FILE_EXTENSION = "nmtsmap";
+/**
+ * The lowest `nmts-recovery` version that reads a document of a given NRM version.
+ *
+ * ⛔ IT SITS BESIDE `nrm` RATHER THAN REPLACING IT. `nrm` says which forms the document uses,
+ *    which is the right question for any reader — ours or a stranger's re-implementation. It is
+ *    the wrong question for the person holding this file during a recovery, whose actual question
+ *    is "what do I need to download".
+ *
+ * ⚠ A CLAIM ABOUT A DIFFERENT PROGRAM, so it cannot be derived — it is measured and written down.
+ *   0.1.0 was the first published build and its ceiling was NRM-2; 0.2.0 raised it and added
+ *   padded parts (NRM-4). A version this table does not know is answered with the newest entry,
+ *   because a form this build can write is a form the build published alongside it reads.
+ *
+ * ⛔ AND IT RESCUES NOBODY. Knowing you need 0.2.0 does not help if 0.2.0 does not exist, which is
+ *    why the program still ships BEFORE a new form is switched on. What it buys is a refusal a
+ *    person can act on, not one they can survive.
+ */
+const MIN_TOOL_FOR_NRM = [
+    { upTo: 2, version: "0.1.0" },
+    { upTo: 4, version: "0.2.0" },
+];
+/** The version to stamp for a document declaring `nrm`. */
+export function minimumToolVersion(nrm) {
+    const row = MIN_TOOL_FOR_NRM.find((r) => nrm <= r.upTo) ?? MIN_TOOL_FOR_NRM.at(-1);
+    // The table is a literal with entries; the fallback exists so this cannot be a non-null
+    // assertion, which is banned here and would be a promise about a value rather than a check.
+    return row === undefined ? "0.1.0" : row.version;
+}
+/**
+ * Plain-language lines for whoever finds this file with no other context.
+ *
+ * ⚠ COPIED WORD FOR WORD from the site's `mapFileNoteEn1..4`. They are product copy and this is
+ *   not the place to rewrite them; if they change there, they change here.
+ */
+const NOTE = [
+    `This file is a recovery list from NMTS (nmts.me). Encrypted inside is the record of where ` +
+        `this account's files are kept on the public storage network (Walrus).`,
+    `It opens only with the account code this list was made for. File names and counts are not ` +
+        `visible from the outside.`,
+    `The original file list lives on the NMTS server. If the server can no longer be reached, this ` +
+        `list together with the account code carries the information needed to find the files still ` +
+        `on the storage network and open them.`,
+    `A list with a higher number in its filename is newer — keep the newest. Store this file ` +
+        `somewhere other than the account code. The program that reads it is at ` +
+        `github.com/needmoretruth/nmts-recovery.`,
+];
+/** Build the on-disk document and the filename to offer it under. */
+export function buildRecoveryMapFile(input) {
+    const doc = {
+        format: MAP_FILE_FORMAT,
+        version: MAP_FILE_VERSION,
+        nrm: input.nrm,
+        seq: input.seq,
+        generated_at: input.generatedAt,
+        account_id: input.accountId,
+        sealed: input.sealed,
+        min_tool: minimumToolVersion(input.nrm),
+        note: [...NOTE],
+        about: artifactAbout("recovery-list"),
+    };
+    // A short slug keeps several accounts' files apart without printing the whole id in a filename
+    // that shows up in screenshots and file managers.
+    const slug = input.accountId.replace(/[^A-Za-z0-9]/g, "").slice(0, 8) || "account";
+    // ⚠ THE SEQUENCE IS IN THE NAME AS WELL AS THE BODY, zero-padded: somebody with three of these
+    //   in a folder needs to know which is newest without opening any of them.
+    return {
+        filename: `nmts-recovery-map-${slug}-${String(input.seq).padStart(4, "0")}.${MAP_FILE_EXTENSION}`,
+        content: `${JSON.stringify(doc, null, 2)}\n`,
+    };
+}

package/dist/recovery-map.js

@@ -0,0 +1,191 @@
+// The RECOVERY LIST DOCUMENT — the exact JSON shape that gets sealed, and nothing else.
+//
+// ⛔ THIS FORMAT HAS TWO INDEPENDENT IMPLEMENTATIONS AND THIS IS A THIRD WRITER. The browser
+//    writes it (`web/src/lib/recovery/manifest-doc.ts`), the standalone recovery program reads it
+//    in Rust (`crypto/src/manifest.rs`), and the authority both answer to is
+//    `docs/RECOVERY-MANIFEST.md` §2. A writer that drifts is not discovered by a failing test — it
+//    is discovered years later, by somebody who has nothing left but this file.
+//
+// ⛔ FIELD NAMES ARE snake_case AND THAT IS NOT THIS CODEBASE'S STYLE. They are the wire format.
+//
+// ⛔ NOTHING HERE TOUCHES A KEY. Callers hand in file keys and content hashes already opened and
+//    re-encoded as base64url; opening them is the builder's job, one layer up.
+//
+// ⚠ RESTATED FROM THE BROWSER'S ENCODER, WHICH THIS PACKAGE CANNOT IMPORT — the two trees share no
+//   code by design, and the browser's copy pulls in its own types tree. What is restated is the
+//   SHAPE and the four refusals below; the arithmetic that decides how much of a padded part is
+//   real is not restated at all, because `shared/lib/crypto/size-padding.ts` is a byte-for-byte
+//   copy of the browser's own file and a gate compares them.
+import { NmtsError } from "./errors.js";
+/** The newest NRM version this writer knows how to emit. */
+export const NRM_VERSION_LATEST = 4;
+/** The first NRM version in which every part carries `part_index`. */
+export const NRM_VERSION_WITH_PART_INDEX = 2;
+/** The first NRM version in which a quilt placement may be `{ identifier }` alone. */
+export const NRM_VERSION_WITH_OWN_QUILT = 3;
+/** The first NRM version in which a part may carry `padded_len`. */
+export const NRM_VERSION_WITH_PADDING = 4;
+/** Practical ceiling from RECOVERY-MANIFEST.md §1 — beyond this the format needs chunk framing. */
+export const MANIFEST_ITEM_SOFT_CAP = 100_000;
+/** Which form a placement is. One narrowing point, so "exactly one of the two" is decided here. */
+export function isOwnQuilt(quilt) {
+    return quilt.identifier !== undefined;
+}
+/**
+ * Thrown when the input cannot produce a document a recovery tool could use.
+ *
+ * ⛔ IT IS AN `NmtsError`, NOT A BARE `Error`. Anything that reaches the top of this program as a
+ *    bare error prints its message with no next step and exits with the generic code — and the
+ *    generic code is the one an agent retries. A discrepancy here is never worth retrying: the
+ *    server has to change, or the account does. Exit 4 is "the command exists and could not do
+ *    it", which is exactly what happened.
+ */
+export class RecoveryListProblem extends NmtsError {
+    constructor(message) {
+        super(message, {
+            exitCode: 4,
+            nextStep: "Nothing was written, and that is deliberate: a list quietly missing files would tell you " +
+                "you are covered when you are not. Retrying will not change it. The account screen at " +
+                "nmts.me builds the same list from the same rows and will report the same thing.",
+        });
+        this.name = "RecoveryListProblem";
+    }
+}
+/**
+ * The lowest `v` a document holding these items may honestly declare.
+ *
+ * ⛔ A WRITER STAMPS THIS, NOT THE NEWEST NUMBER IT KNOWS. People already hold copies of the
+ *    standalone recovery program, and a build only knows the forms that existed when it was made.
+ *    Every version number in this format is a CEILING in every published build: a document
+ *    declaring a number higher than a build knows is REFUSED, unread. So stamping `4` for no
+ *    reason other than the calendar would be a wall in front of a reader that would have
+ *    understood every byte of it.
+ */
+export function minimumVersion(items) {
+    if (items.some((it) => it.parts.some((p) => p.padded_len !== undefined))) {
+        return NRM_VERSION_WITH_PADDING;
+    }
+    const ownQuilt = items.some((it) => it.quilt !== undefined && isOwnQuilt(it.quilt));
+    return ownQuilt ? NRM_VERSION_WITH_OWN_QUILT : NRM_VERSION_WITH_PART_INDEX;
+}
+/**
+ * Assemble the document.
+ *
+ * Rejects rather than emits a list that would mislead somebody in a recovery: a file with no parts
+ * has nothing to fetch, a part list that does not add up to the file's size is missing or repeating
+ * bytes, a part that says it is somewhere other than where it sits contradicts itself, and a
+ * `seq` below 1 is not a version at all. The hostile-input version of the middle two is caught one
+ * layer up, where the size being compared against comes from a source the server cannot write —
+ * but the cost of shipping any of them is that somebody believes they are covered when they are
+ * not, so they are checked here too rather than assumed.
+ */
+export function buildRecoveryListDoc(input) {
+    if (!Number.isSafeInteger(input.seq) || input.seq < 1) {
+        throw new RecoveryListProblem(`seq must be a whole number of at least 1 (got ${input.seq})`);
+    }
+    if (input.items.length > MANIFEST_ITEM_SOFT_CAP) {
+        throw new RecoveryListProblem(`a recovery list of ${input.items.length} files is above the format's cap of ${MANIFEST_ITEM_SOFT_CAP}`);
+    }
+    const items = input.items.map((it) => {
+        if (it.parts.length === 0) {
+            throw new RecoveryListProblem(`item ${it.id} has no parts — nothing to recover from`);
+        }
+        const partBytes = it.parts.reduce((sum, p) => sum + p.plaintext_len, 0);
+        if (partBytes !== it.size) {
+            throw new RecoveryListProblem(`item ${it.id} is ${it.size} bytes but its ${it.parts.length} parts hold ${partBytes}`);
+        }
+        // Where the bytes are, decided once per item. The reader's copy of these two rules is
+        // `crypto/src/manifest.rs::check_quilt_placement`: a document this emits and that parser
+        // refuses would be discovered on the one day it cannot be repaired.
+        if (it.quilt !== undefined && isOwnQuilt(it.quilt)) {
+            const first = it.parts[0];
+            if (it.parts.length !== 1 || first === undefined || first.blob_id !== undefined) {
+                throw new RecoveryListProblem(`item ${it.id}: an own-quilt item must be exactly one part with no blob_id`);
+            }
+        }
+        else {
+            const missing = it.parts.findIndex((p) => p.blob_id === undefined);
+            if (missing >= 0) {
+                throw new RecoveryListProblem(`item ${it.id}: the part at position ${missing} has no blob_id and no own-quilt placement`);
+            }
+        }
+        const item = {
+            id: it.id,
+            name: it.name,
+            path: it.path,
+            size: it.size,
+            dek: it.dek,
+            kind: "file",
+            // Absent, never null: the format says a field that was not recorded is not there, and a
+            // reader must not have to tell two spellings of "not recorded" apart.
+            ...(it.createdAt ? { created_at: it.createdAt } : {}),
+            ...(it.updatedAt ? { updated_at: it.updatedAt } : {}),
+            parts: it.parts.map((p, i) => {
+                // ⛔ THE POSITION IS THE VALUE. Taking `part_index` from the array rather than from the
+                //    caller's field is what makes the two impossible to disagree about in the written
+                //    document; a caller that states its own number is checked against the position, because
+                //    a disagreement means the order it handed in is not the order it meant.
+                if (p.part_index !== undefined && p.part_index !== i) {
+                    throw new RecoveryListProblem(`item ${it.id}: the part at position ${i} says it is part ${p.part_index}`);
+                }
+                const part = p.blob_id === undefined
+                    ? { part_index: i, plaintext_len: p.plaintext_len }
+                    : { part_index: i, blob_id: p.blob_id, plaintext_len: p.plaintext_len };
+                // Strictly larger, or absent. Equal is not padding — writing it would make two identical
+                // lists differ in their bytes — and smaller is a stream that could not hold the part.
+                if (p.padded_len !== undefined) {
+                    if (!Number.isSafeInteger(p.padded_len) || p.padded_len <= p.plaintext_len) {
+                        throw new RecoveryListProblem(`item ${it.id}: the part at position ${i} contributes ${p.plaintext_len} bytes ` +
+                            `out of a padded ${p.padded_len}`);
+                    }
+                    part.padded_len = p.padded_len;
+                }
+                if (p.sui_object_id)
+                    part.sui_object_id = p.sui_object_id;
+                if (p.network)
+                    part.network = p.network;
+                return part;
+            }),
+        };
+        if (it.contentHash)
+            item.content_hash = it.contentHash;
+        // Rebuilt rather than passed through, so a caller that supplied an explicit `undefined`
+        // beside the form it meant cannot put an extra key in the byte output.
+        if (it.quilt !== undefined) {
+            item.quilt = isOwnQuilt(it.quilt)
+                ? { identifier: it.quilt.identifier }
+                : { quilt_blob_id: it.quilt.quilt_blob_id, patch_id: it.quilt.patch_id };
+        }
+        return item;
+    });
+    return {
+        v: minimumVersion(items),
+        seq: input.seq,
+        // Kept as an explicit null so a reader can tell the head of the chain apart from a writer that
+        // never implemented chaining.
+        prev_manifest_blob_id: input.prevBlobId,
+        generated_at: input.generatedAt,
+        account_id: input.accountId,
+        // ⛔ Omitted when absent rather than written as null, and NOT a reason to raise `v`: every
+        //    field in it is additive and its absence changes no meaning, so the recovery builds
+        //    already in people's hands read a document carrying it exactly as one without it.
+        ...(input.meta ? { meta: input.meta } : {}),
+        items,
+    };
+}
+/** Finish a draft once the document's contents are known. */
+export function withTotals(draft, totals) {
+    return { ...draft, totals };
+}
+/** The `meta` block for this build, minus the totals. */
+export function recoveryDocMeta(about, storage) {
+    return {
+        product: about.product,
+        product_url: about.product_url,
+        app_version: about.app_version,
+        tool: about.tool,
+        tool_url: about.tool_url,
+        spec_url: about.spec_url,
+        storage,
+    };
+}

package/dist/recovery-release.js

@@ -0,0 +1,229 @@
+// Where the standalone recovery program's executables come from, and which one this machine needs.
+//
+// ⛔ THE ASSET NAMES ARE A CONTRACT WITH ANOTHER REPOSITORY'S RELEASE WORKFLOW. That workflow
+//    builds one executable per platform and attaches it under exactly the name in the table below.
+//    They are not decoration and they are not guessed here: a name that drifts from the workflow's
+//    becomes a 404, and a 404 on this path reads as "there is no release" to somebody who has just
+//    lost access to their files. That is the worst sentence this command could say, and it would
+//    be a lie. `deploy/check-recovery-assets.mjs` set-compares this table against the workflow so
+//    the copy cannot go stale quietly.
+//
+// ⛔ RAW EXECUTABLES, NOT ARCHIVES, and that is the release's decision rather than a convenience.
+//    This tool has no archive reader; adding one would mean a dependency in a program whose whole
+//    claim is that you can read what it does. One file per platform, downloaded and run.
+//
+// ⛔ NO NEAR MATCHES. A machine whose platform is not in the table is told so, told which ones are
+//    published, and told how to build from source. Handing an aarch64 machine an x86_64 executable
+//    produces "cannot execute binary file", which sends a person debugging their shell instead of
+//    reading one honest sentence.
+/**
+ * The standalone program, by the name it is published under.
+ *
+ * ⛔ ONE SPELLING FOR THE WHOLE PACKAGE. It is the executable's file name, the prefix of every
+ *    asset in the table below, and the word the sealed file list writes into its own header so
+ *    that whoever finds that file years later knows what reads it. Two copies of this string is
+ *    how a rename lands in one of those places and not the others.
+ */
+export const RECOVERY_TOOL = "nmts-recovery";
+/**
+ * Where that program's source and its releases are.
+ *
+ * ⚠ Printed as text into a file that has no links, and used to build the download addresses. It
+ *   is the same one either way, so it is written down once.
+ */
+export const RECOVERY_TOOL_URL = "https://github.com/needmoretruth/nmts-recovery";
+/**
+ * Every executable the release workflow attaches, in the order it builds them.
+ *
+ * ⚠ macOS carries the marketing word in brackets because "aarch64" and "x86_64" are not what
+ *   anybody's machine calls itself on that platform — the person reading a refusal has to be able
+ *   to tell whether their own machine is in this list.
+ */
+export const PUBLISHED = [
+    { platform: "linux", arch: "x64", asset: "nmts-recovery-linux-x86_64", label: "Linux x86_64" },
+    { platform: "linux", arch: "arm64", asset: "nmts-recovery-linux-aarch64", label: "Linux aarch64" },
+    {
+        platform: "darwin",
+        arch: "arm64",
+        asset: "nmts-recovery-macos-aarch64",
+        label: "macOS aarch64 (Apple silicon)",
+    },
+    { platform: "darwin", arch: "x64", asset: "nmts-recovery-macos-x86_64", label: "macOS x86_64 (Intel)" },
+    {
+        platform: "win32",
+        arch: "x64",
+        asset: "nmts-recovery-windows-x86_64.exe",
+        label: "Windows x86_64",
+    },
+];
+/** The checksum file the release attaches beside the executables. */
+export const SUMS_FILE = "SHA256SUMS";
+/** The one this machine can run, or null when the release publishes nothing for it. */
+export function executableFor(platform, arch) {
+    return PUBLISHED.find((e) => e.platform === platform && e.arch === arch) ?? null;
+}
+/** The published platforms, for telling somebody their own is not among them. */
+export function publishedLabels() {
+    return PUBLISHED.map((e) => e.label);
+}
+/**
+ * The exact commands that build this program from source.
+ *
+ * ⛔ EXACT, NOT "BUILD IT YOURSELF". Somebody reading this is on an unusual machine and has
+ *    already lost access to their files; "see the repository" is a research task, and three lines
+ *    they can paste is not.
+ */
+export function buildFromSource(sourceUrl) {
+    // The directory `git clone` makes is the last segment of the address, so it is read from the
+    // address rather than written again: the two cannot then disagree.
+    const cloned = sourceUrl.replace(/\/+$/, "").split("/").pop() ?? RECOVERY_TOOL;
+    return [`git clone ${sourceUrl}`, `cd ${cloned}/recovery`, `cargo build --release`];
+}
+/**
+ * What checking the bytes against SHA256SUMS shows, and what it does not.
+ *
+ * ⛔ BOTH SENTENCES, ALWAYS TOGETHER, AND WORDED ONCE. They are printed by the command and
+ *    repeated in the help text, and if they were written twice one copy would eventually start
+ *    promising more than the other. There is no "verified", no "trusted" and no "safe" in either
+ *    of them on purpose: a checksum published by the same release as the file it describes proves
+ *    the two agree, and nothing whatsoever about who produced them.
+ */
+export const CHECK_PROVES = `The check compares what arrived against the release's own ${SUMS_FILE}, which shows these ` +
+    `bytes are the bytes that release published.`;
+/** The other half. Never printed without the one above it. */
+export const CHECK_DOES_NOT_PROVE = `It does not show who published that release: anybody able to push a tag to that repository can ` +
+    `produce both the file and its line in ${SUMS_FILE}.`;
+/** `SHA256SUMS` for whatever the source repository's newest release is. */
+export function sumsUrl(sourceUrl) {
+    return `${sourceUrl.replace(/\/+$/, "")}/releases/latest/download/${SUMS_FILE}`;
+}
+/** One asset of one NAMED release. Never "latest": the tag is resolved once and then reused. */
+export function assetUrl(sourceUrl, tag, asset) {
+    return `${sourceUrl.replace(/\/+$/, "")}/releases/download/${encodeURIComponent(tag)}/${asset}`;
+}
+/**
+ * Tag names this accepts.
+ *
+ * ⛔ THE TAG COMES OFF THE WIRE AND GOES BACK INTO A URL, so its shape is checked rather than
+ *    trusted. A redirect that answered with `../../somewhere` would otherwise decide which path
+ *    the second request asks for.
+ */
+const TAG_SHAPE = /^[A-Za-z0-9._+-]+$/;
+/**
+ * The release tag a URL names, or null when it does not name one.
+ *
+ * Split into segments rather than matched with a regex because the file name can contain the
+ * characters a regex cares about (`nmts-recovery-windows-x86_64.exe`), and an escaping mistake
+ * there would be a silently looser check.
+ */
+export function tagFromUrl(url, filename) {
+    let segments;
+    try {
+        segments = new URL(url).pathname.split("/").filter((part) => part !== "");
+    }
+    catch {
+        return null;
+    }
+    const last = segments.length - 1;
+    if (last < 3)
+        return null;
+    const name = segments[last];
+    const tag = segments[last - 1];
+    if (name === undefined || tag === undefined)
+        return null;
+    if (segments[last - 2] !== "download" || segments[last - 3] !== "releases")
+        return null;
+    let decodedName;
+    let decodedTag;
+    try {
+        decodedName = decodeURIComponent(name);
+        decodedTag = decodeURIComponent(tag);
+    }
+    catch {
+        return null;
+    }
+    if (decodedName !== filename)
+        return null;
+    if (!TAG_SHAPE.test(decodedTag) || decodedTag.includes(".."))
+        return null;
+    return decodedTag;
+}
+/**
+ * The tag the redirect chain resolved to, or null.
+ *
+ * ⛔ THE WHOLE CHAIN, NOT THE LAST HOP. `…/releases/latest/download/SHA256SUMS` redirects to the
+ *    tagged address and that one redirects again to wherever the bytes are actually served from,
+ *    which carries no tag at all. Reading only where the chain ended would find nothing.
+ */
+export function tagFromChain(chain, filename) {
+    let found = null;
+    for (const url of chain) {
+        const tag = tagFromUrl(url, filename);
+        if (tag !== null)
+            found = tag;
+    }
+    return found;
+}
+/**
+ * The hash `SHA256SUMS` gives for one asset.
+ *
+ * ⛔ TWO LINES FOR ONE NAME IS A REFUSAL, NOT A FIRST-WINS. A file listed twice with different
+ *    hashes has no answer, and picking one would mean this command decides which of two claims to
+ *    act on. It has no basis for that, so it says so instead.
+ */
+export function hashFromSums(sums, asset) {
+    let found = null;
+    let repeated = false;
+    let malformed = false;
+    for (const raw of sums.split("\n")) {
+        // `sha256sum` writes "<hex>  <name>", with a `*` before the name when it read in binary mode.
+        const match = /^([0-9a-fA-F]+)[ \t]+\*?(.+)$/.exec(raw.trim());
+        if (match === null)
+            continue;
+        const hex = match[1];
+        const name = match[2];
+        if (hex === undefined || name === undefined)
+            continue;
+        if (name.trim() !== asset)
+            continue;
+        if (hex.length !== 64) {
+            malformed = true;
+            continue;
+        }
+        if (found !== null) {
+            repeated = true;
+            continue;
+        }
+        found = hex.toLowerCase();
+    }
+    if (repeated)
+        return { found: false, why: "repeated" };
+    if (found !== null)
+        return { found: true, hash: found };
+    if (malformed)
+        return { found: false, why: "malformed" };
+    return { found: false, why: "missing" };
+}
+/**
+ * Break one long sentence into lines a terminal will not fold in the middle of a word.
+ *
+ * ⚠ The two sentences above are written once, as prose, so the help text and the command cannot
+ *   drift apart. Prose has to be wrapped somewhere, and doing it here keeps the wording out of it.
+ */
+export function wrapText(text, width = 88) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ")) {
+        if (line === "")
+            line = word;
+        else if (line.length + 1 + word.length <= width)
+            line = `${line} ${word}`;
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line !== "")
+        lines.push(line);
+    return lines;
+}

package/dist/recovery-seq.js

@@ -0,0 +1,63 @@
+// Which recovery list this machine wrote last, so the next one gets a higher number.
+//
+// ⛔ WHY IT IS REMEMBERED HERE AND NOT ASKED FOR. The account's recorded sequence is reported by
+//    `GET /v1/account`, and that route is closed to an API key outright (`Reach::Never`) — it is
+//    the door that also deletes the account. So a tool holding a key cannot read the number it has
+//    to beat, and the only honest alternatives are to remember its own or to guess. It remembers.
+//
+// ⛔ WHAT THAT COSTS, SAID PLAINLY. A list written from a browser, or from another machine, moves
+//    the server's number without moving this one. The next run here then offers a number the
+//    server has already passed, the server refuses it — that is what its `seq` guard is for — and
+//    the refusal is reported rather than worked around. The attempt is recorded either way, so a
+//    second run offers a higher number and the two converge instead of looping.
+//
+// ⛔ IT IS NOT A SECRET AND IT IS STILL WRITTEN 0600. It holds an account id and a counter. The
+//    mode matches every other file this tool keeps beside it: one mode is easier to keep right
+//    than two.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir } from "./credentials.js";
+import { NmtsError } from "./errors.js";
+import { isRecord } from "./guards.js";
+/**
+ * Where one account's counter lives.
+ *
+ * ⛔ AN ACCOUNT ID BECOMES PART OF A PATH HERE, so it is CHECKED rather than trusted. Every id this
+ *    tool has comes from its own derivation and is base64url, but a value that reaches a path join
+ *    unchecked is how `..` becomes a write somewhere else, and the check costs one line.
+ */
+function seqPath(accountId) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(accountId)) {
+        throw new NmtsError("That is not an account id this tool derived.", {
+            nextStep: "Nothing was written. This is a fault in the tool rather than in the account.",
+        });
+    }
+    return join(configDir(), `recovery-seq-${accountId}.json`);
+}
+/** The highest sequence this machine has offered for an account, or 0 when it has offered none. */
+export function lastOfferedSeq(accountId) {
+    try {
+        const parsed = JSON.parse(readFileSync(seqPath(accountId), "utf8"));
+        if (!isRecord(parsed))
+            return 0;
+        const seq = parsed["seq"];
+        // A record that cannot be read counts as none, which is where a first run already stands.
+        return typeof seq === "number" && Number.isSafeInteger(seq) && seq > 0 ? seq : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Write down a sequence this machine OFFERED — whether or not the server took it.
+ *
+ * ⛔ OFFERED, NOT ACCEPTED, AND THAT IS THE POINT. Recording only the accepted ones would make a
+ *    refused number the number the next run offers again, and every run after it: the same
+ *    refusal for ever. Recording the attempt is what makes a second run get past it.
+ */
+export function rememberOfferedSeq(accountId, seq) {
+    if (seq <= lastOfferedSeq(accountId))
+        return;
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(seqPath(accountId), `${JSON.stringify({ seq }, null, 2)}\n`, { mode: 0o600 });
+}