@noy-db/hub 0.1.0-pre.3

package/dist/index-DhjMjz7L.d.cts

@@ -0,0 +1,380 @@
+import { aU as BundleRecipient, aR as Vault } from './types-Bfs0qr5F.cjs';
+
+/**
+ * `.noydb` container format — byte layout, header schema, validators.
+ *
+ *. Wraps a `vault.dump()` JSON string in a thin
+ * binary container with a magic-byte prefix, a minimum-disclosure
+ * unencrypted header, and a compressed body.
+ *
+ * **Byte layout** (read in order from offset 0):
+ *
+ * ```
+ * +--------+--------+--------+--------+
+ * |  N=78  |  D=68  |  B=66  |  1=49  |  Magic 'NDB1' (4 bytes)
+ * +--------+--------+--------+--------+
+ * | flags  | compr  |  header_length (uint32 BE)            |
+ * +--------+--------+--------+--------+--------+--------+--------+
+ * | header_length bytes of UTF-8 JSON header                       ...
+ * +--------+--------+
+ * | compressed body bytes                                            ...
+ * ```
+ *
+ * Total fixed prefix before the header JSON is **10 bytes**:
+ *   - 4 bytes magic
+ *   - 1 byte flags
+ *   - 1 byte compression algorithm
+ *   - 4 bytes header length (uint32 big-endian)
+ *
+ * **Why a binary container** at all? `vault.dump()` already
+ * produces a JSON string with encrypted records inside. Wrapping it
+ * again seems redundant — but the wrap is what makes the file safe
+ * to drop into cloud storage (Drive, Dropbox, iCloud) without
+ * leaking the vault name and exporter identity through the
+ * cloud's metadata API. The minimum-disclosure header is the only
+ * thing visible without downloading and decompressing the body.
+ * The dump JSON inside the body still contains the original
+ * metadata, but that's only readable by someone who already has the
+ * file bytes — the same person who could read the encrypted records
+ * with the right passphrase.
+ *
+ * **Why minimum disclosure** in the header? Because consumers will
+ * inevitably store these in services where the filename, file size,
+ * and any unencrypted metadata are indexed for search. A field like
+ * `vault: "Acme Corp"` would let an attacker (or a curious
+ * cloud admin) enumerate which compartments exist and who exported
+ * them, even with zero access to the encrypted body. The header
+ * carries only what's needed to identify the file as a NOYDB
+ * bundle and verify its integrity — nothing about the contents.
+ */
+/** Magic bytes 'NDB1' (ASCII), identifying a NOYDB bundle. */
+declare const NOYDB_BUNDLE_MAGIC: Uint8Array<ArrayBuffer>;
+/** Total fixed prefix before the header JSON: 4+1+1+4 bytes. */
+declare const NOYDB_BUNDLE_PREFIX_BYTES = 10;
+/** Current bundle format version. Bumped on layout changes. */
+declare const NOYDB_BUNDLE_FORMAT_VERSION = 1;
+/**
+ * Bitfield interpretation of the flags byte.
+ *
+ * Bit 0 — body is compressed (0 = raw, 1 = compressed)
+ * Bit 1 — header carries an integrity hash over the body bytes
+ * Bits 2-7 — reserved, must be 0 in
+ */
+declare const FLAG_COMPRESSED = 1;
+declare const FLAG_HAS_INTEGRITY_HASH = 2;
+/**
+ * Compression algorithm encoding for the byte at offset 5.
+ *
+ * `none` is admitted for round-trip testing and for callers that
+ * want to bundle without compression (e.g. when piping into a
+ * separately compressed transport). `gzip` is the universally
+ * available baseline (Node 18+, all modern browsers). `brotli` is
+ * preferred when the runtime supports it — typically 30-50% smaller
+ * for JSON payloads — but Node 22+ / Chrome 124+ / Firefox 122+
+ * are required, so the writer feature-detects at runtime and falls
+ * back to gzip. The reader must handle all three.
+ */
+declare const COMPRESSION_NONE = 0;
+declare const COMPRESSION_GZIP = 1;
+declare const COMPRESSION_BROTLI = 2;
+type CompressionAlgo = 0 | 1 | 2;
+/**
+ * The unencrypted header carried in every `.noydb` bundle.
+ *
+ * **Minimum-disclosure rules:** these are the ONLY allowed keys.
+ * Any other key in a parsed header causes
+ * `validateBundleHeader` to throw. The set is kept short to
+ * minimize attack surface from cloud-storage metadata indexing —
+ * see the file-level doc comment for the rationale.
+ *
+ * Forbidden in particular:
+ *   - `vault` / `_compartment` — would leak the tenant name
+ *   - `exporter` / `_exported_by` — would leak user identity
+ *   - `timestamp` / `_exported_at` — would leak activity timing
+ *   - `kdfParams` / salt fields — would leak crypto config that
+ *     could narrow brute-force search space
+ *   - any field starting with `_` (reserved by the dump format)
+ */
+interface NoydbBundleHeader {
+    /** Bundle format version — bumped on layout changes. */
+    readonly formatVersion: number;
+    /**
+     * Opaque ULID identifier — generated once per vault and
+     * stable across re-exports of the same vault. Does not
+     * leak any information about contents (the timestamp prefix is
+     * just monotonicity for sortability, not exporter activity —
+     * see `bundle/ulid.ts` for the design notes).
+     */
+    readonly handle: string;
+    /** Compressed body length in bytes. Lets readers verify completeness without decompressing. */
+    readonly bodyBytes: number;
+    /** SHA-256 of the compressed body bytes (lowercase hex). Lets readers verify integrity without decompressing. */
+    readonly bodySha256: string;
+}
+/**
+ * Validate a parsed bundle header. Throws on any deviation from
+ * the minimum-disclosure schema:
+ *
+ *   - Missing required field
+ *   - Wrong type for any field
+ *   - Any extra key not in `ALLOWED_HEADER_KEYS`
+ *   - Unsupported `formatVersion`
+ *   - Negative or non-integer `bodyBytes`
+ *   - Malformed `handle` (must be 26-char Crockford base32)
+ *   - Malformed `bodySha256` (must be 64-char lowercase hex)
+ *
+ * The error messages name the offending field so consumers can
+ * fix the producer rather than the reader.
+ */
+declare function validateBundleHeader(parsed: unknown): asserts parsed is NoydbBundleHeader;
+/**
+ * Encode a header object to UTF-8 JSON bytes after validating
+ * minimum disclosure. Used by the writer to serialize the header
+ * region of the container.
+ */
+declare function encodeBundleHeader(header: NoydbBundleHeader): Uint8Array;
+/**
+ * Verify the magic prefix of a bundle. Returns true if the first
+ * 4 bytes match `NDB1`. Used by readers as a fast file-type check
+ * before any further parsing.
+ */
+declare function hasNoydbBundleMagic(bytes: Uint8Array): boolean;
+
+/**
+ * `.noydb` container primitives — write, read, header-only read.
+ *
+ *. Wraps a `vault.dump()` JSON string in the
+ * binary container described in `format.ts`.
+ *
+ * **Three primitives:**
+ *
+ *   - `writeNoydbBundle(vault, opts?)` — produces the
+ *     full container bytes ready to write to disk or upload
+ *   - `readNoydbBundleHeader(bytes)` — parses just the header
+ *     without decompressing the body, fast file-type and
+ *     metadata read for cloud listing UIs
+ *   - `readNoydbBundle(bytes)` — full read: validates magic,
+ *     header, integrity hash, and decompresses the body to
+ *     return the original `dump()` JSON string for use with
+ *     `vault.load()`
+ *
+ * **Compression strategy:** brotli when available (Node 22+,
+ * Chrome 124+, Firefox 122+), gzip fallback elsewhere. The
+ * algorithm choice is encoded in the format byte at offset 5,
+ * so readers handle either transparently. Brotli wins ~30-50%
+ * on JSON payloads with repeated keys (which vault dumps
+ * are).
+ *
+ * **Why split read/load?** `readNoydbBundle` returns the
+ * *unwrapped JSON string*, not a Vault object. The caller
+ * is responsible for piping that JSON into
+ * `vault.load(json, passphrase)`. Splitting the layers
+ * keeps the bundle module free of any crypto/passphrase
+ * concerns — it's purely a format layer. The same `readNoydbBundle`
+ * call can also feed verification tools, format inspectors, or
+ * archive utilities that don't care about decryption.
+ */
+
+/**
+ * Options accepted by `writeNoydbBundle`.
+ *
+ * - `compression: 'auto'` (default) — try brotli, fall back to gzip
+ * - `compression: 'brotli'` — force brotli, throw if unsupported
+ * - `compression: 'gzip'` — force gzip
+ * - `compression: 'none'` — no compression (round-trip testing only)
+ *
+ * **Slice filtering** (added in ):
+ * - `collections` — allowlist of collection names to include. Internal
+ *   collections (keyrings, ledger) and excluded user collections are
+ *   dropped from the bundle. Records inside included collections are
+ *   carried through verbatim.
+ * - `since` — only records whose envelope `_ts` is on/after the given
+ *   instant survive. Operates on the unencrypted envelope timestamp,
+ *   so plaintext access to records is not required.
+ *
+ * Both filters intersect (AND). When neither is provided the bundle is
+ * a whole-vault snapshot, identical to today's behaviour.
+ */
+interface WriteNoydbBundleOptions {
+    readonly compression?: 'auto' | 'brotli' | 'gzip' | 'none';
+    /** Allowlist of user-collection names to include. */
+    readonly collections?: readonly string[];
+    /**
+     * Drop records whose envelope `_ts` is strictly older than this
+     * instant. Accepts a `Date` or any ISO-8601 string parseable by
+     * `new Date()`.
+     */
+    readonly since?: Date | string;
+    /**
+     * Plaintext-pipeline record predicate. Decrypts each record
+     * with the vault's per-collection DEK, runs the predicate, and
+     * keeps the original ciphertext for survivors (no re-encrypt —
+     * preserves zero-knowledge cleanly). Records the predicate returns
+     * `false` for are dropped from the bundle.
+     *
+     * Async predicates are supported. Mutating the record from inside
+     * the predicate is undefined behaviour.
+     */
+    readonly where?: (record: unknown, ctx: {
+        collection: string;
+        id: string;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Hierarchical-tier ceiling. Records whose envelope `_tier`
+     * is strictly greater than this number are dropped. Operates on the
+     * envelope `_tier` (no decryption needed) — vault.exportStream is
+     * referenced in the issue body for symmetry, but the tier value
+     * lives on the unencrypted envelope. Vault without tiers is a no-op.
+     */
+    readonly tierAtMost?: number;
+    /**
+     * Single-recipient re-keying shorthand. When set, the
+     * bundle's keyring is replaced with one freshly-derived entry sealed
+     * with this passphrase. The recipient inherits the source keyring's
+     * userId, role, and permissions. Mutually exclusive with `recipients`.
+     */
+    readonly exportPassphrase?: string;
+    /**
+     * Multi-recipient re-keying. Replaces the bundle's keyring
+     * map with one slot per recipient, each sealed with its own
+     * passphrase. DEKs are unwrapped from the source keyring once and
+     * re-wrapped per recipient — record ciphertext is unchanged.
+     *
+     * Mutually exclusive with `exportPassphrase`. When neither is set,
+     * the bundle inherits the source keyring as-is (today's behaviour,
+     * suited to personal backup-and-restore).
+     */
+    readonly recipients?: readonly BundleRecipient[];
+}
+/**
+ * Result returned by `readNoydbBundle`. The caller is expected to
+ * pass `dumpJson` into `vault.load(json, passphrase)` to
+ * actually restore a vault. Splitting the layers keeps the
+ * bundle module free of crypto concerns — see file-level docs.
+ */
+interface NoydbBundleReadResult {
+    readonly header: NoydbBundleHeader;
+    readonly dumpJson: string;
+}
+/** Test-only: reset the brotli detection cache between tests. */
+declare function resetBrotliSupportCache(): void;
+/**
+ * Write a `.noydb` bundle for the given vault.
+ *
+ * Pipeline:
+ *   1. Resolve or create the compartment's stable bundle handle
+ *      via `vault.getBundleHandle()` — same handle on
+ *      every export from the same vault instance, so cloud
+ *      adapters can use it as a primary key.
+ *   2. `vault.dump()` → JSON string with encrypted records
+ *      inside.
+ *   3. UTF-8 encode the dump string.
+ *   4. Compress (brotli if available, gzip fallback by default).
+ *   5. Compute SHA-256 of the compressed body for integrity.
+ *   6. Build the minimum-disclosure header from format version,
+ *      handle, body length, body sha.
+ *   7. Serialize: magic (4) + flags (1) + algo (1) + headerLen (4)
+ *      + header JSON (N) + compressed body (M).
+ *
+ * The output is a single `Uint8Array`. Consumers writing to disk
+ * pass it to `fs.writeFile`; consumers uploading to cloud storage
+ * pass it as the request body. The `@noy-db/file` adapter wraps
+ * this with a `saveBundle(path, vault)` helper.
+ */
+declare function writeNoydbBundle(vault: Vault, opts?: WriteNoydbBundleOptions): Promise<Uint8Array>;
+/**
+ * Read just the bundle header — no body decompression, no
+ * integrity verification. Fast (O(prefix + header bytes)) and
+ * intended for cloud-listing UIs that want to show the handle and
+ * size before downloading the full body.
+ *
+ * Returns the same `NoydbBundleHeader` shape as the writer, with
+ * minimum-disclosure validation already applied.
+ */
+declare function readNoydbBundleHeader(bytes: Uint8Array): NoydbBundleHeader;
+/**
+ * Read a full `.noydb` bundle: validate magic + header, verify
+ * integrity hash over the body bytes, decompress, and return the
+ * original `vault.dump()` JSON string ready to pass to
+ * `vault.load()`.
+ *
+ * Throws `BundleIntegrityError` if the body's actual SHA-256 does
+ * not match the value declared in the header. Distinct from a
+ * format error so consumers can pattern-match in catch blocks
+ * (corrupted-in-transit vs malformed-by-producer).
+ *
+ * Note: this function does NOT take a passphrase. The dump JSON
+ * inside the body still contains encrypted records — restoring
+ * the vault requires `vault.load(dumpJson, passphrase)`
+ * after this call. Splitting the layers keeps the bundle module
+ * free of crypto concerns and lets the same code feed format
+ * inspectors that never decrypt anything.
+ */
+declare function readNoydbBundle(bytes: Uint8Array): Promise<NoydbBundleReadResult>;
+
+/**
+ * Minimal ULID generator — zero dependencies, Web Crypto API only.
+ *
+ *. Used by the bundle writer to generate stable opaque
+ * handles for `.noydb` containers.
+ *
+ * **What's a ULID?** A 128-bit identifier encoded as 26 Crockford
+ * base32 characters. Layout:
+ *
+ * ```
+ *   01HYABCDEFGHJKMNPQRSTVWXYZ
+ *   |--------||---------------|
+ *    48-bit     80-bit
+ *    timestamp  randomness
+ * ```
+ *
+ * The first 10 chars encode a millisecond Unix timestamp (so ULIDs
+ * sort lexicographically by creation time), and the remaining 16
+ * chars are random. Crockford base32 omits I/L/O/U to avoid
+ * ambiguity in handwriting and URLs.
+ *
+ * **Why hand-roll instead of pulling in `ulid`?** The package adds
+ * a dep, the implementation is ~30 lines, and the bundle module
+ * is the only consumer. Adding `ulid` would also drag in its own
+ * crypto polyfill that we don't need on Node 18+ or modern
+ * browsers.
+ *
+ * **Privacy consideration:** the timestamp prefix is observable in
+ * the bundle header. This is a deliberate trade-off:
+ *   - Pro: lexicographic sortability lets bundle adapters list
+ *     newest-first without an extra index.
+ *   - Con: a casual observer can read the bundle's creation time
+ *     from the handle. They cannot read it from any OTHER field
+ *     (the header explicitly forbids `_exported_at`), and a
+ *     creation timestamp is the same kind of metadata that
+ *     filesystem mtime would already expose for a downloaded
+ *     bundle. The leak is therefore equivalent to what's already
+ *     visible from the file's mtime — not a new exposure.
+ *
+ * If a future use case needs timestamp-free handles, a v2 of the
+ * format could specify "use the random portion only" without a
+ * format break — `validateBundleHeader` only checks the regex
+ * shape, not the encoded timestamp.
+ */
+/**
+ * Generate a fresh ULID. Uses `crypto.getRandomValues` for the
+ * randomness portion — same Web Crypto API the rest of the
+ * codebase uses for IVs and salt.
+ *
+ * Returns a 26-character string. Calling twice in the same
+ * millisecond produces two distinct ULIDs (the random portion
+ * differs); ULIDs from the same millisecond are NOT guaranteed
+ * to be monotonically ordered relative to each other, only
+ * relative to ULIDs from a different millisecond. The bundle
+ * format never relies on intra-millisecond ordering.
+ */
+declare function generateULID(): string;
+/**
+ * Validate that a string is a syntactically well-formed ULID. Used
+ * by the bundle header validator. Does NOT verify that the
+ * timestamp portion decodes to a sensible date — the format only
+ * cares about the encoding shape.
+ */
+declare function isULID(value: string): boolean;
+
+export { type CompressionAlgo as C, FLAG_COMPRESSED as F, NOYDB_BUNDLE_FORMAT_VERSION as N, type WriteNoydbBundleOptions as W, NOYDB_BUNDLE_MAGIC as a, NOYDB_BUNDLE_PREFIX_BYTES as b, type NoydbBundleHeader as c, type NoydbBundleReadResult as d, readNoydbBundleHeader as e, resetBrotliSupportCache as f, generateULID as g, hasNoydbBundleMagic as h, isULID as i, COMPRESSION_BROTLI as j, COMPRESSION_GZIP as k, COMPRESSION_NONE as l, FLAG_HAS_INTEGRITY_HASH as m, encodeBundleHeader as n, readNoydbBundle as r, validateBundleHeader as v, writeNoydbBundle as w };