sealkeep 0.5.0

package/dist/packages/vaultline-crypto/src/sha256-stream.js

@@ -0,0 +1,206 @@
+/**
+ * SHA-256 with exportable mid-stream state.
+ *
+ * Node's `createHash` keeps its running state inside OpenSSL and offers no way
+ * to serialize it, which is exactly what a resumable streamed seal needs: an
+ * upload interrupted at chunk 300 must resume its whole-object plaintext hash
+ * and whole-object ciphertext hash without re-reading 1.2 GB of source. This
+ * file is FIPS 180-4 SHA-256 in plain TypeScript so that the entire state —
+ * eight hash words, a byte count, and the sub-block tail — can be written into
+ * a journal and picked up by a later process.
+ *
+ * Digesting runs on a copy of the state rather than consuming it, because one
+ * instance has to answer twice for the same bytes: the archive record speaks
+ * hex (`ciphertextSha256`) while the remote verification speaks base64
+ * (`remote.checksum`), and a hasher that died on its first digest would force
+ * the seal to run two of them over every chunk.
+ */
+import { CryptoError } from "./recipients.js";
+// The first 32 bits of the fractional parts of the cube roots of the first 64
+// primes — the FIPS 180-4 round constants, in order.
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]);
+// The first 32 bits of the fractional parts of the square roots of the first
+// 8 primes — the initial hash value H(0).
+const INITIAL = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+const BLOCK_BYTES = 64;
+const STATE_VERSION = 1;
+/**
+ * One compression round over the 64 bytes at `offset`.
+ *
+ * All arithmetic is done in doubles and folded back to uint32 with `>>> 0`:
+ * every intermediate sum is below 2^35, which a double holds exactly, and
+ * `>>> 0` reduces modulo 2^32 — so mixing the signed results of the bitwise
+ * operators into the sums is still congruent to the unsigned arithmetic the
+ * specification describes.
+ */
+function compressBlock(h, w, block, offset) {
+    for (let i = 0; i < 16; i += 1) {
+        const at = offset + i * 4;
+        w[i] = ((block[at] << 24) | (block[at + 1] << 16) | (block[at + 2] << 8) | block[at + 3]) >>> 0;
+    }
+    for (let i = 16; i < 64; i += 1) {
+        const x = w[i - 15];
+        const y = w[i - 2];
+        const s0 = ((x >>> 7) | (x << 25)) ^ ((x >>> 18) | (x << 14)) ^ (x >>> 3);
+        const s1 = ((y >>> 17) | (y << 15)) ^ ((y >>> 19) | (y << 13)) ^ (y >>> 10);
+        w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+    for (let i = 0; i < 64; i += 1) {
+        const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+        const ch = (e & f) ^ (~e & g);
+        const t1 = (hh + S1 + ch + K[i] + w[i]) >>> 0;
+        const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+        const maj = (a & b) ^ (a & c) ^ (b & c);
+        const t2 = (S0 + maj) >>> 0;
+        hh = g;
+        g = f;
+        f = e;
+        e = (d + t1) >>> 0;
+        d = c;
+        c = b;
+        b = a;
+        a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0] + a) >>> 0;
+    h[1] = (h[1] + b) >>> 0;
+    h[2] = (h[2] + c) >>> 0;
+    h[3] = (h[3] + d) >>> 0;
+    h[4] = (h[4] + e) >>> 0;
+    h[5] = (h[5] + f) >>> 0;
+    h[6] = (h[6] + g) >>> 0;
+    h[7] = (h[7] + hh) >>> 0;
+}
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+function malformed(why) {
+    throw new CryptoError("hash_state_malformed", `This is not a usable saved hash state: ${why}. The interrupted seal cannot resume its hashes; start it over.`);
+}
+/**
+ * Checksum over the exported fields, computed with this same implementation so
+ * the module stays dependency-free. It is not a security boundary — anyone who
+ * can rewrite the state can recompute it — it exists so that a journal bit-flip
+ * or hand edit is refused at import instead of silently resuming into a
+ * whole-object digest that is wrong and only discovered at restore time.
+ */
+function stateCheck(h, bytes, tailB64) {
+    return new StreamingSha256()
+        .update(Buffer.from(`vaultline-sha256-state:v${STATE_VERSION}|${h.join(",")}|${bytes}|${tailB64}`, "utf8"))
+        .digestHex()
+        .slice(0, 16);
+}
+export class StreamingSha256 {
+    h = Uint32Array.from(INITIAL);
+    w = new Uint32Array(64);
+    tail = Buffer.alloc(BLOCK_BYTES);
+    tailLength = 0;
+    bytes = 0;
+    update(data) {
+        this.bytes += data.length;
+        let offset = 0;
+        if (this.tailLength > 0) {
+            const take = Math.min(BLOCK_BYTES - this.tailLength, data.length);
+            data.copy(this.tail, this.tailLength, 0, take);
+            this.tailLength += take;
+            offset = take;
+            if (this.tailLength === BLOCK_BYTES) {
+                compressBlock(this.h, this.w, this.tail, 0);
+                this.tailLength = 0;
+            }
+        }
+        while (offset + BLOCK_BYTES <= data.length) {
+            compressBlock(this.h, this.w, data, offset);
+            offset += BLOCK_BYTES;
+        }
+        if (offset < data.length) {
+            data.copy(this.tail, 0, offset);
+            this.tailLength = data.length - offset;
+        }
+        return this;
+    }
+    /**
+     * Finalizes on a copy of the state: the running stream stays live, so hex and
+     * base64 can both be asked of the same instance and updates may continue —
+     * unlike `createHash`, which a digest consumes.
+     */
+    finalDigest() {
+        const h = Uint32Array.from(this.h);
+        const w = new Uint32Array(64);
+        // Padding: 0x80, zeros to 56 mod 64, then the message length in BITS as a
+        // big-endian 64-bit integer. BigInt keeps the multiply exact where
+        // `bytes * 8` would still fit a double but `bytes << 3` would not.
+        const padded = Buffer.alloc(this.tailLength < 56 ? BLOCK_BYTES : 2 * BLOCK_BYTES);
+        this.tail.copy(padded, 0, 0, this.tailLength);
+        padded[this.tailLength] = 0x80;
+        padded.writeBigUInt64BE(BigInt(this.bytes) * 8n, padded.length - 8);
+        compressBlock(h, w, padded, 0);
+        if (padded.length === 2 * BLOCK_BYTES)
+            compressBlock(h, w, padded, BLOCK_BYTES);
+        const digest = Buffer.alloc(32);
+        for (let i = 0; i < 8; i += 1)
+            digest.writeUInt32BE(h[i], i * 4);
+        return digest;
+    }
+    digestHex() {
+        return this.finalDigest().toString("hex");
+    }
+    digestBase64() {
+        return this.finalDigest().toString("base64");
+    }
+    /** JSON-safe string capturing H[0..7], byte count, and the unprocessed tail. */
+    exportState() {
+        const tailB64 = this.tail.subarray(0, this.tailLength).toString("base64");
+        const h = Array.from(this.h);
+        return JSON.stringify({ alg: "sha256", v: STATE_VERSION, h, bytes: this.bytes, tail: tailB64, check: stateCheck(h, this.bytes, tailB64) });
+    }
+    /**
+     * Rebuilds a stream from `exportState` output. Shape is validated field by
+     * field and the checksum recomputed, so garbage throws here rather than
+     * continuing into a digest that looks plausible and is wrong.
+     */
+    static importState(state) {
+        let parsed;
+        try {
+            parsed = JSON.parse(state);
+        }
+        catch {
+            malformed("it is not JSON");
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            malformed("it is not an object");
+        const record = parsed;
+        if (record.alg !== "sha256")
+            malformed("it does not describe a SHA-256 stream");
+        if (record.v !== STATE_VERSION)
+            malformed(`it claims state version ${String(record.v)} and this build reads version ${STATE_VERSION}`);
+        const h = record.h;
+        if (!Array.isArray(h) || h.length !== 8 || !h.every((word) => Number.isInteger(word) && word >= 0 && word <= 0xffffffff)) {
+            malformed("its hash words are not eight 32-bit integers");
+        }
+        const bytes = record.bytes;
+        if (!Number.isSafeInteger(bytes) || bytes < 0)
+            malformed("its byte count is not a non-negative integer");
+        const tailB64 = record.tail;
+        if (typeof tailB64 !== "string" || !BASE64.test(tailB64))
+            malformed("its unprocessed tail is not base64");
+        const tail = Buffer.from(tailB64, "base64");
+        if (tail.length !== bytes % BLOCK_BYTES)
+            malformed("its unprocessed tail does not agree with its byte count");
+        if (record.check !== stateCheck(h, bytes, tailB64))
+            malformed("it does not match its own checksum, so it was corrupted or edited after it was written");
+        const hash = new StreamingSha256();
+        hash.h.set(h);
+        tail.copy(hash.tail);
+        hash.tailLength = tail.length;
+        hash.bytes = bytes;
+        return hash;
+    }
+}

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

@@ -0,0 +1,139 @@
+/**
+ * File-to-file sealing and opening, in constant memory.
+ *
+ * `envelope.ts` holds the whole plaintext, the whole compressed body and the
+ * whole ciphertext at once, so archiving a 4 GB agent rollout needed roughly
+ * 14.5 GB of resident memory. The archives these functions produce are the
+ * *same* format — a v2 envelope, gzip applied to the whole body before
+ * chunking — so anything written here opens with `decryptArchive`, and anything
+ * written by `encryptArchive` opens with `openArchiveToFile`. Only the memory
+ * profile changes.
+ *
+ * The one thing that stops a seal being a single streaming pass is the
+ * associated data: every chunk commits to the *total* chunk count, which is not
+ * known until the compressed body is complete. Rather than weaken that binding,
+ * the body is written once to scratch, measured, and then sealed. Two sequential
+ * streams, no format change, nothing larger than one chunk ever resident.
+ */
+import { type Unlock } from "./recipients.js";
+import { StreamingSha256 } from "./sha256-stream.js";
+import { type EncryptOptions } from "./envelope.js";
+import { type Envelope, type Suite } from "./format.js";
+/**
+ * The byte range of the source this archive covers.
+ *
+ * `start` is what makes an incremental archive possible: an agent transcript is
+ * append-only JSONL, so once a caller has *proved* the first N bytes are
+ * unchanged it can seal only `[N, size)` and store just the new portion.
+ */
+export type SealSource = {
+    path: string;
+    start?: number;
+    end?: number;
+};
+export type StreamEncryptOptions = EncryptOptions & {
+    /** Where the compressed body is staged. Defaults to the destination's directory. */
+    scratchDir?: string;
+    /** Called as the source is read, with cumulative bytes so far — a person watching a 1.6 GB seal deserves a number that moves. Throttling is the caller's business. */
+    onProgress?: (originalBytes: number) => void;
+};
+export type SealResult = {
+    envelope: Envelope;
+    /** SHA-256 of the stored ciphertext, so the caller never re-reads it to record one. */
+    ciphertextSha256: string;
+    storedBytes: number;
+    /** The caller's own bytes covered by this archive — the sealed range, not the whole file. */
+    originalBytes: number;
+    originalSha256: string;
+};
+/**
+ * Seals a byte range of one file into another, holding one chunk at a time.
+ *
+ * The destination is written but never renamed here: the manifest hashes are
+ * only proven at the very end, so publishing the result is the caller's job and
+ * must happen after this resolves. On failure the destination is removed.
+ */
+export declare function sealArchiveToFile(source: SealSource, destPath: string, options: StreamEncryptOptions): Promise<SealResult>;
+export type OpenResult = {
+    bytes: number;
+    sha256: string;
+};
+/**
+ * Opens an archive straight to a file, holding one chunk at a time.
+ *
+ * Every chunk is authenticated before its bytes reach the destination, so what
+ * is written is never unauthenticated data — but the *whole-archive* manifest
+ * hashes can only be checked once the last chunk has gone past. A caller must
+ * therefore write to a temporary path and publish it only after this resolves;
+ * a rejection can leave a partial file behind, which is why `restoreArchive`
+ * renames into place rather than writing the destination directly.
+ */
+export declare function openArchiveToFile(envelope: Envelope, ciphertextPath: string, destPath: string, unlock: Unlock): Promise<OpenResult>;
+/**
+ * SHA-256 of several prefixes of a file, in one read and in constant memory.
+ *
+ * This is how an append is *proved* rather than assumed: hashing `[0, N)` of the
+ * live file and comparing it with what an archive recorded is the only evidence
+ * that the archive's bytes are still a prefix of it. Several offsets are
+ * answered together because a transcript usually carries several archives, and
+ * asking one at a time would re-read it once per archive.
+ *
+ * An offset past the end of the file is simply absent from the result.
+ */
+export declare function hashFilePrefixes(path: string, offsets: readonly number[]): Promise<Map<number, string>>;
+/**
+ * SHA-256 of a byte range of a file, read in constant memory.
+ *
+ * This is how an append is *proved* rather than assumed: hashing `[0, N)` of the
+ * live file and comparing it with what an archive recorded is the only evidence
+ * that the archive's bytes are still a prefix of it.
+ */
+export declare function hashFileRange(path: string, start?: number, end?: number): Promise<{
+    sha256: string;
+    bytes: number;
+}>;
+/** Where sealed chunks go: a file today, a resumable upload session tomorrow. */
+export type ChunkSink = {
+    write(stored: Buffer): Promise<void>;
+};
+/**
+ * The single-pass gzip-chunk seal, destination-agnostic. This is what makes
+ * seal-to-cloud a sink implementation instead of an architecture project: the
+ * chunk loop neither knows nor cares whether `write` lands on a disk, a GCS
+ * resumable session, or an S3 multipart part buffer. Local cost is one slice
+ * in memory, full stop.
+ */
+export declare function sealChunksToSink(source: SealSource, sink: ChunkSink, options: StreamEncryptOptions & {
+    suite?: Suite;
+    archiveKey?: Buffer;
+    noncePrefix?: Buffer;
+    /**
+     * Externally owned whole-object hashers, for resumable seals: `plaintext`
+     * sees every raw source byte this call reads (it becomes the manifest's
+     * `originalSha256`), `stored` sees every stored byte (it becomes
+     * `SealResult.ciphertextSha256`), both still hex. A resumed seal imports
+     * these from its journal so the digests cover the whole object even though
+     * this call only reads the remainder. Omitted, fresh hashes are used and
+     * nothing changes.
+     */
+    hashers?: {
+        plaintext?: StreamingSha256;
+        stored?: StreamingSha256;
+    };
+    /**
+     * Where chunk numbering starts, for resumable seals. Chunk AAD binds each
+     * chunk's index and the archive's total chunk count, so a seal re-entered
+     * at a byte offset must keep counting where the interrupted run stopped —
+     * restarting at zero would mint chunks whose AAD collides with the ones
+     * already uploaded. The caller passes the journal's `nextChunkIndex` along
+     * with `source.start` at that chunk's byte offset; the produced AADs then
+     * agree with the interrupted run's, including the total.
+     */
+    firstChunkIndex?: number;
+    /**
+     * Observes each RAW source slice as it is read, before compression and
+     * encryption — the hook seal-time indexing rides on. The slice is the
+     * loop's reused buffer window: consume it synchronously, never keep it.
+     */
+    onPlaintext?: (chunkIndex: number, slice: Buffer) => void;
+}): Promise<SealResult>;