sealkeep 0.5.0

package/README.md

@@ -0,0 +1,249 @@
+<div align="center">
+
+# ⌑ Sealkeep
+
+**Keep your agent history, not the disk usage.**
+
+Codex and Claude Code write down every session you have. Sealkeep seals them on your
+machine, verifies a copy landed in your own bucket, and only then lets the local file go.
+
+</div>
+
+```sh
+npm install -g sealkeep
+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.
+
+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.
+
+```sh
+sealkeep autopilot status   # is it alive, and what has it done
+sealkeep autopilot off      # stop it — every archive stays
+```
+
+It tells you it is working rather than leaving you to wonder. The service writes a
+heartbeat every cycle, so `status`, the dashboard, and the local API all answer
+"is it running, when did it last check, and what has it sealed" from the same fact.
+It also raises a native notification when disk is reclaimed or something needs a
+decision — never for routine sealing, which would just train you to ignore it.
+Silence it entirely with `VAULTLINE_NOTIFICATIONS=off`.
+
+Prefer to drive it yourself? `sealkeep quickstart` does the same setup without installing
+a service, and you run `sealkeep queue run` when you feel like it.
+
+---
+
+## Why
+
+Transcripts are the only record of *how* a change happened — the dead ends, the constraint
+you found on the third attempt, the reason that function is strange. They also contain your
+source, your prompts, and whatever you pasted at 2am.
+
+So the two obvious options are both bad: let them fill the disk, or `rm -rf` the reasoning
+behind six months of work. Sealkeep is the third option.
+
+## How it works
+
+The order is the safety property. Nothing is reclaimed before it is verified, and nothing is
+verified before it is sealed.
+
+**1. Catch** — your agent's session hook records that a transcript is ready, then exits. It
+holds no secret, makes no network call, and finishes in milliseconds, so it can never stall
+your agent.
+
+**2. Seal** — a worker encrypts the session with a key generated for that archive alone.
+That key is wrapped once for your recovery phrase and once per device you trust, so revoking
+a laptop rewraps keys rather than re-encrypting your data.
+
+**3. Verify** — the sealed archive goes to your bucket, and Sealkeep reads it back. Byte
+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.
+
+Autopilot runs all four on a loop. 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
+`VAULTLINE_RECOVERY_PHRASE` to the service yourself. Either way, the phrase you wrote down
+stays your disaster-recovery path.
+
+## Your recovery phrase is 24 words
+
+Not a base64 string. Words survive bad handwriting, can be read aloud, and carry a
+checksum — so a misread word is caught and corrected rather than silently locking you out.
+
+```
+acorn oxide lynx atom voyage wool candle umber steel radar east clock
+iris brass stork maple ridge ember quilt fable onyx cedar dune cricket
+```
+
+```sh
+sealkeep recovery kit --out ~/sealkeep-kit.txt   # printable sheet, blanks for the words
+sealkeep recovery verify                          # type it back to prove your copy works
+```
+
+Case and spacing do not matter when you type it back. A wrong word is named with
+suggestions: *Word 1 "acron" is not in the list. Did you mean acorn, arrow?*
+
+## Setting up a bucket, without the usual afternoon
+
+The step people give up on is cloud permissions. So Sealkeep writes it out — the console
+link, the commands with your own bucket and prefix already filled in, and a policy that
+grants the least it can.
+
+```sh
+sealkeep storage setup --provider s3  --bucket my-archives --prefix accounts/me
+sealkeep storage setup --provider r2  --bucket sessions --prefix me --account-id <id>
+sealkeep storage setup --provider gcs --bucket sessions --prefix me --project <project>
+```
+
+For S3 that is an IAM policy scoped to `bucket/prefix/*` with no delete permission and no
+wildcard resource. For GCS it is a service account with an IAM condition pinned to your
+prefix. Nothing runs automatically — you read each step and paste it yourself, which is the
+only honest way to hand someone an IAM policy.
+
+## What we can see
+
+The control plane coordinates devices, quotas, and upload permissions.
+
+| It holds | It never receives |
+| --- | --- |
+| Account and device identifiers | Transcript content — no endpoint accepts it |
+| Byte counts and timestamps | Archive keys — generated and wrapped on your machine |
+| Checksums of sealed archives | Your recovery phrase — shown once, stored nowhere |
+| Encrypted manifests it cannot read | Device private keys — only public halves are registered |
+
+> If you lose your recovery kit and every device you registered, your archives are
+> unreadable. Support cannot get them back. That is not a gap in the product — it is the product.
+
+## What your bucket sees
+
+One archive is one folder of fixed-size encrypted chunks plus a small sealed
+envelope. By default every path segment — project, date, session — is an HMAC
+under a key derived from your phrase, so the bucket's file listing is noise:
+no project names, no dates, no session ids. A sealed sidecar in each folder
+carries the readable identity, so any machine with the phrase rebuilds the
+friendly `project/date/session` view from the bucket alone. Prefer legible
+paths in your own bucket? Set `remoteNaming: "readable"` and the same layout
+is written in plain words.
+
+Search works the same way: the content index is sealed with the archive
+machinery and synced beside your data, so every machine of the vault searches
+your whole history — and the provider never sees a token of it.
+
+The layout also answers the worst day: a transcript too large to seal on a
+nearly-full disk streams straight into its chunk folder — peak local cost is
+one chunk — instead of waiting for space. Google Drive is the one exception:
+it stores archives as single objects, and says so.
+
+## Commands
+
+| | |
+| --- | --- |
+| `sealkeep autopilot` | Set it up once and let it run itself |
+| `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 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 desktop` · `tui` | The dashboard, in a browser or the terminal |
+| `sealkeep audit` | Everything Sealkeep has done to your files |
+
+Every command takes `--json`. Run `sealkeep help` for the full list.
+
+## Your agents know the vault is there
+
+`sealkeep mcp install` registers a local MCP server with Claude Code and
+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.
+
+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.
+
+## Your storage
+
+S3, Cloudflare R2, Google Cloud Storage, Google Drive, or anything
+S3-compatible like MinIO. Credentials go into your OS keychain — macOS
+Keychain, Freedesktop Secret Service, or Windows DPAPI — never into a config
+file in your home directory. On the paid tier, Sealkeep runs the storage
+instead: quotas and uploads are brokered by the control plane, and your keys
+and phrase still never leave your machine.
+
+```sh
+sealkeep storage configure --provider r2 --bucket encrypted-sessions --prefix accounts/me
+echo '{"accessKeyId":"…","secretAccessKey":"…"}' | sealkeep storage credentials set
+VAULTLINE_ENABLE_SIGNER=1 sealkeep upload --all
+```
+
+Or skip storage entirely and keep everything local. Sealkeep still seals every archive; it
+just has nowhere to copy it.
+
+## Encryption
+
+Format v2: a random per-archive key encrypts the session in chunks under ChaCha20-Poly1305
+(or AES-256-GCM), and that key is wrapped separately for each recipient. Every chunk is
+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)
+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).
+
+**It has not been independently audited.** Until it is, this is authenticated encryption
+built on published primitives — not an audited end-to-end-encryption product.
+
+## Status
+
+| 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 |
+| Search | **Shipping** — sealed content index, synced across your machines as ciphertext |
+| Agent integration | **Shipping** — MCP server for Claude Code and Codex, session hooks |
+| 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 |
+| 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
+```
+
+Devices authenticate with Ed25519 request signatures, leases are single-use and expiring,
+and revocation blocks new leases without touching archives. See
+[`CONTROL_PLANE.md`](./CONTROL_PLANE.md) and [`docs/RUNBOOK.md`](./docs/RUNBOOK.md).
+
+## Development
+
+```sh
+npm test        # the full suite — crypto vectors, a tamper suite, provider emulators, dashboard rendering
+npm run build
+```
+
+Architecture is in [`ARCHITECTURE.md`](./ARCHITECTURE.md); designs and operations live in
+[`docs/`](./docs/README.md), including the not-yet-built
+[sharing and spaces design](./docs/sharing-and-spaces.md). The marketing page in
+[`site/`](./site/index.html) is a single self-contained file.

package/THIRD_PARTY.md

@@ -0,0 +1,22 @@
+# Third-party components
+
+Vaultline 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.
+
+## Runtime dependencies
+
+- **zod** — TypeScript schema validation.
+  Licence: MIT. https://github.com/colinhacks/zod
+- **@modelcontextprotocol/sdk** — Model Context Protocol SDK, used by
+  `vaultline mcp`.
+  Licence: MIT. https://github.com/modelcontextprotocol/typescript-sdk
+
+## Vendored data
+
+- **BIP-39 English word list** (`src/bip39-wordlist.ts`) — the 2048-word list
+  exactly as frozen by the BIP-39 specification, vendored from
+  https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt so the
+  supply chain carries no extra dependency. The build verifies it against the
+  specification's published SHA-256 digest. The list is distributed under the
+  terms stated in the bitcoin/bips repository for BIP-0039.

package/THREAT_MODEL.md

@@ -0,0 +1,107 @@
+# Sealkeep Threat Model
+
+**Scope:** the `vaultline-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
+
+Agent transcripts contain prompts, source code, credentials pasted into sessions, and
+business context. The asset is the *plaintext* of an archived transcript, plus the
+secrets that unlock it: the recovery phrase and device private keys.
+
+## 2. Trust assumptions
+
+| Party | Trusted for | Not trusted for |
+| --- | --- | --- |
+| Local client process | Plaintext handling, key generation | — |
+| Local OS user account | Reading its own files | — |
+| Control plane | Availability, metadata integrity, access control | Confidentiality of transcripts |
+| Object store (S3/R2/GCS) | Durability | Confidentiality, integrity |
+| Network | Nothing | Confidentiality, integrity |
+
+The client is the only component that ever holds plaintext or an archive key.
+
+## 3. Adversaries and outcomes
+
+### 3.1 Malicious or breached control plane
+
+Sees: account and device identifiers, archive ids, byte counts, timestamps, ciphertext hashes,
+object keys, and opaque encrypted manifests. Cannot decrypt: it never receives an archive key,
+recovery phrase, or device private key. It *can* deny service and it *can* lie about metadata,
+so the client verifies checksums locally and refuses reclamation on any mismatch.
+
+### 3.2 Stolen object from the bucket
+
+An attacker with the ciphertext holds AEAD output under a random 256-bit per-archive key.
+Recovering plaintext requires breaking ChaCha20-Poly1305 or AES-256-GCM, or obtaining a
+recipient secret. Chunk headers leak archive size and chunk count; the source path is in the
+local record, not in the stored object.
+
+### 3.3 Archive tampering
+
+Every chunk is authenticated with associated data binding format version, suite, archive id,
+chunk index, total chunk count, chunk plaintext length, and a final-chunk flag. Wrapped keys
+are separately bound to archive id and suite. Consequently these are all detected:
+
+| Attack | Detected by | Test |
+| --- | --- | --- |
+| Bit flip in ciphertext or tag | AEAD tag | `detects a flipped bit anywhere in the stored ciphertext` |
+| Chunk reordering | Index in chunk AAD | `rejects a reordered archive even when the headers are rewritten` |
+| Truncation | Final flag plus total chunk count | `rejects truncation of the final chunk` |
+| Splicing chunks between archives | Archive id in chunk AAD | `rejects a chunk spliced in from another archive` |
+| Suite downgrade | Suite in wrap AAD and chunk AAD | `rejects a suite downgrade` |
+| Rewriting a chunk hash to match damage | AEAD tag behind the hash check | `rejects a chunk whose recorded hash was rewritten` |
+
+### 3.4 Compromised local user account
+
+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
+its own state at mode `600`, and never writing the phrase to logs, queue jobs, or the API.
+
+### 3.5 Lost or stolen device
+
+Each device is a separate X25519 recipient. Removing the recipient and running `sealkeep rewrap`
+re-wraps every archive key without that device, without re-encrypting data. Revocation is
+therefore fast, but it is **not retroactive**: an attacker who copied both the ciphertext and the
+device key before revocation retains access to that copy. Control-plane revocation additionally
+blocks new leases.
+
+### 3.6 Replayed or stolen upload lease
+
+Leases are short-lived, single-object, and checked by `assertLeaseUsable`, which tests expiry
+before anything else. A stolen lease can at worst write one object the client already intended
+to write; it cannot read, and it cannot choose the object key, which the server allocates.
+
+### 3.7 Malicious MCP prompt or tool invocation
+
+The MCP server is local but model-driven. Search returns metadata only. Archive and recover
+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.
+
+## 4. Cryptographic design
+
+- **Suite:** ChaCha20-Poly1305 (default) or AES-256-GCM, both from OpenSSL via Node. No custom primitive.
+- **Archive key:** 32 random bytes per archive, never reused, zeroized after use where the runtime allows.
+- **Nonces:** 4-byte per-archive random prefix plus a 64-bit big-endian chunk counter. Unique per chunk by construction; unique across archives because the key is fresh per archive.
+- **Phrase recipients:** scrypt (N=2^15, r=8, p=1 by default; recorded per archive so parameters can be raised later), then AEAD key wrap.
+- **Key recipients:** ephemeral-static X25519, HKDF-SHA256 over the shared secret with both public keys as salt, then AEAD key wrap.
+- **Integrity:** per-chunk SHA-256 recorded for cheap corruption detection, AEAD tags for authenticity, whole-plaintext SHA-256 in the manifest checked after decryption.
+
+## 5. Known limitations
+
+1. **Length and timing leak.** Ciphertext size reveals plaintext size to within one chunk; no padding is applied.
+2. **Metadata in the local record.** Source path, agent, and byte count are stored in cleartext in the local vault directory. Private-metadata mode is not implemented.
+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. Open gates before an end-to-end-encryption claim
+
+- [ ] Independent third-party cryptographic audit of `vaultline-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.
+
+Until all three are met, Sealkeep documentation must describe the envelope as
+"authenticated encryption implemented against published primitives", not as audited E2EE.

package/dist/packages/vaultline-crypto/src/aead.d.ts

@@ -0,0 +1,12 @@
+import { type CipherGCM, type DecipherGCM } from "node:crypto";
+import { type Suite } from "./format.js";
+/**
+ * Both suites take a 12-byte nonce, a 16-byte tag, and plain associated data.
+ *
+ * `@types/node` groups `chacha20-poly1305` with the CCM ciphers, whose typed
+ * `setAAD` demands a plaintext length that ChaCha20-Poly1305 does not use. The
+ * literal suite is narrowed here so the right runtime overload is selected, and the
+ * result is presented with the GCM-shaped interface both ciphers actually have.
+ */
+export declare function aeadCipher(suite: Suite, key: Buffer, nonce: Buffer): CipherGCM;
+export declare function aeadDecipher(suite: Suite, key: Buffer, nonce: Buffer): DecipherGCM;

