@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/s3/xml.d.ts

@@ -0,0 +1,28 @@
+/** The five characters XML cannot carry raw. */
+export declare function escapeXml(value: string): string;
+export declare function errorXml(code: string, message: string, resource: string): string;
+export declare function listBucketsXml(bucket: string, createdAt: string): string;
+export declare function initiateUploadXml(bucket: string, key: string, uploadId: string): string;
+export declare function completeUploadXml(bucket: string, key: string, etag: string): string;
+export interface ObjectRow {
+    readonly key: string;
+    readonly lastModified: string;
+    readonly etag: string;
+    readonly size: number;
+}
+export interface ListingXml {
+    readonly bucket: string;
+    readonly prefix: string;
+    readonly delimiter: string;
+    readonly maxKeys: number;
+    /** Version 2 of the listing call names its cursor differently and counts what it returned. */
+    readonly v2: boolean;
+    readonly contents: readonly ObjectRow[];
+    readonly commonPrefixes: readonly string[];
+    readonly truncated: boolean;
+    /** The cursor a client sends back to continue, when there is more. */
+    readonly next: string | null;
+    /** What the client asked to be url-encoded, or null when it asked for nothing. */
+    readonly encodingType: string | null;
+}
+export declare function listObjectsXml(listing: ListingXml): string;

package/dist/safe-path.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolve where one fetched file goes, refusing anything that leaves the chosen directory.
+ *
+ * ⛔ It takes only the LAST segment of the account path. A file called `../../etc/passwd` in
+ *    somebody's drive is a legal name for a file; it must not become a path on this disk. The
+ *    containment check that follows is belt as well as braces — `basename` already strips the
+ *    separators, and the check catches the day some platform disagrees about what a separator is.
+ *
+ * ⛔ IT IS ALSO WHAT KEEPS `-` FROM MEANING stdout ON THIS SERVER. `get` reads an `out` of exactly
+ *    `-` as "hand the file to whatever is reading stdout", and here that reader is the client's
+ *    protocol connection. Every answer this function gives has been through `resolve`, so it is
+ *    always an absolute path and never the bare `-`: a model asking for a file named `-` gets a
+ *    file named `-` inside the chosen directory, and the streaming branch is unreachable from
+ *    this server rather than merely unused by it.
+ */
+export declare function destinationFor(outDir: string, accountPath: string): string;
+/**
+ * Windows keeps a handful of names for devices, and writing to one succeeds while storing nothing.
+ *
+ * ⛔ THE FAILURE IS SILENT, WHICH IS WHY IT IS WORTH CODE. A drive holding a file called `NUL`
+ *    pulled onto Windows opens the null device: every byte is accepted, nothing is kept, and the
+ *    tool says it wrote the file. A name containing a colon is worse than silent — it writes an
+ *    alternate data stream on a DIFFERENT file, where nothing lists it. And a name ending in a dot
+ *    or a space is not the name it looks like: Win32 strips those before opening, so two files can
+ *    quietly become one.
+ *
+ * ⚠ The check is per PLATFORM, not universal. `NUL` is an ordinary, legal file name on Linux and
+ *   macOS, and refusing it there would take a file away from somebody who can hold it perfectly
+ *   well. The platform is a parameter so a test on any machine can ask the Windows question.
+ *
+ * Returns the reason it cannot be written, or null when it can.
+ */
+export declare function unwritableOn(name: string, platform: NodeJS.Platform): string | null;
+/**
+ * Refuse a name that this platform cannot hold, saying what to do about it.
+ *
+ * ⛔ A REFUSAL, NOT A RENAME. Renaming quietly would hand somebody a file under a name they did not
+ *    choose and cannot predict, and the one thing worse than not getting a file is thinking you got
+ *    it. The person can rename it in the drive, or name it themselves on the way out.
+ */
+export declare function refuseUnwritableName(name: string, platform?: NodeJS.Platform): void;

package/dist/seal.d.ts

