sealkeep 0.5.0

package/dist/src/chunk-store.d.ts

@@ -0,0 +1,142 @@
+import type { ArchiveRecordV2, RemoteObject } from "./types.js";
+import { type ChunkHeader } from "../packages/vaultline-crypto/src/index.js";
+/**
+ * Remote layout v2: a session's archive is a FOLDER of chunk objects, not one
+ * blob. Paul's shape, and the natural completion of the gzip-chunk format —
+ * every chunk was already independently sealed and independently decryptable;
+ * storing them as one object was the leftover assumption, and everything hard
+ * about streaming (multipart sessions, resumable protocols, unknown total
+ * length) existed only to serve it.
+ *
+ *   <project>/<YYYY-MM-DD>/<session>.<id8>/
+ *       chunk-000000 … chunk-NNNNNN      one 4 MB sealed chunk per object
+ *       envelope.vlmeta                  the wrapped-keys envelope
+ *
+ * What the folder buys:
+ *  - A PUT per chunk needs no multipart anything: length known, checksum
+ *    known, one signed request. (This is also what will let MANAGED storage
+ *    stream with the signer it already has — a chunk URL is just a signed PUT.)
+ *  - Resume is HEAD, not protocol: chunk names are deterministic, so the
+ *    provider's truth is "does chunk-000017 exist and match its recorded
+ *    hash" — asked object by object, no ListParts, no sessions.
+ *  - Search fetches the chunk it wants by name.
+ *  - The envelope sidecar makes the folder self-recovering: a bucket plus the
+ *    recovery phrase reconstructs the session with no local records at all.
+ *  - Deleting an archive is deleting its folder.
+ *
+ * On your own bucket the folder is a (hashed or readable) hierarchy; on
+ * managed storage it is the bare archive id and each object rides an ordinary
+ * upload lease as its own file (managed-chunks.ts) — the plane learns nothing
+ * it could not already count, project names included.
+ *
+ * THE RESUME INVARIANT is inherited unchanged from stream-to-cloud.ts: the
+ * same (archiveKey, noncePrefix, chunkIndex) triple must never encrypt two
+ * different plaintexts. Chunk headers are journaled at emission — before the
+ * chunk's PUT — so the provider can never hold a chunk the journal cannot
+ * name, and a resume re-seals and verifies every already-present chunk
+ * against its recorded hash before anything new is encrypted. Any mismatch
+ * abandons the folder and restarts under a fresh key.
+ */
+export type ChunkStoreClient = {
+    putObject(key: string, body: Buffer): Promise<{
+        checksum: string;
+    }>;
+    headObject(key: string): Promise<{
+        exists: boolean;
+        bytes: number;
+        checksum?: string;
+    }>;
+    getObject(key: string): Promise<Buffer>;
+    deleteObject(key: string): Promise<void>;
+};
+export declare const chunkObjectName: (index: number) => string;
+export declare const ENVELOPE_OBJECT = "envelope.vlmeta";
+export type RemoteNaming = "readable" | "hashed";
+/**
+ * The key the hashed naming mode HMACs segments under, derived from the
+ * recovery phrase and pinned to the vault.
+ *
+ * Paul's insight, made safe: hashing the segments keeps the folder STRUCTURE
+ * (same project → same folder, same day → same shelf, grouping and dedupe all
+ * work) while the names say nothing. But a bare hash says everything to
+ * anyone willing to guess: project names are dictionary words and dates are
+ * a 365-entry alphabet per year — sha256("2026-08-17") reverses instantly.
+ * So the segments are HMAC-SHA256 under a phrase-derived key: without the
+ * phrase the folder names are noise; with it, any of the vault's machines
+ * derives the same key and the same grouping.
+ */
+/**
+ * Scoped to the STORAGE, not the vault instance: two machines signed into the
+ * same bucket with the same phrase are one namespace, and vaultId — which is
+ * minted per machine — would scatter them into folders neither can predict.
+ * The test that caught this had machine B hash the index segment differently
+ * from machine A and find nothing where A had pushed everything.
+ */
+export declare function folderNamingKey(phrase: string, storageScope: string): Buffer;
+/** The one canonical spelling of a storage's namespace scope. */
+export declare function storageScopeOf(remoteStorage: {
+    provider: string;
+    bucket: string;
+}): string;
+/**
+ * The folder for one archive: project / day / session, each segment either
+ * readable (your own bucket, browsable in the provider console) or an HMAC
+ * (structure without meaning — what managed storage will use). The archive-id
+ * suffix keeps two same-named sessions, and two snapshots of one session,
+ * from colliding.
+ */
+export declare function chunkFolderFor(input: {
+    configuredPrefix: string;
+    project: string | null;
+    createdAt: string;
+    sourcePath: string;
+    archiveId: string;
+    naming?: RemoteNaming;
+    namingKey?: Buffer;
+}): string;
+export type ChunkSealOutcome = {
+    record: ArchiveRecordV2;
+    folder: string;
+    storedBytes: number;
+    chunkCount: number;
+    /** Chunks that were already in the bucket and were verified instead of re-sent. */
+    reusedChunks: number;
+    heldAtMostBytes: number;
+    /** Whether the archive's tokens were merged into the content index at seal time. */
+    indexed: boolean;
+};
+/**
+ * Seals a source straight into a chunk folder: read a slice, seal it, PUT it
+ * as its own object, journal it, forget it. Peak local cost is one chunk.
+ * A journal for the source resumes the same folder — already-present chunks
+ * are re-sealed locally and verified against both the journal's recorded hash
+ * AND the provider's stored checksum, then skipped.
+ */
+export declare function sealToChunkFolder(dataDir: string, sourcePath: string, rawPhrase: string, agent: string, options?: {
+    client?: ChunkStoreClient;
+    project?: string | null;
+    resume?: boolean;
+    now?: number;
+    targetId?: string;
+}): Promise<ChunkSealOutcome>;
+/**
+ * Seals the readable identity for the sidecar. Its own random nonce — chunk
+ * nonces are (prefix, index) and this must never collide with any of them —
+ * and an AAD binding it to this archive, so a sidecar cannot be swapped
+ * between folders without the opener noticing.
+ */
+export type FolderIdentity = {
+    v: 1;
+    project: string | null;
+    sourcePath: string;
+    agent: string;
+    createdAt: string;
+};
+/** Opens a sidecar's identity with the unwrapped archive key. */
+export declare function openIdentity(archiveKey: Buffer, archiveId: string, blob: Buffer): FolderIdentity;
+/** Fetches a chunked remote back into one ciphertext buffer, hash-checked per chunk. */
+export declare function fetchChunkFolder(client: ChunkStoreClient, remote: RemoteObject, expected: {
+    chunks: ChunkHeader[];
+}): Promise<Buffer>;
+/** Deletes a chunked remote: every chunk object plus the envelope sidecar. */
+export declare function deleteChunkFolder(client: ChunkStoreClient, remote: RemoteObject): Promise<void>;

