@needmoretruth/nmts-cli 0.17.2

package/dist/recovery-source.js

@@ -0,0 +1,143 @@
+// Reading the account's storage dump — every live file and where its bytes are — one page at a time.
+//
+// ⛔ WHY A DUMP AND NOT THE ORDINARY LISTING. The drive listing is per folder and carries no
+//    storage parts; building a list from it would cost one request per folder plus one per file.
+//    This returns the whole account, parts included, 500 at a time.
+//
+// ⛔ EVERY PAGE CARRIES THE ACCOUNT PROOF. The route's verdict is `NeedsAccountProof`: an API key
+//    alone is refused, whatever its permissions. `account-proof.ts` says what the value is, why
+//    sending it is safe, and what it can still do if it is stolen.
+//
+// ⛔ NOTHING HERE TRUSTS THE ANSWER'S SHAPE. It arrives as `unknown` and is narrowed by predicates
+//    rather than asserted, because the whole point of the artefact being built from it is that the
+//    server may one day be hostile or broken. A row this cannot read is a refusal, never a skip: a
+//    list quietly missing a file tells somebody they are covered when they are not.
+//
+// ⚠ ITEMS CREATED DURING THE WALK may or may not appear, depending on where their id sorts. That
+//   is why the caller stamps the moment the walk BEGAN and sends that as the capture time — a file
+//   made while the pages were being read then counts as outside the list rather than falling into
+//   the gap between the two.
+import { request } from "./api.js";
+import { NmtsError } from "./errors.js";
+import { isRecord } from "./guards.js";
+import { plaintextLenFromSealed } from "./seal.js";
+/** `file_parts.storage_kind` for a quilt patch. 0 is a dedicated blob. */
+export const STORAGE_QUILT = 1;
+function unreadable(what) {
+    return new NmtsError(`The server described ${what} in a shape this version cannot read.`, {
+        exitCode: 1,
+        nextStep: "Nothing was written. Update this tool, or build the recovery list from the account " +
+            "screen in a browser — a list that skipped what it could not read would claim to cover " +
+            "files it does not.",
+    });
+}
+function str(row, name, what) {
+    const value = row[name];
+    if (typeof value !== "string" || value.length === 0)
+        throw unreadable(`${what} (${name})`);
+    return value;
+}
+function optionalStr(row, name) {
+    const value = row[name];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function whole(row, name, what) {
+    const value = row[name];
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        throw unreadable(`${what} (${name})`);
+    return value;
+}
+function partOf(value, itemId) {
+    if (!isRecord(value))
+        throw unreadable(`a stored part of file ${itemId}`);
+    const what = `a stored part of file ${itemId}`;
+    const sealedLen = whole(value, "sealed_len", what);
+    const part = {
+        part_index: whole(value, "part_index", what),
+        storage_kind: whole(value, "storage_kind", what),
+        blob_id: str(value, "blob_id", what),
+        sealed_len: sealedLen,
+        // Throws on a length no honest upload could have produced, which is exactly the number a
+        // recovery list must not record.
+        streamPlaintextLen: plaintextLenFromSealed(sealedLen),
+    };
+    const network = value["network"];
+    if (typeof network === "number" && Number.isSafeInteger(network))
+        part.network = network;
+    const patch = optionalStr(value, "patch_id");
+    if (patch !== undefined)
+        part.patch_id = patch;
+    const object = optionalStr(value, "sui_object_id");
+    if (object !== undefined)
+        part.sui_object_id = object;
+    return part;
+}
+function itemOf(value) {
+    if (!isRecord(value))
+        throw unreadable("a stored file");
+    const id = str(value, "id", "a stored file");
+    const parts = value["parts"];
+    if (!Array.isArray(parts))
+        throw unreadable(`the stored parts of file ${id}`);
+    const item = {
+        id,
+        size: whole(value, "size", `stored file ${id}`),
+        createdAt: str(value, "created_at", `stored file ${id}`),
+        updatedAt: str(value, "updated_at", `stored file ${id}`),
+        parts: parts.map((p) => partOf(p, id)),
+    };
+    const dek = optionalStr(value, "dek_wrapped");
+    if (dek !== undefined)
+        item.dekWrapped = dek;
+    const hash = optionalStr(value, "content_hash_ct");
+    if (hash !== undefined)
+        item.contentHashCt = hash;
+    return item;
+}
+/**
+ * Read every page of the dump, oldest cursor first.
+ *
+ * ⛔ A REPEATED CURSOR IS A REFUSAL, NOT A LOOP. The cursor is server-issued and strictly
+ *    increasing, but a bug — or a hand-edited answer — that repeated one would spin here forever
+ *    with nothing to show for it.
+ */
+export async function readAllRecoverySource(options) {
+    const items = [];
+    const seen = new Set();
+    let cursor;
+    do {
+        // ⚠ `after` IS ALWAYS SPELLED OUT, empty on the first page. The server reads an empty value as
+        //   "from the beginning" — and one shape for the address is what lets the route gate read this
+        //   call and compare it against what the server actually registers.
+        // ⚠ THE VALUE IS PREPARED OUTSIDE THE ADDRESS, and not for tidiness: `check:cli-routes` reads
+        //   the literal handed to `request` and its reader stops at a quote character, so a `""`
+        //   written inside the template would take this call out of the gate's sight entirely — the
+        //   exact failure that gate was built for. Proved by breaking the address and watching it go
+        //   red.
+        const after = cursor === undefined ? "" : cursor;
+        const answer = await request(options.server, `/v1/account/recovery-source?after=${encodeURIComponent(after)}`, { token: options.apiKey, accountProof: options.accountProof });
+        if (!isRecord(answer))
+            throw unreadable("this account's stored files");
+        const page = answer["items"];
+        if (!Array.isArray(page))
+            throw unreadable("this account's stored files");
+        for (const row of page)
+            items.push(itemOf(row));
+        options.onProgress?.(items.length);
+        const next = answer["next_cursor"];
+        if (next === undefined || next === null)
+            return items;
+        if (typeof next !== "string" || next.length === 0)
+            throw unreadable("the next page of files");
+        if (seen.has(next)) {
+            throw new NmtsError("The account's stored files repeated a page marker.", {
+                exitCode: 1,
+                nextStep: "Nothing was written. The listing cannot be read to the end, so a list built from it " +
+                    "would be missing files without saying so.",
+            });
+        }
+        seen.add(next);
+        cursor = next;
+    } while (cursor !== undefined);
+    return items;
+}

package/dist/registration.js

@@ -0,0 +1,83 @@
+// Making an account exist: the one derivation this tool performs that it does not keep.
+//
+// ⛔ WHY THIS IS NOT IN `account.ts`. That module's header says `authSecret` and `dataKey` are not
+//    exposed, and it is right to say so — `identityOf` hands back only the two public values.
+//    Registering a new account is the single call in this program that needs a THIRD one: the
+//    server has to be given `authSecret` so it can store the argon2id verifier of it, exactly as
+//    the browser does at sign-up (`web/src/lib/auth/account-service.ts`). Widening `identityOf`
+//    for that would have made a promise false everywhere it is read; a separate module keeps the
+//    exception in one file, next to the reason for it.
+//
+// ⛔ `authSecret` IS NOT THE ACCOUNT CODE AND CANNOT BE TURNED BACK INTO ONE. It is 32 bytes out
+//    of a one-way derivation (NCF-3 §1.2), it opens no file, and the same value goes over the
+//    wire on every sign-in the browser makes. What it can do is prove ownership, so it is built
+//    here, sent once, and never written down, printed or returned to a caller that did not ask.
+//
+// ⛔ THE DERIVED BUFFER IS WIPED. `kdf_derive` returns EVERY key in the account — the sign-in
+//    secret, the key that opens the files, the file-list key, the wallet root. Two public fields
+//    are copied out and the rest is zeroed before this returns, the same discipline `identityOf`
+//    keeps and for the same reason: a live copy of that buffer is a live copy of the account.
+import { DERIVED, loadCrypto } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+/**
+ * A brand-new account code, from the engine.
+ *
+ * ⛔ THE RETURNED STRING IS THE ONLY COPY THAT WILL EVER EXIST. The server keeps a verifier of a
+ *    value derived from it and nothing else, so a caller that loses this has destroyed an account
+ *    and nobody — not the holder, not NMTS — can bring it back. Every caller of this owes the
+ *    person a way to keep it before anything else happens.
+ *
+ * ⛔ AND THE RANDOMNESS IS THE ENGINE'S, NEVER NODE'S — the reason `generate_dek` gives, with more
+ *    at stake. These twenty bytes are the seed every key in an account descends from, so a second
+ *    source of them would be a source the conformance vectors say nothing about, in the one place
+ *    where a weak draw loses an entire account rather than one file. `crypto.ts` declares the
+ *    engine call; this is the only thing in the program that makes it.
+ */
+export async function newAccountCode() {
+    const glue = await loadCrypto();
+    const code = glue.account_code_generate();
+    if (typeof code !== "string" || code.length === 0) {
+        // ⛔ Refused rather than passed on. An empty code would be registered as a real account, and
+        //    the failure would surface much later as an account nobody can open.
+        throw new NmtsError("The NMTS crypto engine did not produce an account code.", {
+            exitCode: 1,
+            nextStep: "Nothing was created. Reinstall the package and try again.",
+        });
+    }
+    return code;
+}
+/**
+ * The pair the server is told about a code, derived here and nowhere else.
+ *
+ * ⚠ It re-parses the code rather than taking bytes: the parser checks the trailing check symbol,
+ *   so a code that arrived through anything but `newAccountCode` is refused before it is used to
+ *   claim an account id.
+ */
+export async function registrationProofOf(code) {
+    const glue = await loadCrypto();
+    let bytes;
+    try {
+        bytes = glue.account_code_parse(code);
+    }
+    catch {
+        // ⛔ The engine's own message is not repeated: it can contain the input, and the input is the
+        //    account code.
+        throw new NmtsError("That is not a valid NMTS account code.", {
+            exitCode: 2,
+            nextStep: "The last character is a check symbol, and it does not match the rest.",
+        });
+    }
+    const derived = glue.kdf_derive(bytes);
+    try {
+        const [idFrom, idTo] = DERIVED.accountId;
+        const [secretFrom, secretTo] = DERIVED.authSecret;
+        return {
+            accountId: Buffer.from(derived.slice(idFrom, idTo)).toString("base64url"),
+            authSecret: Buffer.from(derived.slice(secretFrom, secretTo)).toString("base64url"),
+        };
+    }
+    finally {
+        derived.fill(0);
+        bytes.fill(0);
+    }
+}

package/dist/s3/listing.js

@@ -0,0 +1,134 @@
+// The drive as an S3 client sees it: one bucket, and a key for every live file.
+//
+// ⛔ THE MAPPING IS THE WHOLE DESIGN, so it is written down here rather than spread across the
+//    server. A key is the file's path with the leading slash removed -- `photos/a.jpg` -- because
+//    that is what every S3 tool will put back on the disk when it syncs. Nothing else in this
+//    account's shape is exposed: not item ids, not the trash, not the marks.
+//
+// ⛔ TRASHED FILES ARE NOT KEYS. Being in the trash is inherited from a folder, so filtering on the
+//    entry's own field alone would list files whose bytes the server already refuses -- an S3 client
+//    would see them, ask for them, and get a failure for every one.
+//
+// ⚠ ONE DELIBERATE DIFFERENCE FROM S3: a folder holding no files still comes back as a common
+//   prefix. Real S3 has no folders, so an empty one cannot exist there; this drive does have them,
+//   and hiding them would make `rclone lsd` describe a drive that is not the one in the browser.
+import { buildIndex, fullPathOf, isLive, KIND_FOLDER } from "../drive-paths.js";
+/** The one bucket. Named for what it is, and not configurable: two names for one drive is worse. */
+export const BUCKET = "drive";
+/** S3's own ceiling, and the default when a client does not ask for one. */
+export const MAX_KEYS_LIMIT = 1000;
+/**
+ * An ETag that is stable for a file and changes when the file does.
+ *
+ * ⛔ IT ENDS IN `-1` FOR A REASON. S3 clients treat an ETag that looks like a hex digest as the
+ *    MD5 of the object and check downloads against it; this drive has no MD5 of anything -- the
+ *    bytes are encrypted before they leave the machine and the digest it does keep is a different
+ *    function. The `-N` suffix is S3's own mark for "assembled from parts, not an MD5", and every
+ *    client already knows to skip the check when it sees one. Without it a correct download is
+ *    reported as corrupt.
+ */
+export function etagOf(entry) {
+    const id = entry.id.replace(/[^0-9a-zA-Z]/g, "");
+    const stamp = entry.updatedAt.toString(16);
+    return `"${(id + stamp).slice(0, 32).padEnd(32, "0")}-1"`;
+}
+/** Every live file in the account, as keys, in the order S3 promises: ascending by key. */
+export function objectsOf(entries) {
+    const index = buildIndex(entries);
+    const rows = [];
+    for (const entry of entries) {
+        if (entry.kind === KIND_FOLDER)
+            continue;
+        if (!isLive(index, entry))
+            continue;
+        rows.push({
+            key: fullPathOf(index, entry).replace(/^\//, ""),
+            lastModified: new Date(entry.updatedAt).toISOString(),
+            etag: etagOf(entry),
+            size: entry.size,
+            entry,
+        });
+    }
+    rows.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    return rows;
+}
+/** Every live folder, as a key ending in the delimiter — see the note at the top of this file. */
+export function folderPrefixesOf(entries) {
+    const index = buildIndex(entries);
+    const out = [];
+    for (const entry of entries) {
+        if (entry.kind !== KIND_FOLDER)
+            continue;
+        if (!isLive(index, entry))
+            continue;
+        out.push(`${fullPathOf(index, entry).replace(/^\//, "")}/`);
+    }
+    return out;
+}
+/**
+ * Apply prefix, delimiter and paging the way `ListObjects` does.
+ *
+ * The rules are S3's: a key is returned whole unless it holds the delimiter after the prefix, in
+ * which case everything up to and including that delimiter becomes a common prefix and the key
+ * itself is not listed. Common prefixes and keys share one page budget and one cursor.
+ */
+export function listObjects(objects, folders, query) {
+    const maxKeys = Math.max(0, Math.min(query.maxKeys, MAX_KEYS_LIMIT));
+    const seenPrefix = new Set();
+    const rows = [];
+    for (const object of objects) {
+        if (!object.key.startsWith(query.prefix))
+            continue;
+        if (query.delimiter.length > 0) {
+            const rest = object.key.slice(query.prefix.length);
+            const at = rest.indexOf(query.delimiter);
+            if (at >= 0) {
+                const prefix = query.prefix + rest.slice(0, at + query.delimiter.length);
+                if (!seenPrefix.has(prefix)) {
+                    seenPrefix.add(prefix);
+                    rows.push({ sort: prefix, row: null, prefix });
+                }
+                continue;
+            }
+        }
+        rows.push({ sort: object.key, row: object, prefix: null });
+    }
+    // Folders that hold no listed file still belong in the answer — the note at the top says why.
+    if (query.delimiter.length > 0) {
+        for (const folder of folders) {
+            if (!folder.startsWith(query.prefix))
+                continue;
+            const rest = folder.slice(query.prefix.length);
+            const at = rest.indexOf(query.delimiter);
+            if (at < 0)
+                continue;
+            const prefix = query.prefix + rest.slice(0, at + query.delimiter.length);
+            if (seenPrefix.has(prefix))
+                continue;
+            seenPrefix.add(prefix);
+            rows.push({ sort: prefix, row: null, prefix });
+        }
+    }
+    rows.sort((a, b) => (a.sort < b.sort ? -1 : a.sort > b.sort ? 1 : 0));
+    const started = query.after === null ? rows : rows.filter((r) => r.sort > (query.after ?? ""));
+    const page = started.slice(0, maxKeys);
+    const truncated = started.length > page.length;
+    const last = page[page.length - 1];
+    // ⛔ Split in a loop rather than two filter-and-map passes: a `map` over a filtered array cannot
+    //    convince the type checker that the field is there, and the usual way round that is to invent
+    //    an empty row for a case that cannot happen — which is how an empty key reaches a client.
+    const contents = [];
+    const commonPrefixes = [];
+    for (const item of page) {
+        if (item.row !== null)
+            contents.push(item.row);
+        else if (item.prefix !== null)
+            commonPrefixes.push(item.prefix);
+    }
+    return {
+        contents,
+        commonPrefixes,
+        truncated,
+        next: truncated && last !== undefined ? last.sort : null,
+    };
+}

package/dist/s3/multipart.js

@@ -0,0 +1,104 @@
+// Uploads that arrive in pieces.
+//
+// ⛔ WHY IT IS NOT OPTIONAL. Every S3 client switches to this above a size of its own choosing --
+//    rclone's default is 200 MiB -- so a gateway without it works on small files and fails on the
+//    large ones, which is the half of a backup that matters most.
+//
+// ⛔ MEASURED FROM A REAL CLIENT, NOT FROM THE SPECIFICATION. What rclone actually sends is:
+//    `POST ?uploads=` to begin · `PUT ?partNumber=N&uploadId=…` for each piece, CONCURRENTLY AND
+//    OUT OF ORDER (1, 3, 2 in the capture) · `POST ?uploadId=…` carrying the part list to finish.
+//    The out-of-order part is the one a from-the-specification implementation gets wrong, because
+//    reading the spec top to bottom suggests a sequence.
+//
+// ⚠ THE PIECES ARE STAGED, and staging is the caller's business rather than this file's: this
+//   module speaks the protocol and the writer it is handed does the filesystem.
+import { isKeyConflict } from "./same-file.js";
+import { completeUploadXml, initiateUploadXml } from "./xml.js";
+/** S3's own ceiling, and a bound on what one client can stage on this machine. */
+export const MAX_PARTS = 10_000;
+/** True when this request belongs to a multipart upload rather than a plain object call. */
+export function isMultipartRequest(method, query) {
+    return query.has("uploads") || query.has("uploadId") || method === "POST";
+}
+function send(res, body) {
+    res.writeHead(200, {
+        "content-type": "application/xml",
+        "content-length": String(Buffer.byteLength(body)),
+    });
+    res.end(body);
+}
+/** Answer one multipart request. Returns false when the shape is not one this gateway knows. */
+export async function handleMultipart(context) {
+    const { method, query, writer, key, res, req } = context;
+    const staging = writer.multipart;
+    if (staging === undefined) {
+        context.fail(501, "NotImplemented", "This gateway does not stage multipart uploads.");
+        return true;
+    }
+    if (method === "POST" && query.has("uploads")) {
+        const uploadId = await staging.begin(key);
+        send(res, initiateUploadXml(context.bucket, key, uploadId));
+        context.log?.(`multipart begin ${key}`);
+        return true;
+    }
+    const uploadId = query.get("uploadId");
+    if (uploadId === null)
+        return false;
+    if (method === "PUT") {
+        const partNumber = Number(query.get("partNumber") ?? "");
+        if (!Number.isInteger(partNumber) || partNumber < 1 || partNumber > MAX_PARTS) {
+            context.fail(400, "InvalidPart", `A part number must be between 1 and ${MAX_PARTS}.`);
+            return true;
+        }
+        const size = Number(req.headers["content-length"] ?? "");
+        if (!Number.isInteger(size) || size < 0) {
+            context.fail(411, "MissingContentLength", "This gateway needs the part's size before it starts.");
+            return true;
+        }
+        try {
+            const etag = await staging.part(uploadId, partNumber, req, size, context.payloadHash);
+            res.writeHead(200, { etag, "content-length": "0" });
+            res.end();
+        }
+        catch (error) {
+            context.fail(400, "InvalidPart", error instanceof Error ? error.message : String(error));
+        }
+        return true;
+    }
+    if (method === "POST") {
+        // ⛔ THE PART LIST IN THE BODY IS NOT READ. It carries the tags this gateway itself handed back,
+        //    so believing it would be believing our own echo; what the file is made of is what was
+        //    staged, in part-number order. Reading it would only add a way to disagree with ourselves.
+        await drain(req);
+        try {
+            const etag = await staging.complete(uploadId);
+            send(res, completeUploadXml(context.bucket, key, etag));
+            context.log?.(`multipart complete ${key}`);
+        }
+        catch (error) {
+            // ⛔ A KEY THAT HOLDS A DIFFERENT FILE IS A 409, NOT A 500 — the request was well formed and
+            //    the drive declined it. Told 500, a sync tool retries the whole upload forever; told 409
+            //    it records a conflict and moves on. The verdict itself is the writer's (`same-file.ts`),
+            //    reached only once the pieces are one file, because until then there is nothing to hash.
+            if (isKeyConflict(error)) {
+                context.fail(409, "InvalidRequest", error instanceof Error ? error.message : String(error));
+            }
+            else {
+                context.fail(500, "InternalError", error instanceof Error ? error.message : String(error));
+            }
+        }
+        return true;
+    }
+    if (method === "DELETE") {
+        await staging.abort(uploadId);
+        res.writeHead(204);
+        res.end();
+        context.log?.(`multipart abort ${key}`);
+        return true;
+    }
+    return false;
+}
+async function drain(req) {
+    for await (const chunk of req)
+        void chunk;
+}

package/dist/s3/response-sink.js

@@ -0,0 +1,41 @@
+// Where a decrypted file goes when the reader is an HTTP client rather than a disk.
+//
+// ⛔ THE INTEGRITY PROMISE IS DIFFERENT HERE, AND THE DIFFERENCE IS SAID OUT LOUD. Every other sink
+//    in this tool makes a file visible only after the whole of it has been proved. A response
+//    cannot do that: S3 clients want the body to start arriving immediately, and the status line
+//    and length go out before the first byte. So bytes reach the client as they are decrypted, and
+//    the check at the end can no longer withhold them.
+//
+// ⛔ WHAT IT DOES INSTEAD: if anything fails after the response began, the connection is DESTROYED
+//    rather than ended. A client that was promised `Content-Length` bytes and gets fewer, with no
+//    clean end, reports a failed transfer — which is the truth. Ending the response normally would
+//    hand over a short file that every client would file away as complete.
+/** A sink that writes one file into an HTTP response and never leaves a short body looking whole. */
+export function responseSink(res, options) {
+    let started = false;
+    return {
+        expect(size) {
+            res.writeHead(200, { ...options.headers, "content-length": String(size) });
+            started = true;
+        },
+        async write(bytes) {
+            if (res.writableEnded || res.destroyed)
+                return;
+            await new Promise((resolve, reject) => {
+                res.write(bytes, (error) => (error === null || error === undefined ? resolve() : reject(error)));
+            });
+        },
+        async commit() {
+            if (res.destroyed)
+                return false;
+            await new Promise((resolve) => res.end(resolve));
+            return true;
+        },
+        async abandon() {
+            // Nothing was written yet: the caller can still answer with a proper S3 error document.
+            if (!started)
+                return;
+            res.destroy();
+        },
+    };
+}

package/dist/s3/same-file.js

@@ -0,0 +1,117 @@
+// Is the file arriving at this key the file already there?
+//
+// ⛔ WHY THE QUESTION IS ABOUT CONTENT AND NOT ABOUT NAMES. The gateway used to answer a taken key
+//    with 409 on the strength of the name alone. A backup program's whole job is to send the same
+//    names again, so every run failed on every file it had already stored — and a sync tool writes
+//    a 409 down as a failure, which is the wrong word for "it is already there".
+//
+// ⛔ WHAT IS COMPARED IS THE PLAINTEXT'S SHA-256, AND THE STORED COPY OF IT IS SEALED. Every
+//    upload already records one (`contentHashCt`, sealed under the account's data key), so nothing
+//    about the format changes here. It is sealed rather than stored bare for a reason worth
+//    repeating: a bare hash is the SAME NUMBER for everybody who holds that file, so a server
+//    keeping them could match its users against a published list of hashes. Sealed, only the
+//    account that wrote it can compare.
+//
+// ⛔ "REFUSE" MEANS THE UPLOAD, NOT THE REQUEST. Identical content is answered 200 with nothing
+//    sent and nothing charged, because from the client's side the statement "that file is at that
+//    key" is true. Only DIFFERENT content is a conflict.
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { AAD, DERIVED, loadCrypto } from "../crypto.js";
+import { objectsOf } from "./listing.js";
+import { NmtsError } from "../errors.js";
+/**
+ * Thrown when a key holds a DIFFERENT file. The gateway answers 409 rather than 500: the request
+ * was well formed and the drive declined it, which is what that status is for.
+ */
+export class KeyConflict extends NmtsError {
+    constructor(message) {
+        super(message);
+        this.name = "KeyConflict";
+    }
+}
+/** True when a thrown value is that refusal, without importing the class into the protocol layer. */
+export function isKeyConflict(error) {
+    return error instanceof Error && error.name === "KeyConflict";
+}
+/** The SHA-256 of a file on this machine, read in pieces so a large one costs no memory. */
+export async function hashOfFile(path) {
+    const digest = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        digest.update(chunk);
+    return new Uint8Array(digest.digest());
+}
+/**
+ * Open the hash this drive recorded for a file, with the account's own key.
+ *
+ * `null` when the entry carries none — files stored before the field existed do not have one, and
+ * that is a real state rather than an error. A hash that is present and will not open IS an error:
+ * it means the file list was written by another account or altered, and answering "no hash" there
+ * would quietly turn a tampered list into an upload.
+ */
+export async function recordedHash(accountCode, contentHashCt) {
+    if (contentHashCt === undefined || contentHashCt === "")
+        return null;
+    const crypt = await loadCrypto();
+    const [from, to] = DERIVED.dataKey;
+    const derived = crypt.kdf_derive(crypt.account_code_parse(accountCode));
+    const dataKey = derived.slice(from, to);
+    derived.fill(0);
+    try {
+        return crypt.envelope_open(dataKey, new TextEncoder().encode(AAD.contentHash), Buffer.from(contentHashCt, "base64url"));
+    }
+    catch {
+        throw new NmtsError("The recorded hash of the file at that key did not open with this account's key.", {
+            nextStep: "Either the file list belongs to another account, or it has been altered.",
+        });
+    }
+    finally {
+        dataKey.fill(0);
+    }
+}
+/**
+ * The whole question, for one key: what does this drive hold there, and is the file on disk it?
+ *
+ * ⛔ IT IS ONE FUNCTION SO THERE IS ONE ANSWER. Both ways of uploading — a single PUT, and pieces
+ *    staged and joined — reach the drive through the same store, and this is what that store asks.
+ *    Written at the two call sites instead, the two would differ the first time one of them
+ *    changed, and the difference would show up only above whatever size the client switches at.
+ *
+ * ⚠ THE FILE IS HASHED ONLY WHEN THE KEY IS TAKEN. An upload onto a free key is the common case
+ *   and pays nothing for this.
+ */
+export async function verdictForKey(entries, key, accountCode, path) {
+    const standing = objectsOf(entries).find((o) => o.key === key);
+    if (standing === undefined)
+        return "free";
+    return compare(await recordedHash(accountCode, standing.entry.contentHashCt), await hashOfFile(path));
+}
+/** The verdict, given what is on record and what arrived. */
+export function compare(recorded, arriving) {
+    if (recorded === undefined)
+        return "free";
+    if (recorded === null)
+        return "unknown";
+    if (recorded.length !== arriving.length)
+        return "differs";
+    for (let i = 0; i < recorded.length; i += 1) {
+        if (recorded[i] !== arriving[i])
+            return "differs";
+    }
+    return "same";
+}
+/**
+ * What to tell a client whose upload was declined.
+ *
+ * ⛔ IT NAMES WHICH OF THE TWO HAPPENED. "There is already a file there" is the same sentence for a
+ *    file that changed and for a file this drive cannot compare, and the two need different things
+ *    from the person reading the log.
+ */
+export function refusalFor(verdict, key) {
+    return new KeyConflict(verdict === "differs"
+        ? `A different file is already at ${key}, and this drive does not replace files. Delete it ` +
+            "first — a delete puts it in the trash, where it stays recoverable for thirty days."
+        : `A file is already at ${key} and this drive has no recorded hash for it, so it cannot tell ` +
+            "whether yours is the same one. Files stored before hashes were recorded are in this state. " +
+            "Delete it first if you mean to replace it.");
+}