@noy-db/hub 0.3.0-pre.9 → 0.4.0-pre.0

package/dist/with-pod/bundle.d.ts

@@ -0,0 +1,416 @@
+/**
+ * `.noydb` container primitives — write, read, header-only read.
+ *
+ *. Wraps a `vault.dump()` JSON string in the
+ * binary container described in `format.ts`.
+ *
+ * **Three primitives:**
+ *
+ *   - `writePod(vault, opts?)` — produces the
+ *     full container bytes ready to write to disk or upload
+ *   - `readPodHeader(bytes)` — parses just the header
+ *     without decompressing the body, fast file-type and
+ *     metadata read for cloud listing UIs
+ *   - `readPod(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?** `readPod` 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 `readPod`
+ * call can also feed verification tools, format inspectors, or
+ * archive utilities that don't care about decryption.
+ */
+import { type NoydbPodHeader } from './format.js';
+import type { Vault } from '../kernel/vault.js';
+import type { BundleRecipient } from '../with-party/team/keyring.js';
+import type { Cover } from '../with-party/directory/cover/types.js';
+import type { SealingKeyProvider, RecipientSealer, RecipientHint } from '../with-party/team/managed-passphrase.js';
+/**
+ * The credential kinds that can be bundled for auto-unlock.
+ * WebAuthn is intentionally excluded — it is hardware-bound and
+ * cannot be embedded as a portable credential.
+ */
+export type AutoCredentialKind = 'passphrase' | 'password' | 'pin';
+/**
+ * A typed credential for auto-unlock. Carries the credential `kind`
+ * alongside the plaintext `value`, so consumers can dispatch the
+ * correct login/prefill path rather than treating all credentials
+ * as passphrases.
+ *
+ * `bundle.ts` is a pure format layer — it carries the credential
+ * without interpreting it. The consumer is responsible for
+ * dispatching on `kind`.
+ */
+export interface AutoCredential {
+    readonly kind: AutoCredentialKind;
+    readonly value: string;
+}
+/**
+ * Options accepted by `writePod`.
+ *
+ * - `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:**
+ * - `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.
+ */
+export interface WritePodOptions {
+    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[];
+    /**
+     * Auto-unlock — unsealed per-user credentials.
+     *
+     * Generalises `autoPassphrases` to support any bundleable credential
+     * kind (`passphrase` | `password` | `pin`).
+     *
+     * Public-by-design: anyone holding the bundle bytes can read these
+     * plaintext credentials. Use for demo data, sample vaults,
+     * prospect onboarding.
+     *
+     * The `policy: 'public-by-design'` discriminant is mandatory. A
+     * bare `{ perUser }` without it is rejected at write time — the
+     * safety net against a careless call against a production vault.
+     *
+     * Mutually exclusive with `sealedCredentials`, `autoPassphrases`,
+     * and `sealedPassphrases`.
+     */
+    readonly autoCredentials?: {
+        readonly policy: 'public-by-design';
+        readonly perUser: Record<string, AutoCredential>;
+    };
+    /**
+     * Auto-unlock — per-user credentials sealed under a
+     * {@link SealingKeyProvider}.
+     *
+     * Generalises `sealedPassphrases` to support any bundleable
+     * credential kind (`passphrase` | `password` | `pin`).
+     *
+     * The hub seals each user's plaintext credential under `provider`
+     * and embeds the resulting sealed envelopes in the bundle. The
+     * recipient must hold a provider with a matching `pid` (i.e.,
+     * `provider.id`) to auto-unseal on import.
+     *
+     * `mode: 'self-target'` — sender and recipient share the same
+     * provider identity (same iCloud Keychain entry, same
+     * MDM-provisioned bundle id, same KMS account, etc.).
+     *
+     * `mode: 'recipient-target'` — asymmetric sealing via a
+     * {@link RecipientSealer}. Each user entry carries a
+     * `credential` and a `hint` (the recipient's public material).
+     * The bundle can only be unsealed by the holder of the matching
+     * private key.
+     *
+     * Mutually exclusive with `autoCredentials`, `autoPassphrases`,
+     * and `sealedPassphrases`.
+     */
+    readonly sealedCredentials?: {
+        readonly mode: 'self-target';
+        readonly provider: SealingKeyProvider;
+        readonly perUser: Record<string, AutoCredential>;
+    } | {
+        readonly mode: 'recipient-target';
+        readonly provider: RecipientSealer;
+        readonly perUser: Record<string, {
+            readonly credential: AutoCredential;
+            readonly hint: RecipientHint;
+        }>;
+    };
+    /**
+     * @deprecated Use `autoCredentials` instead.
+     *
+     * Auto-unlock — unsealed per-user passphrases.
+     *
+     * Public-by-design: anyone holding the bundle bytes can read these
+     * plaintext credentials. Use for demo data, sample vaults,
+     * prospect onboarding.
+     *
+     * The `policy: 'public-by-design'` discriminant is mandatory. A
+     * bare `{ perUser }` without it is rejected at write time — the
+     * safety net against a careless call against a production vault.
+     *
+     * Mutually exclusive with `autoCredentials`, `sealedCredentials`,
+     * and `sealedPassphrases`.
+     */
+    readonly autoPassphrases?: {
+        readonly policy: 'public-by-design';
+        readonly perUser: Record<string, string>;
+    };
+    /**
+     * @deprecated Use `sealedCredentials` instead.
+     *
+     * Auto-unlock — per-user passphrases sealed under a
+     * {@link SealingKeyProvider} (self-target only).
+     *
+     * The hub seals each user's plaintext passphrase under `provider`
+     * and embeds the resulting sealed envelopes in the bundle. The
+     * recipient must hold a provider with a matching `pid` (i.e.,
+     * `provider.id`) to auto-unseal on import.
+     *
+     * `mode: 'self-target'` is the only mode for `sealedPassphrases` — sender
+     * and recipient share the same provider identity (same iCloud Keychain
+     * entry, same MDM-provisioned bundle id, same KMS account, etc.).
+     * For recipient-target sealing via the `RecipientSealer` interface,
+     * use `sealedCredentials` with `mode: 'recipient-target'` (§11.4).
+     *
+     * Mutually exclusive with `autoCredentials`, `sealedCredentials`,
+     * and `autoPassphrases`.
+     */
+    readonly sealedPassphrases?: {
+        readonly mode: 'self-target';
+        readonly provider: SealingKeyProvider;
+        readonly perUser: Record<string, string>;
+    };
+}
+/** @deprecated Use `WritePodOptions`. */
+export type WriteNoydbBundleOptions = WritePodOptions;
+/**
+ * Result returned by `readPod`. 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.
+ */
+export interface NoydbBundleReadResult {
+    readonly header: NoydbPodHeader;
+    readonly dumpJson: string;
+    /**
+     * Auto-unlock material. Present only when
+     * the header's `autoUnlock` flag is set AND the body's wrapped
+     * structure survived parsing. Values are typed credentials — either
+     * delivered plain (`kind: 'unsealed'`) or unsealed at read time
+     * using one of the supplied `sealingProviders` (`kind: 'sealed'`).
+     *
+     * Consumers dispatch on `cred.kind` to choose the correct login /
+     * prefill path. Pre-0.2 bundles (bare string entries) are coerced
+     * to `{ kind: 'passphrase', value }` on read for back-compat.
+     *
+     * For `kind: 'sealed'` bundles read without `sealingProviders`, the
+     * `value` field is the raw base64 sealed bytes — opaque to the
+     * consumer until unsealed elsewhere.
+     */
+    readonly autoUnlock?: {
+        readonly kind: 'unsealed' | 'sealed';
+        readonly perUser: Record<string, AutoCredential>;
+    };
+}
+/**
+ * Options accepted by {@link readPod} for the
+ * auto-unlock paths. Without these the reader behaves exactly as before
+ * (header parsed; body returned as `dumpJson`).
+ */
+export interface ReadNoydbBundleOptions {
+    /**
+     * Recipient-side sealing providers used to unseal entries from
+     * `sealedPassphrases`. The reader picks the one whose `.id`
+     * matches each entry's `pid`. Multiple providers may be supplied
+     * (different users may seal under different identities).
+     *
+     * When unset and the bundle carries sealed envelopes, the
+     * `autoUnlock.perUser` map remains the SEALED entries unmodified
+     * — callers can inspect them or unseal elsewhere.
+     */
+    readonly sealingProviders?: readonly SealingKeyProvider[];
+    /**
+     * Opt-in trial mode for unsealing — when an entry's `pid` doesn't
+     * match a registered provider, try each provider whose alg
+     * matches. Default `false` (strict-pid dispatch per foundation
+     * §11.9.2). Surfaces extra credential prompts; use deliberately.
+     */
+    readonly attemptUnsealAcrossProviders?: boolean;
+}
+/**
+ * Transfer-seal payload. The destination DEKs, exported to raw
+ * bytes and AES-256-GCM-sealed *as a set* under the one-time transfer
+ * key. `adoptPartition` unseals this; `createOwnerOnAdoptedPartition`
+ * re-wraps the raw DEKs under the recipient's KEK.
+ */
+export interface TransferSealPayload {
+    readonly v: 1;
+    readonly alg: 'aes-256-gcm-pre-shared';
+    readonly sealId: string;
+    /** base64(AES-256-GCM(transferKey, JSON of { collection: base64(rawDEK) })) — iv ‖ ct ‖ tag. */
+    readonly payload: string;
+}
+/**
+ * Body wrapper for an extracted, transfer-sealed partition.
+ * Sibling to {@link AutoUnlockBody}; selected by `header.bundleKind ===
+ * 'extracted-partition'`. The inner `dump` is a re-keyed projection with
+ * an empty `keyrings` map.
+ */
+export interface ExtractedPartitionBody {
+    readonly _noydb_bundle_body: 1;
+    readonly dump: string;
+    readonly _transferSeal: TransferSealPayload;
+}
+export declare function buildExtractedPartitionWrapper(dumpJson: string, seal: TransferSealPayload): ExtractedPartitionBody;
+export declare function parseExtractedPartitionBody(bodyString: string): {
+    dump: string;
+    seal: TransferSealPayload;
+};
+/** Test-only: reset the brotli detection cache between tests. */
+export 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.
+ */
+/**
+ * Assemble the final `.noydb` container bytes from a body JSON string +
+ * header extras. Shared by `writePod` and `extractPartition`
+ * so both producers go through one compress/hash/prefix path.
+ *
+ * @internal
+ */
+export declare function assembleBundleContainer(opts: {
+    handle: string;
+    bodyJsonStr: string;
+    compression: WritePodOptions['compression'];
+    /** Header fields beyond the always-present four. */
+    headerExtras?: Partial<Pick<NoydbPodHeader, 'publicEnvelope' | 'autoUnlock' | 'bundleKind' | 'transferSeal'>>;
+}): Promise<Uint8Array>;
+export declare function writePod(vault: Vault, opts?: WritePodOptions): Promise<Uint8Array>;
+/** @deprecated Use `writePod`. */
+export declare const writeNoydbBundle: typeof writePod;
+/**
+ * Read just the bundle header — no body decompression, no
+ * integrity verification. Intended for cloud-listing UIs that want
+ * to show the handle and size before downloading the full body.
+ *
+ * Returns the same `NoydbPodHeader` shape as the writer, with
+ * minimum-disclosure validation already applied.
+ *
+ * **Cost** — O(prefix + header bytes). The header is normally well
+ * under 1 KB, but may grow to roughly 256 KB when a `publicEnvelope`
+ * with an inline icon is present. Cloud-listing UIs that previously
+ * assumed sub-KB header reads should account for this when sizing
+ * range requests against bundles that may carry icons.
+ */
+export declare function readPodHeader(bytes: Uint8Array): NoydbPodHeader;
+/** @deprecated Use `readPodHeader`. */
+export declare const readNoydbBundleHeader: typeof readPodHeader;
+/**
+ * Read just the bundle's cover (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`)
+ * — without verifying the body or even parsing the dump JSON. Pass
+ * the raw bundle bytes; receive the owner-curated metadata or
+ * `undefined` if the bundle was written without one.
+ *
+ * Locale-resolves any `name` / `description` map fields when `locale`
+ * is supplied. Omitting `locale` returns the raw cover.
+ *
+ * Same security caveat as the on-vault read path — the cover is an
+ * **untrusted hint** in v1; the encrypted body remains
+ * the source of truth for vault contents.
+ */
+export declare function readPodCover(bytes: Uint8Array, opts?: {
+    readonly locale?: string;
+}): Cover | undefined;
+/** @deprecated Use `readPodCover` (#799 rename). */
+export declare const readNoydbBundlePublicEnvelope: typeof readPodCover;
+/**
+ * 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.
+ */
+export declare function readPod(bytes: Uint8Array, opts?: ReadNoydbBundleOptions): Promise<NoydbBundleReadResult>;
+/** @deprecated Use `readPod`. */
+export declare const readNoydbBundle: typeof readPod;