@@ -0,0 +1,120 @@
+import type { CryptoGlue } from "./crypto.ts";
+/**
+ * How much of a file goes into ONE part, unless the caller says otherwise.
+ *
+ * ⛔ IT IS A MEMORY BOUND, NOT A PRODUCT LIMIT. Sealing holds a part's ciphertext, and the storage
+ *    network's erasure coding then expands it about fivefold while it computes the blob id — so a
+ *    part costs several times its own size in memory before a single byte is sent. The file itself
+ *    is never held: it is read a slice at a time.
+ *
+ * ⚠ THIS NUMBER USED TO BE THE WHOLE FILE'S CEILING, and keeping it as the part size is deliberate.
+ *   It means growing past one part cannot make an upload that worked yesterday run out of memory
+ *   today — the most memory this tool asks for is the same as it always was.
+ *
+ * Bigger parts mean fewer reservations, and every reservation counts against the account's daily
+ * spending allowance; smaller parts mean less memory and a shorter piece of work to lose when
+ * something goes wrong. `put --part-size` is how somebody picks a different trade.
+ */
+export declare const DEFAULT_PART_BYTES: number;
+/**
+ * What NCF-3 adds to a part's plaintext: a fixed header, and one tag per chunk.
+ *
+ * ⛔ NOT MEASURED, BECAUSE THE ONE CALLER NEEDS IT BEFORE SEALING: the price is quoted, and
+ *    `--dry-run` answers, without a very large file ever being read. A test seals real plaintexts
+ *    with the real engine and compares, so this is held against the format rather than against a
+ *    copy of these numbers.
+ */
+export declare const NCF3_SHAPE: {
+    readonly headerLen: 72;
+    readonly tagLen: 16;
+    readonly chunkSize: number;
+};
+/** How many bytes one sealed part of this plaintext length occupies. */
+export declare function sealedLenFor(plaintextLen: number): number;
+/**
+ * The plaintext length a sealed part of this size was sealed FROM.
+ *
+ * ⛔ WHY THE INVERSE EXISTS. The server is told what a part OCCUPIES and nothing about the file
+ *    behind it, and it is the only number it can serve back. A recovery list records the length
+ *    the stored stream DECLARES, because that is what a reader checks the fetched header against —
+ *    so somewhere the one number has to become the other, and this is that place. It sits beside
+ *    the forward arithmetic rather than in a module of its own so that the two can never be
+ *    changed apart.
+ *
+ * ⛔ IT REFUSES RATHER THAN ROUNDS. Every reachable sealed length has exactly one plaintext length
+ *    behind it, and the lengths between them are not reachable at all — a stream of n chunks ends
+ *    where the next one's first tag would begin. The one caller that matters is the recovery
+ *    list's own integrity check, where a lenient answer would be the failure it exists to catch.
+ *
+ * ⚠ RESTATED FROM `web/src/lib/crypto/sealed-size.ts::plaintextLenFromSealed`, which this package
+ *   cannot import (zero imports across the two trees). Only the SEARCH is restated: each candidate
+ *   is confirmed with `chunkCount` from the shared byte-for-byte copy, so the formula itself still
+ *   lives in one file.
+ */
+export declare function plaintextLenFromSealed(sealedLen: number): number;
+/** Everything an upload needs about one file, and nothing that identifies it. */
+export interface SealedFile {
+    /** The complete NCF-3 stream — header, chunks, end mark. These are the bytes that get stored. */
+    sealed: Uint8Array;
+    /** The file's own key wrapped under the account's data key (base64url envelope). */
+    dekWrapped: string;
+    /** SHA-256 of the plaintext, sealed under the account's data key (base64url envelope). */
+    contentHashCt: string;
+    /** Plaintext length — what the file list records, and what a reader reassembles to. */
+    plaintextLen: number;
+    /** Sealed length — what the server is told, what storage is bought for, what credits count. */
+    sealedLen: number;
+}
+/** The three secrets a file carries, made once and reused by every one of its parts. */
+export interface FileSecrets {
+    /**
+     * The file's own key, raw.
+     *
+     * ⛔ THE CALLER WIPES IT. Every part of a file is sealed under this one key, so it has to outlive
+     *    the first part — which means nothing here can wipe it, and the loop that uses it must.
+     */
+    dek: Uint8Array;
+    /** The same key wrapped under the account's data key (base64url envelope). */
+    dekWrapped: string;
+    /** The plaintext's SHA-256, sealed under the account's data key (base64url envelope). */
+    contentHashCt: string;
+}
+/**
+ * Make a file's key and seal the hash of its contents.
+ *
+ * ⛔ THE HASH IS OF THE PLAINTEXT, AND IT IS SEALED RATHER THAN STORED BARE. A bare content hash
+ *    identifies the file itself: it is the same number for everyone who holds that file, and it is
+ *    matchable against published hash sets. Sealed, it is checkable only by the account that wrote
+ *    it — which is the only party that needs to check it.
+ *
+ * `contentDigest` is the SHA-256 of the whole plaintext, which the caller computes while reading
+ * the file. Passing it in rather than the file is what lets this work for a file too large to hold.
+ */
+export declare function fileSecrets(crypt: CryptoGlue, dataKey: Uint8Array, contentDigest: Uint8Array): FileSecrets;
+/**
+ * Seal ONE part of a file, reading its plaintext as it goes.
+ *
+ * ⛔ A FRESH SESSION, AND THEREFORE A FRESH NONCE, EVERY TIME. The format requires each part to be
+ *    its own stream under its own nonce prefix; the engine allocates one inside the session and
+ *    there is no way from here to reuse one. That is the property that makes a re-sealed part a
+ *    DIFFERENT blob — which is exactly why a resumed upload pushes the bytes it wrote down rather
+ *    than sealing again.
+ *
+ * ⛔ THE DECLARED LENGTH IS CHECKED AGAINST WHAT ARRIVES. The engine refuses to finish a stream
+ *    that was fed too little; too much is caught here. A part whose header declares a length its
+ *    bytes do not match is a file that reassembles wrong, and the reader would not find out until
+ *    the download.
+ */
+export declare function sealPart(crypt: CryptoGlue, dek: Uint8Array, chunks: AsyncIterable<Uint8Array>, placement: {
+    index: number;
+    total: number;
+    plaintextLen: number;
+}): Promise<Uint8Array>;
+/**
+ * Seal a whole file held in memory, as one part.
+ *
+ * ⛔ THE DATA KEY IS BORROWED, NOT KEPT. The caller derived it and the caller wipes it; this
+ *    function does not hold a reference past its own return. The file key it makes IS wiped here,
+ *    because nothing outside needs it — the wrapped copy is what travels.
+ */
+export declare function sealFile(crypt: CryptoGlue, dataKey: Uint8Array, plaintext: Uint8Array): Promise<SealedFile>;

