sealkeep 0.9.0 → 0.11.0

package/README.md

@@ -15,14 +15,18 @@ sealkeep autopilot
 ```
 
 That is the whole setup. It creates your vault, shows your recovery phrase once, finds the
-sessions already on this machine, and installs a background service that starts at login.
+sessions already on this machine, installs the agent memory hooks, and installs a background
+service that starts at login.
 
-From then on you do nothing. New sessions are sealed as they finish. Once you point it at a
-bucket, verified copies go up and old local files move to your trash on their own.
+From then on you do nothing. New sessions are sealed, indexed, and uploaded as they finish;
+their original files stay on this machine by default. If you explicitly opt into reclaim,
+verified and searchable old local originals can be permanently reclaimed after every idle,
+grace, identity, and liveness check passes.
 
 ```sh
+sealkeep autopilot --reclaim # explicitly allow safe background disk reclaim on this machine
 sealkeep autopilot status   # is it alive, and what has it done
-sealkeep autopilot off      # stop it — every archive stays
+sealkeep autopilot off      # stop it, remove Sealkeep's hooks — every archive stays
 ```
 
 It tells you it is working rather than leaving you to wonder. The service writes a
@@ -63,10 +67,15 @@ a laptop rewraps keys rather than re-encrypting your data.
 count and checksum must match what was computed locally, or the archive is not marked
 durable and your local file stays exactly where it is.
 
-**4. Reclaim** — only a verified, idle, out-of-grace-period session becomes eligible, and
-then it moves to your trash. There is no code path in Sealkeep that deletes a file.
+**4. Reclaim** — only a remotely verified, searchable, idle, out-of-grace-period session
+whose source still exactly matches its archive becomes eligible. With explicit or opt-in
+automatic approval, Sealkeep durably journals the change, leaves Codex a tiny same-session
+resume pointer, and permanently removes the staged full original. Before the purge decision,
+any failure restores the original; after it, restart reconciliation finishes the committed purge.
 
-Autopilot runs all four on a loop. To unlock the vault without a human present, it keeps
+Autopilot always runs Catch, Seal, and Verify on a loop. Reclaim joins that loop only
+after you explicitly opt this machine in with `--reclaim` or the local Settings switch.
+To unlock the vault without a human present, it keeps
 your phrase in the OS keystore — macOS Keychain, Freedesktop Secret Service, or Windows
 DPAPI. That is a real trade-off, stated plainly: anything running as you can read it once
 you are logged in. Opt out with `--no-remember` and supply
@@ -146,19 +155,20 @@ it stores archives as single objects, and says so.
 
 | | |
 | --- | --- |
-| `sealkeep autopilot` | Set it up once and let it run itself |
+| `sealkeep autopilot` | Preserve, index, and upload automatically; keep original sessions by default |
+| `sealkeep autopilot --reclaim` | Explicitly allow this machine to reclaim eligible originals |
 | `sealkeep autopilot status` · `off` | Check on it, or stop it |
 | `sealkeep quickstart` | Same setup, no background service |
 | `sealkeep status` · `doctor` | What is archived; whether this machine is healthy |
 | `sealkeep queue run` | Encrypt everything waiting |
-| `sealkeep daemon` | Watch, seal, upload, and reclaim continuously |
+| `sealkeep daemon` | Watch, seal, index, and upload continuously; reclaim only when enabled |
 | `sealkeep search <query>` | Metadata search; `--content` searches inside sessions |
 | `sealkeep recover <id> <dest>` | Restore original bytes; `--native` puts them back where they came from |
 | `sealkeep recover <filename>` | The file an agent's resume just complained about, back in place |
 | `sealkeep archive <path> --stream` | Seal straight to the bucket as a chunk folder, resumable mid-upload |
 | `sealkeep share <id>` | A sealed bundle under a one-time passcode — the phrase never travels |
 | `sealkeep mcp install` | Register the vault as a tool server with Claude Code and Codex |
-| `sealkeep retention apply` | Dry run; `--confirm` moves sources to the trash |
+| `sealkeep retention apply` | Dry run; `--confirm` permanently frees verified local originals |
 | `sealkeep desktop` · `tui` | The dashboard, in a browser or the terminal |
 | `sealkeep audit` | Everything Sealkeep has done to your files |
 
@@ -171,13 +181,86 @@ Codex, so the agent itself can search your sealed history, check vault
 status, and restore a session it needs — six tools, all local, nothing new
 exposed to the network.
 
+Ordinary work does not depend on the agent remembering to call that tool.
+The installed lifecycle hooks identify the current Git project and inject a
+small, labelled context automatically:
+
+- **One developer, several machines.** A finished Mac session is sealed and
+  its encrypted index syncs in the background. When the same developer opens
+  the project on a VPS, the newest preserved handoffs, commits, and touched
+  files are prepared automatically—even if the prompt only says “continue.”
+- **Independent accounts working on one project.** One person enables Team mode
+  for the project in the Shared page and invites teammates by account email.
+  Each machine receives only its own wrapped copy of the random project feed
+  key. The background service automatically holds one authenticated realtime
+  connection and multiplexes every bound project over it. Normal Claude Code
+  and Codex lifecycle hooks publish encrypted start/progress/finish events;
+  push writes them to a bounded local inbox, and the next safe agent boundary
+  consumes them without polling. HTTP cursor reads happen only at cold start,
+  after reconnect, or while push is unhealthy, so an API contract chosen on
+  one machine reaches the other invited accounts without sharing a recovery
+  phrase or running a Sealkeep command.
+
+Recall and cooperation use two hook lanes. The agent-facing lane only claims
+and decrypts already-prepared local context, with a two-second fail-open limit;
+it never searches an archive or waits for the network. A companion hook runs
+asynchronously after startup, prompts, and meaningful tools: it publishes the
+current task first, reconciles the encrypted team inbox, refreshes/searches the
+memory index, then seals the result for the next safe agent boundary. Usually
+startup preparation is ready for the first prompt. If a provider is slow, the
+agent continues immediately and receives the consistent result at a later safe
+boundary instead of freezing the person's work.
+
+The hosted realtime route is itself a 256-bit opaque capability derived from
+the team space. A signed-in client that somehow obtains that id can observe
+traffic timing and ciphertext, but cannot publish through the membership-
+checked endpoint or decrypt the feed without a wrapped project key. Durable
+reads and writes always enforce membership. Every displayed team event also
+shows the server-authenticated account id; its friendly label and text remain
+explicitly untrusted because a legitimate member chooses both.
+
+There are no daily `sealkeep search`, `sealkeep team`, or bridge commands in
+that flow. Pairing the machine, choosing whether a project is active, and the
+agent's normal one-time hook trust review are setup/security decisions; after
+that, capture, recall, and exchange are background behavior. Recalled text is
+always labelled as untrusted historical data and current facts are checked
+against Git.
+
+Autopilot-owned background integrations upgrade automatically on macOS and
+Linux. Foreground `ui`, `desktop`, and `api` processes must be restarted after
+an upgrade; they are not part of the background-service promise.
+On a systemd Linux host, Autopilot also enables lingering for the current
+numeric user when the host permits it, so the user service starts at boot and
+survives the last SSH logout. Sealkeep records whether it changed that
+user-wide setting and reverses only its own change when Autopilot is turned
+off. If `loginctl` is unavailable or policy refuses the change, preservation
+continues for the current login and resumes at the next one; setup reports the
+limitation instead of blocking or silently claiming reboot persistence.
+On its first start after an upgrade, the background service reconciles only
+lifecycle hooks that Sealkeep already owns;
+unrelated settings and user hooks are retained and the pre-edit file is backed
+up. It never opts a previously unhooked agent into integration. Running
+`sealkeep autopilot off` removes those owned hooks while keeping the vault and
+every archive. A disclosed, package-independent integration manager also stays
+next to the vault while Autopilot is enabled. If the npm package remains absent
+for five minutes after a raw package-manager uninstall, it removes only the
+owned service and hook entries, writes a cleanup receipt, and preserves sealed
+archives, the outbox, recovery material, and remote objects.
+
+Recovery material is kept in the strongest backend that proves it can perform
+a real reversible write on that machine: macOS Keychain, Linux Secret Service,
+modern systemd user-scoped encrypted credentials on a headless Linux host, or
+Windows DPAPI. If none is usable, setup names the owner-only file fallback
+honestly; the native reboot rehearsal refuses that fallback.
+
 And the failure this whole product could have caused is handled where it
 would happen: resuming a session whose transcript was archived and reclaimed.
-A `SessionStart` hook notices the missing file and restores it — exact path,
-exact bytes — before the agent reads it, so the resume proceeds as if the
-file had never left. If anything is ever missing anyway, `sealkeep recover
-<filename>` with the filename from the agent's error puts it back. Archiving
-must never cost you a resume.
+Codex keeps a tiny valid native pointer under the same session id. The resumed
+agent searches relevant preserved memory through MCP without downloading the
+full transcript. For an explicit full restore, run `sealkeep recover
+<archive-id> --native --overwrite backup` and resume the same id again. The
+backup policy preserves anything already at the native path; no SessionStart
+hook automatically replaces an open transcript or downloads gigabytes.
 
 ## Your storage
 
@@ -204,7 +287,7 @@ Format v2: a random per-archive key encrypts the session in chunks under ChaCha2
 authenticated over its own position, the archive's identity, and the total chunk count — so
 reordering, truncation, splicing, and suite downgrade are all detectable rather than silent.
 
-The format lives in [`packages/vaultline-crypto/`](./packages/vaultline-crypto/README.md)
+The format lives in [`packages/sealkeep-crypto/`](./packages/sealkeep-crypto/README.md)
 with deterministic test vectors and a tamper suite that flips every byte of a stored archive
 in turn. Assumptions and limits are in [`THREAT_MODEL.md`](./THREAT_MODEL.md).
 
@@ -216,20 +299,20 @@ built on published primitives — not an audited end-to-end-encryption product.
 | Area | State |
 | --- | --- |
 | Capture and sealing | **Shipping** — durable queue, crash-safe, deduplicating, resumable streaming |
-| Restore | **Shipping** — byte-identical, verified twice, never overwrites; rehydrates on agent resume |
-| Retention | **Shipping** — trash-staged, never deletes |
+| Restore | **Shipping** — byte-identical, verified twice, refuses to overwrite unless told; a reclaimed-session pointer supports MCP search and explicit safe full restore |
+| Retention | **Shipping** — opt-in, transaction-staged permanent reclaim; pre-commit failures restore and committed crashes reconcile |
 | Search | **Shipping** — sealed content index, synced across your machines as ciphertext |
-| Agent integration | **Shipping** — MCP server for Claude Code and Codex, session hooks |
+| Agent integration | **Shipping** — MCP server plus automatic project recall and active-team lifecycle hooks for Claude Code and Codex |
 | Encryption format | **Unaudited** — vectors and tamper suite, no third-party audit yet |
-| Cloud providers | **GCS live in production**; S3, R2, and Drive verified against signature vectors and emulators, without a long production soak yet |
+| Cloud providers | **R2 live in production** (managed storage); S3, GCS, and Drive verified against signature vectors and emulators, without a long production soak yet |
 | Signed binaries | **Not yet** — npm provenance and a signed manifest; no OS code-signing certificate |
 | Distribution | **Published** — `npm install -g sealkeep` |
 
 ## Self-hosting the control plane
 
 ```sh