package/dist/packages/vaultline-crypto/src/aead.js

@@ -0,0 +1,24 @@
+import { createCipheriv, createDecipheriv } from "node:crypto";
+import { TAG_BYTES } from "./format.js";
+/**
+ * Both suites take a 12-byte nonce, a 16-byte tag, and plain associated data.
+ *
+ * `@types/node` groups `chacha20-poly1305` with the CCM ciphers, whose typed
+ * `setAAD` demands a plaintext length that ChaCha20-Poly1305 does not use. The
+ * literal suite is narrowed here so the right runtime overload is selected, and the
+ * result is presented with the GCM-shaped interface both ciphers actually have.
+ */
+export function aeadCipher(suite, key, nonce) {
+    const options = { authTagLength: TAG_BYTES };
+    const cipher = suite === "chacha20-poly1305"
+        ? createCipheriv("chacha20-poly1305", key, nonce, options)
+        : createCipheriv("aes-256-gcm", key, nonce, options);
+    return cipher;
+}
+export function aeadDecipher(suite, key, nonce) {
+    const options = { authTagLength: TAG_BYTES };
+    const decipher = suite === "chacha20-poly1305"
+        ? createDecipheriv("chacha20-poly1305", key, nonce, options)
+        : createDecipheriv("aes-256-gcm", key, nonce, options);
+    return decipher;
+}

