@needmoretruth/nmts-cli 0.17.2

package/dist/rebuild.js

@@ -0,0 +1,255 @@
+// Building an account's sealed file list back out of the rows the server still holds.
+//
+// ⛔ AN ACCOUNT WITH NO FILE LIST IS NOT AN EMPTY ACCOUNT. Names, folders and every file's key
+//    live in one sealed blob the server cannot read. When that blob is missing — an account older
+//    than the list, or one whose first write never landed — the FILES are still there: the server
+//    keeps a row per stored file, and each row carries the wrapped key the file was committed
+//    with. So "no list" means "nothing can be named yet", never "nothing is stored".
+//
+// ⛔ WHAT COMES BACK, AND WHAT CANNOT. The server was deliberately made to forget names, folders
+//    and placement — that is the whole point of sealing the list — so a rebuild produces a FLAT
+//    drive of placeholder names. What it recovers is everything that cannot be recreated by hand:
+//      · the wrapped file key, without which the bytes are gone for good rather than merely unnamed
+//      · the sealed content hash, so a later download still verifies
+//      · the real dates, so "oldest first" still means something
+//      · the size, and whether the file was in the trash
+//    The trade is deliberate: a person retypes a name in seconds; nobody can regenerate a key.
+//
+// ⛔ NOTHING MAY BE DROPPED, SO A SHORT LISTING STOPS THE REBUILD. A page that could not be read,
+//    a cursor that repeats, or a listing longer than this will read are all refusals here. A
+//    rebuild that silently skipped rows would seal a list that is missing files, and every device
+//    would then agree those files do not exist — while the account goes on paying for them. An
+//    account left un-rebuilt is recoverable; a short list written over nothing is not.
+//
+// ⛔ THE TRASH IS PART OF IT. Trashed files are still stored, still charged for and still
+//    restorable, so a list built from the live rows alone would empty the trash of an account that
+//    rebuilt. ⚠ The server's trash view ends at the restore window: something thrown away longer
+//    ago than that is not in any listing this can read, and is counted and reported rather than
+//    passed over in silence.
+import { request } from "./api.js";
+import { NmtsError } from "./errors.js";
+import { KIND_FILE } from "./shared/lib/drive/manifest-index.js";
+import { uniqueFileName } from "./shared/lib/drive/unique-name.js";
+/**
+ * How many pages of one listing a rebuild will read.
+ *
+ * ⛔ THERE IS A CEILING BECAUSE A REBUILD MUST NOT RUN FOREVER, and there is a REFUSAL at the
+ *    ceiling because "absent from a listing that ran out of patience" is not "not stored". A
+ *    hundred rows a page puts this well past any drive a command-line tool is the right way to
+ *    manage; an account past it has to be rebuilt in a browser, which pages without a limit.
+ */
+const MAX_PAGES = 200;
+/**
+ * Stand-in name for a file the server can no longer name. Deliberately not a sentence and
+ * deliberately language-neutral: it sits in the field a person's own file names sit in, and the
+ * only thing to do with it is type over it.
+ */
+export function placeholderName(id) {
+    return `recovered-${id.replace(/-/g, "").slice(0, 8)}`;
+}
+/** RFC3339 → epoch ms. An unreadable stamp becomes 0: obviously wrong, and it still sorts. */
+function instant(iso) {
+    const ms = Date.parse(iso);
+    return Number.isFinite(ms) ? ms : 0;
+}
+function unreadable() {
+    throw new NmtsError("The server answered with an item listing this version cannot read.", {
+        exitCode: 4,
+        nextStep: "Nothing was written. A row this tool cannot read is a file it would leave out of the " +
+            "rebuilt list, so it stops instead. Update this tool, or rebuild the account in a browser.",
+    });
+}
+function stringField(row, name) {
+    const value = Reflect.get(row, name);
+    return typeof value === "string" ? value : unreadable();
+}
+/** A field that may be absent or null, and must be a string when it is neither. */
+function optionalString(row, name) {
+    const value = Reflect.get(row, name);
+    if (value === undefined || value === null)
+        return null;
+    return typeof value === "string" ? value : unreadable();
+}
+function itemFrom(row) {
+    if (typeof row !== "object" || row === null)
+        return unreadable();
+    const size = Reflect.get(row, "size");
+    if (typeof size !== "number" || !Number.isFinite(size))
+        return unreadable();
+    const deletedAt = optionalString(row, "deleted_at");
+    const dekWrapped = optionalString(row, "dek_wrapped");
+    const contentHashCt = optionalString(row, "content_hash_ct");
+    return {
+        id: stringField(row, "id"),
+        size,
+        createdAt: instant(stringField(row, "created_at")),
+        updatedAt: instant(stringField(row, "updated_at")),
+        ...(deletedAt === null ? {} : { deletedAt: instant(deletedAt) }),
+        ...(dekWrapped === null ? {} : { dekWrapped }),
+        ...(contentHashCt === null ? {} : { contentHashCt }),
+    };
+}
+/**
+ * What `GET /v1/items` answers, narrowed rather than trusted.
+ *
+ * ⛔ A ROW THIS CANNOT READ IS A REFUSAL, not a row to skip. Every row skipped here is a file that
+ *    would be missing from the sealed list, and a file missing from the list is one no device can
+ *    ever name or open again.
+ */
+function asItemsAnswer(value) {
+    if (typeof value !== "object" || value === null)
+        return unreadable();
+    const raw = Reflect.get(value, "items");
+    if (!Array.isArray(raw))
+        return unreadable();
+    const rows = raw;
+    const items = rows.map(itemFrom);
+    const next = Reflect.get(value, "next_cursor");
+    if (next !== null && next !== undefined && typeof next !== "string")
+        return unreadable();
+    return { items, next: typeof next === "string" && next !== "" ? next : null };
+}
+/**
+ * One page of the account's own items, live or trashed.
+ *
+ * ⚠ The four addresses are written out rather than built from a variable so that the gate
+ *   comparing this tool's addresses against the server's routes can see them. It reads literals.
+ */
+async function itemsPage(base, apiKey, trash, cursor) {
+    const after = cursor === null ? "" : `after=${encodeURIComponent(cursor)}`;
+    const answer = trash
+        ? await request(base, `/v1/items?deleted=true${after === "" ? "" : `&${after}`}`, { token: apiKey })
+        : await request(base, `/v1/items${after === "" ? "" : `?${after}`}`, { token: apiKey });
+    return asItemsAnswer(answer);
+}
+/**
+ * Read one whole listing, or refuse.
+ *
+ * ⛔ A REPEATED CURSOR IS A REFUSAL TOO. The cursor is the server's, and it is meant to move; one
+ *    that comes back a second time would spin this loop until the ceiling and then report an
+ *    account too large to rebuild, which is a lie about what went wrong.
+ */
+async function readListing(base, apiKey, trash, onProgress) {
+    const out = [];
+    const seenCursors = new Set();
+    let cursor = null;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const answer = await itemsPage(base, apiKey, trash, cursor);
+        // One at a time rather than a spread: a spread passes every element as a call ARGUMENT, and
+        // the largest account this ever meets must not be the one that overflows the stack.
+        for (const item of answer.items)
+            out.push(item);
+        onProgress?.(out.length);
+        if (answer.next === null)
+            return out;
+        if (seenCursors.has(answer.next)) {
+            throw new NmtsError("The server's item listing repeated a page marker.", {
+                exitCode: 4,
+                nextStep: "Nothing was written. A listing that does not move cannot be read to the end, and a " +
+                    "rebuild from a partial one would leave files out of the list for good.",
+            });
+        }
+        seenCursors.add(answer.next);
+        cursor = answer.next;
+    }
+    throw new NmtsError("This account has more stored files than one rebuild will read.", {
+        exitCode: 4,
+        nextStep: "Nothing was written. Rebuilding from a listing that stopped early would seal a list " +
+            "missing the files it never reached, and every device would then treat them as gone. " +
+            "Rebuild this account in a browser instead.",
+    });
+}
+/**
+ * Every id the server holds a row for, live or trashed, with no window on it.
+ *
+ * ⚠ THIS IS A CROSS-CHECK, NOT A SOURCE. It carries no keys, so nothing here can be rebuilt from
+ *   it — it exists to turn "some rows were not recovered" from something nobody notices into a
+ *   number printed before anybody agrees to anything. A listing that stops early makes the check
+ *   unavailable, which is reported as unknown rather than as zero.
+ */
+async function serverRowIds(base, apiKey) {
+    const ids = new Set();
+    let cursor = null;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const answer = cursor === null
+            ? await request(base, "/v1/objects", { token: apiKey })
+            : await request(base, `/v1/objects?after=${encodeURIComponent(cursor)}`, { token: apiKey });
+        if (typeof answer !== "object" || answer === null)
+            return null;
+        const raw = Reflect.get(answer, "objects");
+        if (!Array.isArray(raw))
+            return null;
+        const rows = raw;
+        for (const row of rows) {
+            if (typeof row !== "object" || row === null)
+                return null;
+            const id = Reflect.get(row, "id");
+            if (typeof id !== "string")
+                return null;
+            ids.add(id);
+        }
+        const next = Reflect.get(answer, "next_cursor");
+        if (typeof next !== "string" || next === "")
+            return ids;
+        cursor = next;
+    }
+    return null;
+}
+/**
+ * Turn the server's rows into entries.
+ *
+ * ⛔ EVERY REBUILT FILE SITS AT THE TOP OF THE DRIVE, because the server has no folder or parent
+ *    left to report and inventing one would be a guess presented as a memory.
+ *
+ * ⛔ AND NO TWO OF THEM SHARE A NAME. A placeholder is the first characters of an id, so two ids
+ *    can produce one name; in a drive addressed by path, two entries with the same path is a
+ *    lookup this tool refuses rather than resolves — a file nobody can fetch. Numbering the second
+ *    one costs nothing and the person is going to rename both anyway.
+ */
+export function entriesFrom(items) {
+    const taken = new Set();
+    return items.map((item) => {
+        const name = uniqueFileName(placeholderName(item.id), taken);
+        taken.add(name);
+        return {
+            id: item.id,
+            parentId: null,
+            kind: KIND_FILE,
+            name,
+            size: item.size,
+            createdAt: item.createdAt,
+            updatedAt: item.updatedAt,
+            ...(item.deletedAt === undefined ? {} : { deletedAt: item.deletedAt }),
+            ...(item.dekWrapped === undefined ? {} : { dekWrapped: item.dekWrapped }),
+            ...(item.contentHashCt === undefined ? {} : { contentHashCt: item.contentHashCt }),
+        };
+    });
+}
+/**
+ * Read the whole account and work out the list it would be sealed as. Writes nothing.
+ *
+ * ⛔ THE TRASH IS READ SECOND AND WINS A TIE. An item thrown away between the two listings comes
+ *    back in both; the trashed row is the newer truth, and taking the live one would resurrect
+ *    something the person had just thrown away.
+ */
+export async function rebuildFromServer(input) {
+    const live = await readListing(input.server, input.apiKey, false, input.onProgress);
+    const liveCount = live.length;
+    const trashed = await readListing(input.server, input.apiKey, true, (read) => input.onProgress?.(liveCount + read));
+    const byId = new Map();
+    for (const item of live)
+        byId.set(item.id, item);
+    for (const item of trashed)
+        byId.set(item.id, item);
+    const items = [...byId.values()];
+    const entries = entriesFrom(items);
+    const held = await serverRowIds(input.server, input.apiKey);
+    const unaccounted = held === null ? null : [...held].filter((id) => !byId.has(id)).length;
+    return {
+        entries,
+        live: items.filter((item) => item.deletedAt === undefined).length,
+        trashed: items.filter((item) => item.deletedAt !== undefined).length,
+        keyless: items.filter((item) => item.dekWrapped === undefined).length,
+        unaccounted,
+    };
+}

