sealkeep 0.5.0

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

@@ -0,0 +1,188 @@
+import { gzipSync, gunzipSync } from "node:zlib";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { aeadCipher, aeadDecipher } from "./aead.js";
+import { CryptoError, unwrapArchiveKey, wrapForKey, wrapForPhrase, x25519PublicKeyFromRaw, zeroize } from "./recipients.js";
+import { DEFAULT_CHUNK_BYTES, ENVELOPE_VERSION, KEY_BYTES, NONCE_BYTES, SUITES, TAG_BYTES, chunkAad, chunkNonce } from "./format.js";
+const sha256 = (input) => createHash("sha256").update(input).digest("hex");
+function toPublicKey(value) {
+    return Buffer.isBuffer(value) ? x25519PublicKeyFromRaw(value) : value;
+}
+/** Exported so `stream.ts` produces byte-for-byte the same wraps as the buffered seal. */
+export function wrapAll(archiveKey, recipients, suite, archiveId, seed) {
+    if (recipients.length === 0)
+        throw new CryptoError("no_recipient", "An archive needs at least one recipient");
+    return recipients.map((recipient, index) => {
+        const nonce = seed?.wrapNonces[index] ?? randomBytes(NONCE_BYTES);
+        if (recipient.kind === "phrase") {
+            return wrapForPhrase(archiveKey, recipient.phrase, suite, archiveId, { salt: seed?.wrapSalts[index] ?? randomBytes(16), nonce, params: recipient.scrypt });
+        }
+        return wrapForKey(archiveKey, toPublicKey(recipient.publicKey), suite, archiveId, { nonce, ephemeralPrivateKey: seed?.ephemeralPrivateKeys?.[index] });
+    });
+}
+/**
+ * Encrypts one archive.
+ *
+ * A random per-archive key encrypts the plaintext in chunks; that key is then
+ * wrapped separately for each recipient. Adding or removing a recipient therefore
+ * never requires re-encrypting the data.
+ */
+export function encryptArchive(plaintext, options) {
+    const suite = options.suite ?? "chacha20-poly1305";
+    if (!SUITES.includes(suite))
+        throw new CryptoError("suite_unsupported", `Unsupported suite: ${suite}`);
+    const chunkBytes = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;
+    if (!Number.isInteger(chunkBytes) || chunkBytes <= 0)
+        throw new CryptoError("invalid_chunk_size", "chunkBytes must be a positive integer");
+    const archiveId = options.archiveId ?? randomUUID();
+    const archiveKey = options.deterministic?.archiveKey ?? randomBytes(KEY_BYTES);
+    const noncePrefix = options.deterministic?.noncePrefix ?? randomBytes(4);
+    if (archiveKey.length !== KEY_BYTES)
+        throw new CryptoError("key_malformed", `An archive key must be ${KEY_BYTES} bytes`);
+    if ((options.compression ?? "none") === "gzip-chunk")
+        throw new CryptoError("envelope_malformed", "gzip-chunk sealing is streaming-only; use sealArchiveToFile");
+    const body = (options.compression ?? "none") === "gzip" ? gzipSync(plaintext, { level: 6 }) : plaintext;
+    const totalChunks = Math.max(1, Math.ceil(body.length / chunkBytes));
+    const chunks = [];
+    const blocks = [];
+    try {
+        for (let index = 0; index < totalChunks; index += 1) {
+            const slice = body.subarray(index * chunkBytes, Math.min((index + 1) * chunkBytes, body.length));
+            const final = index === totalChunks - 1;
+            const nonce = chunkNonce(noncePrefix, index);
+            const cipher = aeadCipher(suite, archiveKey, nonce);
+            cipher.setAAD(chunkAad({ archiveId, suite, index, totalChunks, plaintextBytes: slice.length, final }));
+            const stored = Buffer.concat([cipher.update(slice), cipher.final(), cipher.getAuthTag()]);
+            blocks.push(stored);
+            chunks.push({ index, plaintextBytes: slice.length, storedBytes: stored.length, sha256: sha256(stored), nonce: nonce.toString("base64"), final });
+        }
+        const envelope = {
+            version: ENVELOPE_VERSION, archiveId, suite, chunkBytes, chunks,
+            manifest: { plaintextSha256: sha256(body), plaintextBytes: body.length,
+                ...((options.compression ?? "none") === "gzip"
+                    ? { compression: "gzip", originalBytes: plaintext.length, originalSha256: sha256(plaintext) }
+                    : {}), createdAt: options.createdAt ?? new Date().toISOString(), adapter: options.adapter },
+            wrappedKeys: wrapAll(archiveKey, options.recipients, suite, archiveId, options.deterministic)
+        };
+        return { envelope, ciphertext: Buffer.concat(blocks) };
+    }
+    finally {
+        if (!options.deterministic)
+            zeroize(archiveKey);
+    }
+}
+/**
+ * Structural checks that must pass before any key is used.
+ *
+ * Takes a length rather than the bytes so the streaming reader, which never
+ * holds the ciphertext, is gated by exactly the same rules.
+ */
+export function validateEnvelope(envelope, ciphertextBytes) {
+    if (envelope.version !== ENVELOPE_VERSION)
+        throw new CryptoError("version_unsupported", `Envelope version ${String(envelope.version)} is not supported`);
+    if (!SUITES.includes(envelope.suite))
+        throw new CryptoError("suite_unsupported", `Unsupported suite: ${String(envelope.suite)}`);
+    if (!Array.isArray(envelope.chunks) || envelope.chunks.length === 0)
+        throw new CryptoError("envelope_malformed", "An envelope must describe at least one chunk");
+    let stored = 0;
+    for (const [position, chunk] of envelope.chunks.entries()) {
+        if (chunk.index !== position)
+            throw new CryptoError("chunk_out_of_order", `Chunk ${position} claims index ${chunk.index}`);
+        if (chunk.storedBytes <= TAG_BYTES - 1 || chunk.storedBytes !== chunk.plaintextBytes + TAG_BYTES)
+            throw new CryptoError("envelope_malformed", `Chunk ${position} has an impossible length`);
+        if (chunk.final !== (position === envelope.chunks.length - 1))
+            throw new CryptoError("chunk_truncated", "Exactly the last chunk may be marked final");
+        stored += chunk.storedBytes;
+    }
+    if (stored !== ciphertextBytes)
+        throw new CryptoError("ciphertext_length_mismatch", `Envelope describes ${stored} stored bytes; ${ciphertextBytes} supplied`);
+    const declared = envelope.chunks.reduce((total, chunk) => total + chunk.plaintextBytes, 0);
+    if (declared !== envelope.manifest.plaintextBytes)
+        throw new CryptoError("envelope_malformed", "Chunk lengths do not sum to the manifest plaintext length");
+}
+/**
+ * Decrypts an archive after verifying its structure and every stored chunk hash.
+ * Every chunk is authenticated against associated data that pins its position and
+ * the total chunk count, so a reordered or truncated archive fails rather than
+ * returning partial plaintext.
+ */
+export function decryptArchive(envelope, ciphertext, unlock) {
+    validateEnvelope(envelope, ciphertext.length);
+    const archiveKey = unwrapArchiveKey(envelope.wrappedKeys, envelope.suite, envelope.archiveId, unlock);
+    if (archiveKey.length !== KEY_BYTES) {
+        zeroize(archiveKey);
+        throw new CryptoError("key_malformed", "Unwrapped archive key has the wrong length");
+    }
+    try {
+        const parts = [];
+        let offset = 0;
+        for (const chunk of envelope.chunks) {
+            const stored = ciphertext.subarray(offset, offset + chunk.storedBytes);
+            offset += chunk.storedBytes;
+            if (sha256(stored) !== chunk.sha256)
+                throw new CryptoError("chunk_hash_mismatch", `Chunk ${chunk.index} does not match its recorded hash`);
+            const decipher = aeadDecipher(envelope.suite, archiveKey, Buffer.from(chunk.nonce, "base64"));
+            decipher.setAAD(chunkAad({ archiveId: envelope.archiveId, suite: envelope.suite, index: chunk.index, totalChunks: envelope.chunks.length, plaintextBytes: chunk.plaintextBytes, final: chunk.final }));
+            decipher.setAuthTag(stored.subarray(stored.length - TAG_BYTES));
+            try {
+                parts.push(Buffer.concat([decipher.update(stored.subarray(0, stored.length - TAG_BYTES)), decipher.final()]));
+            }
+            catch {
+                throw new CryptoError("chunk_auth_failed", `Chunk ${chunk.index} failed authentication`);
+            }
+        }
+        const plaintext = Buffer.concat(parts);
+        if (plaintext.length !== envelope.manifest.plaintextBytes)
+            throw new CryptoError("plaintext_length_mismatch", "Decrypted length does not match the manifest");
+        if (sha256(plaintext) !== envelope.manifest.plaintextSha256)
+            throw new CryptoError("plaintext_hash_mismatch", "Decrypted bytes do not match the manifest hash");
+        // Absent on archives written without compression, where the authenticated
+        // body already is the caller's plaintext.
+        if (envelope.manifest.compression === undefined)
+            return plaintext;
+        if (envelope.manifest.compression !== "gzip" && envelope.manifest.compression !== "gzip-chunk")
+            throw new CryptoError("envelope_malformed", "Unsupported compression");
+        let original;
+        try {
+            original = envelope.manifest.compression === "gzip-chunk"
+                // Each part is one chunk's compressed slice, independently made and
+                // independently undone — concatenating the results reproduces the file.
+                ? Buffer.concat(parts.map((part) => gunzipSync(part)))
+                : gunzipSync(plaintext);
+        }
+        catch {
+            throw new CryptoError("plaintext_hash_mismatch", "Decompression failed after authentication");
+        }
+        // The archive is honoured only once the caller's own bytes are proven, not
+        // merely the compressed stream they were derived from.
+        if (original.length !== envelope.manifest.originalBytes)
+            throw new CryptoError("plaintext_length_mismatch", "Decompressed length does not match the manifest");
+        if (sha256(original) !== envelope.manifest.originalSha256)
+            throw new CryptoError("plaintext_hash_mismatch", "Decompressed bytes do not match the manifest hash");
+        return original;
+    }
+    finally {
+        zeroize(archiveKey);
+    }
+}
+/**
+ * Rotates the recipient set without touching ciphertext. `replace` is how a lost
+ * device is cut off; `add` is how a new device or extra recovery key is granted.
+ */
+export function rewrapArchive(envelope, unlock, recipients, options = {}) {
+    const archiveKey = unwrapArchiveKey(envelope.wrappedKeys, envelope.suite, envelope.archiveId, unlock);
+    try {
+        const wrapped = wrapAll(archiveKey, recipients, envelope.suite, envelope.archiveId);
+        const merged = options.mode === "add" ? [...envelope.wrappedKeys, ...wrapped.filter((next) => !envelope.wrappedKeys.some((existing) => existing.id === next.id))] : wrapped;
+        return { ...envelope, wrappedKeys: merged };
+    }
+    finally {
+        zeroize(archiveKey);
+    }
+}
+/** Recipient identifiers present on an archive. Useful for auditing who can open it. */
+export function recipientIds(envelope) {
+    return {
+        phrase: envelope.wrappedKeys.filter((key) => key.type === "phrase").map((key) => key.id),
+        keys: envelope.wrappedKeys.filter((key) => key.type === "x25519").map((key) => key.id)
+    };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Sealkeep archive envelope, format version 2.
+ *
+ * The format is documented here rather than in prose elsewhere: an implementation
+ * that matches these types and the associated-data construction below can read and
+ * write Sealkeep archives without reference to the application code.
+ */
+export declare const ENVELOPE_VERSION: 2;
+export declare const DEFAULT_CHUNK_BYTES: number;
+/** Both suites are AEADs provided by OpenSSL. No protocol is hand-rolled on top. */
+export type Suite = "chacha20-poly1305" | "aes-256-gcm";
+export declare const SUITES: readonly Suite[];
+export declare const KEY_BYTES = 32;
+export declare const NONCE_BYTES = 12;
+export declare const TAG_BYTES = 16;
+export type ScryptParams = {
+    N: number;
+    r: number;
+    p: number;
+};
+export declare const DEFAULT_SCRYPT: ScryptParams;
+/** A recipient derived from a human recovery phrase. */
+export type PhraseRecipient = {
+    type: "phrase";
+    id: string;
+    kdf: {
+        algorithm: "scrypt";
+        salt: string;
+        params: ScryptParams;
+    };
+    nonce: string;
+    ciphertext: string;
+};
+/** A recipient identified by an X25519 public key: a device, or an extra recovery key. */
+export type KeyRecipient = {
+    type: "x25519";
+    id: string;
+    recipientPublicKey: string;
+    ephemeralPublicKey: string;
+    nonce: string;
+    ciphertext: string;
+};
+export type WrappedKey = PhraseRecipient | KeyRecipient;
+export type ChunkHeader = {
+    index: number;
+    /** Bytes this chunk's ciphertext decrypts to. Under "gzip-chunk" that is the compressed slice; the raw length lives in `rawBytes`. */
+    plaintextBytes: number;
+    /** Original (pre-compression) bytes this chunk covers. Present only under "gzip-chunk", where it is what makes byte-ranged retrieval computable without decompressing anything. */
+    rawBytes?: number;
+    /** Stored bytes for this chunk: ciphertext followed by its authentication tag. */
+    storedBytes: number;
+    sha256: string;
+    nonce: string;
+    final: boolean;
+};
+export type Envelope = {
+    version: typeof ENVELOPE_VERSION;
+    archiveId: string;
+    suite: Suite;
+    chunkBytes: number;
+    chunks: ChunkHeader[];
+    manifest: {
+        /**
+         * "gzip": applied to the whole plaintext before chunking — the legacy
+         * layout, still read forever. "gzip-chunk": applied inside each chunk, so
+         * every chunk decrypts AND decompresses on its own — what makes streaming
+         * seals and fetch-only-the-chunks retrieval possible. Absent means none.
+         */
+        compression?: "gzip" | "gzip-chunk";
+        originalBytes?: number;
+        originalSha256?: string;
+        plaintextSha256: string;
+        plaintextBytes: number;
+        createdAt: string;
+        adapter?: {
+            agent: string;
+            version: string;
+        };
+    };
+    wrappedKeys: WrappedKey[];
+};
+/**
+ * Associated data bound to every chunk. It commits to the format version, the
+ * suite, the archive identity, this chunk's position, the total chunk count, the
+ * chunk's plaintext length, and whether it terminates the archive.
+ *
+ * That set is what makes reordering, truncating, splicing between archives, and
+ * suite downgrade detectable: any of those changes produces different associated
+ * data, and the AEAD tag then fails.
+ */
+export declare function chunkAad(input: {
+    archiveId: string;
+    suite: Suite;
+    index: number;
+    totalChunks: number;
+    plaintextBytes: number;
+    final: boolean;
+}): Buffer;
+/** Associated data for a wrapped archive key, binding the wrap to one archive and one recipient. */
+export declare function wrapAad(archiveId: string, recipientId: string): Buffer;
+/**
+ * Chunk nonces are a 4-byte per-archive random prefix followed by a big-endian
+ * 64-bit chunk counter. The archive key is random per archive, so a nonce can
+ * only repeat under a key if the same archive key is generated twice.
+ */
+export declare function chunkNonce(prefix: Buffer, index: number): Buffer;

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

@@ -0,0 +1,43 @@
+/**
+ * Sealkeep archive envelope, format version 2.
+ *
+ * The format is documented here rather than in prose elsewhere: an implementation
+ * that matches these types and the associated-data construction below can read and
+ * write Sealkeep archives without reference to the application code.
+ */
+export const ENVELOPE_VERSION = 2;
+export const DEFAULT_CHUNK_BYTES = 4 * 1024 * 1024;
+export const SUITES = ["chacha20-poly1305", "aes-256-gcm"];
+export const KEY_BYTES = 32;
+export const NONCE_BYTES = 12;
+export const TAG_BYTES = 16;
+export const DEFAULT_SCRYPT = { N: 1 << 15, r: 8, p: 1 };
+/**
+ * Associated data bound to every chunk. It commits to the format version, the
+ * suite, the archive identity, this chunk's position, the total chunk count, the
+ * chunk's plaintext length, and whether it terminates the archive.
+ *
+ * That set is what makes reordering, truncating, splicing between archives, and
+ * suite downgrade detectable: any of those changes produces different associated
+ * data, and the AEAD tag then fails.
+ */
+export function chunkAad(input) {
+    return Buffer.from(`vaultline-chunk:v${ENVELOPE_VERSION}|${input.suite}|${input.archiveId}|${input.index}|${input.totalChunks}|${input.plaintextBytes}|${input.final ? 1 : 0}`, "utf8");
+}
+/** Associated data for a wrapped archive key, binding the wrap to one archive and one recipient. */
+export function wrapAad(archiveId, recipientId) {
+    return Buffer.from(`vaultline-wrap:v${ENVELOPE_VERSION}|${archiveId}|${recipientId}`, "utf8");
+}
+/**
+ * Chunk nonces are a 4-byte per-archive random prefix followed by a big-endian
+ * 64-bit chunk counter. The archive key is random per archive, so a nonce can
+ * only repeat under a key if the same archive key is generated twice.
+ */
+export function chunkNonce(prefix, index) {
+    if (prefix.length !== 4)
+        throw new Error("Nonce prefix must be 4 bytes");
+    const nonce = Buffer.alloc(NONCE_BYTES);
+    prefix.copy(nonce, 0);
+    nonce.writeBigUInt64BE(BigInt(index), 4);
+    return nonce;
+}

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

@@ -0,0 +1,5 @@
+export * from "./format.js";
+export * from "./recipients.js";
+export * from "./envelope.js";
+export * from "./stream.js";
+export * from "./sha256-stream.js";

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

@@ -0,0 +1,5 @@
+export * from "./format.js";
+export * from "./recipients.js";
+export * from "./envelope.js";
+export * from "./stream.js";
+export * from "./sha256-stream.js";

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

@@ -0,0 +1,42 @@
+import { type KeyObject } from "node:crypto";
+import { type KeyRecipient, type PhraseRecipient, type ScryptParams, type Suite, type WrappedKey } from "./format.js";
+export declare class CryptoError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Overwrites key material in place. Best effort: it cannot reach copies the runtime made. */
+export declare function zeroize(...buffers: Buffer[]): void;
+export declare function derivePhraseKey(phrase: string, salt: Buffer, params?: ScryptParams): Buffer;
+declare function sealKey(suite: Suite, kek: Buffer, nonce: Buffer, archiveKey: Buffer, aad: Buffer): Buffer;
+declare function openKey(suite: Suite, kek: Buffer, nonce: Buffer, sealed: Buffer, aad: Buffer): Buffer;
+export declare function phraseRecipientId(salt: Buffer): string;
+export declare function keyRecipientId(publicKeyRaw: Buffer): string;
+export declare function rawPublicKey(key: KeyObject): Buffer;
+export declare function wrapForPhrase(archiveKey: Buffer, phrase: string, suite: Suite, archiveId: string, options: {
+    salt: Buffer;
+    nonce: Buffer;
+    params?: ScryptParams;
+}): PhraseRecipient;
+/**
+ * Ephemeral-static X25519. A fresh ephemeral key per wrap means the shared secret,
+ * and therefore the key-encryption key, is unique to this archive and recipient.
+ */
+export declare function wrapForKey(archiveKey: Buffer, recipientPublicKey: KeyObject, suite: Suite, archiveId: string, options: {
+    nonce: Buffer;
+    ephemeralPrivateKey?: KeyObject;
+}): KeyRecipient;
+export declare function x25519PrivateKeyFromRaw(raw: Buffer): KeyObject;
+export declare function x25519PublicKeyFromRaw(raw: Buffer): KeyObject;
+export type Unlock = {
+    phrase: string;
+} | {
+    privateKey: KeyObject | string;
+};
+/** Tries every recipient this unlock method could open, and reports a single failure if none do. */
+export declare function unwrapArchiveKey(wrappedKeys: readonly WrappedKey[], suite: Suite, archiveId: string, unlock: Unlock): Buffer;
+export declare const wrapInternals: {
+    sealKey: typeof sealKey;
+    openKey: typeof openKey;
+    NONCE_BYTES: number;
+};
+export {};

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

@@ -0,0 +1,129 @@
+import { createHash, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, scryptSync, timingSafeEqual } from "node:crypto";
+import { aeadCipher, aeadDecipher } from "./aead.js";
+import { DEFAULT_SCRYPT, KEY_BYTES, NONCE_BYTES, TAG_BYTES, wrapAad } from "./format.js";
+export class CryptoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CryptoError";
+    }
+}
+const b64 = (value) => value.toString("base64");
+const unb64 = (value) => Buffer.from(value, "base64");
+/** Overwrites key material in place. Best effort: it cannot reach copies the runtime made. */
+export function zeroize(...buffers) {
+    for (const buffer of buffers)
+        buffer.fill(0);
+}
+export function derivePhraseKey(phrase, salt, params = DEFAULT_SCRYPT) {
+    return scryptSync(phrase.normalize("NFKD"), salt, KEY_BYTES, { ...params, maxmem: 256 * 1024 * 1024 });
+}
+function sealKey(suite, kek, nonce, archiveKey, aad) {
+    const cipher = aeadCipher(suite, kek, nonce);
+    cipher.setAAD(aad);
+    return Buffer.concat([cipher.update(archiveKey), cipher.final(), cipher.getAuthTag()]);
+}
+function openKey(suite, kek, nonce, sealed, aad) {
+    if (sealed.length <= TAG_BYTES)
+        throw new CryptoError("wrap_malformed", "Wrapped key is too short to contain a tag");
+    const decipher = aeadDecipher(suite, kek, nonce);
+    decipher.setAAD(aad);
+    decipher.setAuthTag(sealed.subarray(sealed.length - TAG_BYTES));
+    try {
+        return Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - TAG_BYTES)), decipher.final()]);
+    }
+    catch {
+        throw new CryptoError("unwrap_failed", "Wrapped archive key failed authentication");
+    }
+}
+export function phraseRecipientId(salt) {
+    return createHash("sha256").update(Buffer.concat([Buffer.from("vaultline-phrase-recipient:v2"), salt])).digest("hex").slice(0, 32);
+}
+export function keyRecipientId(publicKeyRaw) {
+    return createHash("sha256").update(Buffer.concat([Buffer.from("vaultline-key-recipient:v2"), publicKeyRaw])).digest("hex").slice(0, 32);
+}
+export function rawPublicKey(key) {
+    // The last 32 bytes of an X25519 SPKI DER encoding are the raw public key.
+    return key.export({ type: "spki", format: "der" }).subarray(-32);
+}
+export function wrapForPhrase(archiveKey, phrase, suite, archiveId, options) {
+    const params = options.params ?? DEFAULT_SCRYPT;
+    const id = phraseRecipientId(options.salt);
+    const kek = derivePhraseKey(phrase, options.salt, params);
+    try {
+        return { type: "phrase", id, kdf: { algorithm: "scrypt", salt: b64(options.salt), params }, nonce: b64(options.nonce), ciphertext: b64(sealKey(suite, kek, options.nonce, archiveKey, wrapAad(archiveId, id))) };
+    }
+    finally {
+        zeroize(kek);
+    }
+}
+/**
+ * Ephemeral-static X25519. A fresh ephemeral key per wrap means the shared secret,
+ * and therefore the key-encryption key, is unique to this archive and recipient.
+ */
+export function wrapForKey(archiveKey, recipientPublicKey, suite, archiveId, options) {
+    const ephemeral = options.ephemeralPrivateKey ? { privateKey: options.ephemeralPrivateKey, publicKey: createPublicKey(options.ephemeralPrivateKey) } : generateKeyPairSync("x25519");
+    const recipientRaw = rawPublicKey(recipientPublicKey);
+    const ephemeralRaw = rawPublicKey(ephemeral.publicKey);
+    const shared = diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipientPublicKey });
+    const kek = Buffer.from(hkdfSync("sha256", shared, Buffer.concat([recipientRaw, ephemeralRaw]), Buffer.from("vaultline-recipient:v2"), KEY_BYTES));
+    const id = keyRecipientId(recipientRaw);
+    try {
+        return { type: "x25519", id, recipientPublicKey: b64(recipientRaw), ephemeralPublicKey: b64(ephemeralRaw), nonce: b64(options.nonce), ciphertext: b64(sealKey(suite, kek, options.nonce, archiveKey, wrapAad(archiveId, id))) };
+    }
+    finally {
+        zeroize(kek, shared);
+    }
+}
+export function x25519PrivateKeyFromRaw(raw) {
+    if (raw.length !== 32)
+        throw new CryptoError("key_malformed", "An X25519 private key must be 32 bytes");
+    const der = Buffer.concat([Buffer.from("302e020100300506032b656e04220420", "hex"), raw]);
+    return createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+}
+export function x25519PublicKeyFromRaw(raw) {
+    if (raw.length !== 32)
+        throw new CryptoError("key_malformed", "An X25519 public key must be 32 bytes");
+    const der = Buffer.concat([Buffer.from("302a300506032b656e032100", "hex"), raw]);
+    return createPublicKey({ key: der, format: "der", type: "spki" });
+}
+/** Tries every recipient this unlock method could open, and reports a single failure if none do. */
+export function unwrapArchiveKey(wrappedKeys, suite, archiveId, unlock) {
+    const failures = [];
+    for (const wrapped of wrappedKeys) {
+        if ("phrase" in unlock && wrapped.type === "phrase") {
+            const salt = unb64(wrapped.kdf.salt);
+            if (!timingSafeEqual(Buffer.from(phraseRecipientId(salt)), Buffer.from(wrapped.id))) {
+                failures.push("phrase recipient id mismatch");
+                continue;
+            }
+            const kek = derivePhraseKey(unlock.phrase, salt, wrapped.kdf.params);
+            try {
+                return openKey(suite, kek, unb64(wrapped.nonce), unb64(wrapped.ciphertext), wrapAad(archiveId, wrapped.id));
+            }
+            catch (error) {
+                failures.push(error.code);
+            }
+            finally {
+                zeroize(kek);
+            }
+        }
+        if ("privateKey" in unlock && wrapped.type === "x25519") {
+            const privateKey = typeof unlock.privateKey === "string" ? createPrivateKey(unlock.privateKey) : unlock.privateKey;
+            const shared = diffieHellman({ privateKey, publicKey: x25519PublicKeyFromRaw(unb64(wrapped.ephemeralPublicKey)) });
+            const kek = Buffer.from(hkdfSync("sha256", shared, Buffer.concat([unb64(wrapped.recipientPublicKey), unb64(wrapped.ephemeralPublicKey)]), Buffer.from("vaultline-recipient:v2"), KEY_BYTES));
+            try {
+                return openKey(suite, kek, unb64(wrapped.nonce), unb64(wrapped.ciphertext), wrapAad(archiveId, wrapped.id));
+            }
+            catch (error) {
+                failures.push(error.code);
+            }
+            finally {
+                zeroize(kek, shared);
+            }
+        }
+    }
+    throw new CryptoError("no_recipient", `No recipient could be opened with the supplied secret (${failures.length} attempted)`);
+}
+export const wrapInternals = { sealKey, openKey, NONCE_BYTES };

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

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export declare class StreamingSha256 {
+    private readonly h;
+    private readonly w;
+    private readonly tail;
+    private tailLength;
+    private bytes;
+    update(data: Buffer): 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.
+     */
+    private finalDigest;
+    digestHex(): string;
+    digestBase64(): string;
+    /** JSON-safe string capturing H[0..7], byte count, and the unprocessed tail. */
+    exportState(): string;
+    /**
+     * 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: string): StreamingSha256;
+}