package/dist/src/chunk-store.js

@@ -0,0 +1,502 @@
+import { createHash, createHmac, hkdfSync, randomBytes, randomUUID } from "node:crypto";
+import { stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fail } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { ADAPTER_VERSION, configuredRecipients, readConfig, writeRecord } from "./vault.js";
+import { uploadClientFromStore } from "./providers/index.js";
+import { acquireSpoolLock, createSpool, findSpoolForSource, shredSpool, unwrapSpoolKey, updateSpool } from "./spool.js";
+import { DEFAULT_CHUNK_BYTES, KEY_BYTES, StreamingSha256, sealChunksToSink, wrapAll, zeroize } from "../packages/vaultline-crypto/src/index.js";
+import { frameObject } from "./cloud.js";
+import { aeadCipher, aeadDecipher } from "../packages/vaultline-crypto/src/aead.js";
+const SEAL_SUITE = "chacha20-poly1305";
+const sha256hex = (input) => createHash("sha256").update(input).digest("hex");
+export const chunkObjectName = (index) => `chunk-${String(index).padStart(6, "0")}`;
+export const ENVELOPE_OBJECT = "envelope.vlmeta";
+/** One path segment a person can read in a bucket console, made key-safe. */
+function slug(raw, fallback) {
+    const cleaned = raw.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 60);
+    return cleaned || fallback;
+}
+/**
+ * The key the hashed naming mode HMACs segments under, derived from the
+ * recovery phrase and pinned to the vault.
+ *
+ * Paul's insight, made safe: hashing the segments keeps the folder STRUCTURE
+ * (same project → same folder, same day → same shelf, grouping and dedupe all
+ * work) while the names say nothing. But a bare hash says everything to
+ * anyone willing to guess: project names are dictionary words and dates are
+ * a 365-entry alphabet per year — sha256("2026-08-17") reverses instantly.
+ * So the segments are HMAC-SHA256 under a phrase-derived key: without the
+ * phrase the folder names are noise; with it, any of the vault's machines
+ * derives the same key and the same grouping.
+ */
+/**
+ * Scoped to the STORAGE, not the vault instance: two machines signed into the
+ * same bucket with the same phrase are one namespace, and vaultId — which is
+ * minted per machine — would scatter them into folders neither can predict.
+ * The test that caught this had machine B hash the index segment differently
+ * from machine A and find nothing where A had pushed everything.
+ */
+export function folderNamingKey(phrase, storageScope) {
+    return Buffer.from(hkdfSync("sha256", Buffer.from(phrase, "utf8"), Buffer.from(`vaultline-folder-names:${storageScope}`, "utf8"), "folder-naming-v1", 32));
+}
+/** The one canonical spelling of a storage's namespace scope. */
+export function storageScopeOf(remoteStorage) {
+    return `${remoteStorage.provider}://${remoteStorage.bucket}`;
+}
+function hashedSegment(key, kind, value) {
+    return createHmac("sha256", key).update(`${kind}:${value}`).digest("hex").slice(0, 16);
+}
+/**
+ * The folder for one archive: project / day / session, each segment either
+ * readable (your own bucket, browsable in the provider console) or an HMAC
+ * (structure without meaning — what managed storage will use). The archive-id
+ * suffix keeps two same-named sessions, and two snapshots of one session,
+ * from colliding.
+ */
+export function chunkFolderFor(input) {
+    const prefix = input.configuredPrefix.replace(/^\/+|\/+$/g, "");
+    const day = input.createdAt.slice(0, 10);
+    const sessionName = input.sourcePath.split("/").pop() ?? "";
+    if (input.naming === "hashed") {
+        const key = input.namingKey ?? fail("invalid_argument", "Hashed folder naming needs the vault's naming key");
+        return `${prefix}/${hashedSegment(key, "project", input.project ?? "")}/${hashedSegment(key, "date", day)}/${hashedSegment(key, "session", sessionName)}.${input.archiveId.slice(0, 8)}`;
+    }
+    return `${prefix}/${slug(input.project ?? "", "no-project")}/${day}/${slug(sessionName, "session")}.${input.archiveId.slice(0, 8)}`;
+}
+async function clientFor(dataDir, target) {
+    const config = await readConfig(dataDir);
+    // Managed-ness follows the same rule as everything else (storedCopiesMode):
+    // an own bucket wins when configured; otherwise a vault signed into the
+    // cloud account IS managed — enrolled vaults carry the token, not a
+    // remoteStorage entry. The live drill on a real vault caught the gap:
+    // gating on config.remoteStorage alone meant no production managed vault
+    // could ever stream. A routed TARGET (multi-target vaults) overrides both.
+    const remoteStorage = (target ? { provider: target.provider, bucket: target.bucket ?? "vaultline-managed", prefix: target.prefix ?? "vaultline", region: target.region } : undefined)
+        ?? config.remoteStorage
+        ?? await (async () => {
+            const { cloudToken } = await import("./cloud.js");
+            try {
+                await cloudToken(dataDir);
+                return { provider: "vaultline", bucket: "vaultline-managed", prefix: "" };
+            }
+            catch {
+                return fail("storage_not_configured", "No remote target configured. Run: sealkeep storage configure ...  (or sign in to Sealkeep Cloud)");
+            }
+        })();
+    if (remoteStorage.provider === "vaultline") {
+        // Managed storage needs no chunk support: the client already chunks, and
+        // each sealed chunk is an ordinary known-length file delivered through the
+        // ordinary upload lease (see managed-chunks.ts). The folder is the archive
+        // id — opaque to the plane, no project or date anywhere — and the readable
+        // hierarchy lives in the sealed sidecar, exactly as on an own bucket.
+        const { managedChunkClient } = await import("./managed-chunks.js");
+        return { client: managedChunkClient(dataDir), remoteStorage: { provider: "vaultline", bucket: "vaultline-managed", prefix: "" } };
+    }
+    const raw = await uploadClientFromStore(dataDir, config.vaultId, remoteStorage);
+    const client = raw;
+    if (typeof client.putObject !== "function" || typeof client.headObject !== "function" || typeof client.getObject !== "function" || typeof client.deleteObject !== "function") {
+        fail("invalid_argument", `The ${remoteStorage.provider} client cannot store chunk folders`);
+    }
+    return { client: client, remoteStorage };
+}
+/**
+ * Seals a source straight into a chunk folder: read a slice, seal it, PUT it
+ * as its own object, journal it, forget it. Peak local cost is one chunk.
+ * A journal for the source resumes the same folder — already-present chunks
+ * are re-sealed locally and verified against both the journal's recorded hash
+ * AND the provider's stored checksum, then skipped.
+ */
+export async function sealToChunkFolder(dataDir, sourcePath, rawPhrase, agent, options = {}) {
+    const config = await readConfig(dataDir);
+    if (config.storageMode === "plain") {
+        fail("invalid_argument", "This vault stores archives as plain readable files; chunking them into a bucket would upload your transcripts unencrypted. Use a sealed vault for cloud archiving.");
+    }
+    // Routing: which of the vault's targets takes this seal. Project pins and
+    // byte limits are the rules; chunk streaming excludes Drive (single-object
+    // by design). Injected clients (tests) bypass routing entirely.
+    let routedTarget;
+    if (!options.client) {
+        const preSize = await stat(resolve(sourcePath)).then((info) => info.size).catch(() => 0);
+        const { chooseTarget } = await import("./storage-targets.js");
+        routedTarget = await chooseTarget(dataDir, { project: options.project ?? null, bytes: preSize, requireChunkCapable: true, targetId: options.targetId });
+    }
+    const bundled = options.client ? null : await clientFor(dataDir, routedTarget);
+    const remoteStorage = bundled?.remoteStorage ?? config.remoteStorage ?? { provider: "vaultline", bucket: "vaultline-managed", prefix: "" };
+    const client = options.client ?? bundled.client;
+    const absolute = resolve(sourcePath);
+    const source = await stat(absolute).catch(() => null);
+    if (!source || !source.isFile())
+        fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+    const phrase = canonicalPhrase(rawPhrase);
+    const totalBytes = source.size;
+    const chunkBytes = DEFAULT_CHUNK_BYTES;
+    const totalChunks = Math.max(1, Math.ceil(totalBytes / chunkBytes));
+    // Journal triage, chunk-layout edition. Same drain-the-stack shape as the
+    // streaming path: resume the newest matching journal or abandon it with the
+    // reason and look again.
+    for (;;) {
+        const journal = await findSpoolForSource(dataDir, absolute);
+        if (!journal)
+            break;
+        if (journal.providerState !== null && !isChunkFolderState(journal.providerState)) {
+            // A single-object streaming journal for this source belongs to the other
+            // pipeline; leave it alone and let that pipeline (or --fresh) decide.
+            break;
+        }
+        const abandon = async (reason) => {
+            await abandonFolderJournal(dataDir, client, journal, reason);
+        };
+        if (options.resume === false) {
+            await abandon("a fresh start was requested (--fresh)");
+            continue;
+        }
+        if (journal.provider !== remoteStorage.provider || journal.bucket !== remoteStorage.bucket || journal.source.totalBytes !== totalBytes) {
+            await abandon("the source file or the storage target is no longer the one the journal describes");
+            continue;
+        }
+        const lock = await acquireSpoolLock(dataDir, journal.archiveId, { now: options.now });
+        try {
+            return await resumeChunkFolder({ dataDir, client, remoteStorage, targetId: routedTarget?.id, absolute, totalBytes, chunkBytes, totalChunks, phrase, agent, now: options.now }, journal);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !/cannot resume/i.test(error.message))
+                throw error;
+            await abandon(error.message);
+            continue;
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    // Fresh seal.
+    const archiveId = randomUUID();
+    const createdAt = new Date(options.now ?? Date.now()).toISOString();
+    // Sealed vault ⇒ unreadable bucket, everywhere. Sealing the CONTENT while
+    // labelling it project/date/session.jsonl would hand every storage provider
+    // the story of the work; the readable hierarchy is the dashboard's job,
+    // built from local records — and from the encrypted identity in each
+    // folder's sidecar when only the bucket survives. `remoteNaming:
+    // "readable"` in config.json is the explicit opt-out for people who want
+    // their own bucket browsable and accept what that says.
+    // Managed vaults skip the naming machinery entirely: the folder is the bare
+    // archive id, so the plane's references (`<id>.chunk-000000`) carry nothing
+    // but the grouping it could always see. Own buckets keep the hashed (or
+    // opted-in readable) project/date/session hierarchy.
+    const naming = config.remoteNaming ?? "hashed";
+    const folder = remoteStorage.provider === "vaultline" ? archiveId : chunkFolderFor({
+        configuredPrefix: remoteStorage.prefix, project: options.project ?? null, createdAt, sourcePath: absolute, archiveId,
+        naming, ...(naming === "hashed" ? { namingKey: folderNamingKey(phrase, storageScopeOf(remoteStorage)) } : {})
+    });
+    const recipients = configuredRecipients(config, phrase);
+    const archiveKey = randomBytes(KEY_BYTES);
+    const noncePrefix = randomBytes(4);
+    const lock = await acquireSpoolLock(dataDir, archiveId, { now: options.now });
+    try {
+        await createSpool(dataDir, {
+            archiveId, suite: SEAL_SUITE, provider: remoteStorage.provider, bucket: remoteStorage.bucket, objectKey: folder,
+            source: { path: absolute, totalBytes, chunkBytes },
+            wrappedKeys: wrapAll(archiveKey, recipients, SEAL_SUITE, archiveId),
+            noncePrefixB64: noncePrefix.toString("base64"),
+            nextChunkIndex: 0,
+            consumedPrefixSha256: createHash("sha256").digest("hex"),
+            chunkHeaders: [],
+            hashState: { plaintext: "", stored: "" },
+            providerState: { kind: "chunk-folder", folder, uploaded: 0 }
+        }, { now: options.now });
+        return await runChunkSeal({ dataDir, client, remoteStorage, targetId: routedTarget?.id, absolute, totalBytes, chunkBytes, totalChunks, phrase, agent, now: options.now }, { archiveId, createdAt, folder, archiveKey, noncePrefix, project: options.project ?? null, startAt: 0, verifiedHeaders: [], reusedChunks: 0 });
+    }
+    finally {
+        zeroize(archiveKey);
+        await lock.release();
+    }
+}
+function isChunkFolderState(state) {
+    return typeof state === "object" && state !== null && state.kind === "chunk-folder";
+}
+async function abandonFolderJournal(dataDir, client, journal, reason) {
+    // Best-effort folder cleanup: every chunk the journal ever named, plus the
+    // sidecar. Deterministic names make the sweep exact — no listing needed.
+    for (let index = 0; index < journal.chunkHeaders.length; index += 1) {
+        await client.deleteObject(`${journal.objectKey}/${chunkObjectName(index)}`).catch(() => undefined);
+    }
+    await client.deleteObject(`${journal.objectKey}/${ENVELOPE_OBJECT}`).catch(() => undefined);
+    await recordAudit(dataDir, "upload.verify", "denied", { archiveId: journal.archiveId, objectKey: journal.objectKey, resumeAbandoned: reason });
+    await shredSpool(dataDir, journal.archiveId);
+}
+/**
+ * The one seal loop both fresh and resumed paths run. `startAt` chunks are
+ * ALREADY verified present in the folder (the resume proved them); the seal
+ * re-produces them CPU-only to advance the whole-object hashes, verifies each
+ * against the journal, and PUTs only what the bucket lacks.
+ */
+async function runChunkSeal(ctx, args) {
+    const config = await readConfig(ctx.dataDir);
+    const recipients = configuredRecipients(config, ctx.phrase);
+    const { tokenize, indexableToken, tokenCapFor } = await import("./search.js");
+    const perChunkTokenCap = Math.max(4000, Math.floor(tokenCapFor(ctx.totalBytes) / 4));
+    const hashers = { plaintext: new StreamingSha256(), stored: new StreamingSha256() };
+    const headers = [];
+    let storedBytes = 0;
+    let heldAtMostBytes = 0;
+    // Uploads ride a small pool: the seal loop stays sequential (it is the CPU
+    // and the nonce discipline), but a sealed chunk does not wait for the wire
+    // before the next one seals. Four in flight bounds peak memory at four
+    // chunks and roughly quarters the wall clock of a lease-per-chunk upload.
+    const UPLOAD_CONCURRENCY = 4;
+    const pending = new Map();
+    const completedUploads = new Set();
+    let watermark = args.startAt;
+    let uploadError = null;
+    let inFlightBytes = 0;
+    // Journal writes are serialized: two concurrent read-modify-write updates
+    // of the spool would lose one of them.
+    let spoolChain = Promise.resolve();
+    const journal = (patch) => {
+        const next = spoolChain.then(async () => { await updateSpool(ctx.dataDir, args.archiveId, patch); });
+        spoolChain = next.catch(() => undefined);
+        return next;
+    };
+    // Seal-time indexing: the seal holds every plaintext slice anyway, so the
+    // tokens are collected here for free — the alternative was uploading the
+    // archive and then downloading it back just to read it again.
+    const tokensByChunk = new Map();
+    const sink = {
+        write: async (stored) => {
+            const index = headers.length;
+            const header = {
+                index,
+                plaintextBytes: stored.length - 16,
+                rawBytes: Math.max(0, Math.min(ctx.chunkBytes, ctx.totalBytes - index * ctx.chunkBytes)),
+                storedBytes: stored.length,
+                sha256: sha256hex(stored),
+                nonce: "", // filled from the seal's own envelope below; the journal needs only the hash
+                final: index === ctx.totalChunks - 1
+            };
+            // The stored-bytes hash belongs to sealChunksToSink: it updates the
+            // injected hasher once per chunk. Updating it here as well was the bug
+            // that had every chunk-folder record carry a double-hashed
+            // ciphertextSha256 — sealing verified, and every later RESTORE refused
+            // the perfectly good bytes as "not the archive that was stored there".
+            storedBytes += stored.length;
+            if (index < args.startAt) {
+                // Already in the bucket, already verified: this re-seal exists only to
+                // advance the hashes. Refusing on any drift is what keeps the resume
+                // on the safe side of the nonce invariant.
+                if (header.sha256 !== args.verifiedHeaders[index].sha256) {
+                    fail("invalid_argument", `Cannot resume the interrupted upload of ${args.folder}: re-sealing chunk ${index} did not reproduce the bytes the bucket already holds. The archive starts over from byte zero with a fresh key.`, { archiveId: args.archiveId });
+                }
+                headers.push(args.verifiedHeaders[index]);
+                return;
+            }
+            // Emission-first: the journal names the chunk BEFORE its PUT can land,
+            // so the bucket can never hold a chunk the journal cannot vouch for.
+            headers.push(header);
+            await journal({ chunkHeaders: [...headers] });
+            if (uploadError)
+                throw uploadError;
+            while (pending.size >= UPLOAD_CONCURRENCY) {
+                await Promise.race(pending.values());
+                if (uploadError)
+                    throw uploadError;
+            }
+            inFlightBytes += stored.length;
+            heldAtMostBytes = Math.max(heldAtMostBytes, inFlightBytes);
+            const task = (async () => {
+                await ctx.client.putObject(`${args.folder}/${chunkObjectName(index)}`, stored);
+                completedUploads.add(index);
+                while (completedUploads.has(watermark))
+                    watermark += 1;
+                await journal({
+                    nextChunkIndex: watermark,
+                    consumedPrefixSha256: hashers.plaintext.digestHex(),
+                    providerState: { kind: "chunk-folder", folder: args.folder, uploaded: watermark }
+                });
+            })().catch((error) => { uploadError = uploadError ?? error; }).finally(() => {
+                inFlightBytes -= stored.length;
+                pending.delete(index);
+            });
+            pending.set(index, task);
+        }
+    };
+    const sealed = await sealChunksToSink({ path: ctx.absolute, end: ctx.totalBytes }, sink, {
+        recipients, archiveId: args.archiveId, adapter: { agent: ctx.agent, version: ADAPTER_VERSION },
+        suite: SEAL_SUITE, chunkBytes: ctx.chunkBytes, archiveKey: args.archiveKey, noncePrefix: args.noncePrefix,
+        hashers, createdAt: args.createdAt,
+        onPlaintext: (chunkIndex, slice) => {
+            let bucket = tokensByChunk.get(chunkIndex);
+            if (!bucket) {
+                bucket = new Set();
+                tokensByChunk.set(chunkIndex, bucket);
+            }
+            // Filtered and budgeted at collection: junk (hex digests, base64
+            // runs) never takes a slot, and the budget scales with the archive —
+            // the flat 4000 starved everything past chunk zero of a 1.7 GB seal.
+            for (const token of tokenize(slice.toString("utf8"))) {
+                if (bucket.size >= perChunkTokenCap)
+                    break;
+                if (!indexableToken(token))
+                    continue;
+                bucket.add(token);
+            }
+        }
+    });
+    // Drain the pool before anything downstream trusts the folder.
+    while (pending.size > 0)
+        await Promise.race(pending.values());
+    await spoolChain;
+    if (uploadError)
+        throw uploadError;
+    // The sidecar: the envelope framed with a sealed identity blob. Folder
+    // names are opaque on purpose, so the names live HERE — project, source
+    // path, date — encrypted under the archive key. A machine holding only the
+    // bucket and the phrase lists the folders, opens each sidecar, and gets the
+    // readable hierarchy back; a provider holding the bucket alone gets noise.
+    const envelope = sealed.envelope;
+    const identity = sealIdentity(args.archiveKey, args.archiveId, {
+        v: 1, project: args.project, sourcePath: ctx.absolute, agent: ctx.agent, createdAt: args.createdAt
+    });
+    await ctx.client.putObject(`${args.folder}/${ENVELOPE_OBJECT}`, frameObject(envelope, identity));
+    // Verification, per chunk, in the provider's own answers: every chunk
+    // present at its recorded size. Byte-level trust is the chunk hash in the
+    // envelope — restore proves it, AEAD enforces it.
+    const problems = [];
+    for (let index = 0; index < envelope.chunks.length; index += 1) {
+        const head = await ctx.client.headObject(`${args.folder}/${chunkObjectName(index)}`);
+        if (!head.exists)
+            problems.push(`chunk ${index} is not in the bucket`);
+        else if (head.bytes !== envelope.chunks[index].storedBytes)
+            problems.push(`chunk ${index} is ${head.bytes} bytes; ${envelope.chunks[index].storedBytes} were sent`);
+        if (problems.length >= 3)
+            break;
+    }
+    if (problems.length > 0) {
+        await recordAudit(ctx.dataDir, "upload.verify", "denied", { archiveId: args.archiveId, objectKey: args.folder, problems: problems.length });
+        fail("ciphertext_integrity_failed", `Refusing to record the chunked archive as durable: ${problems.join("; ")}. The journal was kept; re-running resumes what is already there.`, { archiveId: args.archiveId, objectKey: args.folder });
+    }
+    const now = new Date(ctx.now ?? Date.now()).toISOString();
+    const remote = {
+        provider: ctx.remoteStorage.provider, bucket: ctx.remoteStorage.bucket, objectKey: args.folder,
+        bytes: sealed.storedBytes, checksum: hashers.stored.digestBase64(), verifiedAt: now,
+        layout: { kind: "chunks", chunkCount: envelope.chunks.length },
+        ...(ctx.targetId ? { targetId: ctx.targetId } : {})
+    };
+    const record = {
+        version: 2, id: args.archiveId, createdAt: envelope.manifest.createdAt,
+        source: { path: ctx.absolute, agent: ctx.agent, bytes: ctx.totalBytes, sha256: sealed.originalSha256 },
+        cipher: { algorithm: envelope.suite, ciphertextSha256: sealed.ciphertextSha256, storedBytes: sealed.storedBytes, chunks: envelope.chunks.length },
+        envelope,
+        objectPath: join(config.storage.root, `${args.archiveId}.vlarchive`),
+        remote,
+        offloaded: { at: now, provider: ctx.remoteStorage.provider, bucket: ctx.remoteStorage.bucket, objectKey: args.folder }
+    };
+    await writeRecord(config.storage.root, record);
+    await recordAudit(ctx.dataDir, "archive.create", "allowed", { archiveId: args.archiveId, agent: ctx.agent, bytes: ctx.totalBytes, recipients: envelope.wrappedKeys.length, chunked: true, reused: args.reusedChunks });
+    await recordAudit(ctx.dataDir, "upload.verify", "allowed", { archiveId: args.archiveId, objectKey: args.folder, bytes: sealed.storedBytes, provider: ctx.remoteStorage.provider, chunked: true });
+    await shredSpool(ctx.dataDir, args.archiveId);
+    // The tokens collected during the seal become the archive's index entry —
+    // search knows this session the moment the seal returns, and no machine
+    // ever downloads it back just to read it. Advisory by design: an index
+    // hiccup must never turn a durable archive into a failure.
+    let indexed = false;
+    try {
+        const { indexArchiveTokens } = await import("./search.js");
+        await indexArchiveTokens(ctx.dataDir, ctx.phrase, record, tokensByChunk);
+        indexed = true;
+    }
+    catch { /* the next `index build` re-indexes this archive */ }
+    return { record, folder: args.folder, storedBytes: sealed.storedBytes, chunkCount: envelope.chunks.length, reusedChunks: args.reusedChunks, heldAtMostBytes, indexed };
+}
+/**
+ * Resume: the provider's truth is asked chunk by chunk — HEAD chunk-000000
+ * upward until the first absence — and every present chunk must match its
+ * journaled header's size and hash (hash proven by the re-seal inside
+ * `runChunkSeal`; size and existence proven here, against the bucket).
+ */
+async function resumeChunkFolder(ctx, journal) {
+    const refuse = (why) => fail("invalid_argument", `Cannot resume the interrupted upload of ${journal.objectKey}: ${why}. The archive starts over from byte zero with a fresh key.`, { archiveId: journal.archiveId });
+    if (journal.source.chunkBytes !== ctx.chunkBytes)
+        return refuse("the chunk size changed between builds");
+    if (journal.chunkHeaders.length > ctx.totalChunks)
+        return refuse("the journal names more chunks than this archive has");
+    const noncePrefix = Buffer.from(journal.noncePrefixB64, "base64");
+    if (noncePrefix.length !== 4)
+        return refuse("its nonce prefix is malformed");
+    // The provider's truth: contiguous presence from zero. A gap ends the
+    // verified range — chunks past a gap are unreachable by a contiguous
+    // restore anyway, and re-PUTting a verified re-seal of chunk k is
+    // invariant-safe (identical bytes under the same nonce).
+    let present = 0;
+    const verifiedHeaders = [];
+    while (present < journal.chunkHeaders.length) {
+        const head = await ctx.client.headObject(`${journal.objectKey}/${chunkObjectName(present)}`);
+        if (!head.exists)
+            break;
+        if (head.bytes !== journal.chunkHeaders[present].storedBytes) {
+            return refuse(`the bucket's chunk ${present} is ${head.bytes} bytes but the journal recorded ${journal.chunkHeaders[present].storedBytes} — the folder holds something this vault did not put there`);
+        }
+        verifiedHeaders.push(journal.chunkHeaders[present]);
+        present += 1;
+    }
+    const archiveKey = unwrapSpoolKey(journal, { phrase: ctx.phrase });
+    try {
+        await recordAudit(ctx.dataDir, "upload.verify", "allowed", { archiveId: journal.archiveId, objectKey: journal.objectKey, resumedAtChunk: present });
+        return await runChunkSeal(ctx, {
+            archiveId: journal.archiveId, createdAt: journal.createdAt, folder: journal.objectKey,
+            archiveKey, noncePrefix, project: null, startAt: present, verifiedHeaders, reusedChunks: present
+        });
+    }
+    finally {
+        zeroize(archiveKey);
+    }
+}
+function sealIdentity(archiveKey, archiveId, identity) {
+    const nonce = randomBytes(12);
+    const cipher = aeadCipher(SEAL_SUITE, archiveKey, nonce);
+    cipher.setAAD(Buffer.from(`vaultline-folder-identity:${archiveId}`, "utf8"));
+    const body = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(identity), "utf8")), cipher.final(), cipher.getAuthTag()]);
+    return Buffer.concat([nonce, body]);
+}
+/** Opens a sidecar's identity with the unwrapped archive key. */
+export function openIdentity(archiveKey, archiveId, blob) {
+    if (blob.length < 12 + 16)
+        fail("invalid_argument", "This sidecar carries no identity");
+    const nonce = blob.subarray(0, 12);
+    const body = blob.subarray(12);
+    const decipher = aeadDecipher(SEAL_SUITE, archiveKey, nonce);
+    decipher.setAAD(Buffer.from(`vaultline-folder-identity:${archiveId}`, "utf8"));
+    decipher.setAuthTag(body.subarray(body.length - 16));
+    try {
+        const plain = Buffer.concat([decipher.update(body.subarray(0, body.length - 16)), decipher.final()]);
+        return JSON.parse(plain.toString("utf8"));
+    }
+    catch {
+        return fail("invalid_argument", "The sidecar's identity does not open for this archive — wrong key, or a sidecar moved between folders.");
+    }
+}
+/** Fetches a chunked remote back into one ciphertext buffer, hash-checked per chunk. */
+export async function fetchChunkFolder(client, remote, expected) {
+    if (remote.layout?.kind !== "chunks")
+        fail("invalid_argument", "This remote is not a chunk folder");
+    const parts = [];
+    for (let index = 0; index < remote.layout.chunkCount; index += 1) {
+        const body = await client.getObject(`${remote.objectKey}/${chunkObjectName(index)}`);
+        const header = expected.chunks[index];
+        if (header && sha256hex(body) !== header.sha256) {
+            fail("ciphertext_integrity_failed", `Chunk ${index} fetched from the bucket does not match its recorded hash`, { objectKey: remote.objectKey });
+        }
+        parts.push(body);
+    }
+    return Buffer.concat(parts);
+}
+/** Deletes a chunked remote: every chunk object plus the envelope sidecar. */
+export async function deleteChunkFolder(client, remote) {
+    if (remote.layout?.kind !== "chunks")
+        fail("invalid_argument", "This remote is not a chunk folder");
+    for (let index = 0; index < remote.layout.chunkCount; index += 1) {
+        await client.deleteObject(`${remote.objectKey}/${chunkObjectName(index)}`);
+    }
+    await client.deleteObject(`${remote.objectKey}/${ENVELOPE_OBJECT}`);
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};