package/dist/recovery-assemble.js

@@ -0,0 +1,148 @@
+// The steps both recovery artefacts share: prove the code, read the account, seal the list.
+//
+// ⛔ ONE PLACE, BECAUSE THE TWO COMMANDS MUST NOT DISAGREE. `recovery-list` writes the sealed list
+//    as a file of its own; `kit` writes the same document inside the one file that also carries the
+//    account code. If those were assembled twice, one of them would eventually be built from a
+//    check the other had dropped — and the difference would only show up in a recovery.
+//
+// ⛔ THE CAPTURE TIME IS STAMPED BEFORE ANYTHING IS READ. The server keeps it to decide which files
+//    count as "not in your list yet". Stamped after the walk, it would leave a hole exactly the
+//    width of the walk: a file created while the pages were being read would be in neither the
+//    list nor the count. It is also clamped server-side, so claiming the future buys nothing.
+//
+// ⛔ THE DATA KEY IS DERIVED HERE AND WIPED HERE. It opens every file in the account; the
+//    derivation output it is cut from holds the wallet root and the sign-in secret as well, so it
+//    is zeroed on every path out, including the failing one.
+import { accountProofFor } from "./account-proof.js";
+import { request, ServerError } from "./api.js";
+import { DERIVED, loadCrypto } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+import { readFileList } from "./manifest.js";
+import { BINARY_NAME } from "./product.js";
+import { artifactAbout } from "./artifact-about.js";
+import { buildRecoveryList } from "./recovery-build.js";
+import { buildRecoveryMapFile } from "./recovery-map-file.js";
+import { recoveryDocMeta } from "./recovery-map.js";
+import { lastOfferedSeq, rememberOfferedSeq } from "./recovery-seq.js";
+import { readAllRecoverySource } from "./recovery-source.js";
+import { openSession } from "./session.js";
+import { AGGREGATOR_HOSTS, suiRpcHost } from "./walrus.js";
+/**
+ * Where the bytes this list points at live, for the sealed self-description.
+ *
+ * ⚠ `aggregators` AND `chain_rpc` ARE HINTS. They are the endpoints this build reads from today —
+ *   the first thing in the file to go stale — so a reader treats them as candidates AFTER its own
+ *   built-in defaults, never as instructions. `chain` is the one that changes behaviour: a blob id
+ *   from testnet and one from mainnet are the same kind of string, and without this a recovery has
+ *   to try both and let a wrong guess look like missing bytes.
+ */
+function storageFor(network) {
+    return {
+        network: "walrus",
+        chain: network,
+        aggregators: [...(AGGREGATOR_HOSTS[network] ?? [])],
+        chain_rpc: suiRpcHost(network),
+    };
+}
+export async function assembleRecoveryList(options = {}) {
+    // ⛔ BEFORE THE FIRST READ. Everything created from here on is outside this list.
+    const capturedAt = new Date().toISOString();
+    const session = await openSession({ server: options.server, network: options.network });
+    const proof = await accountProofFor({ code: session.code, source: session.source });
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (list.manifest === null) {
+        throw new NmtsError("This account has no file list, so nothing can be described.", {
+            exitCode: 4,
+            nextStep: `Nothing was written. A recovery list says what each stored file is CALLED and which key ` +
+                `opens it, and both come from the account's own file list — the storage network holds ` +
+                `neither. Run \`${BINARY_NAME} rebuild\` if this account has stored files but no list.`,
+        });
+    }
+    const source = await readAllRecoverySource({
+        server: session.server,
+        apiKey: session.apiKey,
+        accountProof: proof,
+        onProgress: options.onProgress,
+    });
+    const generatedAt = new Date().toISOString();
+    const seq = lastOfferedSeq(session.accountId) + 1;
+    const crypt = await loadCrypto();
+    const derived = crypt.kdf_derive(crypt.account_code_parse(session.code));
+    const [from, to] = DERIVED.dataKey;
+    const dataKey = derived.slice(from, to);
+    derived.fill(0);
+    let built;
+    try {
+        built = buildRecoveryList({
+            crypt,
+            dataKey,
+            accountId: session.accountId,
+            entries: list.manifest.entries,
+            source,
+            seq,
+            generatedAt,
+            meta: recoveryDocMeta(artifactAbout("recovery-list"), storageFor(session.network)),
+        });
+    }
+    finally {
+        dataKey.fill(0);
+    }
+    return {
+        session,
+        proof,
+        built,
+        seq,
+        capturedAt,
+        file: buildRecoveryMapFile({
+            accountId: session.accountId,
+            seq,
+            generatedAt,
+            // ⛔ READ BACK OUT OF THE DOCUMENT, not assumed. From NRM-3 on the number a document declares
+            //    depends on what is in it, and a wrapper that stated the newest version this build knows
+            //    would mislabel every ordinary file.
+            nrm: built.doc.v,
+            sealed: built.sealed,
+        }),
+    };
+}
+/**
+ * Tell the server a list was written, and what number it carries.
+ *
+ * ⛔ THE FILE FIRST, THE RECORD SECOND — so this takes the path that already exists. The record is
+ *    what makes an account screen say "your list is up to date"; saying that before the file
+ *    exists would be a claim about something that may never have been written.
+ *
+ * ⛔ `kind: "local"` AND NO BLOB ID. This tool keeps the list on the person's own disk and writes
+ *    no copy to the storage network, and the server refuses a blob id alongside `local` for
+ *    exactly that reason: a recorded address nothing was written to would let a screen advertise
+ *    a copy that does not exist.
+ *
+ * ⛔ THE ATTEMPT IS REMEMBERED WHETHER OR NOT IT LANDS. See `recovery-seq.ts`: a number the server
+ *    refused must not be the number the next run offers again, or the refusal repeats for ever.
+ */
+export async function recordRecoveryList(assembled, destination) {
+    const { session, seq } = assembled;
+    rememberOfferedSeq(session.accountId, seq);
+    try {
+        await request(session.server, "/v1/account/recovery-map", {
+            method: "PUT",
+            token: session.apiKey,
+            accountProof: assembled.proof,
+            body: { kind: "local", seq, captured_at: assembled.capturedAt },
+        });
+    }
+    catch (error) {
+        // ⛔ THE FILE IS GOOD AND THE RECORD IS NOT. Those are two different facts and the person needs
+        //    both, so this neither swallows the failure nor pretends the run succeeded.
+        if (error instanceof ServerError && error.code === "VERSION_CONFLICT") {
+            throw new NmtsError(`The file was written, and the server did not record it: ${error.message}`, {
+                exitCode: 4,
+                nextStep: `${destination} IS usable — keep it. What did not happen is the note on the server that ` +
+                    `says which list is newest, because this account already has one numbered ${seq} or ` +
+                    `higher: a browser or another machine wrote one this machine has not seen. This run has ` +
+                    `been remembered, so running the command again offers a higher number.`,
+            });
+        }
+        throw error;
+    }
+}