package/dist/with-pod/format.d.ts

@@ -0,0 +1,207 @@
+/**
+ * `.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.
+ */
+import type { Cover } from '../with-party/directory/cover/types.js';
+/** Magic bytes 'NDB1' (ASCII), identifying a NOYDB bundle. */
+export declare const NOYDB_BUNDLE_MAGIC: Uint8Array<ArrayBuffer>;
+/** Total fixed prefix before the header JSON: 4+1+1+4 bytes. */
+export declare const NOYDB_BUNDLE_PREFIX_BYTES = 10;
+/** Current bundle format version. Bumped on layout changes. */
+export 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
+ */
+export declare const FLAG_COMPRESSED = 1;
+export 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.
+ */
+export declare const COMPRESSION_NONE = 0;
+export declare const COMPRESSION_GZIP = 1;
+export declare const COMPRESSION_BROTLI = 2;
+export 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)
+ */
+export interface NoydbPodHeader {
+    /** 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;
+    /**
+     * Owner-curated cover (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`).
+     * Optional — present only when the source vault has a
+     * `_meta/public-envelope` document AND the writer's hub is opted
+     * into the feature. Treat as **untrusted hint**; the body's
+     * encrypted contents remain the source of truth.
+     *
+     * The JSON key keeps its frozen wire name `publicEnvelope` (#799
+     * renamed only the developer surface — existing bundles stay
+     * readable byte-for-byte).
+     *
+     * The cover deliberately widens the minimum-disclosure rule
+     * for explicit, owner-curated label fields (name, icon, …). Every
+     * other unknown header key still rejects at parse time.
+     */
+    readonly publicEnvelope?: Cover;
+    /**
+     * Auto-unlock material indicator. When present, the bundle
+     * body wraps the dump JSON in a structure carrying per-user
+     * passphrases — either plaintext (`'unsealed'`, public-by-design)
+     * or sealed under a `SealingKeyProvider` (`'sealed'`, requires
+     * matching provider on the recipient side).
+     *
+     * Visible pre-decompression so cloud listing UIs can warn before
+     * download: "this bundle opens itself for anyone holding the file"
+     * (unsealed) or "this bundle is sealed for a specific provider"
+     * (sealed).
+     *
+     * Absent → the body is a raw `vault.dump()` JSON string (the
+     * the legacy shape; back-compatible).
+     */
+    readonly autoUnlock?: 'unsealed' | 'sealed';
+    /**
+     * Bundle's role in the source → destination lifecycle.
+     *   - omitted / 'snapshot' (default): backup/copy of an existing vault.
+     *   - 'extracted-partition': re-keyed projection awaiting adoption.
+     */
+    readonly bundleKind?: 'snapshot' | 'extracted-partition';
+    /**
+     * Transfer-seal INDICATOR — metadata only, no payload (the
+     * sealed DEKs live in the body). Present iff
+     * bundleKind === 'extracted-partition'.
+     */
+    readonly transferSeal?: {
+        readonly v: 1;
+        readonly alg: 'aes-256-gcm-pre-shared';
+        readonly sealId: string;
+    };
+}
+/** @deprecated Use `NoydbPodHeader`. */
+export type NoydbBundleHeader = NoydbPodHeader;
+/**
+ * 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.
+ */
+export declare function validateBundleHeader(parsed: unknown): asserts parsed is NoydbPodHeader;
+/**
+ * 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.
+ */
+export declare function encodeBundleHeader(header: NoydbPodHeader): Uint8Array;
+/**
+ * Parse a bundle header from its UTF-8 JSON bytes. Throws on
+ * invalid JSON or any minimum-disclosure violation.
+ */
+export declare function decodeBundleHeader(bytes: Uint8Array): NoydbPodHeader;
+/**
+ * Read a uint32 from `bytes` at `offset` in big-endian byte order.
+ * No bounds check — callers must guarantee `offset + 4 <= bytes.length`.
+ * Used to decode the header length field; kept inline so the parser
+ * doesn't depend on DataView allocation per call.
+ */
+export declare function readUint32BE(bytes: Uint8Array, offset: number): number;
+/**
+ * Write a uint32 to `bytes` at `offset` in big-endian byte order.
+ * No bounds check — callers must guarantee `offset + 4 <= bytes.length`.
+ */
+export declare function writeUint32BE(bytes: Uint8Array, offset: number, value: number): void;
+/**
+ * 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.
+ */
+export declare function hasNoydbBundleMagic(bytes: Uint8Array): boolean;

