@remnic/core 1.1.11 → 1.1.13

package/dist/secure-store/index.d.ts

@@ -0,0 +1,890 @@
+import { Readable, Writable } from 'node:stream';
+
+/**
+ * AES-256-GCM encrypt / decrypt primitives for the secure-store
+ * module.
+ *
+ * Issue #690 (PR 1/4) — pure primitives, no I/O.
+ *
+ * Sealed envelope format
+ * ----------------------
+ * A "sealed" buffer is the canonical on-disk shape for a single
+ * encrypted blob. It contains the salt used to derive the key from
+ * the user's passphrase, so a caller who has the passphrase + the
+ * sealed buffer can decrypt without any external metadata.
+ *
+ *   [VERSION:1][SALT:16][IV:12][AUTHTAG:16][CIPHERTEXT:...]
+ *
+ *   - VERSION (1 byte): envelope format version. Currently 1. Future
+ *     versions can change the layout (e.g. variable salt length, an
+ *     algorithm identifier byte) by bumping this byte.
+ *   - SALT (16 bytes): KDF salt. Persisted with the ciphertext so the
+ *     same passphrase can re-derive the key on read.
+ *   - IV (12 bytes): GCM nonce. Must be unique per (key, ciphertext)
+ *     pair. We generate it fresh from `randomBytes` on every encrypt
+ *     call. Reusing an IV with the same key destroys GCM's
+ *     confidentiality and authenticity guarantees.
+ *   - AUTHTAG (16 bytes): GCM authentication tag. Tampering with any
+ *     byte of (salt | iv | tag | ciphertext) causes decryption to
+ *     fail with an auth-tag mismatch.
+ *   - CIPHERTEXT (variable): the encrypted payload.
+ *
+ * The salt is stored alongside the ciphertext (rather than only in a
+ * separate metadata file) so an individual encrypted blob is
+ * self-contained for diagnostics and recovery. The metadata file
+ * (see `metadata.ts`) records the *canonical* salt + KDF params for a
+ * store; the per-blob salt is expected to match the metadata salt in
+ * normal operation, but the format does not require it — a future PR
+ * could rotate per-blob salts if desired.
+ *
+ * AAD support
+ * -----------
+ * Callers can pass associated authenticated data (AAD) — typically a
+ * file path or namespace tag — that is authenticated but not
+ * encrypted. AAD must be supplied identically on encrypt and decrypt;
+ * a mismatch causes auth-tag failure. AAD is NOT serialized into the
+ * envelope; the caller is responsible for re-supplying it on decrypt.
+ */
+/** Current envelope format version. */
+declare const ENVELOPE_VERSION: 1;
+/** GCM nonce length. 96 bits is the NIST-recommended size for AES-GCM. */
+declare const IV_LENGTH = 12;
+/** GCM authentication tag length. 16 bytes (128 bits) — the maximum. */
+declare const AUTH_TAG_LENGTH = 16;
+/** Salt length carried in the envelope. Must match KDF_SALT_LENGTH. */
+declare const ENVELOPE_SALT_LENGTH = 16;
+/** Required key length for AES-256. */
+declare const AES_KEY_LENGTH = 32;
+/** Byte offsets of each envelope field (for clarity at call sites). */
+declare const ENVELOPE_LAYOUT: Readonly<{
+    version: 0;
+    salt: 1;
+    iv: number;
+    authTag: number;
+    ciphertext: number;
+}>;
+/** Minimum envelope size: header + zero-length ciphertext. */
+declare const ENVELOPE_HEADER_SIZE: number;
+interface EncryptOptions {
+    /**
+     * Optional associated data — authenticated but not encrypted.
+     * Caller must supply the same value on decrypt.
+     */
+    aad?: Uint8Array;
+    /**
+     * Override the per-call IV. Strongly discouraged outside of tests:
+     * GCM is catastrophically broken if an IV is reused under the same
+     * key. Production callers should always let the cipher generate a
+     * fresh random IV.
+     */
+    iv?: Uint8Array;
+}
+interface DecryptOptions {
+    /** Same AAD that was supplied to `encrypt`. */
+    aad?: Uint8Array;
+}
+/**
+ * Encrypt `plaintext` under `key` and return a sealed envelope buffer.
+ *
+ * @param key 32-byte AES-256 key (from `deriveKey`).
+ * @param salt 16-byte KDF salt to embed in the envelope. The caller is
+ *   responsible for using the same salt that was passed to the KDF.
+ * @param plaintext the bytes to encrypt.
+ * @param options optional `aad` / `iv` overrides.
+ */
+declare function seal(key: Uint8Array, salt: Uint8Array, plaintext: Uint8Array, options?: EncryptOptions): Buffer;
+/** Parsed view of a sealed envelope. Useful for inspection in tests. */
+interface ParsedEnvelope {
+    version: number;
+    salt: Buffer;
+    iv: Buffer;
+    authTag: Buffer;
+    ciphertext: Buffer;
+}
+/**
+ * Parse a sealed envelope into its component fields without
+ * decrypting. Throws on malformed input. The returned buffers are
+ * sub-views (not copies) — do not mutate.
+ */
+declare function parseEnvelope(envelope: Uint8Array): ParsedEnvelope;
+/**
+ * Decrypt a sealed envelope and return the plaintext.
+ *
+ * Throws on:
+ *   - malformed envelope (wrong length, wrong version);
+ *   - wrong key (auth-tag mismatch);
+ *   - tampered ciphertext / iv / auth tag (auth-tag mismatch);
+ *   - mismatched AAD (auth-tag mismatch).
+ *
+ * The same error class is intentional: from the caller's standpoint
+ * "wrong passphrase" and "tampered ciphertext" should both be
+ * non-recoverable failures.
+ */
+declare function open(key: Uint8Array, envelope: Uint8Array, options?: DecryptOptions): Buffer;
+/**
+ * Generate a fresh random salt of the canonical envelope length.
+ * Convenience wrapper so callers don't reach into `node:crypto`.
+ */
+declare function generateSalt(): Buffer;
+
+/**
+ * Key-derivation functions for the secure-store module.
+ *
+ * Issue #690 (PR 1/4) — pure primitives, no I/O.
+ *
+ * Naming note
+ * -----------
+ * The directory is named `secure-store/` — NOT `vault/` — because
+ * `vault` is already a content-source concept in `native-knowledge.ts`
+ * (Obsidian vaults: `ObsidianVaultState`, `vaultId`, `obsidianVaults`
+ * config, etc.). Reusing the `vault` namespace for at-rest encryption
+ * would cause symbol collisions and reader confusion.
+ *
+ * KDF choice — Argon2id primary, scrypt compatibility
+ * ---------------------------------------------------
+ * Issue #690 specifies Argon2id (OWASP m=64 MiB, t=3, p=4) as the
+ * preferred KDF. We use `@node-rs/argon2` for the Argon2id runtime
+ * and keep scrypt as the compatibility path for stores initialized
+ * before Argon2id support landed.
+ *
+ * The algorithm name + params are persisted in the metadata file, so
+ * stores keep deriving with the same KDF they were initialized with.
+ *
+ * Trade-off summary:
+ *   - scrypt N=2^17, r=8, p=1 → ~128 MiB memory, ~150 ms on a modern
+ *     laptop. Memory-hard. Resists GPU/ASIC attacks meaningfully.
+ *   - Argon2id m=64 MiB, t=3, p=4 → ~64 MiB memory, similar wall
+ *     time. Considered the modern best-in-class but requires native
+ *     bindings.
+ *
+ * Both produce a 32-byte key suitable for AES-256-GCM.
+ */
+/** KDF algorithms supported by the secure-store metadata format. */
+type KdfAlgorithm = "scrypt" | "argon2id";
+/** Parameters for the scrypt KDF (RFC 7914). */
+interface ScryptParams {
+    /** CPU/memory cost. Must be a power of 2. Default 2^17 = 131072. */
+    N: number;
+    /** Block size. Default 8. */
+    r: number;
+    /** Parallelization. Default 1. */
+    p: number;
+    /** Output key length in bytes. Default 32 (AES-256). */
+    keyLength: number;
+    /** maxmem ceiling for scrypt; defaults to 256 MiB. */
+    maxmem: number;
+}
+/** Parameters for the Argon2id KDF. */
+interface Argon2idParams {
+    /** Memory cost in KiB. OWASP default 65536 (64 MiB). */
+    memoryKiB: number;
+    /** Time cost (iterations). OWASP default 3. */
+    iterations: number;
+    /** Parallelism. OWASP default 4. */
+    parallelism: number;
+    /** Output key length in bytes. Default 32 (AES-256). */
+    keyLength: number;
+}
+/** Strong scrypt defaults (OWASP-acceptable for 2024+). */
+declare const DEFAULT_SCRYPT_PARAMS: Readonly<ScryptParams>;
+/** OWASP Argon2id defaults. */
+declare const DEFAULT_ARGON2ID_PARAMS: Readonly<Argon2idParams>;
+/** Salt length in bytes. 128 bits is the modern minimum. */
+declare const KDF_SALT_LENGTH = 16;
+/** Required derived-key length for AES-256 (32 bytes). */
+declare const KDF_KEY_LENGTH = 32;
+/**
+ * Validate that scrypt parameters are within sane bounds and that
+ * `N` is a power of 2 (required by RFC 7914).
+ */
+declare function validateScryptParams(params: ScryptParams): void;
+/**
+ * Derive a key from a passphrase + salt using scrypt.
+ *
+ * Pure: no I/O, no global state, deterministic for a given
+ * (passphrase, salt, params) tuple.
+ *
+ * @throws if params are invalid.
+ */
+declare function deriveKeyScrypt(passphrase: string, salt: Uint8Array, params?: ScryptParams): Buffer;
+/**
+ * Algorithm-dispatching KDF. The algorithm name is recorded in the
+ * metadata file so existing stores continue using their original KDF.
+ */
+declare function deriveKey(algorithm: KdfAlgorithm, passphrase: string, salt: Uint8Array, params: ScryptParams | Argon2idParams): Buffer;
+/**
+ * Constant-time equality for two derived keys / MACs. Re-exported so
+ * callers don't reach into `node:crypto` directly for this primitive.
+ */
+declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Secure-store metadata file format.
+ *
+ * Issue #690 (PR 1/4) — pure data structure + serialize/parse helpers.
+ * No I/O. The eventual `secure-store init` CLI (PR 2/4) will be the
+ * surface that actually writes a metadata file to disk.
+ *
+ * Purpose
+ * -------
+ * When at-rest encryption is enabled, the memory directory needs a
+ * stable record of:
+ *
+ *   - which KDF algorithm was used to derive the master key,
+ *   - the algorithm parameters (so changing OWASP defaults later
+ *     doesn't break existing stores),
+ *   - the canonical salt for the master key,
+ *   - the metadata format version (so we can evolve the file).
+ *
+ * Crucially, the metadata file does **not** contain the master key,
+ * the passphrase, or anything that would let an attacker decrypt
+ * memories. It contains only the public parameters needed to
+ * re-derive the same key from the same passphrase.
+ *
+ * On-disk shape
+ * -------------
+ * The file is JSON. All binary fields are encoded as lowercase hex
+ * strings (chosen over base64 for readability when the file is
+ * `cat`'d during incident response).
+ *
+ *   {
+ *     "format": "remnic.secure-store.metadata",
+ *     "formatVersion": 1,
+ *     "kdf": {
+ *       "algorithm": "argon2id",
+ *       "params": { "memoryKiB": 65536, "iterations": 3, "parallelism": 4, "keyLength": 32 },
+ *       "salt": "<32-hex-chars-for-16-bytes>"
+ *     },
+ *     "createdAt": "<ISO-8601 timestamp>",
+ *     "note": "<optional human-readable note>"
+ *   }
+ */
+
+/** Stable identifier so we can sniff the file shape without parsing JSON. */
+declare const METADATA_FORMAT: "remnic.secure-store.metadata";
+/** Current metadata format version. Bump on breaking schema changes. */
+declare const METADATA_FORMAT_VERSION: 1;
+interface SecureStoreMetadataKdfScrypt {
+    algorithm: "scrypt";
+    params: ScryptParams;
+    /** Hex-encoded salt. Length must match `KDF_SALT_LENGTH` after decode. */
+    salt: string;
+}
+interface SecureStoreMetadataKdfArgon2id {
+    algorithm: "argon2id";
+    params: Argon2idParams;
+    salt: string;
+}
+type SecureStoreMetadataKdf = SecureStoreMetadataKdfScrypt | SecureStoreMetadataKdfArgon2id;
+interface SecureStoreMetadata {
+    format: typeof METADATA_FORMAT;
+    formatVersion: number;
+    kdf: SecureStoreMetadataKdf;
+    /** ISO-8601 timestamp recorded at init time. */
+    createdAt: string;
+    /** Optional human-readable note. Never persist secrets here. */
+    note?: string;
+}
+interface BuildMetadataOptions {
+    algorithm: KdfAlgorithm;
+    salt: Uint8Array;
+    /** Optional override; defaults to `DEFAULT_SCRYPT_PARAMS` / `DEFAULT_ARGON2ID_PARAMS`. */
+    params?: ScryptParams | Argon2idParams;
+    /** Optional ISO timestamp. Defaults to `new Date().toISOString()`. */
+    createdAt?: string;
+    /** Optional human-readable note. */
+    note?: string;
+}
+/**
+ * Build an in-memory `SecureStoreMetadata` object from the given
+ * algorithm + salt. Pure: does not touch the filesystem or the clock
+ * unless `createdAt` is omitted (in which case `new Date()` is read).
+ */
+declare function buildMetadata(options: BuildMetadataOptions): SecureStoreMetadata;
+/**
+ * Serialize metadata to a stable JSON string with sorted top-level
+ * keys. Stable ordering matters because hash-based integrity checks
+ * may eventually consume the serialized form.
+ */
+declare function serializeMetadata(meta: SecureStoreMetadata): string;
+/**
+ * Parse a metadata JSON string. Throws on any structural problem.
+ * Callers that need to migrate older formats should branch on
+ * `formatVersion` *before* calling this; this function is strict
+ * about the current version.
+ */
+declare function parseMetadata(json: string): SecureStoreMetadata;
+/** Validate a metadata object's invariants. Throws on the first problem. */
+declare function validateMetadata(meta: SecureStoreMetadata): void;
+/**
+ * Decode the salt field of a metadata object back into bytes.
+ * Convenience helper so callers don't reach into the hex codec.
+ */
+declare function decodeMetadataSalt(meta: SecureStoreMetadata): Buffer;
+
+/**
+ * On-disk header for an initialized secure-store (issue #690 PR 2/4).
+ *
+ * The header file is the persistent record that a memory directory
+ * has had `remnic secure-store init` run against it. It is a JSON
+ * file at `<memoryDir>/.secure-store/header.json` with two parts:
+ *
+ *   1. The KDF metadata from PR 1/4 (`SecureStoreMetadata`) —
+ *      algorithm, params, and salt. Public; safe to read/copy.
+ *   2. A "verifier" — a tiny AES-GCM-encrypted envelope sealed under
+ *      the derived key at init time. Unlock re-derives the key from
+ *      the entered passphrase and tries to `open()` the verifier; if
+ *      the auth tag validates, the passphrase is correct.
+ *
+ * Why a verifier?
+ * ---------------
+ * Without one, "wrong passphrase" can only be detected when the
+ * daemon tries to decrypt actual memory data — too late for a
+ * useful CLI error. The verifier gives the unlock command a fast,
+ * data-independent passphrase check.
+ *
+ * The verifier plaintext is a fixed magic string (no secret content).
+ * Its only role is to be sealable + openable; the auth-tag check is
+ * what proves the key.
+ *
+ * Naming
+ * ------
+ * Directory: `.secure-store/` (leading dot — hidden, hints at
+ * sensitivity). File: `header.json`. Avoids collision with
+ * `.secure-store-metadata.json` from PR 1/4 docs since the header
+ * is a strict superset.
+ */
+
+/** Subdirectory under `memoryDir` that holds the header + future state. */
+declare const SECURE_STORE_DIR_NAME = ".secure-store";
+/** Header filename. Stable name so operators can locate it. */
+declare const HEADER_FILENAME = "header.json";
+/** Stable identifier so the file shape is sniffable without parsing JSON. */
+declare const HEADER_FORMAT: "remnic.secure-store.header";
+/** Current header format version. Bump on breaking schema changes. */
+declare const HEADER_FORMAT_VERSION: 1;
+interface SecureStoreHeader {
+    format: typeof HEADER_FORMAT;
+    formatVersion: number;
+    /** KDF metadata (algorithm + params + salt). */
+    metadata: SecureStoreMetadata;
+    /** Hex-encoded sealed envelope. */
+    verifier: string;
+    /** ISO-8601 timestamp recorded at init time. */
+    createdAt: string;
+}
+/** Resolve the canonical secure-store directory for a memory root. */
+declare function secureStoreDir(memoryDir: string): string;
+/** Resolve the canonical header path for a memory root. */
+declare function headerPath(memoryDir: string): string;
+/**
+ * Build a `SecureStoreHeader` in memory from an already-derived key
+ * and metadata. Pure: does not touch the filesystem. The clock is
+ * read once if `createdAt` is omitted.
+ */
+declare function buildHeader(options: {
+    metadata: SecureStoreMetadata;
+    derivedKey: Buffer;
+    createdAt?: string;
+}): SecureStoreHeader;
+/** Stable JSON serialization with locked top-level key order. */
+declare function serializeHeader(header: SecureStoreHeader): string;
+/** Parse a header JSON string. Throws on any structural problem. */
+declare function parseHeader(json: string): SecureStoreHeader;
+/** Validate a header object's invariants. Throws on the first problem. */
+declare function validateHeader(header: SecureStoreHeader): void;
+/**
+ * Verify a candidate key against the header's verifier envelope.
+ *
+ * Returns true iff the AES-GCM auth tag validates. Wrong passphrase,
+ * tampered envelope, and tampered AAD all return false.
+ */
+declare function verifyKey(header: SecureStoreHeader, candidateKey: Buffer): boolean;
+/**
+ * Derive a key from the passphrase using the algorithm + params +
+ * salt recorded in the header. Pure: no I/O.
+ */
+declare function deriveKeyFromHeader(header: SecureStoreHeader, passphrase: string): Buffer;
+/**
+ * Read and parse the header at `<memoryDir>/.secure-store/header.json`.
+ * Returns `null` if the file does not exist; throws on malformed
+ * content.
+ */
+declare function readHeader(memoryDir: string): Promise<SecureStoreHeader | null>;
+/**
+ * Write the header with atomic exclusive-create semantics.
+ *
+ * Uses the `wx` flag (`O_CREAT | O_EXCL`) so the OS rejects the call
+ * atomically when the file already exists. Two concurrent
+ * `secure-store init` invocations cannot both observe "missing" and
+ * race to overwrite each other — the second writer reliably gets
+ * `EEXIST` and surfaces "Refusing to overwrite".
+ *
+ * Codex P1 on PR #737: a previous version pre-checked existence with
+ * `readFile` then `writeFile`+`rename`, which is a check-then-act
+ * race. The `wx` flag closes that window at the kernel layer.
+ *
+ * Crash safety: if the write is interrupted mid-flight, a partial
+ * `header.json` may remain on disk. `parseHeader` rejects partial
+ * files cleanly and the operator can delete the stub and retry. We
+ * don't use temp+rename here because (a) headers are tiny (≤ 1 KiB),
+ * (b) there is no prior valid file to destroy, and (c) `wx` already
+ * gives us atomic exclusivity — the rename trick (CLAUDE.md gotcha
+ * #54) is for replacing an existing valid file, which is exactly the
+ * scenario this function refuses.
+ */
+declare function writeHeader(memoryDir: string, header: SecureStoreHeader): Promise<string>;
+/** Convenience: build metadata + header in one call from a passphrase. */
+declare function buildHeaderFromPassphrase(options: {
+    passphrase: string;
+    salt: Buffer;
+    /** Optional override; defaults to Argon2id with `DEFAULT_ARGON2ID_PARAMS`. */
+    algorithm?: "scrypt" | "argon2id";
+    params?: ScryptParams | Argon2idParams;
+    createdAt?: string;
+    note?: string;
+}): {
+    header: SecureStoreHeader;
+    derivedKey: Buffer;
+};
+
+/**
+ * In-memory keyring for the secure-store module (issue #690 PR 2/4).
+ *
+ * Holds derived AES-256-GCM master keys for unlocked stores. The
+ * keyring is process-local: keys are NEVER persisted to disk, never
+ * logged, and never serialized. A daemon restart re-locks every
+ * registered store.
+ *
+ * Scoping
+ * -------
+ * Entries are keyed by a stable string id (typically the absolute
+ * path to the secure-store directory, after `~` expansion). This
+ * lets multiple memory roots share a single daemon process without
+ * one store's key bleeding into another (matches the per-`serviceId`
+ * scoping discipline called out in CLAUDE.md gotcha #11).
+ *
+ * Lifecycle
+ * ---------
+ *   - `unlock(id, key)` — register a derived key.
+ *   - `getKey(id)` — read a registered key (or `null`).
+ *   - `lock(id)` — clear a single entry, zeroing the key bytes.
+ *   - `lockAll()` — clear every entry, zeroing every key.
+ *   - `status(id)` — non-secret status snapshot for `secure-store
+ *     status`.
+ *
+ * Zeroization
+ * -----------
+ * `lock` and `lockAll` overwrite the key buffer with zeros before
+ * dropping the reference. The JS engine may keep additional copies
+ * outside our control; this is best-effort hygiene, not a defense
+ * against memory-dump attacks.
+ */
+/** Status snapshot — no secret material. */
+interface KeyringStatus {
+    /** True iff a key is currently registered for this id. */
+    unlocked: boolean;
+    /** ISO-8601 timestamp the key was registered, or null when locked. */
+    unlockedAt: string | null;
+}
+/**
+ * Register a derived key for the given id. If an entry already
+ * exists, its old key is zeroed before being replaced.
+ *
+ * The caller MUST pass an exclusive 32-byte buffer; the keyring
+ * takes ownership and will zero it on lock.
+ */
+declare function unlock(id: string, key: Buffer, now?: () => Date): void;
+/** Read the registered key for `id`, or `null` if locked. */
+declare function getKey(id: string): Buffer | null;
+/** Clear a single entry. Zeros the underlying buffer. Returns true if cleared. */
+declare function lock(id: string): boolean;
+/** Clear every registered key. Used on shutdown or for tests. */
+declare function lockAll(): void;
+/** Non-secret status snapshot. */
+declare function status(id: string): KeyringStatus;
+/** Test-only helper: how many entries are currently registered. */
+declare function size(): number;
+
+type keyring_KeyringStatus = KeyringStatus;
+declare const keyring_getKey: typeof getKey;
+declare const keyring_lock: typeof lock;
+declare const keyring_lockAll: typeof lockAll;
+declare const keyring_size: typeof size;
+declare const keyring_status: typeof status;
+declare const keyring_unlock: typeof unlock;
+declare namespace keyring {
+  export { type keyring_KeyringStatus as KeyringStatus, keyring_getKey as getKey, keyring_lock as lock, keyring_lockAll as lockAll, keyring_size as size, keyring_status as status, keyring_unlock as unlock };
+}
+
+/**
+ * Transparent file-level encryption for the secure-store module.
+ *
+ * Issue #690 (PR 3/4) — storage.ts integration layer.
+ *
+ * This module sits between the raw filesystem and StorageManager.
+ * Every memory file is either:
+ *   - a plain UTF-8 text file (legacy, back-compat), or
+ *   - a REMNIC-ENC sealed file (AES-256-GCM, see format below).
+ *
+ * On-disk format
+ * --------------
+ * Encrypted files begin with a 9-byte magic header:
+ *
+ *   REMNIC-ENC  (7 ASCII bytes)
+ *   VER         (1 byte, currently 0x01)
+ *   FLAGS       (1 byte, reserved, must be 0x00)
+ *
+ * Followed immediately by a `seal()` envelope from `cipher.ts`:
+ *
+ *   [VERSION:1][SALT:16][IV:12][AUTHTAG:16][CIPHERTEXT:...]
+ *
+ * The magic header makes encrypted files sniffable without attempting
+ * a full `open()` call and gives operators a clear signal that the
+ * file cannot be read by opening it in an editor.
+ *
+ * AAD
+ * ---
+ * The file path relative to the memory root is bound as Associated
+ * Authenticated Data (AAD) on both encrypt and decrypt. This means
+ * moving or renaming an encrypted file without re-encrypting it will
+ * cause auth-tag failure on the next read — the file is tied to its
+ * path. Callers that move files must re-encrypt them.
+ *
+ * Back-compat
+ * -----------
+ * `readMaybeEncryptedFile` transparently handles both formats: if the
+ * file does NOT start with the magic bytes, it is returned as-is (plain
+ * text). This lets an operator migrate incrementally: newly-written
+ * files are encrypted while existing files continue to be read in plain
+ * form until `migrateMemoryDirToEncrypted` is run.
+ *
+ * Naming: `secure-fs.ts` (not `vault-fs.ts`) — see `kdf.ts` naming note.
+ */
+/**
+ * Thrown when a read is attempted but the keyring entry for this
+ * store is absent (i.e. `secure-store unlock` has not been run
+ * since the last daemon start).
+ */
+declare class SecureStoreLockedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown when `open()` fails because the auth tag does not validate.
+ * This covers both wrong-key and tampered-ciphertext scenarios —
+ * intentionally indistinguishable from the caller's perspective.
+ */
+declare class SecureStoreDecryptError extends Error {
+    constructor(message?: string);
+}
+/** Magic bytes: the ASCII string "REMNIC-ENC" (10 bytes). */
+declare const MAGIC_BYTES: Buffer<ArrayBuffer>;
+/** Current on-disk version byte. */
+declare const FILE_FORMAT_VERSION = 1;
+/** Reserved flags byte — must be 0x00. */
+declare const FILE_FORMAT_FLAGS = 0;
+/** Total size of the magic header prefix (magic + version + flags). */
+declare const MAGIC_HEADER_SIZE: number;
+/**
+ * Return true iff `buf` begins with the REMNIC-ENC magic header.
+ * Does not validate the envelope; just identifies the format.
+ */
+declare function isEncryptedFile(buf: Uint8Array): boolean;
+/**
+ * Encrypt `plain` (UTF-8 content of a memory file) and return a
+ * Buffer ready to write to disk.
+ *
+ * @param plain  Plain-text file content (UTF-8 string or Buffer).
+ * @param key    32-byte AES-256 key from the keyring.
+ * @param aad    Optional associated data — defaults to empty if omitted.
+ *               Callers should pass the file path relative to memoryDir
+ *               so the ciphertext is bound to its location.
+ */
+declare function encryptFileBody(plain: string | Buffer, key: Buffer, aad?: Buffer): Buffer;
+/**
+ * Decrypt a buffer produced by `encryptFileBody` and return the
+ * original UTF-8 content.
+ *
+ * Throws `SecureStoreDecryptError` on auth failure (wrong key or
+ * tampered ciphertext). Throws a plain `Error` for structural problems
+ * (truncated buffer, wrong magic, unsupported version).
+ */
+declare function decryptFileBody(buf: Buffer, key: Buffer, aad?: Buffer): Buffer;
+/**
+ * Build the AAD buffer for a file at `filePath` relative to
+ * `memoryDir`. The AAD binds the ciphertext to its path so a
+ * file cannot be silently relocated without re-encryption.
+ *
+ * When `memoryDir` is supplied and `filePath` is absolute, the
+ * relative sub-path is used. Otherwise `filePath` is used verbatim.
+ */
+declare function filePathAad(filePath: string, memoryDir?: string): Buffer;
+/**
+ * Read a file from `filePath`.
+ *
+ * - If the file is plaintext (no magic header), return its content
+ *   as-is — back-compat with unencrypted stores.
+ * - If the file is encrypted AND `key` is provided, decrypt and return
+ *   the plaintext content.
+ * - If the file is encrypted AND `key` is null, throw
+ *   `SecureStoreLockedError`.
+ *
+ * @param filePath  Absolute path to the file.
+ * @param key       32-byte AES-256 key, or null when the store is locked.
+ * @param memoryDir Memory root for path-bound AAD.  Should be absolute.
+ */
+declare function readMaybeEncryptedFile(filePath: string, key: Buffer | null, memoryDir?: string): Promise<string>;
+interface WriteMaybeEncryptedFileOptions {
+    /**
+     * File mode bits. Default 0o600 (owner read/write only).
+     * Applied only on create; existing files inherit their existing mode.
+     */
+    mode?: number;
+    /**
+     * If true, write atomically via a temp file + rename (CLAUDE.md gotcha #54).
+     * Default true.
+     */
+    atomic?: boolean;
+}
+/**
+ * Write `content` to `filePath`.
+ *
+ * - If `key` is provided and non-null, encrypt the content first.
+ * - If `key` is null, write the content as plain UTF-8 (unencrypted store).
+ *
+ * Writes atomically: content is written to a `.tmp-<pid>-<ts>` file
+ * first, then renamed into place (CLAUDE.md gotcha #54 — never delete
+ * before write).
+ */
+declare function writeMaybeEncryptedFile(filePath: string, content: string, key: Buffer | null, options?: WriteMaybeEncryptedFileOptions, memoryDir?: string): Promise<void>;
+interface MigrateResult {
+    /** Number of files successfully encrypted. */
+    encrypted: number;
+    /** Number of files already encrypted (skipped). */
+    skipped: number;
+    /** Files that failed to encrypt (path → error message). */
+    errors: Array<{
+        filePath: string;
+        error: string;
+    }>;
+}
+interface DecryptResult {
+    /** Number of files successfully decrypted back to plaintext. */
+    decrypted: number;
+    /** Number of files already plaintext (skipped). */
+    skipped: number;
+    /** Files that failed to decrypt (path → error message). */
+    errors: Array<{
+        filePath: string;
+        error: string;
+    }>;
+}
+/**
+ * Walk `dir` recursively, find encryptable storage-managed files that are not
+ * yet encrypted, and re-write them as encrypted files under `key`.
+ *
+ * Safety rules per CLAUDE.md gotchas #54 and #25:
+ *   1. A page-version snapshot is taken (via `createVersion`) BEFORE
+ *      each overwrite so the plaintext version is preserved in history.
+ *      Since this module has no direct access to `page-versioning.ts`
+ *      internals, callers who have page-versioning configured should
+ *      pass `onBeforeEncrypt` to take the snapshot.
+ *   2. The new encrypted content is written to a temp file first,
+ *      then renamed atomically — never deleted before written.
+ *   3. If encryption of any file fails, the error is recorded and the
+ *      original file is left intact (partial migration is safe).
+ *
+ * @param dir              Absolute path to the memory directory.
+ * @param key              32-byte AES-256 key.
+ * @param onBeforeEncrypt  Optional callback invoked before encrypting
+ *                         each file. Can be used to take page-version
+ *                         snapshots. Errors here are non-fatal.
+ */
+declare function migrateMemoryDirToEncrypted(dir: string, key: Buffer, onBeforeEncrypt?: (filePath: string) => Promise<void>): Promise<MigrateResult>;
+/**
+ * Walk `dir` recursively, find storage-managed encrypted files, and
+ * re-write them as plaintext under the same paths.
+ *
+ * This is the reversible counterpart to {@link migrateMemoryDirToEncrypted}.
+ * It only touches files under the same storage-managed roots, skips
+ * plaintext files, skips symlinks, excludes `.secure-store/`, and writes
+ * each plaintext replacement via temp-file + rename so a per-file failure
+ * leaves the ciphertext intact.
+ */
+declare function decryptMemoryDirToPlaintext(dir: string, key: Buffer): Promise<DecryptResult>;
+
+/**
+ * Pure handlers behind the `remnic secure-store {init,unlock,lock,
+ * status,migrate,disable}` CLI surface (issue #690 PR 2/4 + #779/#780).
+ *
+ * Each handler:
+ *   - takes an explicit `memoryDir` (already `~`-expanded by the CLI),
+ *   - takes an injectable passphrase reader (so tests don't need a
+ *     real TTY and never touch real readline state),
+ *   - returns a structured report (no `console.log` inside),
+ *   - never logs the passphrase or any secret material.
+ *
+ * The actual `console.log` formatting lives in `cli-renderer.ts` so
+ * tests can assert on the report shape without parsing text.
+ */
+
+/** Passphrase source — async so callers can read from a TTY without echo. */
+type PassphraseReader = (prompt: string, options?: {
+    confirm?: boolean;
+}) => Promise<string>;
+/** Common options accepted by every handler. */
+interface SecureStoreHandlerCommon {
+    memoryDir: string;
+    /**
+     * Stable identifier for the in-memory keyring entry. Defaults to
+     * the secure-store directory under `memoryDir`. Tests override
+     * this to keep entries from leaking across cases.
+     */
+    keyringId?: string;
+    /** Optional clock injection for deterministic tests. */
+    now?: () => Date;
+}
+interface SecureStoreInitOptions extends SecureStoreHandlerCommon {
+    /** Passphrase reader — called twice (entry + confirmation). */
+    readPassphrase: PassphraseReader;
+    /**
+     * KDF algorithm. Defaults to `"argon2id"` for new stores.
+     * `"scrypt"` remains supported for explicit compatibility cases.
+     */
+    algorithm?: KdfAlgorithm;
+    /** KDF parameter override; defaults to OWASP-acceptable params for the selected KDF. */
+    params?: ScryptParams | Argon2idParams;
+    /** Pre-generated salt for tests; production callers should omit. */
+    salt?: Buffer;
+    /** Optional human-readable note recorded in metadata. Never persist secrets. */
+    note?: string;
+}
+interface SecureStoreInitReport {
+    ok: true;
+    /** Absolute path of the header file that was written. */
+    headerPath: string;
+    /** Algorithm + params used for the master key derivation. */
+    kdf: SecureStoreHeader["metadata"]["kdf"];
+    /** ISO-8601 timestamp recorded in the header. */
+    createdAt: string;
+}
+/**
+ * Initialize a new secure-store header. Refuses to overwrite an
+ * existing header (use `header.ts:writeHeader` directly with explicit
+ * intent if you need to reinitialize a destroyed store).
+ */
+declare function runSecureStoreInit(options: SecureStoreInitOptions): Promise<SecureStoreInitReport>;
+interface SecureStoreUnlockOptions extends SecureStoreHandlerCommon {
+    readPassphrase: PassphraseReader;
+}
+type SecureStoreUnlockReport = {
+    ok: true;
+    unlockedAt: string;
+    algorithm: KdfAlgorithm;
+} | {
+    ok: false;
+    reason: "not-initialized" | "wrong-passphrase";
+};
+declare function runSecureStoreUnlock(options: SecureStoreUnlockOptions): Promise<SecureStoreUnlockReport>;
+interface SecureStoreLockOptions extends SecureStoreHandlerCommon {
+}
+interface SecureStoreLockReport {
+    ok: true;
+    /** True if a key was registered and is now cleared; false if it was already locked. */
+    cleared: boolean;
+}
+declare function runSecureStoreLock(options: SecureStoreLockOptions): SecureStoreLockReport;
+interface SecureStoreMigrateOptions extends SecureStoreHandlerCommon {
+}
+type SecureStoreMigrateReport = ({
+    ok: true;
+} & MigrateResult) | ({
+    ok: false;
+    reason: "not-initialized" | "locked" | "file-errors";
+} & MigrateResult);
+declare function runSecureStoreMigrate(options: SecureStoreMigrateOptions): Promise<SecureStoreMigrateReport>;
+interface SecureStoreDisableOptions extends SecureStoreHandlerCommon {
+}
+type SecureStoreDisableReport = ({
+    ok: true;
+} & DecryptResult) | ({
+    ok: false;
+    reason: "not-initialized" | "locked" | "file-errors";
+} & DecryptResult);
+declare function runSecureStoreDisable(options: SecureStoreDisableOptions): Promise<SecureStoreDisableReport>;
+interface SecureStoreStatusOptions extends SecureStoreHandlerCommon {
+}
+interface SecureStoreStatusReport {
+    /** True iff a header file exists in `<memoryDir>/.secure-store/`. */
+    initialized: boolean;
+    /** Path the status check probed. Useful for operators. */
+    headerPath: string;
+    /** Locked/unlocked state of the in-memory keyring entry. */
+    locked: boolean;
+    /** ISO-8601 timestamp of the most recent unlock, or null when locked. */
+    unlockedAt: string | null;
+    /** Header metadata (algorithm + params + salt hex), or null when uninitialized. */
+    kdf: SecureStoreHeader["metadata"]["kdf"] | null;
+    /** Header `createdAt`, or null when uninitialized. */
+    createdAt: string | null;
+}
+declare function runSecureStoreStatus(options: SecureStoreStatusOptions): Promise<SecureStoreStatusReport>;
+/** Minimum passphrase length. 8 chars is intentionally permissive — operators may use phrase managers. */
+declare const MIN_PASSPHRASE_LENGTH = 8;
+
+/**
+ * Console-text renderers for the `remnic engram secure-store {init,unlock,
+ * lock,status,migrate,disable}` CLI surface (issue #690 PR 2/4 + #779/#780).
+ *
+ * Pure: each `render*` function takes a typed report and returns a
+ * string. CLI handlers do the `console.log`. Tests assert on the
+ * returned text directly so behavior stays decoupled from stdout.
+ */
+
+declare function renderInitReport(report: SecureStoreInitReport): string;
+declare function renderUnlockReport(report: SecureStoreUnlockReport): string;
+declare function renderLockReport(report: SecureStoreLockReport): string;
+declare function renderMigrateReport(report: SecureStoreMigrateReport): string;
+declare function renderDisableReport(report: SecureStoreDisableReport): string;
+declare function renderStatusReport(report: SecureStoreStatusReport): string;
+
+/**
+ * TTY passphrase reader (issue #690 PR 2/4).
+ *
+ * Reads a line from stdin without echoing it back to the terminal.
+ * Disables echo by setting raw mode + manually buffering input until
+ * Enter / EOT.
+ *
+ * Why not `readline.question`?
+ * ----------------------------
+ * `readline` echoes by default and has no clean "no-echo" toggle that
+ * survives across Node versions. The raw-mode loop is the canonical
+ * idiom for reading passwords on Node and matches what `npm` uses
+ * internally.
+ *
+ * Security
+ * --------
+ *   - Never log the passphrase (no `console.log`, no debug output).
+ *   - Never include it in a thrown error message.
+ *   - On Ctrl+C / Ctrl+D, abort with a clear error rather than
+ *     silently treating EOF as an empty submission.
+ *   - On non-TTY stdin (pipe, redirect), read a line via line-buffered
+ *     readline so automation (`echo "passphrase" | remnic ...`) works.
+ *     Operators are responsible for not piping plaintext passphrases
+ *     in shell history; we surface a stderr warning.
+ */
+
+interface CreatePassphraseReaderOptions {
+    input?: Readable;
+    output?: Writable;
+    /** Override stderr for warning surface; defaults to `process.stderr`. */
+    errorStream?: Writable;
+}
+/**
+ * Build a `PassphraseReader` bound to the given streams. Exported so
+ * tests can construct one against in-memory streams without touching
+ * the real TTY.
+ */
+declare function createPassphraseReader(options?: CreatePassphraseReaderOptions): PassphraseReader;
+
+export { AES_KEY_LENGTH, AUTH_TAG_LENGTH, type Argon2idParams, type BuildMetadataOptions, DEFAULT_ARGON2ID_PARAMS, DEFAULT_SCRYPT_PARAMS, type DecryptOptions, type DecryptResult, ENVELOPE_HEADER_SIZE, ENVELOPE_LAYOUT, ENVELOPE_SALT_LENGTH, ENVELOPE_VERSION, type EncryptOptions, FILE_FORMAT_FLAGS, FILE_FORMAT_VERSION, HEADER_FILENAME, HEADER_FORMAT, HEADER_FORMAT_VERSION, IV_LENGTH, KDF_KEY_LENGTH, KDF_SALT_LENGTH, type KdfAlgorithm, MAGIC_BYTES, MAGIC_HEADER_SIZE, METADATA_FORMAT, METADATA_FORMAT_VERSION, MIN_PASSPHRASE_LENGTH, type MigrateResult, type ParsedEnvelope, type PassphraseReader, SECURE_STORE_DIR_NAME, type ScryptParams, SecureStoreDecryptError, type SecureStoreDisableOptions, type SecureStoreDisableReport, type SecureStoreHeader, type SecureStoreInitOptions, type SecureStoreInitReport, type SecureStoreLockOptions, type SecureStoreLockReport, SecureStoreLockedError, type SecureStoreMetadata, type SecureStoreMetadataKdf, type SecureStoreMetadataKdfArgon2id, type SecureStoreMetadataKdfScrypt, type SecureStoreMigrateOptions, type SecureStoreMigrateReport, type SecureStoreStatusOptions, type SecureStoreStatusReport, type SecureStoreUnlockOptions, type SecureStoreUnlockReport, type WriteMaybeEncryptedFileOptions, buildHeader, buildHeaderFromPassphrase, buildMetadata, constantTimeEqual, createPassphraseReader, decodeMetadataSalt, decryptFileBody, decryptMemoryDirToPlaintext, deriveKey, deriveKeyFromHeader, deriveKeyScrypt, encryptFileBody, filePathAad, generateSalt, headerPath, isEncryptedFile, keyring, migrateMemoryDirToEncrypted, open, parseEnvelope, parseHeader, parseMetadata, readHeader, readMaybeEncryptedFile, renderDisableReport, renderInitReport, renderLockReport, renderMigrateReport, renderStatusReport, renderUnlockReport, runSecureStoreDisable, runSecureStoreInit, runSecureStoreLock, runSecureStoreMigrate, runSecureStoreStatus, runSecureStoreUnlock, seal, secureStoreDir, serializeHeader, serializeMetadata, validateHeader, validateMetadata, validateScryptParams, verifyKey, writeHeader, writeMaybeEncryptedFile };