@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/credentials.d.ts

@@ -0,0 +1,146 @@
+import { type LockedCode } from "./code-vault.ts";
+/** The environment variable an agent sets instead of running `login`. */
+export declare const CODE_ENV_VAR = "NMTS_ACCOUNT_CODE";
+/** The API key, same rules: read fresh, never an argument, never printed. */
+export declare const API_KEY_ENV_VAR = "NMTS_API_KEY";
+/**
+ * Opens a passphrase-locked stored code without a terminal.
+ *
+ * ⚠ A passphrase in an environment variable protects the FILE, not this run: anything that can
+ *   read this variable can read the code the moment the tool decodes it. What it still buys is
+ *   real — a copied home directory, a backup, an image layer and a stolen disk all yield nothing
+ *   — and it is the only shape that works where no person is present to type.
+ */
+export declare const PASSPHRASE_ENV_VAR = "NMTS_PASSPHRASE";
+/**
+ * Names a FILE holding the NMTS key, rather than holding it directly.
+ *
+ * ⛔ THE ONLY SAFE WAY TO GIVE A CONTAINER A SECRET. See `readSecretFile`.
+ */
+export declare const CODE_FILE_ENV_VAR = "NMTS_ACCOUNT_CODE_FILE";
+/** Names a file holding the API key. Same reason. */
+export declare const API_KEY_FILE_ENV_VAR = "NMTS_API_KEY_FILE";
+/** Where a credential came from. Reported, never guessed. */
+export type CredentialSource = "env" | "secret-file" | "file" | "file-locked";
+/**
+ * An NMTS key that has been FOUND but not necessarily opened.
+ *
+ * ⛔ THE TWO CASES ARE SEPARATE TYPES so that no caller can read `.code` off a locked one. A
+ *    single shape with a nullable field would compile everywhere and be wrong in exactly one
+ *    place — the command that forgot to unlock and treated "no code" as "not signed in".
+ */
+export type ResolvedCode = {
+    readonly source: "env" | "secret-file" | "file";
+    readonly code: string;
+} | {
+    readonly source: "file-locked";
+    readonly locked: LockedCode;
+};
+/** Directory holding everything this tool keeps. 0700 where the platform honours it. */
+export declare function configDir(): string;
+export declare function credentialsPath(): string;
+/**
+ * What is kept on disk. `apiKey` is absent until API keys exist and one has been supplied.
+ *
+ * ⛔ EXACTLY ONE OF `accountCode` AND `lockedCode`, and `isCredentials` enforces it. A file with
+ *    both would leave a reader to choose, and the wrong choice is the plain copy of a code
+ *    somebody asked to have locked.
+ */
+export interface Credentials {
+    /**
+     * The NMTS key in the clear.
+     *
+     * ⛔ ONLY WHEN THE PERSON CHOSE IT (`login --plain`, behind the `unsafe-code-storage` consent).
+     *    The default writes `lockedCode` instead.
+     */
+    accountCode?: string;
+    /** The NMTS key sealed under a passphrase. The default form. */
+    lockedCode?: LockedCode;
+    /** Server credential that waives the human check. Optional: not every account has one. */
+    apiKey?: string;
+    /** Base URL of the NMTS server this code belongs to. */
+    server: string;
+    /**
+     * Which storage network that server uses.
+     *
+     * ⛔ Stored rather than inferred each run: the network decides WHERE the files are, and a later
+     *    run that guessed differently from the run that uploaded would look in the wrong place and
+     *    report an empty account.
+     */
+    network?: string;
+}
+/** True on platforms where Node applies a POSIX file mode. */
+export declare function modesAreEnforced(): boolean;
+/**
+ * Can this machine actually keep a file private, where the NMTS key would go?
+ *
+ * ⛔ IT MEASURES RATHER THAN ASSUMES. "Not Windows" is not the same question: a container with a
+ *    bind mount from a Windows host, a network drive, an exFAT stick and several FUSE filesystems
+ *    all accept `chmod` and then ignore it. The mode comes back as whatever the filesystem felt
+ *    like, and the tool would have written the NMTS key into a file anybody can read while
+ *    believing it had locked it.
+ *
+ * So: write a file, ask for 0600, read the mode back, and delete it. The probe is empty, its name
+ * is not the credentials name, and it is removed whatever happens.
+ *
+ * Returns false on Windows without probing — the platform has no POSIX mode to check, and
+ * answering "yes" from a successful no-op would be the worst of the three possible answers.
+ */
+export declare function codeStorageIsPrivate(): boolean;
+/**
+ * Write credentials, replacing any existing file, without ever leaving a readable window.
+ *
+ * The write goes to a fresh file created with `wx` (fails if the name exists, so nothing already
+ * on disk is opened) and is then renamed over the target. A rename within the same directory is
+ * atomic, so a reader either sees the old file or the new one and never a half-written one.
+ */
+export declare function writeCredentials(creds: Credentials): void;
+/** Raised when the file exists but this machine is not keeping it private. */
+export declare class CredentialsTooOpenError extends Error {
+    readonly path: string;
+    readonly mode: number;
+    constructor(path: string, mode: number);
+}
+/**
+ * Read credentials from disk, refusing a file other users can read.
+ *
+ * ⛔ The refusal is the point. A credentials file that went world-readable — copied with `cp -r`,
+ *    restored from an archive, written by an older version — is a leak that nothing else in the
+ *    system would ever mention. Reading it anyway and carrying on is how that stays quiet.
+ */
+export declare function readCredentialsFile(): Credentials | null;
+/**
+ * The NMTS key this run should use, and where it came from.
+ *
+ * The environment variable wins over the file so an agent can be handed a code for one run without
+ * writing anything to disk — which is the safer shape when the machine is shared or ephemeral.
+ */
+export declare function resolveAccountCode(): ResolvedCode | null;
+/**
+ * Read a secret out of the file an environment variable NAMES.
+ *
+ * ⛔ THIS IS HOW A SECRET GETS INTO A CONTAINER. An environment variable holding the value itself
+ *    is readable by anybody who can inspect the container — `docker inspect` prints the whole
+ *    environment, and so does the API behind it. A variable holding a PATH gives that reader a
+ *    filename and nothing else, while the value rides in on a `--secret` mount, a tmpfs, or a
+ *    bind-mounted file whose permissions the host controls. It is the convention the official
+ *    database images use, for the same reason.
+ *
+ * Trailing whitespace and a trailing newline are removed: writing a secret to a file with `echo`
+ * appends one, and refusing a code because of it would be a puzzle with no clue.
+ */
+export declare function readSecretFile(variable: string): string | null;
+/**
+ * The API key this run should use, and where it came from.
+ *
+ * ⚠ SEPARATE FROM THE NMTS KEY ON PURPOSE, and the two can come from different places. The
+ *   code is what opens the files; the key is only what makes the server answer without a human
+ *   check. Somebody may keep the code in the environment for one run while the key stays on the
+ *   machine, or the other way round, and neither combination is unusual enough to refuse.
+ */
+export declare function resolveApiKey(): {
+    key: string;
+    source: CredentialSource;
+} | null;
+/** Scratch location used only by tests that need a directory outside the real home. */
+export declare function testConfigDir(name: string): string;