package/dist/with-pod/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @noy-db/hub/pod — opt-in .noydb container-format (artifact) service.
+ *
+ * @category capability
+ *
+ * The `.noydb` binary wrapper around `vault.dump()` for safe
+ * cloud-storage drops: 10-byte magic prefix + JSON header +
+ * compressed body, plus the ULID helpers. This is the artifact half of
+ * the former `/bundle` subpath (partition-transfer ops now live under
+ * `@noy-db/hub/cargo`). Consumers that don't export/import bundles can
+ * omit this subpath and save ~805 LOC of format code + Brotli/gzip
+ * wiring.
+ */
+export { writePod, readPod, readPodHeader, readPodCover, writeNoydbBundle, readNoydbBundle, readNoydbBundleHeader, resetBrotliSupportCache, } from './bundle.js';
+export type { Cover } from '../with-party/directory/cover/types.js';
+export type { WritePodOptions, WriteNoydbBundleOptions, ReadNoydbBundleOptions, NoydbBundleReadResult, } from './bundle.js';
+export { NOYDB_BUNDLE_MAGIC, NOYDB_BUNDLE_PREFIX_BYTES, NOYDB_BUNDLE_FORMAT_VERSION, FLAG_COMPRESSED, FLAG_HAS_INTEGRITY_HASH, COMPRESSION_NONE, COMPRESSION_GZIP, COMPRESSION_BROTLI, validateBundleHeader, encodeBundleHeader, } from './format.js';
+export type { CompressionAlgo, NoydbPodHeader, NoydbBundleHeader, } from './format.js';
+export { generateULID, isULID } from './ulid.js';
+export { wrapPodStore, createPodStore, wrapBundleStore, createBundleStore } from './pod-store.js';
+export type { WrappedPodNoydbStore, WrapPodStoreOptions, WrappedBundleNoydbStore, WrapBundleStoreOptions, } from './pod-store.js';