package/dist/recovery-build.js

@@ -0,0 +1,260 @@
+// Building one account's recovery list end to end: read the whole account, join it to the sealed
+// file list, check it against itself, seal it, and prove the sealed bytes open again.
+//
+// ⛔ IT NEVER PARTIALLY SUCCEEDS. If a page, a name or a key fails, the whole build fails. A list
+//    that quietly omits files tells somebody they are covered when they are not, and they find out
+//    on the one day it cannot be repaired.
+//
+// ⛔ IT DOES NOT TRUST THE ARRANGEMENT IT WAS HANDED. The storage parts come from a SERVER dump and
+//    this artefact exists for the day that server is hostile or gone, so a file's part numbering
+//    and its total length are checked against the account's own sealed file list before anything is
+//    sealed. Two checks are available to a builder that fetches no blob, and both are free:
+//      1. the numbering must be a complete 0…n-1 run. A repeated row, a gap, or a set shifted by
+//         one all break it, and none can be produced by an honest server.
+//      2. the parts must reconcile with the size in the sealed file list. That list is sealed under
+//         the account key and the server cannot write it, which is what makes the size the one
+//         number in the comparison an attacker does not control.
+//    Check 1 catches what leaves the total intact; check 2 catches what leaves the numbering
+//    intact. Neither proves that blob i really holds part i — only fetching it does, and the list
+//    records `part_index` so that whoever fetches it later can.
+//
+// ⛔ TWO SOURCES, JOINED ON ID. The server is asked only for what it still owns — a file's storage
+//    parts. Its NAME, its folder, its size and its key envelope come from the account's sealed file
+//    list, because that is the only place the tree exists.
+import { AAD, DERIVED } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+import { buildRecoveryListDoc, RecoveryListProblem, withTotals, } from "./recovery-map.js";
+import { STORAGE_QUILT } from "./recovery-source.js";
+import { NCF3_SHAPE } from "./seal.js";
+import { freeCeiling, keepLengths, padmeLen, pow2Len, } from "./shared/lib/crypto/size-padding.js";
+import { buildIndex, KIND_FOLDER, pathOf } from "./shared/lib/drive/manifest-index.js";
+import { NETWORK_WHEN_UNRECORDED, networkName, } from "./shared/lib/storage-network.js";
+import { CREDIT_BYTES } from "./upload-price.js";
+const utf8 = new TextEncoder();
+/** Path of the account root. Every file sits at this or below it. */
+export const ROOT_PATH = "/";
+/**
+ * A path segment that cannot break the `/a/b` encoding.
+ *
+ * ⛔ Folder names are people's text and may contain `/`. Left alone, a folder literally called
+ *    `a/b` is indistinguishable from two nested folders when a recovery splits the path, and the
+ *    file lands in the wrong place. The name itself is preserved exactly in the item's `name`.
+ *
+ * ⚠ RESTATED FROM `web/src/lib/recovery/paths.ts`, which this package cannot import. The
+ *   substitute character is part of what a reader sees, so it must be the same one.
+ */
+function segment(name) {
+    return name.replaceAll("/", "／");
+}
+/** Folder names, root-down, as the `/a/b` string the format stores. Empty means the root. */
+export function pathString(names) {
+    if (names.length === 0)
+        return ROOT_PATH;
+    return `/${names.map(segment).join("/")}`;
+}
+/**
+ * Every padded length THIS BUILD could have written for a part of `len` real bytes.
+ *
+ * ⛔ FOR THE WRITER ONLY. A READER must not enforce it: it may be years newer or older than the
+ *    build that sealed the part, and refusing a file because its padding follows a rule this copy
+ *    has not heard of turns a recovery into a refusal for no gain.
+ *
+ * # What it defends
+ * Before padding, the arithmetic was an equality — the parts had to sum to exactly the `size` in
+ * the sealed file list — and that is what caught a server inflating a length so a truncated file
+ * looked whole. Padding makes the last part's declared length legitimately larger, so the equality
+ * alone would read an inflated length as padding. Checking it against the finite set of numbers
+ * our own rules produce puts almost all of that back: an inflated length has to LAND on one.
+ *
+ * ⚠ RESTATED FROM `web/src/lib/crypto/padding.ts::paddingCandidates`. The rules themselves are not
+ *   restated — `padmeLen`, `pow2Len` and `freeCeiling` are the shared byte-for-byte copy.
+ */
+function couldBePadding(len, declared) {
+    const floor = freeCeiling(len, CREDIT_BYTES, NCF3_SHAPE);
+    const rules = [len, padmeLen(len), pow2Len(len)];
+    return [...rules, ...rules.map((r) => Math.max(r, floor))].includes(declared);
+}
+function describeAll(entries) {
+    const index = buildIndex(entries);
+    const out = new Map();
+    for (const entry of entries) {
+        out.set(entry.id, {
+            name: entry.name,
+            isFolder: entry.kind === KIND_FOLDER,
+            size: entry.size,
+            dekWrapped: entry.dekWrapped,
+            contentHashCt: entry.contentHashCt,
+            path: pathOf(index, entry),
+        });
+    }
+    return out;
+}
+/** base64url of the RAW bytes inside one envelope sealed under the account's data key. */
+function openRaw(crypt, dataKey, envelope, aad, what) {
+    let opened;
+    try {
+        opened = crypt.envelope_open(dataKey, utf8.encode(aad), Buffer.from(envelope, "base64url"));
+    }
+    catch {
+        // ⛔ The engine's own message is not repeated: it can quote what it was given.
+        throw new RecoveryListProblem(`${what} did not open with this account's key, so it cannot be written down. ` +
+            `The recovery list was not written.`);
+    }
+    try {
+        return Buffer.from(opened).toString("base64url");
+    }
+    finally {
+        opened.fill(0);
+    }
+}
+/** Build and seal the account's recovery list. Throws on any discrepancy; there is no partial list. */
+export function buildRecoveryList(input) {
+    const described = describeAll(input.entries);
+    const items = [];
+    let totalBytes = 0;
+    for (const stored of input.source) {
+        const about = described.get(stored.id);
+        // A stored file the list does not describe cannot be named or placed, and a list that omitted
+        // it would claim to cover an account it does not.
+        if (about === undefined) {
+            throw new RecoveryListProblem(`Stored file ${stored.id} is missing from your file list, so it cannot be described. ` +
+                `The recovery list was not written.`);
+        }
+        if (about.isFolder)
+            continue;
+        if (about.dekWrapped === undefined) {
+            throw new RecoveryListProblem(`Stored file ${stored.id} has no stored key, so it could never be opened again. ` +
+                `The recovery list was not written.`);
+        }
+        if (stored.parts.length === 0) {
+            throw new RecoveryListProblem(`Stored file ${stored.id} has no stored parts, so there would be nothing to fetch. ` +
+                `The recovery list was not written.`);
+        }
+        const ordered = [...stored.parts].sort((a, b) => a.part_index - b.part_index);
+        const misnumbered = ordered.findIndex((p, i) => p.part_index !== i);
+        if (misnumbered >= 0) {
+            throw new RecoveryListProblem(`Stored file ${stored.id} has a part numbered ${ordered[misnumbered]?.part_index} where ` +
+                `part ${misnumbered} should be, so its ${ordered.length} stored parts are not a ` +
+                `complete set. The recovery list was not written.`);
+        }
+        let keeps;
+        try {
+            keeps = keepLengths(about.size, ordered.map((p) => p.streamPlaintextLen));
+        }
+        catch {
+            // ⛔ THE SIZE IS NOT IN THE SENTENCE. A file's plaintext length is a value the server is not
+            //    told, and a message that printed it would put it in whatever the caller logs.
+            throw new RecoveryListProblem(`Stored file ${stored.id} has ${ordered.length} stored parts that do not add up to the ` +
+                `size in your file list. A part is missing, repeated, or the wrong length. ` +
+                `The recovery list was not written.`);
+        }
+        const parts = ordered.map((p, i) => {
+            const keep = keeps[i] ?? 0;
+            // ⭐ AND THE PADDING ITSELF HAS TO BE A NUMBER THIS BUILD COULD HAVE WRITTEN. Without this
+            //    the check above softens: an inflated last-part length reads as padding, and a truncated
+            //    file seals into a list that says the account is covered.
+            if (p.streamPlaintextLen > keep && !couldBePadding(keep, p.streamPlaintextLen)) {
+                throw new RecoveryListProblem(`Stored file ${stored.id} has a part ${i} whose stored stream is not padded by any rule ` +
+                    `this version writes. The recovery list was not written.`);
+            }
+            const part = {
+                blob_id: p.blob_id,
+                plaintext_len: keep,
+                // Every part names its network, even the default one: this is read years later by a tool
+                // that has only this document, and "it must have been the network that existed back then"
+                // is not something to make a stranger reason about.
+                network: nameOfNetwork(p, stored.id),
+            };
+            if (p.streamPlaintextLen > keep)
+                part.padded_len = p.streamPlaintextLen;
+            if (p.sui_object_id !== undefined)
+                part.sui_object_id = p.sui_object_id;
+            return part;
+        });
+        // A quilted file is one patch inside one shared blob — by construction one part — so the
+        // placement is read off that part rather than tracked separately.
+        const patch = ordered.find((p) => p.storage_kind === STORAGE_QUILT && p.patch_id !== undefined && p.patch_id.length > 0);
+        const item = {
+            id: stored.id,
+            name: about.name,
+            path: pathString(about.path),
+            size: about.size,
+            dek: openRaw(input.crypt, input.dataKey, about.dekWrapped, AAD.dekWrap, `the key of ${about.name}`),
+            // Straight from the dump: the one pair of values in an item that nothing here can check.
+            createdAt: stored.createdAt,
+            updatedAt: stored.updatedAt,
+            parts,
+        };
+        if (about.contentHashCt !== undefined) {
+            // RAW in this document on purpose: the live drive keeps it sealed so the server cannot use
+            // it as a cross-account fingerprint, and inside one authenticated envelope that precaution
+            // is redundant. Carrying it open is what lets a standalone tool check a reassembled file.
+            item.contentHash = openRaw(input.crypt, input.dataKey, about.contentHashCt, AAD.contentHash, `the content hash of ${about.name}`);
+        }
+        if (patch?.patch_id !== undefined) {
+            item.quilt = { quilt_blob_id: patch.blob_id, patch_id: patch.patch_id };
+        }
+        items.push(item);
+        totalBytes += about.size;
+    }
+    const doc = buildRecoveryListDoc({
+        seq: input.seq,
+        // ⛔ ALWAYS NULL FROM THIS TOOL. `prev_manifest_blob_id` chains MIRRORS: it is a storage-network
+        //    address, and a list written to somebody's own disk has none for a successor to point at.
+        //    `seq` still increases across every list of either kind, so "which is newest" stays
+        //    answerable; only "what came before it" is unavailable for the stretches never mirrored.
+        prevBlobId: null,
+        generatedAt: input.generatedAt,
+        accountId: input.accountId,
+        // Finished here because here is where they are first true: everything before this point could
+        // still throw, and a block claiming a count for a document that was never written would be the
+        // one kind of self-description worse than none.
+        meta: withTotals(input.meta, { items: items.length, bytes: totalBytes }),
+        items,
+    });
+    const json = JSON.stringify(doc);
+    const sealed = Buffer.from(input.crypt.envelope_seal(input.dataKey, utf8.encode(AAD.recoveryMap), utf8.encode(json))).toString("base64url");
+    // ⛔ READ IT BACK BEFORE ANYBODY IS TOLD IT EXISTS. Catches a truncated seal, a wrong key, and
+    //    any future change that returns something other than what it just sealed. Without it, "your
+    //    list covers 412 files" is an assumption rather than a measurement.
+    let reopened;
+    try {
+        reopened = input.crypt.envelope_open(input.dataKey, utf8.encode(AAD.recoveryMap), Buffer.from(sealed, "base64url"));
+    }
+    catch {
+        throw new NmtsError("The sealed recovery list did not open again on this machine.", {
+            exitCode: 1,
+            nextStep: "Nothing was written. This is a fault in the tool rather than in the account.",
+        });
+    }
+    if (Buffer.from(reopened).toString("utf8") !== json) {
+        throw new NmtsError("The sealed recovery list did not come back as what was sealed.", {
+            exitCode: 1,
+            nextStep: "Nothing was written. This is a fault in the tool rather than in the account.",
+        });
+    }
+    reopened.fill(0);
+    // ⛔ THE OTHER DIRECTION. A file the sealed list names that the dump never returned is not a
+    //    reason to refuse — but it is a reason not to call the account covered.
+    const returned = new Set(input.source.map((s) => s.id));
+    const missingFromSource = [...described.entries()]
+        .filter(([id, about]) => !about.isFolder && about.dekWrapped !== undefined && !returned.has(id))
+        .map(([id]) => id);
+    return { sealed, doc, fileCount: items.length, totalBytes, missingFromSource };
+}
+/**
+ * The NAME a list stores for a part's storage network. Refuses a code this build does not know.
+ *
+ * ⛔ NO NEAR MATCH. A code from a newer client means these bytes are somewhere this build cannot
+ *    name, and writing "walrus" anyway would send a future recovery to the wrong network with no
+ *    sign anything was wrong. An ABSENT field is a different matter: it predates the field and
+ *    really is Walrus.
+ */
+function nameOfNetwork(part, itemId) {
+    const name = networkName(part.network ?? NETWORK_WHEN_UNRECORDED);
+    if (name === null) {
+        throw new RecoveryListProblem(`Stored file ${itemId} is on storage network ${part.network}, which this version does not ` +
+            `know how to name. Update this tool and try again. The recovery list was not written.`);
+    }
+    return name;
+}