package/dist/secret-reader.d.ts

@@ -0,0 +1,28 @@
+export type SecretStep = {
+    kind: "more";
+} | {
+    kind: "done";
+    value: string;
+} | {
+    kind: "cancelled";
+};
+/**
+ * Accumulates typed bytes into a secret.
+ *
+ * ⛔ `wipe()` is separate from `take()` on purpose: the caller reads the value and only then
+ *    clears the buffer. Doing both in one step is what produced the NUL-run defect this file
+ *    exists to make impossible.
+ */
+export declare class SecretReader {
+    #private;
+    /** Bytes that arrived after the answer ended, for the prompt that comes next. */
+    takeLeftover(): Uint8Array;
+    /** Feed one chunk. Returns what the caller should do next. */
+    push(chunk: Uint8Array): SecretStep;
+    /** The value typed so far, with surrounding spaces removed. Clears the buffer. */
+    take(): string;
+    /** Drop the bytes without reading them. */
+    wipe(): void;
+    /** How many bytes are held. For tests; never printed. */
+    get length(): number;
+}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_SERVER = "https://nmts.me";
+export declare const SERVER_ENV_VAR = "NMTS_SERVER";
+/**
+ * Resolve the server for this run: an explicit argument, then the environment, then the default.
+ *
+ * ⛔ Refuses anything that is not http(s). A credential is sent to whatever this returns, so a
+ *    typo that lands on another scheme must stop here rather than somewhere further in.
+ */
+export declare function resolveServer(explicit?: string | undefined): string;

package/dist/session.d.ts