-docker build -t vaultline-control-plane .
-docker run -p 8787:8787 -v vaultline-data:/data vaultline-control-plane
+docker build -t sealkeep-control-plane .
+docker run -p 8787:8787 -v sealkeep-data:/data sealkeep-control-plane
 ```
 
 Devices authenticate with Ed25519 request signatures, leases are single-use and expiring,
@@ -241,6 +324,9 @@ and revocation blocks new leases without touching archives. See
 ```sh
 npm test        # the full suite — crypto vectors, a tamper suite, provider emulators, dashboard rendering
 npm run build
+npm run rehearsal:install-upgrade   # disposable global install plus real 0.9.0 → current upgrade
+npm run rehearsal:automatic-memory  # real Mac/VPS Codex; needs documented QA account + SSH VPS env vars
+npm run rehearsal:team-realtime     # four real Codex actors; isolated local control-plane lab
 ```
 
 Architecture is in [`ARCHITECTURE.md`](./ARCHITECTURE.md); designs and operations live in

package/THIRD_PARTY.md

@@ -1,6 +1,6 @@
 # Third-party components
 
-Vaultline ships with the following third-party components, each under its own
+Sealkeep ships with the following third-party components, each under its own
 licence (see §8 of LICENSE). Nothing else in the published package is
 third-party code.
 
@@ -9,7 +9,7 @@ third-party code.
 - **zod** — TypeScript schema validation.
   Licence: MIT. https://github.com/colinhacks/zod
 - **@modelcontextprotocol/sdk** — Model Context Protocol SDK, used by
-  `vaultline mcp`.
+  `sealkeep mcp`.
   Licence: MIT. https://github.com/modelcontextprotocol/typescript-sdk
 
 ## Vendored data

package/THREAT_MODEL.md

@@ -1,6 +1,6 @@
 # Sealkeep Threat Model
 
-**Scope:** the `vaultline-crypto` archive envelope (format v2) and the client that produces it.
+**Scope:** the `sealkeep-crypto` archive envelope (format v2) and the client that produces it.
 **Status:** written by the implementing engineers. **Not yet independently audited.** See "Open gates".
 
 ## 1. What the system protects
@@ -56,7 +56,7 @@ are separately bound to archive id and suite. Consequently these are all detecte
 
 Out of scope for confidentiality: an attacker running as the user can read the plaintext
 transcripts directly from the agent's own directories. Sealkeep reduces blast radius by
-keeping the recovery phrase out of files (it is passed by environment to one command), storing
+keeping the recovery phrase out of files (today it is also accepted as a `--recovery-phrase` argument, which lands in shell history and the process list — prefer the keystore or the environment variable; tightening this is an open item), storing
 its own state at mode `600`, and never writing the phrase to logs, queue jobs, or the API.
 
 ### 3.5 Lost or stolen device
@@ -79,6 +79,25 @@ The MCP server is local but model-driven. Search returns metadata only. Archive
 require the recovery phrase from the local environment, recover refuses to overwrite by default,
 and native restore refuses any path outside the adapter's own transcript roots.
 
+### 3.8 One-time Backup Recovery Kit
+
+The ordinary escrow record contains only the permanent 24-word phrase wrap. Each of the five
+backup codes has a separate encrypted capsule, indexed by the first 128 bits of SHA-256 over the
+canonical 128-bit code. The service therefore sees an opaque, non-enumerable locator but never
+the code, phrase, archive key, or plaintext vault material.
+
+Redeeming a capsule and recording its random per-machine claim happen in one database
+transaction, scoped to the authenticated account. A different claim receives no capsule. If the
+winning response is lost, only that same claim can retrieve the capsule. Replacing the kit
+atomically removes both the active capsules and their consumption rows before installing the new
+set. The client checks that the target has no physical archive records before redemption and does
+not decrypt or persist permanent vault material until Cloud has awarded the capsule.
+
+The control plane can still deny recovery or destroy a capsule. It cannot use a stored capsule
+without the printed code, and a database copy cannot replay a spent code through the service.
+As with any bearer recovery secret, anyone who copies an unused printed code and can sign in to
+the same account may race its owner; exactly one claim wins.
+
 ## 4. Cryptographic design
 
 - **Suite:** ChaCha20-Poly1305 (default) or AES-256-GCM, both from OpenSSL via Node. No custom primitive.
@@ -95,11 +114,11 @@ and native restore refuses any path outside the adapter's own transcript roots.
 3. **No forward secrecy for the phrase.** Anyone who learns the recovery phrase can open every archive it was a recipient for, including old ones.
 4. **Zeroization is best effort.** JavaScript may retain copies of buffers the implementation cannot reach.
 5. **scrypt parameters are modest** so that a hook-driven flow stays responsive; they are recorded per archive and can be raised without breaking existing archives.
-6. **No streaming.** Archives are encrypted from an in-memory buffer, which bounds practical archive size to available memory.
+6. **Streaming.** Archives seal through a chunked stream (64 MB windows); neither sealing nor verification holds a whole archive in memory.
 
 ## 6. Open gates before an end-to-end-encryption claim
 
-- [ ] Independent third-party cryptographic audit of `vaultline-crypto` and this document.
+- [ ] Independent third-party cryptographic audit of `sealkeep-crypto` and this document.
 - [ ] Publication of the package under a public repository with the test vectors.
 - [ ] Review of the key lifecycle by someone outside the implementing team.
 

package/dist/packages/{vaultline-crypto → sealkeep-crypto}/src/chunk-access.d.ts

@@ -22,6 +22,26 @@ export type ChunkWindow = {
     rawStartInWindow: number;
     rawLengthInWindow: number;
 };
+export type ChunkAccessOptions = {
+    /** Stored bytes in this window, including chunks that pad the requested range. */
+    maxStoredBytes?: number;
+    /** All expanded bytes in this window, including padding, not just returned bytes. */
+    maxExpandedBytes?: number;
+    maxExpandedChunkBytes?: number;
+    /** Checked before/after synchronous decompression and between chunks. */
+    signal?: AbortSignal;
+    /**
+     * The archive key of this envelope, already unwrapped by the caller (see
+     * `unwrapWindowKey`). Unwrapping a phrase recipient is an scrypt derivation
+     * of ~70 ms; a reader that opens dozens of windows of one sealed file pays
+     * it once instead of per window. The caller owns the key's lifetime and
+     * zeroization — it is never zeroized here.
+     */
+    archiveKey?: Buffer;
+};
+/** The archive key `openChunkWindow` would unwrap for every window; unwrap it
+ * once, pass it as `options.archiveKey`, and zeroize it when done. */
+export declare function unwrapWindowKey(envelope: Envelope, unlock: Unlock): Buffer;
 /** True when an envelope supports random access at all. */
 export declare function supportsChunkAccess(envelope: Envelope): boolean;
 /**
@@ -32,8 +52,10 @@ export declare function supportsChunkAccess(envelope: Envelope): boolean;
 export declare function chunkWindowForRange(envelope: Envelope, rawStart: number, rawEnd: number): ChunkWindow;
 /**
  * Opens the chunks inside a fetched stored slice and returns exactly the raw
- * bytes the window was asked for. Every chunk is hash-checked and
- * authenticated before a byte of it is trusted — a ranged read keeps the
- * whole-archive guarantees, chunk by chunk.
+ * bytes the window was asked for. The caller MUST authenticate the complete
+ * envelope and source-to-range mapping before using this primitive: v2 chunk
+ * AAD does not bind rawBytes or the codec, and a partial read cannot verify the
+ * whole-source hash or the lengths of chunks outside the window. The checks
+ * here prove selected ciphertext integrity and exact expanded chunk lengths.
  */
-export declare function openChunkWindow(envelope: Envelope, window: ChunkWindow, storedSlice: Buffer, unlock: Unlock): Buffer;
+export declare function openChunkWindow(envelope: Envelope, window: ChunkWindow, storedSlice: Buffer, unlock: Unlock, options?: ChunkAccessOptions): Buffer;

package/dist/packages/sealkeep-crypto/src/chunk-access.js

@@ -0,0 +1,219 @@
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { unsqueezeSync } from "./squeeze.js";
+import { aeadDecipher } from "./aead.js";
+import { validateEnvelope } from "./envelope.js";
+import { chunkAad, TAG_BYTES } from "./format.js";
+import { CryptoError, unwrapArchiveKey, zeroize } from "./recipients.js";
+const sha256 = (input) => createHash("sha256").update(input).digest("hex");
+/** The archive key `openChunkWindow` would unwrap for every window; unwrap it
+ * once, pass it as `options.archiveKey`, and zeroize it when done. */
+export function unwrapWindowKey(envelope, unlock) {
+    return unwrapArchiveKey(envelope.wrappedKeys, envelope.suite, envelope.archiveId, unlock);
+}
+const DEFAULT_WINDOW_BYTES = 128 * 1024 * 1024;
+const DEFAULT_EXPANDED_CHUNK_BYTES = 64 * 1024 * 1024;
+const nonnegativeInteger = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+function checkedAdd(left, right) {
+    const total = left + right;
+    if (!nonnegativeInteger(total))
+        throw new CryptoError("envelope_malformed", "Chunk lengths exceed the safe integer range");
+    return total;
+}
+/** True when an envelope supports random access at all. */
+export function supportsChunkAccess(envelope) {
+    // Both chunk codecs qualify. What makes ranged access possible is that each
+    // chunk compresses and encrypts ALONE and records its own raw length — that
+    // is true of zstd-chunk exactly as it is of gzip-chunk. Naming only gzip here
+    // silently disqualified every zstd-chunk archive: they were built chunk-wise
+    // precisely so search could quote a line without decompressing a gigabyte,
+    // and then reported as un-rangeable, so search decompressed the gigabyte.
+    const codec = envelope?.manifest?.compression;
+    return (codec === "gzip-chunk" || codec === "zstd-chunk") && Array.isArray(envelope.chunks)
+        && envelope.chunks.length > 0 && envelope.chunks.every((chunk) => chunk && nonnegativeInteger(chunk.rawBytes));
+}
+/** Structural validation is not authentication of the envelope or its raw offsets. */
+function validateChunkLayout(envelope, signal) {
+    if (!supportsChunkAccess(envelope)) {
+        throw new CryptoError("envelope_malformed", "This archive has no valid chunk-independent layout; for a legacy archive, restore it whole instead of by range.");
+    }
+    if (!nonnegativeInteger(envelope.manifest.originalBytes)
+        || !nonnegativeInteger(envelope.manifest.plaintextBytes)) {
+        throw new CryptoError("envelope_malformed", "The chunk manifest has invalid byte lengths");
+    }
+    let rawBytes = 0;
+    let storedBytes = 0;
+    let plaintextBytes = 0;
+    for (const chunk of envelope.chunks) {
+        signal?.throwIfAborted();
+        if (!nonnegativeInteger(chunk.storedBytes) || !nonnegativeInteger(chunk.plaintextBytes)) {
+            throw new CryptoError("envelope_malformed", "A chunk has invalid byte lengths");
+        }
+        rawBytes = checkedAdd(rawBytes, chunk.rawBytes);
+        storedBytes = checkedAdd(storedBytes, chunk.storedBytes);
+        plaintextBytes = checkedAdd(plaintextBytes, chunk.plaintextBytes);
+    }
+    if (rawBytes !== envelope.manifest.originalBytes || plaintextBytes !== envelope.manifest.plaintextBytes
+        || envelope.chunks.some((chunk) => chunk.rawBytes === 0 && (rawBytes !== 0 || envelope.chunks.length !== 1))) {
+        throw new CryptoError("envelope_malformed", "Chunk lengths do not describe the manifest's original bytes");
+    }
+    validateEnvelope(envelope, storedBytes);
+}
+/**
+ * Maps a raw (original-file) byte range to the chunk window that covers it.
+ * Legacy whole-body-gzip archives cannot answer this — a slice of their stream
+ * is undecodable alone — and the error says to restore whole instead.
+ */
+export function chunkWindowForRange(envelope, rawStart, rawEnd) {
+    validateChunkLayout(envelope);
+    return windowForValidatedRange(envelope, rawStart, rawEnd);
+}
+function windowForValidatedRange(envelope, rawStart, rawEnd) {
+    const total = envelope.manifest.originalBytes;
+    // An empty archive still has one authenticated compressed chunk. Explicitly
+    // reading its empty interval must verify that chunk rather than skip AEAD.
+    if (total === 0 && rawStart === 0 && rawEnd === 0) {
+        return { firstIndex: 0, lastIndex: 0, storedOffset: 0, storedLength: envelope.chunks[0].storedBytes,
+            rawStartInWindow: 0, rawLengthInWindow: 0 };
+    }
+    if (!nonnegativeInteger(rawStart) || !nonnegativeInteger(rawEnd) || rawEnd <= rawStart || rawStart >= total) {
+        throw new CryptoError("invalid_range", `Range ${rawStart}..${rawEnd} is not a range of this ${total}-byte archive`);
+    }
+    const end = Math.min(rawEnd, total);
+    let rawCursor = 0;
+    let storedCursor = 0;
+    let firstIndex = -1;
+    let lastIndex = -1;
+    let storedOffset = 0;
+    let storedLength = 0;
+    let rawStartInWindow = 0;
+    for (const chunk of envelope.chunks) {
+        const rawFrom = rawCursor;
+        const rawTo = rawCursor + (chunk.rawBytes ?? 0);
+        const overlaps = rawTo > rawStart && rawFrom < end;
+        if (overlaps && firstIndex === -1) {
+            firstIndex = chunk.index;
+            storedOffset = storedCursor;
+            rawStartInWindow = rawStart - rawFrom;
+        }
+        if (overlaps) {
+            lastIndex = chunk.index;
+            storedLength += chunk.storedBytes;
+        }
+        rawCursor = rawTo;
+        storedCursor += chunk.storedBytes;
+    }
+    return { firstIndex, lastIndex, storedOffset, storedLength, rawStartInWindow, rawLengthInWindow: end - rawStart };
+}
+/**
+ * Opens the chunks inside a fetched stored slice and returns exactly the raw
+ * bytes the window was asked for. The caller MUST authenticate the complete
+ * envelope and source-to-range mapping before using this primitive: v2 chunk
+ * AAD does not bind rawBytes or the codec, and a partial read cannot verify the
+ * whole-source hash or the lengths of chunks outside the window. The checks
+ * here prove selected ciphertext integrity and exact expanded chunk lengths.
+ */
+export function openChunkWindow(envelope, window, storedSlice, unlock, options = {}) {
+    options.signal?.throwIfAborted();
+    validateChunkLayout(envelope, options.signal);
+    const maxStoredBytes = options.maxStoredBytes ?? DEFAULT_WINDOW_BYTES;
+    const maxExpandedBytes = options.maxExpandedBytes ?? DEFAULT_WINDOW_BYTES;
+    const maxExpandedChunkBytes = options.maxExpandedChunkBytes ?? DEFAULT_EXPANDED_CHUNK_BYTES;
+    for (const [name, limit] of Object.entries({ maxStoredBytes, maxExpandedBytes, maxExpandedChunkBytes })) {
+        if (!nonnegativeInteger(limit))
+            throw new CryptoError("resource_limit_invalid", `${name} must be a non-negative safe integer`);
+    }
+    const fields = ["firstIndex", "lastIndex", "storedOffset", "storedLength", "rawStartInWindow", "rawLengthInWindow"];
+    if (!window || fields.some((field) => !nonnegativeInteger(window[field]))
+        || window.firstIndex > window.lastIndex || window.lastIndex >= envelope.chunks.length) {
+        throw new CryptoError("invalid_range", "The requested chunk window has invalid bounds");
+    }
+    let rawBeforeWindow = 0;
+    for (let index = 0; index < window.firstIndex; index += 1)
+        rawBeforeWindow += envelope.chunks[index].rawBytes;
+    const rawStart = rawBeforeWindow + window.rawStartInWindow;
+    const rawEnd = rawStart + window.rawLengthInWindow;
+    const expected = windowForValidatedRange(envelope, rawStart, rawEnd);
+    if (fields.some((field) => window[field] !== expected[field])) {
+        throw new CryptoError("invalid_range", "The requested chunk window does not match its declared raw range");
+    }
+    if (storedSlice.length !== window.storedLength) {
+        throw new CryptoError("ciphertext_length_mismatch", `The fetched slice is ${storedSlice.length} bytes; the window needs ${window.storedLength}`);
+    }
+    if (window.storedLength > maxStoredBytes)
+        throw new CryptoError("resource_limit_exceeded", "The chunk window exceeds its stored byte limit");
+    let expandedBytes = 0;
+    for (let index = window.firstIndex; index <= window.lastIndex; index += 1) {
+        const rawBytes = envelope.chunks[index].rawBytes;
+        expandedBytes += rawBytes;
+        if (rawBytes > maxExpandedChunkBytes || expandedBytes > maxExpandedBytes) {
+            throw new CryptoError("resource_limit_exceeded", "The chunk window exceeds its expanded byte limit, including padding");
+        }
+    }
+    options.signal?.throwIfAborted();
+    const ownsKey = options.archiveKey === undefined;
+    const archiveKey = options.archiveKey ?? unwrapArchiveKey(envelope.wrappedKeys, envelope.suite, envelope.archiveId, unlock);
+    let result;
+    try {
+        result = Buffer.allocUnsafe(window.rawLengthInWindow);
+        let offset = 0;
+        let rawOffset = 0;
+        let written = 0;
+        for (let index = window.firstIndex; index <= window.lastIndex; index += 1) {
+            options.signal?.throwIfAborted();
+            const chunk = envelope.chunks[index];
+            const stored = storedSlice.subarray(offset, offset + chunk.storedBytes);
+            offset += chunk.storedBytes;
+            if (sha256(stored) !== chunk.sha256)
+                throw new CryptoError("chunk_hash_mismatch", `Chunk ${chunk.index} does not match its recorded hash`);
+            const decipher = aeadDecipher(envelope.suite, archiveKey, Buffer.from(chunk.nonce, "base64"));
+            decipher.setAAD(chunkAad({ archiveId: envelope.archiveId, suite: envelope.suite, index: chunk.index, totalChunks: envelope.chunks.length, plaintextBytes: chunk.plaintextBytes, final: chunk.final }));
+            decipher.setAuthTag(stored.subarray(stored.length - TAG_BYTES));
+            let packed;
+            try {
+                packed = Buffer.concat([decipher.update(stored.subarray(0, stored.length - TAG_BYTES)), decipher.final()]);
+            }
+            catch {
+                throw new CryptoError("chunk_auth_failed", `Chunk ${chunk.index} failed authentication`);
+            }
+            let raw;
+            try {
+                const expand = envelope.manifest.compression === "zstd-chunk" ? unsqueezeSync : gunzipSync;
+                // Native output bounds stop expansion during decompression. zlib
+                // requires a positive bound even for the one valid empty chunk.
+                try {
+                    raw = expand(packed, { maxOutputLength: Math.max(1, chunk.rawBytes) });
+                }
+                catch (error) {
+                    if (error.code === "ERR_BUFFER_TOO_LARGE") {
+                        throw new CryptoError("plaintext_length_mismatch", `Chunk ${chunk.index} exceeds its declared original length`);
+                    }
+                    throw new CryptoError("plaintext_hash_mismatch", `Chunk ${chunk.index} failed decompression after authentication`);
+                }
+                options.signal?.throwIfAborted();
+                if (raw.length !== chunk.rawBytes)
+                    throw new CryptoError("plaintext_length_mismatch", `Chunk ${chunk.index} does not match its declared original length`);
+                const from = Math.max(0, window.rawStartInWindow - rawOffset);
+                const to = Math.min(raw.length, window.rawStartInWindow + window.rawLengthInWindow - rawOffset);
+                if (to > from)
+                    written += raw.copy(result, written, from, to);
+                rawOffset += raw.length;
+            }
+            finally {
+                packed.fill(0);
+                raw?.fill(0);
+            }
+        }
+        if (written !== result.length)
+            throw new CryptoError("plaintext_length_mismatch", "The chunk window did not reproduce the complete requested range");
+        return result;
+    }
+    catch (error) {
+        result?.fill(0);
+        throw error;
+    }
+    finally {
+        if (ownsKey)
+            zeroize(archiveKey);
+    }
+}

package/dist/packages/{vaultline-crypto → sealkeep-crypto}/src/envelope.d.ts

@@ -20,7 +20,7 @@ export type DeterministicSeed = {
 export type EncryptOptions = {
     recipients: Recipient[];
     suite?: Suite;
-    compression?: "none" | "gzip" | "gzip-chunk";
+    compression?: "none" | "gzip" | "gzip-chunk" | "zstd" | "zstd-chunk";
     chunkBytes?: number;
     archiveId?: string;
     createdAt?: string;
@@ -50,6 +50,16 @@ export declare function encryptArchive(plaintext: Buffer, options: EncryptOption
  * holds the ciphertext, is gated by exactly the same rules.
  */
 export declare function validateEnvelope(envelope: Envelope, ciphertextBytes: number): void;
+/**
+ * Authenticates and decrypts the stored body without expanding its compression.
+ *
+ * Keeping the authenticated chunks separate matters for callers that can stream
+ * decompression. A highly-compressible search index may be tens of megabytes on
+ * disk and more than a gigabyte after gzip; forcing that expanded body through a
+ * single Buffer is enough to OOM a long-lived agent process before it can inspect
+ * one query term.
+ */
+export declare function decryptArchiveBodyChunks(envelope: Envelope, ciphertext: Buffer, unlock: Unlock): Buffer[];
 /**
  * Decrypts an archive after verifying its structure and every stored chunk hash.
  * Every chunk is authenticated against associated data that pins its position and