package/dist/packages/vaultline-crypto/src/chunk-access.d.ts

@@ -0,0 +1,39 @@
+import { type Envelope } from "./format.js";
+import { type Unlock } from "./recipients.js";
+/**
+ * Random access into a gzip-chunk archive: the primitive behind "fetch the
+ * chunks, not the archive".
+ *
+ * Under gzip-chunk every chunk compresses and encrypts on its own and records
+ * the RAW byte range it covers, so a question like "bytes 40–60 MB of that
+ * session" resolves to chunk indices and a single stored byte range — without
+ * downloading, decrypting, or decompressing anything else. A ranged GET plus
+ * this module is a partial restore; a loop over all chunks is a full one, in
+ * one chunk of memory.
+ */
+export type ChunkWindow = {
+    /** First and last chunk index covering the requested raw range. */
+    firstIndex: number;
+    lastIndex: number;
+    /** The byte range of the STORED object holding those chunks — what a ranged GET fetches. */
+    storedOffset: number;
+    storedLength: number;
+    /** Where the requested raw range sits inside the decompressed window. */
+    rawStartInWindow: number;
+    rawLengthInWindow: number;
+};
+/** True when an envelope supports random access at all. */
+export declare function supportsChunkAccess(envelope: Envelope): boolean;
+/**
+ * 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 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.
+ */
+export declare function openChunkWindow(envelope: Envelope, window: ChunkWindow, storedSlice: Buffer, unlock: Unlock): Buffer;

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

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { aeadDecipher } from "./aead.js";
+import { chunkAad, TAG_BYTES } from "./format.js";
+import { CryptoError, unwrapArchiveKey, zeroize } from "./recipients.js";
+const sha256 = (input) => createHash("sha256").update(input).digest("hex");
+/** True when an envelope supports random access at all. */
+export function supportsChunkAccess(envelope) {
+    return envelope.manifest.compression === "gzip-chunk" && envelope.chunks.every((chunk) => typeof chunk.rawBytes === "number");
+}
+/**
+ * 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) {
+    if (!supportsChunkAccess(envelope)) {
+        throw new CryptoError("envelope_malformed", "This archive predates chunk-independent compression; restore it whole instead of by range.");
+    }
+    const total = envelope.manifest.originalBytes ?? 0;
+    if (rawStart < 0 || rawEnd <= rawStart || rawStart >= Math.max(total, 1)) {
+        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. 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.
+ */
+export function openChunkWindow(envelope, window, storedSlice, unlock) {
+    if (storedSlice.length !== window.storedLength) {
+        throw new CryptoError("ciphertext_length_mismatch", `The fetched slice is ${storedSlice.length} bytes; the window needs ${window.storedLength}`);
+    }
+    const archiveKey = unwrapArchiveKey(envelope.wrappedKeys, envelope.suite, envelope.archiveId, unlock);
+    try {
+        const parts = [];
+        let offset = 0;
+        for (let index = window.firstIndex; index <= window.lastIndex; index += 1) {
+            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`);
+            }
+            try {
+                parts.push(gunzipSync(packed));
+            }
+            catch {
+                throw new CryptoError("plaintext_hash_mismatch", `Chunk ${chunk.index} failed decompression after authentication`);
+            }
+        }
+        const raw = Buffer.concat(parts);
+        return raw.subarray(window.rawStartInWindow, window.rawStartInWindow + window.rawLengthInWindow);
+    }
+    finally {
+        zeroize(archiveKey);
+    }
+}

package/dist/packages/vaultline-crypto/src/envelope.d.ts

@@ -0,0 +1,71 @@
+import { type KeyObject } from "node:crypto";
+import { type Unlock } from "./recipients.js";
+import { type Envelope, type ScryptParams, type Suite, type WrappedKey } from "./format.js";
+export type Recipient = {
+    kind: "phrase";
+    phrase: string;
+    scrypt?: ScryptParams;
+} | {
+    kind: "x25519";
+    publicKey: KeyObject | Buffer;
+};
+/** Supplied only by the test-vector generator so a randomized format can have known answers. */
+export type DeterministicSeed = {
+    archiveKey: Buffer;
+    noncePrefix: Buffer;
+    wrapSalts: Buffer[];
+    wrapNonces: Buffer[];
+    ephemeralPrivateKeys?: KeyObject[];
+};
+export type EncryptOptions = {
+    recipients: Recipient[];
+    suite?: Suite;
+    compression?: "none" | "gzip" | "gzip-chunk";
+    chunkBytes?: number;
+    archiveId?: string;
+    createdAt?: string;
+    adapter?: {
+        agent: string;
+        version: string;
+    };
+    deterministic?: DeterministicSeed;
+};
+/** Exported so `stream.ts` produces byte-for-byte the same wraps as the buffered seal. */
+export declare function wrapAll(archiveKey: Buffer, recipients: readonly Recipient[], suite: Suite, archiveId: string, seed?: DeterministicSeed): WrappedKey[];
+/**
+ * Encrypts one archive.
+ *
+ * A random per-archive key encrypts the plaintext in chunks; that key is then
+ * wrapped separately for each recipient. Adding or removing a recipient therefore
+ * never requires re-encrypting the data.
+ */
+export declare function encryptArchive(plaintext: Buffer, options: EncryptOptions): {
+    envelope: Envelope;
+    ciphertext: Buffer;
+};
+/**
+ * Structural checks that must pass before any key is used.
+ *
+ * Takes a length rather than the bytes so the streaming reader, which never
+ * holds the ciphertext, is gated by exactly the same rules.
+ */
+export declare function validateEnvelope(envelope: Envelope, ciphertextBytes: number): void;
+/**
+ * Decrypts an archive after verifying its structure and every stored chunk hash.
+ * Every chunk is authenticated against associated data that pins its position and
+ * the total chunk count, so a reordered or truncated archive fails rather than
+ * returning partial plaintext.
+ */
+export declare function decryptArchive(envelope: Envelope, ciphertext: Buffer, unlock: Unlock): Buffer;
+/**
+ * Rotates the recipient set without touching ciphertext. `replace` is how a lost
+ * device is cut off; `add` is how a new device or extra recovery key is granted.
+ */
+export declare function rewrapArchive(envelope: Envelope, unlock: Unlock, recipients: readonly Recipient[], options?: {
+    mode?: "replace" | "add";
+}): Envelope;
+/** Recipient identifiers present on an archive. Useful for auditing who can open it. */
+export declare function recipientIds(envelope: Envelope): {
+    phrase: string[];
+    keys: string[];
+};