package/dist/credentials.js

@@ -1,4 +1,4 @@
-// Where an account code lives on this machine, and every rule about how it gets there.
+// Where an NMTS key lives on this machine, and every rule about how it gets there.
 //
 // ⛔ NEVER FROM THE COMMAND LINE. On Linux any process can read /proc/<pid>/cmdline, so a secret
 //    passed as an argument is readable by anything running as the same user for as long as the
@@ -34,7 +34,7 @@ export const API_KEY_ENV_VAR = "NMTS_API_KEY";
  */
 export const PASSPHRASE_ENV_VAR = "NMTS_PASSPHRASE";
 /**
- * Names a FILE holding the account code, rather than holding it directly.
+ * Names a FILE holding the NMTS key, rather than holding it directly.
  *
  * ⛔ THE ONLY SAFE WAY TO GIVE A CONTAINER A SECRET. See `readSecretFile`.
  */
@@ -54,12 +54,12 @@ export function modesAreEnforced() {
     return process.platform !== "win32";
 }
 /**
- * Can this machine actually keep a file private, where the account code would go?
+ * Can this machine actually keep a file private, where the NMTS key would go?
  *
  * ⛔ IT MEASURES RATHER THAN ASSUMES. "Not Windows" is not the same question: a container with a
  *    bind mount from a Windows host, a network drive, an exFAT stick and several FUSE filesystems
  *    all accept `chmod` and then ignore it. The mode comes back as whatever the filesystem felt
- *    like, and the tool would have written the account code into a file anybody can read while
+ *    like, and the tool would have written the NMTS key into a file anybody can read while
  *    believing it had locked it.
  *
  * So: write a file, ask for 0600, read the mode back, and delete it. The probe is empty, its name
@@ -108,7 +108,7 @@ export function writeCredentials(creds) {
     const target = credentialsPath();
     const scratch = join(dir, `.credentials.${process.pid}.${Date.now()}.tmp`);
     // ⛔ THE SCRATCH FILE NEVER OUTLIVES A FAILURE. It holds exactly what the target would — the
-    //    account code, in the clear when that is the shape being written — and `logout` removes
+    //    NMTS key, in the clear when that is the shape being written — and `logout` removes
     //    only `credentials.json`, so one left behind by a full disk or a failed rename would sit
     //    there unreferenced and unnoticed. The rename is the last thing that happens; anything that
     //    stops before it leaves nothing.
@@ -173,7 +173,7 @@ export function readCredentialsFile() {
         throw error;
     }
     // ⛔ THE PARSER'S OWN MESSAGE NEVER ESCAPES. V8 quotes about thirty characters of the input in
-    //    `Unexpected token …`, and the input here is the file the account code is in — an
+    //    `Unexpected token …`, and the input here is the file the NMTS key is in — an
     //    adversarial review printed nine symbols of a real code to stderr from a single lost quote.
     //    `errors.ts` prints an unknown error's message verbatim, so the only place to stop it is
     //    here, before it becomes an error at all.
@@ -192,7 +192,7 @@ export function readCredentialsFile() {
  * The one refusal for a file this version cannot use, in the one wording.
  *
  * ⛔ IT NAMES THE PATH AND NOTHING ELSE. Not the contents, not the parser's complaint, not which
- *    field was wrong — the file is the account code's file, and every one of those quotes it.
+ *    field was wrong — the file is the NMTS key's file, and every one of those quotes it.
  *
  * ⚠ AND IT IS AN `NmtsError` WITH A WAY OUT. It used to be a bare `Error`, which meant the
  *    generic exit code and no next step: `whoami`, `ls`, `get` and `put` all died at 1 saying
@@ -203,7 +203,7 @@ function unusable(path, what) {
     return new NmtsError(`${path} ${what}.`, {
         exitCode: 3,
         nextStep: `Nothing was read from it. \`nmts logout\` removes it, and \`nmts login\` writes a fresh ` +
-            `one. If that file is the only copy of the account code, take the code out of it by hand ` +
+            `one. If that file is the only copy of the NMTS key, copy that key out of it by hand ` +
             `first — this tool will not open it.`,
     });
 }
@@ -231,7 +231,7 @@ function isCredentials(value) {
     return true;
 }
 /**
- * The account code this run should use, and where it came from.
+ * The NMTS key this run should use, and where it came from.
  *
  * The environment variable wins over the file so an agent can be handed a code for one run without
  * writing anything to disk — which is the safer shape when the machine is shared or ephemeral.
@@ -288,7 +288,7 @@ export function readSecretFile(variable) {
 /**
  * The API key this run should use, and where it came from.
  *
- * ⚠ SEPARATE FROM THE ACCOUNT CODE ON PURPOSE, and the two can come from different places. The
+ * ⚠ SEPARATE FROM THE NMTS KEY ON PURPOSE, and the two can come from different places. The
  *   code is what opens the files; the key is only what makes the server answer without a human
  *   check. Somebody may keep the code in the environment for one run while the key stays on the
  *   machine, or the other way round, and neither combination is unusual enough to refuse.

package/dist/crypto-surface.d.ts

@@ -0,0 +1,197 @@
+/**
+ * One part's OPENING session, held open by the engine.
+ *
+ * `push()` the sealed bytes in any slice sizes, in order; each call returns the plaintext of
+ * whatever chunks that completed, which is usually nothing and then one whole chunk. `finish()`
+ * after the last byte checks every end-of-stream invariant the format has — that all chunks were
+ * consumed, that the final one was flagged final, that the total matches the length in the header,
+ * that nothing trails.
+ *
+ * ⛔ `finish()` IS NOT OPTIONAL AND IS NOT A FORMALITY. Tampering with a chunk is caught by
+ *    `push()`, but a stream cut short is only caught here: every chunk that arrived authenticates
+ *    perfectly and the file is simply missing its end. A caller that skipped this would accept a
+ *    truncated part as a whole one.
+ *
+ * ⛔ `free()` IS NOT HOUSEKEEPING. The engine holds the file key for as long as the session is
+ *    open, so every path out — including a failed read — has to reach it.
+ */
+export interface StreamOpener {
+    /** Feed sealed bytes. Returns the plaintext of any chunks that completed, possibly empty. */
+    push(data: Uint8Array): Uint8Array;
+    /** Check the stream ended as the format requires. Throws when it did not. */
+    finish(): void;
+    /** Release the engine-side memory, and the key with it. */
+    free(): void;
+}
+/**
+ * One part's sealing session, held open by the engine.
+ *
+ * `header()`, then every `push()` output in order, then `finish()`, concatenated, IS the part's
+ * complete NCF-3 stream. Nothing is buffered on this side.
+ *
+ * ⛔ `free()` IS NOT HOUSEKEEPING. The engine holds the file key for as long as the session is
+ *    open, so a caller that abandons one leaves key material live in the engine's memory for the
+ *    rest of the process. Every path out of a sealing loop — including a failed read — has to
+ *    reach it.
+ */
+export interface StreamSealer {
+    /** The stream header. Goes out first, before any chunk. */
+    header(): Uint8Array;
+    /** Feed plaintext. Returns whatever complete chunks that made, which may be nothing. */
+    push(data: Uint8Array): Uint8Array;
+    /** The buffered remainder plus the end mark. Refuses if fewer bytes were pushed than declared. */
+    finish(): Uint8Array;
+    /** Release the engine-side memory, and the key with it. */
+    free(): void;
+}
+/** The slice of the engine this tool uses. Every name here is checked at load time. */
+export interface CryptoGlue {
+    /** A brand-new NMTS key, display form. ⛔ The only copy there will be — `registration.ts`. */
+    account_code_generate(): string;
+    /** Text form to the 20 raw bytes. Throws when the check symbol does not match. */
+    account_code_parse(input: string): Uint8Array;
+    /** The grouped, human-readable spelling of a code. */
+    account_code_display(codeBytes: Uint8Array): string;
+    /** The full derivation output. Offsets are named in DERIVED below. */
+    kdf_derive(codeBytes: Uint8Array): Uint8Array;
+    /** Display form — the grouped PUBLIC CODE a person reads, copies and types. */
+    share_address_display(address: Uint8Array): string;
+    /**
+     * The typed form back to the 16 raw bytes. Throws when the check symbol does not match.
+     *
+     * ⛔ A TYPO FAILS HERE, NOT AS A SERVER LOOKUP. Sending a mistyped address to the recipient
+     *    lookup would ask the server a question about somebody who may exist, and the answer — or
+     *    the refusal — is not ours to collect.
+     */
+    share_address_parse(input: string): Uint8Array;
+    /**
+     * This account's published sharing identity: the 4,989-byte bundle other people encrypt to.
+     *
+     * ⛔ DETERMINISTIC, AND THAT IS LOAD-BEARING (NCF-3 §5.1). The self-signature uses the
+     *    deterministic signing variant, so the same NMTS key produces the same bytes on every
+     *    machine. A hedged signature would make each device publish a different identity, and the
+     *    server takes the first one forever.
+     */
+    share_public_key(shareKemSeed: Uint8Array, shareAuthSecret: Uint8Array, shareSigSeed: Uint8Array): Uint8Array;
+    /** The address an identity bundle fingerprints to. Used to check what a server handed back. */
+    share_address_of(recipientPublic: Uint8Array): Uint8Array;
+    /** Which account an envelope CLAIMS to be from. A claim until the unwrap succeeds. */
+    share_claimed_sender(envelope: Uint8Array): Uint8Array;
+    /**
+     * Wrap a file's key to one recipient.
+     *
+     * ⛔ THE ADDRESS IS AN ARGUMENT BECAUSE THE IDENTITY IS NOT TRUSTED. The server hands back a
+     *    bundle; this checks it fingerprints to the address that was asked for, that it
+     *    self-signs, and that its halves decode, BEFORE encrypting anything to it (NCF-3 §5.2a).
+     *    There is deliberately no form of this that takes the bundle alone.
+     *
+     * ⛔ THE LAST THREE ARGUMENTS MUST BE THE BYTES ACTUALLY SENT. They are hashed, with length
+     *    prefixes, into the wrapping key — so a name sealed after this call, or an id spelled
+     *    differently, produces an envelope the recipient cannot open.
+     */
+    share_wrap_dek(senderAuthSecret: Uint8Array, senderSigSeed: Uint8Array, recipientPublic: Uint8Array, recipientAddress: Uint8Array, dek: Uint8Array, itemId: string, nameShareCt: Uint8Array, contentHashShareCt: Uint8Array): Uint8Array;
+    /**
+     * Open an envelope somebody sent to this account.
+     *
+     * ⛔ OPENING IT IS THE AUTHENTICATION. There is no separate verify step: the sender's secret is
+     *    inside the key agreement, so a bundle that is not the real sender's cannot produce a key
+     *    that opens this. That is why the claimed sender may only be printed AFTER this succeeds.
+     */
+    share_unwrap_dek(shareKemSeed: Uint8Array, shareAuthSecret: Uint8Array, shareSigSeed: Uint8Array, senderPublic: Uint8Array, envelope: Uint8Array, itemId: string, nameShareCt: Uint8Array, contentHashShareCt: Uint8Array): Uint8Array;
+    /**
+     * Open one NCF-3 envelope: key, the associated data it was sealed with, the envelope bytes.
+     *
+     * ⛔ The associated data is not decoration. An envelope sealed for one purpose cannot be opened
+     *    as another, so passing the wrong string here does not silently produce wrong plaintext —
+     *    it throws. That is why the strings live in one table (`AAD`) rather than at call sites.
+     */
+    envelope_open(key: Uint8Array, aad: Uint8Array, envelope: Uint8Array): Uint8Array;
+    /**
+     * Decrypt one whole NCF-3 stream — header, every chunk, and the end-of-stream check.
+     *
+     * ⚠ IT HOLDS THE WHOLE PART OPEN IN MEMORY as well as sealed, which is why the download path
+     *   stopped using it: a file is delivered as it is decrypted now, through `StreamDecryptor`
+     *   below. This stays because the conformance tests seal a part and open it again in one line,
+     *   and reading that test is how a person checks the streaming path against the simple one.
+     */
+    stream_decrypt_all(dek: Uint8Array, stream: Uint8Array): Uint8Array;
+    /**
+     * A fresh random 32-byte file key.
+     *
+     * ⛔ THE RANDOMNESS IS THE ENGINE'S, NOT THIS FILE'S. Node has its own generator, and reaching
+     *    for it here would put a second source of file keys in the world -- one this package's
+     *    conformance vectors say nothing about. One generator, inside the engine, for both the
+     *    browser and this tool.
+     */
+    generate_dek(): Uint8Array;
+    /**
+     * Seal one NCF-3 envelope: key, the associated data to bind it to, the plaintext.
+     *
+     * The inverse of `envelope_open`, and the same warning applies to the associated data -- an
+     * envelope sealed under the wrong string is not openable as the thing it was meant to be.
+     */
+    envelope_seal(key: Uint8Array, aad: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    /**
+     * Encrypt one whole part into a complete NCF-3 stream -- header, chunks and the end mark.
+     *
+     * ⚠ IT HOLDS THE WHOLE PART IN MEMORY, open and sealed, exactly as `stream_decrypt_all` does.
+     *   That is what bounds the size this tool will upload in one piece; `put` refuses a larger file
+     *   rather than discovering the limit as an out-of-memory crash halfway through.
+     *
+     * ⛔ A FRESH CALL PER PART. The nonce prefix is allocated inside, and the format requires it to
+     *   differ per stream. Re-sealing different bytes under a header that was already used is the
+     *   one catastrophic mistake available here, so there is no entry point that accepts a header.
+     */
+    stream_encrypt_all(dek: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    /**
+     * Seal ONE part of a file, feeding the plaintext in as it is read.
+     *
+     * ⛔ THIS IS WHAT LETS A FILE BE LARGER THAN MEMORY. `stream_encrypt_all` above needs the whole
+     *    part open and sealed at once; this holds one chunk at a time, so the caller can read a
+     *    file in slices and never have more than a chunk of it live.
+     *
+     * ⛔ A FRESH SESSION PER PART, ALWAYS. The nonce prefix is allocated inside the engine and the
+     *    format requires it to differ per stream. There is deliberately no entry point here that
+     *    accepts a header: re-sealing DIFFERENT bytes under a header that was already used repeats
+     *    a (key, nonce) pair, which is the one mistake in this format that loses the file's secrecy
+     *    outright rather than making it unreadable.
+     *
+     * `partIndex` and `partTotal` say where this stream sits in the file. They go into the header
+     * and therefore into every chunk's associated data, so a part later served in another part's
+     * position fails authentication instead of decrypting into the wrong place. A whole file in one
+     * stream is part 0 of 1.
+     */
+    StreamEncryptor: new (dek: Uint8Array, plaintextLen: number, partIndex: number, partTotal: number) => StreamSealer;
+    /**
+     * OPEN one part of a file, handing back its plaintext as the bytes arrive.
+     *
+     * ⛔ THIS IS WHAT LETS A FILE COME BACK ON A MACHINE SMALLER THAN THE FILE. The mirror of
+     *    `StreamEncryptor`, and the download path's only decryptor: `stream_decrypt_all` needs the
+     *    whole part open at once, so the size a file could be uploaded at and the size it could be
+     *    read back at had drifted apart.
+     *
+     * `header` is the first 72 bytes of the stored stream and is parsed and checked here — a wrong
+     * magic, an unknown version or an impossible chunk size fails at construction, before any
+     * ciphertext is fed in.
+     */
+    StreamDecryptor: new (dek: Uint8Array, header: Uint8Array) => StreamOpener;
+    /**
+     * The Ed25519 seed of wallet `index`, from the 32-byte wallet root (NCF-3 §1).
+     *
+     * ⛔ EVERY WALLET COMES FROM HERE, INCLUDING WALLET 0. There is no separate rule for the first
+     *    one and no index this refuses. A tool that derived wallet 0 some other way would produce a
+     *    different address from the browser and the recovery tool for the same NMTS key — which
+     *    would look like the account's money had vanished.
+     */
+    wallet_seed_for(walletRoot: Uint8Array, index: number): Uint8Array;
+}
+export declare function isCryptoGlue(value: unknown): value is CryptoGlue;
+/** Which of the required functions this object does not have. Empty means it is the engine. */
+export declare function missingExports(value: unknown): (keyof CryptoGlue)[];
+/**
+ * Where the engine is.
+ *
+ * Two layouts are real: inside the published package the vendored engine sits beside the code, and
+ * inside this repository it lives in web/vendor where the browser build also reads it. Looking in
+ * both is what lets the same source run from a checkout and from an install.
+ */

package/dist/crypto.d.ts

@@ -0,0 +1,81 @@
+import { type CryptoGlue } from "./crypto-surface.ts";
+export type { CryptoGlue, StreamOpener, StreamSealer } from "./crypto-surface.ts";
+/**
+ * The associated-data strings of NCF-3, for the envelopes this tool opens.
+ *
+ * ⛔ FROZEN (NCF-3 §2.2). They are the separator between one purpose and another: the file list
+ *    cannot be opened as a delegation, and neither can be opened as a file. Copied here rather
+ *    than imported because this package does not import the browser tree — the conformance
+ *    vectors are what arbitrate, and they are in the crypto repository.
+ */
+export declare const AAD: {
+    readonly fileList: "nmts/v3/file-list";
+    /** Wraps a file's own key under the account's data key (NCF-3 §3). */
+    readonly dekWrap: "nmts/v3/dek-wrap";
+    /**
+     * Wraps the SHA-256 of a file's whole plaintext (NCF-3 §2.2).
+     *
+     * Sealed rather than stored bare because a plaintext content hash identifies the FILE: it is
+     * matchable against public hash sets, and it is equal across two accounts holding the same file.
+     */
+    readonly contentHash: "nmts/v3/content-hash";
+    /**
+     * Seals a shared file's name and size FOR THE RECIPIENT, under the file's own key (NCF-3 §5.4).
+     *
+     * ⚠ A different separator from the account's own file list on purpose: the recipient holds the
+     *   file key and nothing else, so the name has to travel under that key rather than under an
+     *   account data key they do not have.
+     */
+    readonly shareName: "nmts/v3/share-name";
+    /** Seals the shared file's plaintext digest for the recipient, under the same file key. */
+    readonly shareContentHash: "nmts/v3/share-content-hash";
+    /** Seals the RECOVERY LIST — where every file's bytes are (NRM §1). ⛔ The old spelling of the
+     *  artefact's name is frozen INTO the separator: every list ever sealed is bound to these bytes. */
+    readonly recoveryMap: "nmts/v3/recovery-map";
+};
+/**
+ * Byte ranges inside `kdf_derive`'s output.
+ *
+ * ⛔ These are a CONTRACT WITH A FROZEN FORMAT (NCF-3 §1), not a convenience. They are written
+ *    here as ranges rather than magic numbers at call sites so a reader can check them against the
+ *    format document in one place — and so a future version bump changes one table.
+ */
+export declare const DERIVED: {
+    readonly accountId: readonly [0, 16];
+    readonly authSecret: readonly [16, 48];
+    readonly dataKey: readonly [48, 80];
+    readonly fileListKey: readonly [80, 112];
+    /**
+     * The three secrets behind this account's sharing identity (NCF-3 §5.1).
+     *
+     * ⚠ `shareSigSeed` SITS AT THE TAIL, not beside the other two, and that is not tidiness lost —
+     *   it was appended on 2026-08-02 because filing it in the obvious place would have shifted
+     *   `walletRoot` and `shareAddress`, which are frozen. `web/src/lib/crypto/kdf-offsets.ts`
+     *   carries the same table for the browser.
+     */
+    readonly shareKemSeed: readonly [112, 144];
+    readonly shareAuthSecret: readonly [144, 176];
+    /**
+     * The root every one of this account's wallets is derived from.
+     *
+     * ⚠ IT IS AN HKDF PRK, NOT KEY MATERIAL TO EXTRACT AGAIN. `wallet_seed_for` expands from it
+     *   directly; a re-implementation that ran a second Extract over these bytes would produce
+     *   plausible-looking seeds for a different set of addresses.
+     */
+    readonly walletRoot: readonly [176, 208];
+    readonly shareAddress: readonly [208, 224];
+    readonly shareSigSeed: readonly [224, 256];
+    /**
+     * The root every one of this account's AI-account NMTS KEYS is expanded from (NCF-3 §1.5).
+     *
+     * ⚠ Appended at the TAIL on 2026-09-06, for the reason `shareSigSeed` was: filing it anywhere
+     *   else would have shifted frozen offsets. Like `walletRoot` it is an HKDF PRK, expanded from
+     *   directly — and what it expands to is 20 bytes that ARE an NMTS key, not a seed.
+     */
+    readonly aiAccountRoot: readonly [256, 288];
+};
+export declare function engineDir(): string;
+/** Load the engine once per process. */
+export declare function loadCrypto(): Promise<CryptoGlue>;
+/** For tests that need a fresh load. */
+export declare function forgetCrypto(): void;

package/dist/crypto.js

@@ -35,6 +35,11 @@ import { isCryptoGlue, missingExports } from "./crypto-surface.js";
  */
 export const AAD = {
     fileList: "nmts/v3/file-list",
+    // ⚠ THE CHUNK LABEL IS NOT SPELLED HERE. One CHUNK of the chunked file list is sealed under
+    //   `nmts/v3/file-list-chunk` (NCF-3 §6.3.2), and that string is declared in the shared copy of
+    //   the chunk codec as `AAD_FILE_LIST_CHUNK` and used from there. A second spelling in this
+    //   table is exactly how the two halves of the product would come to disagree about a separator
+    //   whose whole job is that a chunk can never be presented as an index.
     /** Wraps a file's own key under the account's data key (NCF-3 §3). */
     dekWrap: "nmts/v3/dek-wrap",
     /**
@@ -90,6 +95,14 @@ export const DERIVED = {
     walletRoot: [176, 208],
     shareAddress: [208, 224],
     shareSigSeed: [224, 256],
+    /**
+     * The root every one of this account's AI-account NMTS KEYS is expanded from (NCF-3 §1.5).
+     *
+     * ⚠ Appended at the TAIL on 2026-09-06, for the reason `shareSigSeed` was: filing it anywhere
+     *   else would have shifted frozen offsets. Like `walletRoot` it is an HKDF PRK, expanded from
+     *   directly — and what it expands to is 20 bytes that ARE an NMTS key, not a seed.
+     */
+    aiAccountRoot: [256, 288],
 };
 export function engineDir() {
     const here = dirname(fileURLToPath(import.meta.url));

package/dist/deposit.d.ts

@@ -0,0 +1,25 @@
+import type { AccountSettings } from "./shared/lib/drive/manifest-settings.ts";
+export declare const DEPOSIT_CREDITS_MAX = 64;
+export declare const DEPOSIT_CREDITS_DEFAULT = 64;
+/**
+ * What `--deposit <n>` asked for, or undefined when it was not given.
+ *
+ * ⛔ WHOLE CREDITS ONLY. A deposit is a number of credits the ledger moves, and there is no such
+ *    thing as half of one; `--deposit 1.5` is refused rather than rounded, because rounding picks
+ *    an amount for somebody who was already being specific.
+ */
+export declare function parseDeposit(asked: string | number | undefined): number | undefined;
+/** The account's own default: what the sealed list holds, or `DEPOSIT_CREDITS_DEFAULT`. */
+export declare function depositDefaultOf(settings: AccountSettings | undefined): number;
+/** ⛔ The wallet buys its own storage, so there is no treasury deposit to set aside against it. */
+export declare function refuseDepositWithWallet(asked: string | number | undefined): void;
+/**
+ * What the price says about the deposit, under the line that names the credits.
+ *
+ * ⚠ ONE SENTENCE FOR 0 AND NONE OF THE USUAL HEDGING. It is the one answer whose cost lands later
+ *   and somewhere else — on a release, out of the balance — so it is said where the choice shows.
+ *
+ * `files` is how many files this run puts the deposit on: absent for one file, a count for a
+ * directory, where the number set aside is per file and the total is what the balance must cover.
+ */
+export declare function depositLines(credits: number, files?: number): string[];

package/dist/deposit.js

@@ -0,0 +1,78 @@
+// How many credits an upload sets aside on the file it uploads — the rule, in one place.
+//
+// ⛔ IT IS A CHOICE, AND THE TOOL ALWAYS SENDS IT. A credit-paid upload holds a deposit against
+//    the chain fee of any later operation on that file (releasing its storage early, or reshaping
+//    it): the fee is converted to credits and taken from that deposit, at least one credit, and
+//    whatever is left comes back when the storage period ends. The number is chosen per upload,
+//    from 0 to `DEPOSIT_CREDITS_MAX`, and an account's own default lives in the sealed file list.
+//
+// ⚠ ZERO IS A REAL ANSWER, NOT A MISTAKE. A file with no deposit still releases — it just pays
+//   twice the same fee out of the balance at that moment, and is refused when the balance cannot
+//   cover that. Withholding the option would be safety that shackles; the cost is said instead,
+//   at the moment it is chosen and again in the price the upload prints.
+//
+// ⛔ THE REFUSAL HAPPENS BEFORE ANYTHING IS SENT. A number outside the range is a command line to
+//    fix, not a request to make: rounding it into range would spend money on an amount nobody
+//    typed, and asking the server would cost a round trip to learn about a typo.
+import { NmtsError } from "./errors.js";
+import { BINARY_NAME } from "./product.js";
+import { DEPOSIT_DEFAULT_CREDITS, DEPOSIT_MAX_CREDITS, } from "./shared/lib/drive/manifest-settings.js";
+// The shared module (generated from the browser's source) names the two numbers the other way
+// round; the CLI's own vocabulary is kept so the commands and their tests read as written.
+export const DEPOSIT_CREDITS_MAX = DEPOSIT_MAX_CREDITS;
+export const DEPOSIT_CREDITS_DEFAULT = DEPOSIT_DEFAULT_CREDITS;
+/**
+ * What `--deposit <n>` asked for, or undefined when it was not given.
+ *
+ * ⛔ WHOLE CREDITS ONLY. A deposit is a number of credits the ledger moves, and there is no such
+ *    thing as half of one; `--deposit 1.5` is refused rather than rounded, because rounding picks
+ *    an amount for somebody who was already being specific.
+ */
+export function parseDeposit(asked) {
+    if (asked === undefined || asked === "")
+        return undefined;
+    const credits = typeof asked === "number" ? asked : Number(asked.trim());
+    if (!Number.isInteger(credits) || credits < 0 || credits > DEPOSIT_CREDITS_MAX) {
+        throw new NmtsError(`--deposit takes a whole number of credits from 0 to ${DEPOSIT_CREDITS_MAX}, not "${String(asked)}".`, {
+            exitCode: 2,
+            nextStep: `Nothing was sent and nothing was charged. Leave --deposit off to use this account's ` +
+                `default (\`${BINARY_NAME} deposit\` prints it).`,
+        });
+    }
+    return credits;
+}
+/** The account's own default: what the sealed list holds, or `DEPOSIT_CREDITS_DEFAULT`. */
+export function depositDefaultOf(settings) {
+    const held = settings?.depositDefault;
+    return typeof held === "number" && Number.isInteger(held) && held >= 0 && held <= DEPOSIT_CREDITS_MAX
+        ? held
+        : DEPOSIT_CREDITS_DEFAULT;
+}
+/** ⛔ The wallet buys its own storage, so there is no treasury deposit to set aside against it. */
+export function refuseDepositWithWallet(asked) {
+    if (asked === undefined || asked === "")
+        return;
+    throw new NmtsError("--deposit only applies when credits pay: the wallet buys its own storage.", {
+        exitCode: 2,
+        nextStep: `Nothing was sent. Leave --pay wallet off to pay with credits and set a deposit aside.`,
+    });
+}
+/**
+ * What the price says about the deposit, under the line that names the credits.
+ *
+ * ⚠ ONE SENTENCE FOR 0 AND NONE OF THE USUAL HEDGING. It is the one answer whose cost lands later
+ *   and somewhere else — on a release, out of the balance — so it is said where the choice shows.
+ *
+ * `files` is how many files this run puts the deposit on: absent for one file, a count for a
+ * directory, where the number set aside is per file and the total is what the balance must cover.
+ */
+export function depositLines(credits, files) {
+    if (credits === 0) {
+        return [`  no deposit — a release costs twice the fee from your balance`];
+    }
+    const each = `${credits} credit${credits === 1 ? "" : "s"}`;
+    const set = files === undefined || files === 1
+        ? `  ${each} set aside as a deposit`
+        : `  ${each} set aside as a deposit on each of them (${credits * files} in all)`;
+    return [`${set}, back when the storage period ends`];
+}