@noy-db/as-zip 0.1.0-pre.3

package/dist/index.d.ts

@@ -0,0 +1,349 @@
+import { VaultDiff, Vault } from '@noy-db/hub';
+
+/**
+ * Minimal zero-dependency ZIP writer — STORE method only (no compression).
+ *
+ * Produces single-disk zip archives readable by `unzip`, macOS Finder,
+ * Windows Explorer, and every well-behaved unzipper. Store-method is
+ * sufficient here because:
+ *
+ * 1. Most blobs reaching this writer are already compressed — PDFs,
+ *    PNGs, JPEGs, `.zip`-inside-zip, encrypted `.noydb` bundles.
+ *    Re-deflating yields near-zero savings at non-trivial CPU cost.
+ * 2. STORE keeps the encoder compact (~150 lines) and dependency-free.
+ *    Deflate would need a ~5KB gzip-style implementation or an
+ *    external dep; we're zero-deps by design.
+ * 3. Consumers who need further compression can deflate the whole zip
+ *    after it's produced (`gzip archive.zip`).
+ *
+ * ## Wire format used
+ *
+ * Per PKWARE APPNOTE (the canonical ZIP spec):
+ *
+ * ```
+ * [Local File Header 1][File 1 data]
+ * [Local File Header 2][File 2 data]
+ * ...
+ * [Central Directory File Header 1]
+ * [Central Directory File Header 2]
+ * ...
+ * [End of Central Directory Record]
+ * ```
+ *
+ * All multi-byte integers are little-endian. Filenames are UTF-8
+ * (flag bit 11 set so unzippers interpret them correctly). The
+ * per-file CRC-32 uses the standard polynomial 0xEDB88320.
+ *
+ * ## What this does NOT support
+ *
+ * - Deflate / bzip2 / lzma / zstd compression methods.
+ * - Zip64 (files / archives > 4 GiB). 32-bit size fields apply.
+ * - Multi-disk / spanned archives.
+ * - Encryption (the ZIP-level kind — noy-db records are already
+ *   encrypted at the envelope layer before reaching this writer).
+ * - Symlinks, extended attributes, NTFS/UNIX permissions.
+ *
+ * @module
+ */
+/** Input entry to `writeZip`. */
+interface ZipEntry {
+    /** Slash-delimited path inside the archive (e.g. `"records.json"`, `"attachments/01H.../raw.pdf"`). */
+    readonly path: string;
+    /** Raw bytes. Pass plaintext as-is; the writer doesn't interpret content. */
+    readonly bytes: Uint8Array;
+    /** Optional file mtime. Defaults to the call-time `Date`. */
+    readonly mtime?: Date;
+}
+/** Optional archive-wide settings for `writeZip`. */
+interface WriteZipOptions {
+    /**
+     * When set, every entry is encrypted with WinZip-AES-256 sealed
+     * under this passphrase. Recipients open with stock archive
+     * tooling (7-Zip, Archive Utility, WinRAR, modern unzip builds)
+     * by typing the same passphrase.
+     *
+     * Single passphrase across all entries by design — per-entry
+     * passwords don't fit a noy-db export workflow and would muddy
+     * the API.
+     */
+    readonly password?: string;
+}
+/**
+ * Build a complete ZIP archive byte stream from `entries`. The result
+ * is the full archive including central directory and EOCD — ready
+ * to `fs.writeFile` or hand to `new Blob([bytes])`.
+ *
+ * When `options.password` is set, every entry is encrypted with
+ * WinZip-AES-256 (vendor version AE-2). Output remains a valid
+ * single-disk ZIP that archive tools recognising WinZip-AES prompt
+ * for the password on extract.
+ */
+declare function writeZip(entries: readonly ZipEntry[], options?: WriteZipOptions): Promise<Uint8Array>;
+declare function crc32(bytes: Uint8Array): number;
+
+/**
+ * Minimal zero-dependency ZIP reader — STORE method only, with
+ * optional WinZip-AES-256 decryption.
+ *
+ * Mirror of `./zip.ts`'s writer. Reads the central directory, walks
+ * each entry, decrypts when the AES marker (method 99) is set and a
+ * password was supplied. Same scope limits as the writer:
+ *
+ *   - **No DEFLATE / bzip2 / lzma / zstd.** STORE-only. Trying to read
+ *     a deflated entry throws `ZipReadError`.
+ *   - **No Zip64.** 32-bit size + offset fields apply.
+ *   - **AES-256 only.** AES-128/192 and ZipCrypto are refused — same
+ *     stance as the writer.
+ *
+ * @module
+ */
+declare class ZipReadError extends Error {
+    readonly code = "ZIP_READ_ERROR";
+    constructor(message: string);
+}
+interface ReadZipEntry {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+    /** True iff the entry was decrypted from a WinZip-AES region. */
+    readonly encrypted: boolean;
+}
+interface ReadZipOptions {
+    /** WinZip-AES-256 passphrase. Required for encrypted archives. */
+    readonly password?: string;
+}
+/**
+ * Parse a ZIP archive and return its entries. When the archive
+ * contains AES-encrypted entries (method 99 with the 0x9901 extra
+ * field), `options.password` MUST be supplied. Wrong password
+ * surfaces a `ZipCipherError` from the underlying decrypt step.
+ */
+declare function readZip(bytes: Uint8Array, options?: ReadZipOptions): Promise<ReadZipEntry[]>;
+
+/**
+ * WinZip-AES encryption for ZIP entries — write + read.
+ *
+ * Implements the AES-256 variant of the WinZip-AES extension as
+ * documented in
+ * https://www.winzip.com/win/en/aes_info.html and PKWARE Appendix E.
+ *
+ * **AES-256 only by design.** ZipCrypto and AES-128/192 are refused at
+ * both write and read time — the security story for the package is
+ * "if you need encryption, use AES-256." Adding weaker tiers would
+ * give consumers the impression of meaningful choice.
+ *
+ * ## Layout of an encrypted entry's data region
+ *
+ * ```
+ * ┌──────────┬──────────┬─────────────┬──────────┐
+ * │ salt(16) │ verif(2) │ ciphertext  │ auth(10) │
+ * └──────────┴──────────┴─────────────┴──────────┘
+ * ```
+ *
+ *   - **salt** — 16 random bytes per entry
+ *   - **verifier** — 2 bytes, last 2 bytes of the PBKDF2 output;
+ *     used to fail-fast on a wrong password without running CTR
+ *   - **ciphertext** — input bytes XOR-ed with AES-CTR keystream
+ *   - **auth** — first 10 bytes of HMAC-SHA1(ciphertext, authKey),
+ *     where authKey is the second half of the PBKDF2 output
+ *
+ * ## Local file header changes
+ *
+ * For an encrypted entry:
+ *
+ *   - `compression method` field is forced to **99** (AES marker)
+ *   - flag **bit 0** is set (encryption)
+ *   - extra field tag **0x9901** is appended with 7 bytes:
+ *     - `2 bytes` vendor version  → `0x0002` (AE-2)
+ *     - `2 bytes` vendor ID       → `'AE'` (`0x4541` LE)
+ *     - `1 byte`  AES strength    → `0x03` (AES-256)
+ *     - `2 bytes` real method     → `0x0000` (STORE)
+ *   - For AE-2, `crc` is forced to 0 (the spec recommends this — the
+ *     authentication code already covers integrity)
+ *
+ * ## Counter convention (subtle!)
+ *
+ * AES-CTR per WinZip uses a **little-endian** 16-byte counter. The
+ * counter starts at **1** (not 0) and increments by 1 per 16-byte
+ * block. The lower 8 bytes hold the counter; the upper 8 bytes are 0.
+ *
+ * @module
+ */
+
+declare class ZipCipherError extends Error {
+    readonly code = "ZIP_CIPHER_ERROR";
+    constructor(message: string);
+}
+
+/**
+ * **@noy-db/as-zip** — composite record + blob archive for noy-db.
+ *
+ * Bundles a collection's records AND every record's attached blobs
+ * into a single zip archive. The canonical "download this audit
+ * trail" / "migrate this case folder" primitive. Part of the
+ * `@noy-db/as-*` portable-artefact family — plaintext tier,
+ * document sub-family.
+ *
+ * ## Authorisation
+ *
+ * One capability check: `assertCanExport('plaintext', 'zip')`.
+ * A composite archive is semantically the `'zip'` format from the
+ * auth model's POV — requiring separate `'json'`, `'csv'`, `'blob'`
+ * grants for a single call would fragment the grant surface without
+ * adding any real isolation (the archive concatenates them anyway).
+ *
+ * The owner grants the composite capability explicitly:
+ *
+ * ```ts
+ * await db.grant('firm', {
+ *   userId: 'auditor',
+ *   role: 'viewer',
+ *   passphrase: '…',
+ *   exportCapability: { plaintext: ['zip'] },
+ * })
+ * ```
+ *
+ * ## Archive layout
+ *
+ * ```
+ * archive.zip
+ * ├── manifest.json      # index + provenance (record count, blob count, exported-at, exported-by)
+ * ├── records.json       # array of decrypted records
+ * └── attachments/
+ *     ├── <recordId>/<slot>        # raw blob bytes, MIME-native
+ *     └── ...
+ * ```
+ *
+ * The folder-per-record layout makes composite entities (email +
+ * body + attachments, invoice + scan + receipt) navigable in
+ * Finder/Explorer without tooling.
+ *
+ * See [`docs/patterns/as-exports.md`](https://github.com/vLannaAi/noy-db/blob/main/docs/patterns/as-exports.md).
+ *
+ * @packageDocumentation
+ */
+
+/** Record-selection options. */
+interface AsZipRecordsOptions {
+    /** Collection to export. Must be in the caller's read ACL. */
+    readonly collection: string;
+    /**
+     * Optional predicate against each decrypted record. When omitted,
+     * every record is included. Runs after decryption, before zip
+     * assembly — doesn't reduce I/O, just the final set.
+     */
+    readonly filter?: (record: unknown) => boolean;
+}
+/** Blob-selection options. */
+interface AsZipAttachmentsOptions {
+    /**
+     * Which slots to include per record. `'*'` (default) includes
+     * every slot on every record; a string[] selects specific slot
+     * names. Pass an empty array to skip blob inclusion entirely.
+     */
+    readonly slots?: readonly string[] | '*';
+}
+/** Top-level options for every entry point. */
+interface AsZipOptions {
+    readonly records: AsZipRecordsOptions;
+    readonly attachments?: AsZipAttachmentsOptions;
+    /**
+     * Optional WinZip-AES-256 passphrase. When set, every entry
+     * inside the archive (records + attachments + manifest) is
+     * encrypted with WinZip-AES-256 and the recipient must supply the
+     * passphrase to extract.
+     *
+     * **Interop note:** the implementation is strictly to spec but has
+     * not been validated against 7-Zip / Archive Utility / WinRAR in
+     * this checkout. Round-trips against the package's own reader pass.
+     * See https://github.com/vLannaAi/noy-db/issues/304 for the
+     * cross-tool validation matrix.
+     *
+     * **Security framing:** this is the *interop* layer for
+     * cross-platform handoff to archive tools, not the *encryption*
+     * layer for sharing noy-db state. Use `as-noydb` for multi-recipient
+     * + revocable + audited egress.
+     */
+    readonly password?: string;
+}
+/** Options for `download()` — adds an optional filename. */
+interface AsZipDownloadOptions extends AsZipOptions {
+    /** Filename offered to the browser. Default `'<collection>.zip'`. */
+    readonly filename?: string;
+}
+/** Options for `write()` — requires explicit risk acknowledgement. */
+interface AsZipWriteOptions extends AsZipOptions {
+    /**
+     * Required for Node file-write calls — consumer acknowledgement
+     * that plaintext bytes will persist on disk past the current
+     * process lifetime (Tier 3 risk).
+     */
+    readonly acknowledgeRisks: true;
+}
+/** Manifest entry — one per record that landed in the archive. */
+interface ManifestRecord {
+    readonly id: string;
+    readonly attachments: ReadonlyArray<{
+        readonly slot: string;
+        readonly path: string;
+        readonly size: number;
+        readonly mimeType?: string;
+    }>;
+}
+/** Archive-level manifest. Serialised as `manifest.json`. */
+interface ArchiveManifest {
+    readonly _noydb_archive: 1;
+    readonly collection: string;
+    readonly exportedAt: string;
+    readonly recordCount: number;
+    readonly attachmentCount: number;
+    readonly records: readonly ManifestRecord[];
+}
+/**
+ * Assemble the archive bytes. Pure beyond the auth check + store
+ * reads. Records are written as `records.json`; blobs as
+ * `attachments/<recordId>/<slot>`. A `manifest.json` index lands
+ * at the archive root so extractors can walk the content without
+ * re-reading every file.
+ */
+declare function toBytes(vault: Vault, options: AsZipOptions): Promise<Uint8Array>;
+/**
+ * Browser download — wraps `toBytes()` in a `Blob` and triggers the
+ * browser's download prompt. Requires `URL.createObjectURL` +
+ * `document.createElement`. Throws in headless Node.
+ */
+declare function download(vault: Vault, options: AsZipDownloadOptions): Promise<void>;
+/**
+ * Node file-write — persists the archive to disk. Requires
+ * explicit `acknowledgeRisks: true` (Tier 3 egress — the archive
+ * contains plaintext records + blob bytes).
+ */
+declare function write(vault: Vault, path: string, options: AsZipWriteOptions): Promise<void>;
+
+type ImportPolicy = 'merge' | 'replace' | 'insert-only';
+interface AsZipImportOptions {
+    /** Target collection for the records. */
+    readonly collection: string;
+    /** Field on each record that carries its id. Default `'id'`. */
+    readonly idKey?: string;
+    /** Reconciliation policy. Default `'merge'`. */
+    readonly policy?: ImportPolicy;
+    /** WinZip-AES-256 passphrase if the archive is encrypted. */
+    readonly password?: string;
+}
+interface AsZipImportPlan {
+    readonly plan: VaultDiff;
+    readonly policy: ImportPolicy;
+    apply(): Promise<void>;
+}
+/**
+ * Read a `.zip` archive (optionally WinZip-AES-256 encrypted), parse
+ * `records.json` from it, and return an `ImportPlan` whose `apply()`
+ * writes the changes through the normal collection API.
+ *
+ * Pairs with `toBytes` for round-trip workflows. The records JSON
+ * format matches what `toBytes` writes — array of records under
+ * the configured collection's id key.
+ */
+declare function fromBytes(vault: Vault, bytes: Uint8Array, options: AsZipImportOptions): Promise<AsZipImportPlan>;
+
+export { type ArchiveManifest, type AsZipAttachmentsOptions, type AsZipDownloadOptions, type AsZipImportOptions, type AsZipImportPlan, type AsZipOptions, type AsZipRecordsOptions, type AsZipWriteOptions, type ImportPolicy, type ManifestRecord, type ReadZipEntry, type ReadZipOptions, type WriteZipOptions, ZipCipherError, type ZipEntry, ZipReadError, crc32, download, fromBytes, readZip, toBytes, write, writeZip };