@@ -0,0 +1,32 @@
+import { type CredentialSource } from "./credentials.ts";
+export interface Session {
+    /** The NMTS key. ⛔ Held for the command's own work and never written anywhere. */
+    code: string;
+    /**
+     * Where this machine got that code from.
+     *
+     * ⛔ CARRIED BECAUSE ONE THING A COMMAND DOES WITH THE CODE STILL NEEDS AN AGREEMENT. Sending
+     *    the account proof (`account-proof.ts`) is that thing, and the agreement it asks for —
+     *    `plain-env` — is about WHERE the code came from, not what is being done with it. A session
+     *    that dropped this would leave the deciding module unable to tell a sealed stored code from
+     *    an environment variable, and its only options would be to ask always or to ask never.
+     */
+    source: CredentialSource;
+    apiKey: string;
+    server: string;
+    network: string;
+    accountId: string;
+}
+/**
+ * The API key, or the one refusal for not having one.
+ *
+ * ⛔ IT IS ITS OWN FUNCTION BECAUSE ONE COMMAND NEEDS THE KEY AND NOT THE CODE. `verify` asks the
+ *    server about the account and opens no file, so making it resolve an NMTS key would refuse
+ *    a run over a credential it never uses — and wording that refusal a second time is exactly how
+ *    two texts for one problem start.
+ */
+export declare function requireApiKey(): string;
+export declare function openSession(options: {
+    server?: string | undefined;
+    network?: string | undefined;
+}): Promise<Session>;

package/dist/session.js

@@ -15,7 +15,7 @@ import { resolveServer } from "./server.js";
  * The API key, or the one refusal for not having one.
  *
  * ⛔ IT IS ITS OWN FUNCTION BECAUSE ONE COMMAND NEEDS THE KEY AND NOT THE CODE. `verify` asks the
- *    server about the account and opens no file, so making it resolve an account code would refuse
+ *    server about the account and opens no file, so making it resolve an NMTS key would refuse
  *    a run over a credential it never uses — and wording that refusal a second time is exactly how
  *    two texts for one problem start.
  */

package/dist/setup-questions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The one question setup asks about uploads.
+ *
+ * ⛔ CALL THIS OUTSIDE `holdTerminal`. Inside it the terminal is in raw mode, where a line prompt
+ *    never sees a line.
+ */
+export declare function askAboutCollisions(say: (line: string) => void): Promise<void>;

package/dist/share.d.ts

