sealkeep 0.5.0

package/dist/src/stream-to-cloud.js

@@ -0,0 +1,820 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { open, stat } from "node:fs/promises";
+import { gzipSync } from "node:zlib";
+import { join, resolve } from "node:path";
+import { fail, isVaultlineError } 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 { compositeChecksum } from "./providers/s3.js";
+import { acquireSpoolLock, createSpool, findSpoolForSource, shredSpool, unwrapSpoolKey, updateSpool } from "./spool.js";
+import { DEFAULT_CHUNK_BYTES, ENVELOPE_VERSION, KEY_BYTES, StreamingSha256, TAG_BYTES, chunkAad, chunkNonce, hashFileRange, sealChunksToSink, wrapAll, zeroize } from "../packages/vaultline-crypto/src/index.js";
+// The package's index deliberately exports formats and flows, not raw AEAD
+// primitives. Resuming needs exactly one primitive operation the flows do not
+// expose: re-producing a single chunk's ciphertext to prove the source still
+// seals to the bytes the provider already holds. Reaching into the package for
+// that beats re-implementing the cipher setup here and drifting from it.
+import { aeadCipher, aeadDecipher } from "../packages/vaultline-crypto/src/aead.js";
+const STREAMABLE = new Set(["s3", "r2", "b2", "gcs"]);
+const SEAL_SUITE = "chacha20-poly1305";
+const sha256hex = (input) => createHash("sha256").update(input).digest("hex");
+/** SHA-256 of zero bytes — what `consumedPrefixSha256` means before any chunk is confirmed. Derived, not pasted, so it cannot rot. */
+const EMPTY_PREFIX_SHA256 = createHash("sha256").digest("hex");
+/**
+ * A tiny handoff channel: the seal loop pushes stored chunks, the provider
+ * stream consumes them, and neither side ever holds more than `capacity`
+ * chunks. If the consumer dies, `push` throws its error into the seal loop so
+ * the file handle closes through the normal error path instead of hanging.
+ */
+class ChunkChannel {
+    capacity;
+    buffered = [];
+    done = false;
+    error = null;
+    wakeConsumer = null;
+    wakeProducer = null;
+    constructor(capacity = 4) {
+        this.capacity = capacity;
+    }
+    async push(chunk) {
+        if (this.error)
+            throw this.error;
+        while (this.buffered.length >= this.capacity) {
+            await new Promise((wake) => { this.wakeProducer = wake; });
+            if (this.error)
+                throw this.error;
+        }
+        this.buffered.push(chunk);
+        this.wakeConsumer?.();
+        this.wakeConsumer = null;
+    }
+    close() {
+        this.done = true;
+        this.wakeConsumer?.();
+        this.wakeConsumer = null;
+    }
+    failWith(error) {
+        this.error = error;
+        this.done = true;
+        this.wakeConsumer?.();
+        this.wakeConsumer = null;
+        this.wakeProducer?.();
+        this.wakeProducer = null;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            if (this.buffered.length > 0) {
+                const next = this.buffered.shift();
+                this.wakeProducer?.();
+                this.wakeProducer = null;
+                yield next;
+                continue;
+            }
+            if (this.error)
+                throw this.error;
+            if (this.done)
+                return;
+            await new Promise((wake) => { this.wakeConsumer = wake; });
+        }
+    }
+}
+function interpretProviderState(state) {
+    if (typeof state !== "object" || state === null)
+        return null;
+    const record = state;
+    if (typeof record.uploadId === "string" && Array.isArray(record.parts)) {
+        const s3 = state;
+        // Only a prefix of FULL parts is a resumable seed: the S3 client refuses a
+        // short non-final part because the resume offset must land on a part
+        // boundary. The final short part of a finished stream may appear in the
+        // last onState — trim it (and count only what remains as confirmed for
+        // resume purposes) so what lands in the journal is always seedable. The
+        // trimmed tail part is not lost: a resume re-seals its chunks and S3
+        // overwrites the same part number with the identical bytes.
+        const partBytes = s3.parts[0]?.bytes ?? 0;
+        let full = s3.parts.length;
+        while (full > 0 && s3.parts[full - 1].bytes !== partBytes)
+            full -= 1;
+        const usable = s3.parts.slice(0, full);
+        return {
+            confirmedBytes: usable.reduce((sum, part) => sum + part.bytes, 0),
+            journalable: { uploadId: s3.uploadId, parts: usable },
+            s3UploadId: s3.uploadId
+        };
+    }
+    if (typeof record.session === "string" && typeof record.confirmedBytes === "number") {
+        const gcs = state;
+        return { confirmedBytes: gcs.confirmedBytes, journalable: gcs };
+    }
+    return null;
+}
+/**
+ * True for a failure that means the journaled state can never be resumed —
+ * as opposed to a transient failure, after which the journal is exactly what
+ * the next attempt needs. The distinction decides whether the journal is
+ * shredded (and the seal restarted fresh) or kept for another try:
+ * - "Cannot resume …": the provider layer's own entry refusals, and this
+ *   module's pre-flight refusals, all thrown before a data byte moved.
+ * - "resumable session …": a GCS session that is finalized, expired, or
+ *   answering the status query with an error — dead either way.
+ * - "NoSuchUpload": the S3 multipart the journal references was aborted or
+ *   completed; its seeded parts do not exist anymore.
+ * Anything else (network drop, full disk, a provider 5xx) keeps the journal.
+ */
+function resumeRefused(error) {
+    if (!isVaultlineError(error))
+        return false;
+    return /cannot resume/i.test(error.message) || /resumable session/.test(error.message) || /NoSuchUpload/.test(error.message);
+}
+/**
+ * Kills whatever half-object the provider still holds for a journal that will
+ * never finish. S3-family multiparts must be aborted explicitly or their
+ * invisible parts bill forever; GCS resumable sessions need no call — an
+ * unfinished session expires on its own within a week and holds no visible
+ * object until finalized. Best-effort on purpose: abandoning must not fail
+ * because the provider is unreachable, and a missed abort costs money, not
+ * correctness.
+ */
+async function abortProviderState(client, objectKey, progress) {
+    if (progress?.s3UploadId && client.abortMultipart) {
+        await client.abortMultipart(objectKey, progress.s3UploadId).catch(() => undefined);
+    }
+}
+/** Aborts the remote state, writes the one honest audit line, and shreds the journal. */
+async function abandonJournal(dataDir, client, journal, reason) {
+    await abortProviderState(client, journal.objectKey, interpretProviderState(journal.providerState));
+    await recordAudit(dataDir, "upload.verify", "denied", { archiveId: journal.archiveId, objectKey: journal.objectKey, resumeAbandoned: reason });
+    await shredSpool(dataDir, journal.archiveId);
+}
+/**
+ * After an archive of this source lands, any journal still naming the source
+ * describes an upload nobody will ever finish — an older crashed attempt, or
+ * one superseded by --fresh. Left alone it would win `findSpoolForSource` on
+ * some later run and resurrect a dead upload as a duplicate archive.
+ */
+async function sweepStaleJournals(dataDir, client, sourcePath) {
+    for (;;) {
+        const stale = await findSpoolForSource(dataDir, sourcePath);
+        if (!stale)
+            return;
+        await abandonJournal(dataDir, client, stale, "superseded: a completed archive of this source landed");
+    }
+}
+export async function sealArchiveToCloud(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; streaming them to a bucket would upload your transcripts unencrypted. Use a sealed vault for cloud archiving.");
+    }
+    const remoteStorage = config.remoteStorage ?? fail("storage_not_configured", "No remote target configured. Run: sealkeep storage configure ...");
+    if (!STREAMABLE.has(remoteStorage.provider)) {
+        fail("invalid_argument", remoteStorage.provider === "vaultline"
+            ? "Managed storage cannot take a streamed seal yet: the control plane signs one upload of a known size, and a stream's size is not known until it ends. Seal locally and let the upload pass offload it — same end state, one extra local write."
+            : `Streaming seals are not supported for ${remoteStorage.provider} yet; seal locally and upload.`);
+    }
+    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 rawClient = options.client ?? await uploadClientFromStore(dataDir, config.vaultId, remoteStorage);
+    if (!("uploadStream" in rawClient) || typeof rawClient.uploadStream !== "function") {
+        fail("invalid_argument", `The ${remoteStorage.provider} client cannot stream uploads`);
+    }
+    const client = rawClient;
+    const shared = { dataDir, client, config, remoteStorage, absolute, totalBytes: source.size, phrase, agent, now: options.now };
+    // Journal triage. Each pass either resumes the newest journal for this
+    // source or abandons it with the reason and looks again, so a stack of
+    // crashed attempts drains to the one worth continuing — or to none.
+    for (;;) {
+        const journal = await findSpoolForSource(dataDir, absolute);
+        if (!journal)
+            break;
+        if (options.resume === false) {
+            await abandonJournal(dataDir, client, journal, "a fresh start was requested (--fresh)");
+            continue;
+        }
+        if (journal.provider !== remoteStorage.provider || journal.bucket !== remoteStorage.bucket
+            || journal.source.totalBytes !== source.size
+            || !Number.isInteger(journal.source.chunkBytes) || journal.source.chunkBytes <= 0
+            || !Number.isInteger(journal.nextChunkIndex) || journal.nextChunkIndex < 0) {
+            await abandonJournal(dataDir, client, journal, "the source file or the storage target is no longer the one the journal describes");
+            continue;
+        }
+        // THE SAFETY GATE, before anything else: the same (archiveKey,
+        // noncePrefix, chunkIndex) triple must never encrypt two different
+        // plaintexts, and every resume decision must be provably on the safe side
+        // of that line. Chunks below `nextChunkIndex` were already encrypted and
+        // handed over under this journal's key, so this seal may only continue if
+        // the bytes they covered are still byte-for-byte the bytes on disk. Hash
+        // the consumed prefix and compare; on any mismatch the journal — key,
+        // nonce prefix, provider session, all of it — is dead, and the archive
+        // starts over with a fresh identity.
+        const consumed = Math.min(journal.nextChunkIndex * journal.source.chunkBytes, source.size);
+        const gate = await hashFileRange(absolute, 0, consumed);
+        if (gate.sha256 !== journal.consumedPrefixSha256) {
+            await abandonJournal(dataDir, client, journal, "the source bytes under the already-uploaded chunks changed, so the sealed prefix no longer describes this file");
+            continue;
+        }
+        // One process per journal, held across the whole resume including its
+        // abandon path — a second process asking meanwhile is told to wait.
+        const lock = await acquireSpoolLock(dataDir, journal.archiveId, { now: options.now });
+        try {
+            return await resumeSeal(shared, journal);
+        }
+        catch (error) {
+            if (!resumeRefused(error))
+                throw error;
+            await abandonJournal(dataDir, client, journal, error instanceof Error ? error.message : "the journaled provider state was not resumable");
+            continue;
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    return freshSeal(shared);
+}
+/**
+ * The seal↔upload bridge both the fresh and the resumed path run: seal chunks
+ * into the channel, stream the channel into the provider, and journal every
+ * durability point the provider reports.
+ */
+async function streamSealCore(ctx, args) {
+    const channel = new ChunkChannel();
+    let heldAtMostBytes = 0;
+    let cumStored = args.prefixStoredBytes;
+    const producedHeaders = [];
+    // One snapshot per produced chunk: the exact journal fields that describe
+    // "everything up to and including this chunk". `onState` picks the highest
+    // snapshot the provider's confirmed bytes fully cover — never a partial one,
+    // so `nextChunkIndex` only ever names chunks that are durably placed.
+    const snapshots = [];
+    const sink = {
+        write: async (stored) => {
+            const index = args.firstChunkIndex + producedHeaders.length;
+            const rawStart = index * args.chunkBytes;
+            // Derived from first principles rather than read back out of
+            // sealChunksToSink, which only reveals its headers when the whole seal
+            // resolves — too late for a journal that must describe chunks as they
+            // leave. Every field is forced by the format: plaintextBytes is the
+            // stored length minus the tag, the nonce is the prefix plus the index,
+            // final is a position.
+            const header = {
+                index,
+                plaintextBytes: stored.length - TAG_BYTES,
+                rawBytes: Math.max(0, Math.min(args.chunkBytes, ctx.totalBytes - rawStart)),
+                storedBytes: stored.length,
+                sha256: sha256hex(stored),
+                nonce: chunkNonce(args.noncePrefix, index).toString("base64"),
+                final: index === args.totalChunks - 1
+            };
+            const first = index === args.firstChunkIndex;
+            if (first && args.skipStoredBytes > 0 && header.sha256 !== args.spliceGuardSha256) {
+                // The provider holds a prefix of this very chunk from the interrupted
+                // run. If re-sealing it does not reproduce those bytes exactly,
+                // splicing would corrupt the object AND re-encrypt a different
+                // plaintext under an already-exposed nonce — so the refusal happens
+                // here, before a single byte of it reaches the channel.
+                fail("invalid_argument", `Cannot resume the interrupted upload of ${args.objectKey}: re-sealing chunk ${index} did not reproduce the bytes the provider already holds, so continuing would corrupt the stored object. The archive starts over from byte zero with a fresh key.`, { archiveId: args.archiveId });
+            }
+            if (args.bodyHasher) {
+                // The whole-body manifest hash covers each chunk's compressed slice,
+                // which only exists inside the seal loop. Opening the chunk we sealed
+                // a microsecond ago recovers it without a second gzip pass.
+                args.bodyHasher.update(openStoredChunk(args, header, stored));
+            }
+            heldAtMostBytes = Math.max(heldAtMostBytes, stored.length);
+            cumStored += stored.length;
+            producedHeaders.push(header);
+            snapshots.push({
+                cumStored,
+                // The final chunk's live state would carry the source's last
+                // totalBytes % 64 bytes RAW in its unprocessed tail — a plaintext
+                // slice sitting in a journal on disk. After the final chunk no state
+                // is ever resumed INTO (nothing further is absorbed), so the finished
+                // digests are journaled instead; every non-final boundary is 64-aligned
+                // (chunkBytes is a multiple of 64) and its tail is provably empty.
+                plaintext: header.final ? doneDigestState(args.hashers.plaintext) : args.hashers.plaintext.exportState(),
+                stored: header.final ? doneDigestState(args.hashers.stored) : args.hashers.stored.exportState(),
+                // The plaintext hasher has absorbed exactly the source bytes up to
+                // this chunk boundary, so its (non-destructive) digest IS the consumed
+                // prefix hash the safety gate will verify on the next resume.
+                consumedPrefix: args.hashers.plaintext.digestHex()
+            });
+            // THE ORDER THAT CLOSES THE EMISSION RACE: the journal learns this
+            // chunk's header BEFORE the chunk can reach the provider. A crash
+            // between a provider PUT and a journal write can therefore only ever
+            // leave the provider holding chunks the journal ALREADY describes —
+            // which is exactly what lets a resume verify, byte for byte, everything
+            // the provider might hold before re-encrypting anything.
+            await updateSpool(ctx.dataDir, args.archiveId, { chunkHeaders: [...args.prefixHeaders, ...producedHeaders] });
+            await channel.push(first && args.skipStoredBytes > 0 ? stored.subarray(args.skipStoredBytes) : stored);
+        }
+    };
+    const onState = async (state) => {
+        const progress = interpretProviderState(state);
+        if (!progress)
+            return;
+        let advanced = 0;
+        while (advanced < snapshots.length && snapshots[advanced].cumStored <= progress.confirmedBytes)
+            advanced += 1;
+        const at = advanced > 0 ? snapshots[advanced - 1] : null;
+        await updateSpool(ctx.dataDir, args.archiveId, {
+            nextChunkIndex: args.firstChunkIndex + advanced,
+            consumedPrefixSha256: at ? at.consumedPrefix : args.consumedPrefixFallback,
+            hashState: at ? { plaintext: at.plaintext, stored: at.stored } : args.hashStateFallback,
+            providerState: progress.journalable
+        });
+    };
+    const sealPromise = sealChunksToSink({ path: ctx.absolute, start: args.firstChunkIndex * args.chunkBytes, end: ctx.totalBytes }, sink, {
+        recipients: args.recipients, archiveId: args.archiveId, adapter: { agent: ctx.agent, version: ADAPTER_VERSION },
+        suite: args.suite, chunkBytes: args.chunkBytes, archiveKey: args.archiveKey, noncePrefix: args.noncePrefix,
+        firstChunkIndex: args.firstChunkIndex, hashers: args.hashers,
+        ...(args.createdAt ? { createdAt: args.createdAt } : {})
+    }).then((sealed) => { channel.close(); return sealed; }, (error) => { channel.failWith(error); throw error; });
+    const uploadPromise = ctx.client.uploadStream(args.objectKey, channel, { ...(args.resume === null ? {} : { resume: args.resume }), onState })
+        .catch((error) => { channel.failWith(error); throw error; });
+    const [sealed, uploaded] = await Promise.all([sealPromise, uploadPromise]);
+    return { sealed, uploaded, heldAtMostBytes };
+}
+/**
+ * A finished hasher's journal form: digests only, no internal state, no tail.
+ * Recognised (and refused as a resume source) by its `alg` marker.
+ */
+function doneDigestState(hasher) {
+    return JSON.stringify({ alg: "sha256-done", hex: hasher.digestHex(), b64: hasher.digestBase64() });
+}
+/** Opens one just-sealed chunk back to its compressed slice. Never fails for bytes this process produced; a failure is reported as the internal wrongness it is. */
+function openStoredChunk(args, header, stored) {
+    const decipher = aeadDecipher(args.suite, args.archiveKey, chunkNonce(args.noncePrefix, header.index));
+    decipher.setAAD(chunkAad({ archiveId: args.archiveId, suite: args.suite, index: header.index, totalChunks: args.totalChunks, plaintextBytes: header.plaintextBytes, final: header.final }));
+    decipher.setAuthTag(stored.subarray(stored.length - TAG_BYTES));
+    try {
+        return Buffer.concat([decipher.update(stored.subarray(0, stored.length - TAG_BYTES)), decipher.final()]);
+    }
+    catch {
+        return fail("internal", `Chunk ${header.index} failed to open immediately after it was sealed; refusing to continue with a cipher that disagrees with itself.`, { archiveId: args.archiveId });
+    }
+}
+/**
+ * The same verification `uploadArchive` performs, in the provider's own
+ * checksum language — a streamed object earns "durable" the same way a copied
+ * one does, or the record is not written at all.
+ */
+async function verifyAndRecord(ctx, flight) {
+    const { archiveId, objectKey, uploaded } = flight;
+    const head = await ctx.client.head({ objectKey });
+    const problems = [];
+    if (!head.exists)
+        problems.push("the provider does not report the object as present");
+    if (head.bytes !== uploaded.bytes)
+        problems.push(`the provider stored ${head.bytes} bytes; ${uploaded.bytes} were sent`);
+    if (uploaded.remoteChecksum === null) {
+        // A resumed GCS upload cannot roll the provider-language MD5 over bytes an
+        // earlier process sent, so this run has no provider checksum to compare
+        // (src/providers/gcs.ts returns null exactly then). The whole-object proof
+        // is the byte count above plus our own resumable SHA-256 over every stored
+        // byte — the same digest the record carries as `remote.checksum` — whose
+        // prefix state was journaled only after the provider confirmed those bytes.
+    }
+    else if (head.checksum === undefined)
+        problems.push("the provider did not report a stored checksum, so the bytes it holds cannot be proven");
+    else if (head.checksum !== uploaded.remoteChecksum)
+        problems.push(`the provider's stored checksum ${head.checksum} does not match the ${uploaded.remoteChecksum} we streamed`);
+    if (flight.wholeStoredBytes !== uploaded.bytes)
+        problems.push(`the seal produced ${flight.wholeStoredBytes} bytes but ${uploaded.bytes} reached the provider`);
+    if (problems.length > 0) {
+        await recordAudit(ctx.dataDir, "upload.verify", "denied", { archiveId, objectKey, problems: problems.length });
+        // No record, and no lingering halves either: the unverifiable remote state
+        // is torn down and the journal shredded, so the next attempt starts clean
+        // instead of resuming into an object verification already refused.
+        await abortProviderState(ctx.client, objectKey, flight.progress);
+        await shredSpool(ctx.dataDir, archiveId);
+        fail("ciphertext_integrity_failed", `Refusing to record the streamed archive as durable: ${problems.join("; ")}. Nothing was written locally; re-run the archive.`, { archiveId, objectKey });
+    }
+    const now = new Date(ctx.now ?? Date.now()).toISOString();
+    // `remote.checksum` stays OUR whole-object stored SHA-256 (base64), resumed
+    // or not — the resumable hasher covered every stored byte across processes.
+    const remote = { provider: ctx.remoteStorage.provider, bucket: ctx.remoteStorage.bucket, objectKey, bytes: flight.wholeStoredBytes, checksum: flight.hashers.stored.digestBase64(), verifiedAt: now };
+    const record = {
+        version: 2, id: archiveId, createdAt: flight.envelope.manifest.createdAt,
+        source: { path: ctx.absolute, agent: ctx.agent, bytes: ctx.totalBytes, sha256: flight.hashers.plaintext.digestHex() },
+        cipher: { algorithm: flight.envelope.suite, ciphertextSha256: flight.hashers.stored.digestHex(), storedBytes: flight.wholeStoredBytes, chunks: flight.envelope.chunks.length },
+        envelope: flight.envelope,
+        // Born offloaded: this path names where the blob would live, and the
+        // offloaded marker says truthfully that no file is there — the same state
+        // an uploaded-then-offloaded archive reaches, arrived at without the detour.
+        objectPath: join(ctx.config.storage.root, `${archiveId}.vlarchive`),
+        remote,
+        offloaded: { at: now, provider: ctx.remoteStorage.provider, bucket: ctx.remoteStorage.bucket, objectKey }
+    };
+    await writeRecord(ctx.config.storage.root, record);
+    await recordAudit(ctx.dataDir, "archive.create", "allowed", { archiveId, agent: ctx.agent, bytes: ctx.totalBytes, recipients: flight.envelope.wrappedKeys.length, streamed: true, ...(flight.resumed ? { resumed: true } : {}) });
+    await recordAudit(ctx.dataDir, "upload.verify", "allowed", { archiveId, objectKey, bytes: flight.wholeStoredBytes, provider: ctx.remoteStorage.provider, streamed: true, ...(flight.resumed ? { resumed: true } : {}) });
+    await shredSpool(ctx.dataDir, archiveId);
+    await sweepStaleJournals(ctx.dataDir, ctx.client, ctx.absolute);
+    return { record, objectKey, storedBytes: flight.wholeStoredBytes, heldAtMostBytes: flight.heldAtMostBytes };
+}
+/** A brand-new streamed seal: fresh identity, fresh key, journal from byte zero. */
+async function freshSeal(ctx) {
+    const archiveId = randomUUID();
+    const prefix = ctx.remoteStorage.prefix.replace(/^\/+|\/+$/g, "");
+    const objectKey = `${prefix}/${archiveId}.vlarchive`;
+    const chunkBytes = DEFAULT_CHUNK_BYTES;
+    const totalChunks = Math.max(1, Math.ceil(ctx.totalBytes / chunkBytes));
+    const recipients = configuredRecipients(ctx.config, ctx.phrase);
+    // The key is minted here, not inside the seal, because the journal must
+    // carry it (wrapped for the same recipients an envelope would name) BEFORE
+    // the first byte goes out — a journal written any later could describe
+    // uploaded chunks that no surviving key can ever finish.
+    const archiveKey = randomBytes(KEY_BYTES);
+    const noncePrefix = randomBytes(4);
+    const lock = await acquireSpoolLock(ctx.dataDir, archiveId, { now: ctx.now });
+    try {
+        const hashers = { plaintext: new StreamingSha256(), stored: new StreamingSha256() };
+        const hashStateInit = { plaintext: hashers.plaintext.exportState(), stored: hashers.stored.exportState() };
+        await createSpool(ctx.dataDir, {
+            archiveId, suite: SEAL_SUITE, provider: ctx.remoteStorage.provider, bucket: ctx.remoteStorage.bucket, objectKey,
+            source: { path: ctx.absolute, totalBytes: ctx.totalBytes, chunkBytes },
+            wrappedKeys: wrapAll(archiveKey, recipients, SEAL_SUITE, archiveId),
+            noncePrefixB64: noncePrefix.toString("base64"),
+            nextChunkIndex: 0,
+            consumedPrefixSha256: EMPTY_PREFIX_SHA256,
+            chunkHeaders: [],
+            hashState: hashStateInit,
+            providerState: null
+        }, { now: ctx.now });
+        const core = await streamSealCore(ctx, {
+            objectKey, archiveId, suite: SEAL_SUITE, archiveKey, noncePrefix, recipients, chunkBytes, totalChunks,
+            firstChunkIndex: 0, skipStoredBytes: 0, spliceGuardSha256: null, prefixHeaders: [], prefixStoredBytes: 0,
+            hashers, hashStateFallback: hashStateInit, consumedPrefixFallback: EMPTY_PREFIX_SHA256,
+            bodyHasher: null, resume: null
+        });
+        return await verifyAndRecord(ctx, {
+            archiveId, objectKey, envelope: core.sealed.envelope, wholeStoredBytes: core.sealed.storedBytes,
+            uploaded: core.uploaded, hashers, heldAtMostBytes: core.heldAtMostBytes, resumed: false,
+            progress: null
+        });
+    }
+    finally {
+        zeroize(archiveKey);
+        await lock.release();
+    }
+}
+/** `FileHandle.read` may come up short; a chunk boundary is not a suggestion. */
+async function readExactly(handle, into, length, position) {
+    let filled = 0;
+    while (filled < length) {
+        const { bytesRead } = await handle.read(into, filled, length - filled, position + filled);
+        if (bytesRead === 0)
+            fail("source_unreadable", `Expected ${length} bytes at offset ${position}; the file ended after ${filled}`, { position });
+        filled += bytesRead;
+    }
+    return into.subarray(0, length);
+}
+/**
+ * Continues an interrupted streamed seal from its journal.
+ *
+ * THE INVARIANT this function exists to uphold: the same (archiveKey,
+ * noncePrefix, chunkIndex) triple must never encrypt two different plaintexts.
+ * Ciphertext can reach the provider AHEAD of any journal write, so the bound
+ * on "what may already be out there" is never the journal's cursor — it is
+ * the PROVIDER'S OWN ANSWER (ListParts for a multipart, the session status
+ * query for GCS), and the journal's emission-ordered chunk headers must vouch
+ * for every byte of it:
+ *
+ * 1. Headers are journaled at EMISSION, before a chunk can leave (see the
+ *    sink), so the provider can never hold a chunk the journal cannot name.
+ *    A provider frontier past the journaled headers is therefore tampering or
+ *    corruption — refused, remote state aborted, fresh key.
+ * 2. Every chunk inside the provider's frontier is re-sealed locally (read,
+ *    gzip, encrypt — CPU only) and must reproduce its recorded ciphertext
+ *    hash exactly; for S3-family, each provider-held part's ETag must also
+ *    equal the MD5 of the re-sealed bytes, proving the bucket holds OUR bytes
+ *    and not some other write. Any mismatch — including a source that changed
+ *    anywhere under the held range — refuses before a single byte is pushed.
+ * 3. The whole-object hashers are REBUILT during that verification walk, so a
+ *    resume needs nothing from the journaled hash state — the provider's
+ *    frontier may be behind or ahead of the journal's cursor and the hashes
+ *    are still exactly right.
+ * 4. A journal whose headers cover the whole archive is checked against a
+ *    HEAD of the object first: a crash after completion but before the record
+ *    write is recovered as the finished object it is, not re-uploaded.
+ */
+async function resumeSeal(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 });
+    const chunkBytes = journal.source.chunkBytes;
+    const totalChunks = Math.max(1, Math.ceil(ctx.totalBytes / chunkBytes));
+    if (journal.chunkHeaders.length > totalChunks)
+        return refuse("the journal names more chunks than this archive has");
+    const cumStoredAt = [0];
+    for (const header of journal.chunkHeaders)
+        cumStoredAt.push(cumStoredAt[cumStoredAt.length - 1] + header.storedBytes);
+    const headersTotal = cumStoredAt[cumStoredAt.length - 1];
+    const journaled = interpretProviderState(journal.providerState);
+    const noncePrefix = Buffer.from(journal.noncePrefixB64, "base64");
+    if (noncePrefix.length !== 4)
+        return refuse("its nonce prefix is malformed");
+    // The wrong phrase must surface as the wrong phrase — silently "resuming" by
+    // starting a fresh seal would mint an archive the real phrase cannot open.
+    const archiveKey = unwrapSpoolKey(journal, { phrase: ctx.phrase });
+    try {
+        const suite = journal.suite;
+        const recipients = configuredRecipients(ctx.config, ctx.phrase);
+        /**
+         * Re-seals chunks [0, count) from the CURRENT source, verifying each
+         * against the journaled header — and, when the S3 part map is known,
+         * verifying each provider-held part's ETag against the MD5 of the very
+         * bytes being re-produced. Returns everything the rest of the resume
+         * needs: rebuilt whole-object hashers, the compressed-body hash, the
+         * verified headers, and the per-part checksums a seeded resume must carry.
+         */
+        const reproducePrefix = async (count, trueParts, feedPartialTo = 0) => {
+            const hashers = { plaintext: new StreamingSha256(), stored: new StreamingSha256() };
+            const bodyHasher = createHash("sha256");
+            const prefixHeaders = [];
+            let prefixStoredBytes = 0;
+            let prefixBodyBytes = 0;
+            let heldAtMostBytes = 0;
+            // Part-boundary bookkeeping for the ETag proof and the reseeded checksums.
+            let partIndex = 0;
+            let partHash = trueParts ? createHash("md5") : null;
+            let partSha = trueParts ? createHash("sha256") : null;
+            let partFilled = 0;
+            const partChecksums = [];
+            const feedPart = (bytes) => {
+                if (!trueParts)
+                    return;
+                let offset = 0;
+                while (offset < bytes.length && partIndex < trueParts.length) {
+                    const want = trueParts[partIndex].bytes - partFilled;
+                    const piece = bytes.subarray(offset, offset + Math.min(want, bytes.length - offset));
+                    partHash.update(piece);
+                    partSha.update(piece);
+                    partFilled += piece.length;
+                    offset += piece.length;
+                    if (partFilled === trueParts[partIndex].bytes) {
+                        const etag = partHash.digest("hex");
+                        if (trueParts[partIndex].etag !== "" && etag !== trueParts[partIndex].etag) {
+                            refuse(`the provider's part ${trueParts[partIndex].partNumber} does not contain the bytes this vault sealed — the stored object cannot be trusted`);
+                        }
+                        partChecksums.push(partSha.digest("base64"));
+                        partIndex += 1;
+                        partHash = createHash("md5");
+                        partSha = createHash("sha256");
+                        partFilled = 0;
+                    }
+                }
+            };
+            if (count > 0 || (feedPartialTo > 0 && trueParts)) {
+                const handle = await open(ctx.absolute, "r");
+                try {
+                    const buffer = Buffer.allocUnsafe(Math.min(chunkBytes, Math.max(ctx.totalBytes, 1)));
+                    for (let index = 0; index < count; index += 1) {
+                        const want = Math.max(0, Math.min(chunkBytes, ctx.totalBytes - index * chunkBytes));
+                        const slice = want === 0 ? buffer.subarray(0, 0) : await readExactly(handle, buffer, want, index * chunkBytes);
+                        const packed = gzipSync(slice, { level: 6 });
+                        const final = index === totalChunks - 1;
+                        const cipher = aeadCipher(suite, archiveKey, chunkNonce(noncePrefix, index));
+                        cipher.setAAD(chunkAad({ archiveId: journal.archiveId, suite, index, totalChunks, plaintextBytes: packed.length, final }));
+                        const stored = Buffer.concat([cipher.update(packed), cipher.final(), cipher.getAuthTag()]);
+                        const digest = sha256hex(stored);
+                        if (digest !== journal.chunkHeaders[index].sha256) {
+                            refuse(`re-sealing chunk ${index} did not reproduce the bytes already sent, so the source changed under the uploaded range`);
+                        }
+                        hashers.plaintext.update(slice);
+                        hashers.stored.update(stored);
+                        bodyHasher.update(packed);
+                        feedPart(stored);
+                        prefixBodyBytes += packed.length;
+                        prefixStoredBytes += stored.length;
+                        heldAtMostBytes = Math.max(heldAtMostBytes, stored.length);
+                        prefixHeaders.push({ index, plaintextBytes: packed.length, rawBytes: slice.length, storedBytes: stored.length, sha256: digest, nonce: chunkNonce(noncePrefix, index).toString("base64"), final });
+                    }
+                    // A provider part can straddle the frontier into the NEXT chunk —
+                    // the one the streamed tail will re-send from `skip`. Its bytes up
+                    // to the frontier must still flow through the part hashes, or the
+                    // straddling part could never be seeded with a real checksum and a
+                    // verified ETag. The chunk is re-sealed and header-verified exactly
+                    // like the ones before it, but it joins neither the prefix headers
+                    // nor the whole-object hashers — the streamed tail owns it.
+                    if (feedPartialTo > 0 && trueParts && count < journal.chunkHeaders.length) {
+                        const index = count;
+                        const want = Math.max(0, Math.min(chunkBytes, ctx.totalBytes - index * chunkBytes));
+                        const slice = want === 0 ? buffer.subarray(0, 0) : await readExactly(handle, buffer, want, index * chunkBytes);
+                        const packed = gzipSync(slice, { level: 6 });
+                        const final = index === totalChunks - 1;
+                        const cipher = aeadCipher(suite, archiveKey, chunkNonce(noncePrefix, index));
+                        cipher.setAAD(chunkAad({ archiveId: journal.archiveId, suite, index, totalChunks, plaintextBytes: packed.length, final }));
+                        const stored = Buffer.concat([cipher.update(packed), cipher.final(), cipher.getAuthTag()]);
+                        if (sha256hex(stored) !== journal.chunkHeaders[index].sha256) {
+                            refuse(`re-sealing chunk ${index} did not reproduce the bytes already sent, so the source changed under the uploaded range`);
+                        }
+                        feedPart(stored.subarray(0, Math.min(feedPartialTo, stored.length)));
+                    }
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            return { hashers, bodyHasher, prefixHeaders, prefixStoredBytes, prefixBodyBytes, heldAtMostBytes, partChecksums };
+        };
+        /** The finish line for an object the provider already holds whole. */
+        const recordWholeObject = async () => {
+            // A completed multipart's provider checksum is the composite over ALL
+            // its parts — including the short tail the conservative journal never
+            // seeds. The layout is our own uploader's arithmetic (full parts of the
+            // journaled size, one short tail), so the verification walk rebuilds
+            // every part checksum from re-sealed bytes; empty etags mean "nothing
+            // provider-side to compare" — the retired multipart cannot be listed.
+            let layout = null;
+            if (journaled?.s3UploadId) {
+                const partBytes = journaled.journalable.parts[0]?.bytes ?? 0;
+                if (partBytes > 0) {
+                    layout = [];
+                    let remaining = headersTotal;
+                    while (remaining > 0) {
+                        const bytes = Math.min(partBytes, remaining);
+                        layout.push({ partNumber: layout.length + 1, etag: "", bytes });
+                        remaining -= bytes;
+                    }
+                }
+            }
+            const walk = await reproducePrefix(totalChunks, layout);
+            const remoteChecksum = layout ? compositeChecksum(walk.partChecksums) : null;
+            const envelope = {
+                version: ENVELOPE_VERSION, archiveId: journal.archiveId, suite, chunkBytes, chunks: walk.prefixHeaders,
+                manifest: {
+                    plaintextSha256: walk.bodyHasher.digest("hex"), plaintextBytes: walk.prefixBodyBytes,
+                    compression: "gzip-chunk", originalBytes: ctx.totalBytes, originalSha256: walk.hashers.plaintext.digestHex(),
+                    createdAt: journal.createdAt, adapter: { agent: ctx.agent, version: ADAPTER_VERSION }
+                },
+                wrappedKeys: wrapAll(archiveKey, recipients, suite, journal.archiveId)
+            };
+            return verifyAndRecord(ctx, {
+                archiveId: journal.archiveId, objectKey: journal.objectKey, envelope, wholeStoredBytes: walk.prefixStoredBytes,
+                uploaded: { remoteChecksum, bytes: walk.prefixStoredBytes }, hashers: walk.hashers,
+                heldAtMostBytes: walk.heldAtMostBytes, resumed: true, progress: journaled
+            });
+        };
+        // Recovery before anything else: if every chunk was emitted, the object
+        // may already be complete — a crash between completion and the record
+        // write. HEAD is cheap and turns "re-upload 2 GB" into "verify and record".
+        if (journal.chunkHeaders.length === totalChunks) {
+            const already = await ctx.client.head({ objectKey: journal.objectKey });
+            if (already.exists && already.bytes === headersTotal) {
+                return await recordWholeObject();
+            }
+        }
+        // THE PROVIDER'S TRUTH. The journal's cursor lags emission by design; what
+        // bounds re-encryption is what the bucket actually holds.
+        let trueHeld;
+        let trueParts = null;
+        let resumeState;
+        if (journaled?.s3UploadId) {
+            if (typeof ctx.client.listParts !== "function")
+                return refuse("this provider client cannot list an in-flight upload's parts, so what the bucket holds cannot be proven");
+            let parts;
+            try {
+                parts = await ctx.client.listParts(journal.objectKey, journaled.s3UploadId);
+            }
+            catch (error) {
+                // The multipart is gone — aborted, expired, or already completed. If
+                // completed, the whole object is sitting at the key: recover it.
+                const already = await ctx.client.head({ objectKey: journal.objectKey }).catch(() => null);
+                if (already?.exists && already.bytes === headersTotal && journal.chunkHeaders.length === totalChunks) {
+                    return await recordWholeObject();
+                }
+                return refuse(error instanceof Error ? `the provider no longer holds the in-flight upload (${error.message})` : "the provider no longer holds the in-flight upload");
+            }
+            parts.forEach((part, index) => { if (part.partNumber !== index + 1)
+                refuse("the provider's held parts are not a contiguous prefix, which this vault never produces"); });
+            trueParts = parts;
+            trueHeld = parts.reduce((sum, part) => sum + part.bytes, 0);
+        }
+        else if (journaled && typeof journaled.journalable.session === "string") {
+            const session = journaled.journalable.session;
+            if (typeof ctx.client.resumableStatus !== "function")
+                return refuse("this provider client cannot query the session's confirmed bytes, so what the bucket holds cannot be proven");
+            const status = await ctx.client.resumableStatus(session);
+            trueHeld = status.confirmedBytes;
+            resumeState = { session, confirmedBytes: trueHeld };
+        }
+        else {
+            // No provider state was ever journaled: nothing durable exists remotely,
+            // and (headers being emission-ordered) nothing may have left either —
+            // but "may" is not "provably did not". Bytes could sit in a multipart
+            // this journal never learned the id of. Without an id there is nothing
+            // to query, so the only provably-safe move is a fresh key.
+            return refuse("no provider upload state was journaled, so what the bucket may hold cannot be proven");
+        }
+        // Headers must vouch for every provider-held byte (guaranteed by
+        // emission-ordering unless the journal was cut down by hand) and the
+        // frontier must land exactly on our chunk arithmetic.
+        if (trueHeld > headersTotal)
+            return refuse("the provider holds bytes beyond every chunk the journal ever emitted — the journal cannot vouch for them");
+        let kEff = 0;
+        while (kEff < journal.chunkHeaders.length && cumStoredAt[kEff + 1] <= trueHeld)
+            kEff += 1;
+        const skip = trueHeld - cumStoredAt[kEff];
+        if (skip > 0 && kEff >= journal.chunkHeaders.length)
+            return refuse("the provider's frontier lands inside a chunk the journal has no record of");
+        if (skip > 0 && skip >= journal.chunkHeaders[kEff].storedBytes)
+            return refuse("the provider's frontier does not match the journaled chunk sizes");
+        if (trueParts) {
+            resumeState = {
+                uploadId: journaled.s3UploadId,
+                // Checksums rebuilt below by the verification walk; placeholders are
+                // replaced before anything is sent.
+                parts: trueParts.map((part) => ({ partNumber: part.partNumber, etag: part.etag, checksum: "", bytes: part.bytes }))
+            };
+        }
+        // Step 2+3 of the invariant, over the PROVIDER'S range: re-seal [0, kEff)
+        // — and the partial chunk at the frontier is guarded in the sink before
+        // its first byte is pushed. This walk also rebuilds every whole-object
+        // hash from the verified bytes, so nothing is trusted from the journal's
+        // own hash state.
+        const walk = await reproducePrefix(kEff, trueParts, skip);
+        if (trueParts && resumeState) {
+            const seeded = resumeState.parts;
+            // Only fully re-verified parts can be seeded with a real checksum; the
+            // walk covers [0, kEff) which by the boundary checks spans every FULL
+            // part (a part ends inside a chunk only at the frontier).
+            if (walk.partChecksums.length < seeded.length) {
+                // The frontier part is partially covered: S3 seeding must stop at the
+                // last full part, and the remainder re-ships from the chunk boundary.
+                seeded.length = walk.partChecksums.length;
+            }
+            seeded.forEach((part, index) => { part.checksum = walk.partChecksums[index]; });
+            const seededBytes = seeded.reduce((sum, part) => sum + part.bytes, 0);
+            // Recompute the frontier against what is actually seedable.
+            let kSeed = 0;
+            while (kSeed < journal.chunkHeaders.length && cumStoredAt[kSeed + 1] <= seededBytes)
+                kSeed += 1;
+            if (seededBytes !== trueHeld) {
+                return await resumeFromFrontier(kSeed, seededBytes - cumStoredAt[kSeed], resumeState);
+            }
+        }
+        return await resumeFromFrontier(kEff, skip, resumeState);
+        /** Streams the tail from a verified frontier and splices the envelope. */
+        async function resumeFromFrontier(k, skipBytes, resume) {
+            const walkAt = k === kEff && skipBytes === skip ? walk : await reproducePrefix(k, null);
+            if (k === totalChunks) {
+                if (skipBytes !== 0)
+                    return refuse("the provider confirms more bytes than the finished archive contains");
+                const uploaded = await ctx.client.uploadStream(journal.objectKey, (async function* () { })(), { resume });
+                const envelope = {
+                    version: ENVELOPE_VERSION, archiveId: journal.archiveId, suite, chunkBytes, chunks: walkAt.prefixHeaders,
+                    manifest: {
+                        plaintextSha256: walkAt.bodyHasher.digest("hex"), plaintextBytes: walkAt.prefixBodyBytes,
+                        compression: "gzip-chunk", originalBytes: ctx.totalBytes, originalSha256: walkAt.hashers.plaintext.digestHex(),
+                        createdAt: journal.createdAt, adapter: { agent: ctx.agent, version: ADAPTER_VERSION }
+                    },
+                    wrappedKeys: wrapAll(archiveKey, recipients, suite, journal.archiveId)
+                };
+                return verifyAndRecord(ctx, {
+                    archiveId: journal.archiveId, objectKey: journal.objectKey, envelope, wholeStoredBytes: walkAt.prefixStoredBytes,
+                    uploaded, hashers: walkAt.hashers, heldAtMostBytes: walkAt.heldAtMostBytes, resumed: true, progress: journaled
+                });
+            }
+            await recordAudit(ctx.dataDir, "upload.verify", "allowed", { archiveId: journal.archiveId, objectKey: journal.objectKey, resumedAtChunk: k, confirmedBytes: cumStoredAt[k] + skipBytes });
+            const guard = journal.chunkHeaders[k] ?? null;
+            const core = await streamSealCore(ctx, {
+                objectKey: journal.objectKey, archiveId: journal.archiveId, suite, archiveKey, noncePrefix, recipients,
+                chunkBytes, totalChunks, firstChunkIndex: k, skipStoredBytes: skipBytes,
+                spliceGuardSha256: skipBytes > 0 && guard ? guard.sha256 : null,
+                prefixHeaders: walkAt.prefixHeaders, prefixStoredBytes: walkAt.prefixStoredBytes, hashers: walkAt.hashers,
+                hashStateFallback: { plaintext: walkAt.hashers.plaintext.exportState(), stored: walkAt.hashers.stored.exportState() },
+                consumedPrefixFallback: walkAt.hashers.plaintext.digestHex(),
+                bodyHasher: walkAt.bodyHasher, resume, createdAt: journal.createdAt
+            });
+            const envelope = {
+                version: ENVELOPE_VERSION, archiveId: journal.archiveId, suite, chunkBytes,
+                chunks: [...walkAt.prefixHeaders, ...core.sealed.envelope.chunks],
+                manifest: {
+                    plaintextSha256: walkAt.bodyHasher.digest("hex"),
+                    plaintextBytes: walkAt.prefixBodyBytes + core.sealed.envelope.manifest.plaintextBytes,
+                    compression: "gzip-chunk", originalBytes: ctx.totalBytes, originalSha256: core.sealed.originalSha256,
+                    createdAt: core.sealed.envelope.manifest.createdAt, adapter: core.sealed.envelope.manifest.adapter
+                },
+                wrappedKeys: core.sealed.envelope.wrappedKeys
+            };
+            return verifyAndRecord(ctx, {
+                archiveId: journal.archiveId, objectKey: journal.objectKey, envelope,
+                wholeStoredBytes: walkAt.prefixStoredBytes + core.sealed.storedBytes,
+                uploaded: core.uploaded, hashers: walkAt.hashers,
+                heldAtMostBytes: Math.max(walkAt.heldAtMostBytes, core.heldAtMostBytes), resumed: true, progress: journaled
+            });
+        }
+    }
+    finally {
+        zeroize(archiveKey);
+    }
+}
+/** The provider-language checksum a completed S3 multipart reports: the composite of its part checksums. GCS state yields null — nothing rollable across runs. */
+function s3Composite(progress) {
+    const state = progress.journalable;
+    if (!progress.s3UploadId || !Array.isArray(state.parts) || state.parts.length === 0)
+        return null;
+    return compositeChecksum(state.parts.map((part) => part.checksum));
+}