@@ -0,0 +1,108 @@
+import { type CryptoGlue } from "./crypto.ts";
+/**
+ * This account's sharing secrets, and the identity other people encrypt to.
+ *
+ * ⛔ THE CALLER WIPES IT. Three of these are secrets sliced out of the account's derivation, and
+ *    they open every share this account has ever received. `wipe()` on every path out, including
+ *    failures.
+ */
+export interface ShareKeys {
+    /** Key-agreement seed. */
+    kemSeed: Uint8Array;
+    /** Proves this account SENT a share. */
+    authSecret: Uint8Array;
+    /** Signs the published identity. */
+    sigSeed: Uint8Array;
+    /** This account's 16-byte public code, in its wire form. */
+    address: Uint8Array;
+    /** The published identity bundle other people encrypt to. */
+    identity: Uint8Array;
+    /** The address in the form a person reads and types. */
+    display: string;
+    wipe(): void;
+}
+/** Derive everything sharing needs from an NMTS key. */
+export declare function shareKeysOf(crypt: CryptoGlue, code: string): ShareKeys;
+/** The three sealed fields a share carries, base64url, exactly as they go to the server. */
+export interface SharePayload {
+    dek_share_ct: string;
+    name_share_ct: string;
+    content_hash_share_ct: string;
+}
+/**
+ * Seal one file for one recipient.
+ *
+ * `recipientIdentity` is checked against `recipientAddress` inside the engine before anything is
+ * encrypted to it — length, fingerprint, self-signature and key decoding — which is why both are
+ * arguments and why there is no form of this that takes the identity alone. A tool that fetched an
+ * identity and wrapped to it without naming the address it asked for would hand a readable key to
+ * whoever answered.
+ */
+export declare function sealShare(crypt: CryptoGlue, input: {
+    keys: ShareKeys;
+    recipientIdentity: Uint8Array;
+    recipientAddress: Uint8Array;
+    /** The file's own key, already unwrapped from the account's sealed list. */
+    dek: Uint8Array;
+    /** The file's id, exactly as it will be posted. */
+    itemId: string;
+    /** The name the recipient sees, and the file's real plaintext length. */
+    name: string;
+    size: number;
+    /** The file's whole-plaintext digest, opened from the account's own sealed copy. */
+    digest: Uint8Array;
+}): SharePayload;
+/** One row of what somebody shared with this account, as the server describes it. */
+export interface ReceivedRow {
+    id: string;
+    item_id: string;
+    /** Bytes on the storage network — NOT the file's length. The sealed document has that. */
+    size: number;
+    sender_public_key?: string;
+    dek_share_ct: string;
+    name_share_ct: string;
+    content_hash_share_ct: string;
+    created_at: string;
+}
+/** What a received share turns into once opened, or why it could not be. */
+export interface OpenedShare {
+    id: string;
+    itemId: string;
+    createdAt: string;
+    /** The file's name as the sender sealed it, or null when the row would not open. */
+    name: string | null;
+    /** The file's real plaintext length, when the sender recorded one. */
+    size: number | null;
+    /** The sender's address, in readable form — only ever set when the open SUCCEEDED. */
+    sender: string | null;
+    /** The file's own key. Present only when it opened; the caller wipes it. */
+    dek: Uint8Array | null;
+    /** The sealed digest, carried through so a download can check the bytes. */
+    digestCt: string;
+    /** Why it did not open, for a row that must still be listed. */
+    problem: string | null;
+}
+/**
+ * Open one received share.
+ *
+ * ⛔ A ROW THAT WILL NOT OPEN IS STILL RETURNED. Dropping it would tell the account it was sent
+ *    less than it was, and the honest answer to "this one will not open" is to say so on its own
+ *    line — not to leave a gap somebody has no way to notice.
+ */
+export declare function openReceived(crypt: CryptoGlue, keys: ShareKeys, row: ReceivedRow): OpenedShare;
+/** The digest a recipient checks the downloaded bytes against. */
+export declare function openSharedDigest(crypt: CryptoGlue, dek: Uint8Array, digestCt: string): Uint8Array | null;
+/**
+ * Turn what a person typed into the 16 bytes behind a public code.
+ *
+ * ⛔ A TYPO FAILS HERE, NOT AS A LOOKUP. Sending a mistyped address to the server would ask it a
+ *    question about somebody who might exist, and the answer is not ours to collect.
+ */
+export declare function addressFromTyped(crypt: CryptoGlue, typed: string): Uint8Array;
+/**
+ * Check that an identity the server handed back is the one that was asked for.
+ *
+ * The engine checks this again inside the wrap, and this exists so the refusal says WHICH thing
+ * was wrong rather than failing inside a sealing step.
+ */
+export declare function identityMatches(crypt: CryptoGlue, identity: Uint8Array, address: Uint8Array): boolean;

package/dist/share.js

@@ -24,7 +24,7 @@ const encoder = new TextEncoder();
 const ENVELOPE_LEN = 1240;
 const DIGEST_ENVELOPE_LEN = 104;
 const IDENTITY_LEN = 4989;
-/** Derive everything sharing needs from an account code. */
+/** Derive everything sharing needs from an NMTS key. */
 export function shareKeysOf(crypt, code) {
     const derived = crypt.kdf_derive(crypt.account_code_parse(code));
     const slice = (range) => derived.slice(range[0], range[1]);

package/dist/shared/lib/crypto/size-padding.d.ts

@@ -0,0 +1,55 @@
+/**
+ * How coarsely a stored length is rounded up.
+ *
+ * `"none"` does not round at all: the sealed length IS the real one, so the stored stream states
+ * the file's exact size. It is a choice somebody makes with what it costs them written beside it
+ * (2026-09-06) — never a default, and never what an unrecognised spelling falls back to.
+ */
+export type PaddingRule = "padme" | "pow2" | "none";
+/**
+ * Padmé: round up to a multiple of 2^(E−S), where E = floor(log2 L) and S = floor(log2 E)+1.
+ *
+ * About 32 possible lengths per doubling, for roughly 1% more storage. Lengths below 4 are
+ * returned unchanged — the step there would be a single byte, which hides nothing.
+ */
+export declare function padmeLen(len: number): number;
+/** The next power of two at or above `len`: one possible length per doubling. Below 2, unchanged. */
+export declare function pow2Len(len: number): number;
+/** What sealing costs: a fixed header, plus one authentication tag per chunk. */
+export interface SealingShape {
+    headerLen: number;
+    tagLen: number;
+    chunkSize: number;
+}
+/** Chunks a stream of this plaintext length splits into. Empty is one chunk, not zero. */
+export declare function chunkCount(plaintextLen: number, shape: SealingShape): number;
+/** How many bytes one sealed stream of this plaintext length occupies. */
+export declare function sealedLenFor(plaintextLen: number, shape: SealingShape): number;
+/**
+ * The largest plaintext length whose sealed stream still fits inside bytes already paid for.
+ *
+ * Storage for a file of its own is charged in whole units, so every byte between the real sealed
+ * length and the next unit boundary has already been bought. Filling them is the one padding that
+ * costs nothing at all, which is why it applies before any rule and whichever rule was chosen.
+ *
+ * `unitBytes` is the billing unit. Pass 0 when the bytes are not billed that way — a file sharing a
+ * stored object with others is billed alongside them, and there is no free room to claim.
+ */
+export declare function freeCeiling(len: number, unitBytes: number, shape: SealingShape): number;
+/**
+ * The plaintext length to seal a final part from. Never smaller than `len`.
+ *
+ * ⛔ FINAL PART ONLY — see the module note.
+ */
+export declare function paddedPlaintextLen(len: number, rule: PaddingRule, options: {
+    unitBytes: number;
+    shape: SealingShape;
+}): number;
+/**
+ * Each part's REAL contributed length, from the file's real size and what each stored stream
+ * declares. The read side of the same contract, and the only place that arithmetic is written.
+ *
+ * Throws rather than repairing. Numbers that do not reconcile would hand back a file with bytes
+ * missing or padding in the middle of it, and neither announces itself afterwards.
+ */
+export declare function keepLengths(size: number, streamLens: readonly number[]): number[];

package/dist/shared/lib/crypto/size-padding.js

@@ -84,6 +84,11 @@ export function paddedPlaintextLen(len, rule, options) {
     if (!Number.isSafeInteger(len) || len < 0) {
         throw new RangeError(`padded length needs a non-negative safe integer, got ${len}`);
     }
+    // ⛔ `none` RETURNS THE LENGTH ITSELF, THE FREE FLOOR INCLUDED. Filling out bytes already paid
+    //    for costs nothing, but it still rounds — and a person who asked to store their exact size
+    //    and got the next billing boundary instead was told one thing and given another.
+    if (rule === "none")
+        return len;
     const byRule = rule === "pow2" ? pow2Len(len) : padmeLen(len);
     return Math.max(len, byRule, freeCeiling(len, options.unitBytes, options.shape));
 }

package/dist/shared/lib/drive/manifest-chunks.d.ts

@@ -0,0 +1,95 @@
+import { manifestFingerprint, type AccountSettings, type Manifest, type ManifestEntry } from "./manifest-codec.ts";
+/**
+ * Envelope AAD for ONE CHUNK of the chunked file list (NCF-3 §2, §6.3). Its own label, distinct
+ * from `AAD_FILE_LIST`, so a chunk can never be presented as an index or an index as a chunk —
+ * the server holds both as opaque bytes of the same shape.
+ */
+export declare const AAD_FILE_LIST_CHUNK = "nmts/v3/file-list-chunk";
+/** The version an index and its chunks carry. Version 1 is the single blob `manifest-codec` reads. */
+export declare const FILE_LIST_VERSION_CHUNKED = 2;
+/** Compression flag 0x02 — zstd (NCF-3 §6.3.4). 0x00 and 0x01 are `manifest-codec`'s. */
+export declare const FLAG_ZSTD = 2;
+/**
+ * The plaintext bound for ONE CHUNK (NCF-3 §6.3.3).
+ *
+ * On the PLAINTEXT and not on the sealed size, so a writer can decide where to close a chunk
+ * before it compresses or seals anything: 3,900,000 bytes plus the flag byte plus the 72-byte
+ * envelope is under the server's 4 MiB ceiling by construction, and a compressed chunk is smaller
+ * still. The unused remainder is left unused — an entry is never split across two chunks.
+ */
+export declare const CHUNK_PLAIN_MAX = 3900000;
+/**
+ * The plaintext bound for the INDEX.
+ *
+ * The index sits where the single blob sat, so it inherits that ceiling (16 MiB sealed · §8.291).
+ * It holds one ~110-byte row per chunk plus the account settings, so nothing an account can do
+ * brings it near this; the number exists so a reader has a bound to check a compressed frame
+ * against instead of trusting what the frame claims about itself.
+ */
+export declare const INDEX_PLAIN_MAX = 15000000;
+/** One row of the index: a chunk's name and the range of entries it holds. */
+export interface ManifestChunkRef {
+    /** base64url SHA-256 of THIS CHUNK's transport string — its name and its pin. */
+    h: string;
+    /** How many entries it holds. */
+    n: number;
+    /** Placement key of its first entry (`manifest-pack.ts`). */
+    f: string;
+    /** Placement key of its last entry. */
+    l: string;
+}
+/** The index — everything version 1 kept except the entries themselves (NCF-3 §6.3.1). */
+export interface ManifestIndexV2 {
+    v: typeof FILE_LIST_VERSION_CHUNKED;
+    /** The store version this index was sealed at, as §6.1. */
+    seq: number;
+    /** base64url SHA-256 of the parent INDEX's transport string; absent at version 1. */
+    p?: string;
+    /** Account-level settings, moved here from beside the entries. */
+    settings?: AccountSettings;
+    /** In placement order. Empty for an account with no items. */
+    chunks: readonly ManifestChunkRef[];
+}
+/** One chunk (NCF-3 §6.3.2). Immutable: an edit produces a new chunk with a new hash. */
+export interface ManifestChunkDoc {
+    v: typeof FILE_LIST_VERSION_CHUNKED;
+    /**
+     * The index version this chunk was written FOR — not the current one. A chunk untouched for a
+     * hundred saves still says the version that made it, and that is correct: the index is what says
+     * which chunks make up version 141.
+     */
+    seq: number;
+    /** Entries exactly as version 1 carried them, in placement order. */
+    items: readonly ManifestEntry[];
+}
+/** What a sealed file-list blob turned out to be. The reader decides by `v`, never by guessing. */
+export type FileListDocument = {
+    v: 1;
+    manifest: Manifest;
+} | {
+    v: typeof FILE_LIST_VERSION_CHUNKED;
+    index: ManifestIndexV2;
+};
+/**
+ * A chunk's name. The SAME function the parent link uses, deliberately: both commit to the
+ * base64url transport string rather than the bytes it encodes, because the string is what travels
+ * and the encoding is canonical (fixed alphabet, no padding, one string per byte sequence).
+ */
+export declare const chunkFingerprint: typeof manifestFingerprint;
+/** The index → the plaintext to seal under `AAD_FILE_LIST`. */
+export declare function encodeIndex(index: ManifestIndexV2): Promise<Uint8Array>;
+/** Sealed plaintext → the index. Throws `ManifestFormatError` on anything it cannot read. */
+export declare function decodeIndex(body: Uint8Array): Promise<ManifestIndexV2>;
+/** A chunk → the plaintext to seal under `AAD_FILE_LIST_CHUNK`. */
+export declare function encodeChunk(doc: ManifestChunkDoc): Promise<Uint8Array>;
+/** Sealed chunk plaintext → its entries. */
+export declare function decodeChunk(body: Uint8Array): Promise<ManifestChunkDoc>;
+/**
+ * The reader's one door: sealed plaintext → whichever version it turned out to be.
+ *
+ * ⚠ A version-1 body is inflated twice — once here to read `v`, once by `decodeManifest`. That is
+ * deliberate rather than a duplicate validator: version 1's rules live in one place and stay
+ * there. The cost is bounded and self-extinguishing, because the first save after a version-1 load
+ * converts the account (§6.3.6) and no later read takes this branch.
+ */
+export declare function decodeFileList(body: Uint8Array): Promise<FileListDocument>;