sealkeep 0.8.1 → 0.11.0

package/dist/src/device-enrollment.js

@@ -0,0 +1,349 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { decryptArchive, encryptArchive, x25519PublicKeyFromRaw, } from "../packages/sealkeep-crypto/src/index.js";
+import { approveCloudDeviceEnrollment, bootstrapMachineRefFor, bootstrapTokenRefFor, claimCloudDeviceEnrollment, cloudUrl, completeCloudDeviceEnrollment, createCloudDeviceEnrollment, listPendingCloudDeviceEnrollments, machineRefFor, tokenRefFor, } from "./cloud.js";
+import { equalHex, phraseCheck } from "./crypto.js";
+import { fail, isSealkeepError } from "./errors.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { chooseBackend, forgetRecoveryPhrase, rememberRecoveryPhrase, resolveRecoveryPhrase, } from "./secrets.js";
+import { initializeTransferredVault, readConfig, writeConfig } from "./vault.js";
+/**
+ * Fresh-device enrollment without key custody.
+ *
+ * Cloud authentication links the account, but it must not become a decryption
+ * key. A fresh machine therefore creates an ephemeral X25519 keypair locally.
+ * An already-unlocked machine seals the vault identity directly to its public
+ * half, and SealKeep Cloud relays only that ciphertext. The target private key
+ * is stored in this machine's native secret backend and never crosses HTTP.
+ */
+const STATE_SERVICE = "sealkeep-device-enrollment";
+const PAYLOAD_KIND = "sealkeep-personal-vault-enrollment";
+const PAYLOAD_VERSION = 1;
+const enrollmentStateRef = (requestId) => ({
+    service: STATE_SERVICE,
+    account: `${requestId}@${cloudUrl()}`,
+});
+function parseRawPublicKey(publicKey) {
+    const raw = Buffer.from(publicKey, "base64");
+    if (raw.length !== 32 || raw.toString("base64") !== publicKey) {
+        fail("invalid_argument", "A device enrollment public key must be a canonical 32-byte X25519 key");
+    }
+    return raw;
+}
+/** A short comparison code derived from the key itself, never supplied by Cloud. */
+export function deviceEnrollmentVerificationCode(publicKey) {
+    const digest = createHash("sha256").update(parseRawPublicKey(publicKey)).digest();
+    return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, "0");
+}
+export function generateDeviceEnrollmentKeys() {
+    const pair = generateKeyPairSync("x25519");
+    return {
+        publicKey: pair.publicKey.export({ type: "spki", format: "der" }).subarray(-32).toString("base64"),
+        privateKey: pair.privateKey.export({ type: "pkcs8", format: "der" }).toString("base64"),
+    };
+}
+function assertEnrollmentKeyPair(keys) {
+    parseRawPublicKey(keys.publicKey);
+    try {
+        const privateKey = createPrivateKey({ key: Buffer.from(keys.privateKey, "base64"), type: "pkcs8", format: "der" });
+        const derived = createPublicKey(privateKey).export({ type: "spki", format: "der" }).subarray(-32);
+        if (!derived.equals(Buffer.from(keys.publicKey, "base64")))
+            throw new Error("public key does not match");
+    }
+    catch {
+        fail("invalid_argument", "The local device enrollment key pair is not valid");
+    }
+}
+async function rememberDraft(dataDir, draft, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.set(enrollmentStateRef(draft.requestId), JSON.stringify(draft));
+}
+export async function readDeviceEnrollmentDraft(dataDir, requestId, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    const raw = await backend.get(enrollmentStateRef(requestId));
+    if (!raw)
+        return null;
+    try {
+        const draft = JSON.parse(raw);
+        if (draft.version !== 1 || draft.requestId !== requestId || !draft.privateKey || !draft.requestSecret)
+            return null;
+        if (deviceEnrollmentVerificationCode(draft.publicKey) !== draft.verificationCode)
+            return null;
+        return draft;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Starts the target side after ordinary Cloud sign-in. The request secret is a
+ * capability for claiming this one response; it is not a vault key and cannot
+ * decrypt any archive.
+ */
+export async function beginDeviceEnrollment(dataDir, label, preferred) {
+    return beginDeviceEnrollmentWithKeys(dataDir, label, generateDeviceEnrollmentKeys(), preferred);
+}
+/**
+ * Starts the existing-vault approval lane with a key pair prepared before
+ * hosted account authorization. Reusing that exact public key means the
+ * account page and the existing device approve the same target, instead of
+ * silently changing identity between the two steps.
+ */
+export async function beginDeviceEnrollmentWithKeys(dataDir, label, keys, preferred) {
+    const cleanLabel = label.trim();
+    if (!cleanLabel)
+        fail("invalid_argument", "Name this machine before requesting your preserved memory");
+    assertEnrollmentKeyPair(keys);
+    const requestSecret = randomBytes(32).toString("base64url");
+    const created = await createCloudDeviceEnrollment(dataDir, {
+        label: cleanLabel,
+        publicKey: keys.publicKey,
+        requestSecret,
+    }, preferred);
+    const draft = {
+        version: 1,
+        requestId: created.id,
+        label: cleanLabel,
+        ...keys,
+        requestSecret,
+        verificationCode: deviceEnrollmentVerificationCode(keys.publicKey),
+        createdAt: created.created_at,
+        expiresAt: created.expires_at,
+    };
+    try {
+        await rememberDraft(dataDir, draft, preferred);
+    }
+    catch (error) {
+        fail("internal", `Cloud created the enrollment request, but this machine could not protect its private key locally: ${error instanceof Error ? error.message : "secret backend refused it"}. Do not approve this request; create a new one after the local keystore is available.`);
+    }
+    const { privateKey: _privateKey, requestSecret: _requestSecret, ...publicDraft } = draft;
+    return publicDraft;
+}
+/**
+ * Persists a request the hosted approval endpoint already created from the
+ * public key supplied at authorization start. The returned request secret is
+ * consumed only here, over the verifier-protected claim response, and then
+ * remains in the native secret backend with the private key.
+ */
+export async function rememberHostedDeviceEnrollment(dataDir, input, preferred) {
+    if (!Number.isSafeInteger(input.requestId) || input.requestId < 1 || input.requestSecret.length < 32) {
+        fail("internal", "Sealkeep Cloud returned an invalid preserved-memory enrollment request");
+    }
+    const cleanLabel = input.label.trim();
+    if (!cleanLabel)
+        fail("internal", "Sealkeep Cloud returned an unnamed preserved-memory enrollment request");
+    assertEnrollmentKeyPair(input.keys);
+    if (!Number.isFinite(Date.parse(input.createdAt)) || !Number.isFinite(Date.parse(input.expiresAt))) {
+        fail("internal", "Sealkeep Cloud returned invalid preserved-memory enrollment timing");
+    }
+    const draft = {
+        version: 1,
+        requestId: input.requestId,
+        label: cleanLabel,
+        ...input.keys,
+        requestSecret: input.requestSecret,
+        verificationCode: deviceEnrollmentVerificationCode(input.keys.publicKey),
+        createdAt: input.createdAt,
+        expiresAt: input.expiresAt,
+    };
+    await rememberDraft(dataDir, draft, preferred);
+    const { privateKey: _privateKey, requestSecret: _requestSecret, ...publicDraft } = draft;
+    return publicDraft;
+}
+function enrollmentPayload(config, phrase) {
+    const canonical = canonicalPhrase(phrase);
+    if (!equalHex(config.recovery.phraseCheck, phraseCheck(canonical))) {
+        fail("recovery_phrase_mismatch", "This machine's stored recovery phrase does not open this vault, so enrollment was not approved");
+    }
+    return {
+        kind: PAYLOAD_KIND,
+        version: PAYLOAD_VERSION,
+        vaultId: config.vaultId,
+        recoveryPhrase: canonical,
+        storageMode: config.storageMode === "plain" ? "plain" : "sealed",
+        ...(config.recipients?.length ? { recipients: config.recipients } : {}),
+        ...(config.remoteNaming ? { remoteNaming: config.remoteNaming } : {}),
+        approvedAt: new Date().toISOString(),
+    };
+}
+export function sealDeviceEnrollmentPayload(config, phrase, targetPublicKey) {
+    const raw = parseRawPublicKey(targetPublicKey);
+    const sealed = encryptArchive(Buffer.from(JSON.stringify(enrollmentPayload(config, phrase))), {
+        recipients: [{ kind: "x25519", publicKey: x25519PublicKeyFromRaw(raw) }],
+        adapter: { agent: "sealkeep-device-enrollment", version: String(PAYLOAD_VERSION) },
+    });
+    return { envelope: sealed.envelope, sealed: sealed.ciphertext.toString("base64") };
+}
+function openDeviceEnrollmentPayload(envelope, sealed, privateKeyBase64) {
+    let payload;
+    try {
+        const privateKey = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), type: "pkcs8", format: "der" });
+        payload = JSON.parse(decryptArchive(envelope, Buffer.from(sealed, "base64"), { privateKey }).toString("utf8"));
+    }
+    catch {
+        return fail("forbidden", "The approved enrollment package was not sealed to this machine. Nothing local was changed.");
+    }
+    if (!payload || typeof payload !== "object")
+        return fail("internal", "The approved enrollment package is malformed");
+    const value = payload;
+    if (value.kind !== PAYLOAD_KIND || value.version !== PAYLOAD_VERSION || typeof value.vaultId !== "string" || typeof value.recoveryPhrase !== "string") {
+        return fail("internal", "The approved enrollment package is not a supported SealKeep vault identity");
+    }
+    const phrase = canonicalPhrase(value.recoveryPhrase);
+    if (!phrase.trim())
+        return fail("internal", "The approved enrollment package contains no recovery material");
+    return { ...value, recoveryPhrase: phrase };
+}
+/**
+ * Existing-device side. Requiring the independently displayed code prevents a
+ * Cloud-side public-key substitution from being approved silently.
+ */
+export async function approveDeviceEnrollment(dataDir, requestId, displayedCode, preferred) {
+    const request = (await listPendingCloudDeviceEnrollments(dataDir, preferred)).find((item) => item.id === requestId);
+    if (!request)
+        fail("archive_not_found", "That device enrollment request is no longer pending");
+    const expected = deviceEnrollmentVerificationCode(request.public_key);
+    if (displayedCode.trim() !== expected) {
+        fail("forbidden", "The verification code does not match the new machine. Do not approve it; cancel and start enrollment again.");
+    }
+    const config = await readConfig(dataDir);
+    const phrase = await resolveRecoveryPhrase(dataDir, config.vaultId, undefined, process.env, preferred);
+    if (!phrase) {
+        fail("recovery_phrase_missing", "This machine must be locally unlocked before it can approve another machine. Open SealKeep Settings and unlock this vault; do not send the phrase to Cloud or to the new machine.");
+    }
+    const bundle = sealDeviceEnrollmentPayload(config, phrase, request.public_key);
+    await approveCloudDeviceEnrollment(dataDir, requestId, bundle, preferred);
+    return { approved: true, requestId, label: request.label };
+}
+function restoredConfig(dataDir, payload) {
+    return {
+        version: 1,
+        vaultId: payload.vaultId,
+        storage: { provider: "local", root: join(dataDir, "archives") },
+        ...(payload.storageMode === "plain" ? { storageMode: "plain" } : {}),
+        recovery: { phraseCheck: phraseCheck(payload.recoveryPhrase) },
+        ...(payload.recipients?.length ? { recipients: payload.recipients } : {}),
+        ...(payload.remoteNaming ? { remoteNaming: payload.remoteNaming } : {}),
+    };
+}
+async function physicalArchiveCount(dataDir) {
+    return (await readdir(join(dataDir, "archives")).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    })).filter((name) => name.endsWith(".json")).length;
+}
+/**
+ * Read-only adoption gate. Recovery codes call this before atomically spending
+ * a code, so an occupied data directory or a lost Cloud login cannot burn a
+ * valid code and then fail locally.
+ */
+export async function assertPersonalVaultAdoptable(dataDir, payload, preferred) {
+    const current = await readConfig(dataDir).catch((error) => {
+        if (isSealkeepError(error) && error.code === "vault_not_initialized")
+            return null;
+        throw error;
+    });
+    if (current?.vaultId === payload.vaultId)
+        return;
+    await assertFreshPersonalVaultTarget(dataDir, preferred);
+}
+/**
+ * Checks everything a fresh recovery target can check before a one-time code
+ * is redeemed. This deliberately does not need the encrypted vault payload.
+ */
+export async function assertFreshPersonalVaultTarget(dataDir, preferred) {
+    const current = await readConfig(dataDir).catch((error) => {
+        if (isSealkeepError(error) && error.code === "vault_not_initialized")
+            return null;
+        throw error;
+    });
+    // Count physical records, including malformed ones. A damaged archive must
+    // block replacement just as strongly as a readable archive; skipping it
+    // here could burn a one-time recovery code and overwrite evidence.
+    const existingArchives = await physicalArchiveCount(dataDir);
+    if (existingArchives > 0) {
+        fail("forbidden", "This machine already has local archives. SealKeep will not replace that vault during device enrollment; use a separate data directory or finish syncing the existing vault first.");
+    }
+    const backend = await chooseBackend(dataDir, preferred);
+    const oldTokenRef = current ? tokenRefFor(current.vaultId) : bootstrapTokenRefFor(dataDir);
+    if (!await backend.get(oldTokenRef)) {
+        fail("unauthorized", "This machine is no longer signed in to SealKeep Cloud, so its approved vault cannot be adopted");
+    }
+    return current;
+}
+export async function adoptPersonalVaultMaterial(dataDir, payload, preferred) {
+    await assertPersonalVaultAdoptable(dataDir, payload, preferred);
+    const current = await readConfig(dataDir).catch((error) => {
+        if (isSealkeepError(error) && error.code === "vault_not_initialized")
+            return null;
+        throw error;
+    });
+    if (current?.vaultId === payload.vaultId) {
+        await rememberRecoveryPhrase(dataDir, current.vaultId, payload.recoveryPhrase, preferred);
+        return;
+    }
+    const existingArchives = await physicalArchiveCount(dataDir);
+    if (existingArchives > 0) {
+        fail("forbidden", "This machine already has local archives. SealKeep will not replace that vault during device enrollment; use a separate data directory or finish syncing the existing vault first.");
+    }
+    // Stage every new-vault secret before switching config identity. A crash can
+    // leave harmless duplicate keystore entries, but never a config whose Cloud
+    // token disappeared because it is still filed under a temporary or bootstrap
+    // identity.
+    const backend = await chooseBackend(dataDir, preferred);
+    const oldTokenRef = current ? tokenRefFor(current.vaultId) : bootstrapTokenRefFor(dataDir);
+    const oldMachineRef = current ? machineRefFor(current.vaultId) : bootstrapMachineRefFor(dataDir);
+    const nextTokenRef = tokenRefFor(payload.vaultId);
+    const nextMachineRef = machineRefFor(payload.vaultId);
+    const [token, machine] = await Promise.all([backend.get(oldTokenRef), backend.get(oldMachineRef)]);
+    if (!token)
+        fail("unauthorized", "This machine is no longer signed in to SealKeep Cloud, so its approved vault cannot be adopted");
+    try {
+        await backend.set(nextTokenRef, token);
+        if (machine)
+            await backend.set(nextMachineRef, machine);
+        await rememberRecoveryPhrase(dataDir, payload.vaultId, payload.recoveryPhrase, preferred);
+        const restored = restoredConfig(dataDir, payload);
+        if (current)
+            await writeConfig(dataDir, restored);
+        else
+            await initializeTransferredVault(dataDir, restored);
+    }
+    catch (error) {
+        await Promise.all([
+            backend.delete(nextTokenRef).catch(() => undefined),
+            backend.delete(nextMachineRef).catch(() => undefined),
+            forgetRecoveryPhrase(dataDir, payload.vaultId, preferred).catch(() => undefined),
+        ]);
+        throw error;
+    }
+    await Promise.all([
+        backend.delete(oldTokenRef).catch(() => undefined),
+        backend.delete(oldMachineRef).catch(() => undefined),
+        ...(current ? [forgetRecoveryPhrase(dataDir, current.vaultId, preferred).catch(() => undefined)] : []),
+    ]);
+}
+/** Target side: claim ciphertext, decrypt locally, adopt, then acknowledge. */
+export async function completeDeviceEnrollment(dataDir, requestId, preferred) {
+    const draft = await readDeviceEnrollmentDraft(dataDir, requestId, preferred);
+    if (!draft)
+        fail("archive_not_found", "This machine no longer holds the private enrollment request. Start a new device enrollment request.");
+    const claimed = await claimCloudDeviceEnrollment(dataDir, requestId, draft.requestSecret, preferred);
+    const envelope = typeof claimed.envelope === "string" ? JSON.parse(claimed.envelope) : claimed.envelope;
+    const payload = openDeviceEnrollmentPayload(envelope, claimed.sealed, draft.privateKey);
+    await adoptPersonalVaultMaterial(dataDir, payload, preferred);
+    let cloudReceiptCleared = true;
+    try {
+        await completeCloudDeviceEnrollment(dataDir, requestId, draft.requestSecret, preferred);
+    }
+    catch {
+        cloudReceiptCleared = false;
+    }
+    if (cloudReceiptCleared) {
+        const backend = await chooseBackend(dataDir, preferred);
+        await backend.delete(enrollmentStateRef(requestId)).catch(() => undefined);
+    }
+    return { requestId, vaultId: payload.vaultId, verificationCode: draft.verificationCode, cloudReceiptCleared };
+}

package/dist/src/disk.d.ts

@@ -1,11 +1,11 @@
 /**
  * How much room archiving needs, and whether there is any.
  *
- * Archiving costs disk before it saves any. A transcript is gzipped to a
- * scratch file and then sealed into a second one, while the original is still
- * sitting there — so free space dips by roughly twice the compressed size
- * before the source is eligible to be reclaimed, and it is only ever reclaimed
- * later, by a separate decision.
+ * Archiving costs disk before it saves any. The current chunked writer streams
+ * one compressed-and-sealed object to a partial file while the original still
+ * exists. That source is input already paid for; the new object's worst-case
+ * size, plus the standing reserve, is the additional free space admission must
+ * protect. The source is only ever reclaimed later, by a separate decision.
  *
  * That matters because of who this is for. The people who install this have
  * nearly full disks; that is the problem it exists to solve. A background
@@ -40,18 +40,23 @@ export declare function resolveReserveBytes(dataDir: string): Promise<number>;
  * `vault.ts` assumed agent transcripts compress about 2x. Measured on a real
  * 1.6 GB Codex rollout it is 1.5x — the sealed copy is 68.8% of the source —
  * because these files carry a lot of base64 and tool output that has already
- * been compressed once. Planning space against 2x would under-reserve on every
- * real file, so the number here is the one that was observed, rounded against
- * our own favour.
+ * been compressed once. That remains useful when describing expected storage,
+ * but it cannot decide whether arbitrary not-yet-compressed input is safe to
+ * start.
  */
 export declare const OBSERVED_COMPRESSION = 0.7;
+/** The normal worker seals one independently searchable zstd frame at a time. */
+export declare const LOCAL_SEAL_CHUNK_BYTES: number;
+/** Maximum bytes the current local chunk-seal can add to the archive volume. */
+export declare function maximumArchiveOutputBytes(sourceBytes: number): number;
 /**
  * What one archive of this size needs before it is safe to start.
  *
- * The gzip scratch and the sealed object both exist at once, so it is two
- * compressed copies, plus the reserve. Incompressible input is the worst case
- * and it is not rare enough to ignore, so the ratio is capped at 1: a file that
- * does not shrink is planned for as if it will not.
+ * The source already exists, and the chunked seal writes one new partial object
+ * beside it. Incompressible input is the worst case: the output can be larger
+ * than the source by the codec's documented bound plus one authentication tag
+ * per chunk. The measured 70% ratio above describes typical storage, never a
+ * safe admission threshold.
  */
 export declare function spaceNeededFor(sourceBytes: number, reserveBytes?: number): number;
 /** Free bytes on the volume holding `path`, or undefined where that cannot be asked. */

package/dist/src/disk.js

@@ -2,11 +2,11 @@ import { statfs } from "node:fs/promises";
 /**
  * How much room archiving needs, and whether there is any.
  *
- * Archiving costs disk before it saves any. A transcript is gzipped to a
- * scratch file and then sealed into a second one, while the original is still
- * sitting there — so free space dips by roughly twice the compressed size
- * before the source is eligible to be reclaimed, and it is only ever reclaimed
- * later, by a separate decision.
+ * Archiving costs disk before it saves any. The current chunked writer streams
+ * one compressed-and-sealed object to a partial file while the original still
+ * exists. That source is input already paid for; the new object's worst-case
+ * size, plus the standing reserve, is the additional free space admission must
+ * protect. The source is only ever reclaimed later, by a separate decision.
  *
  * That matters because of who this is for. The people who install this have
  * nearly full disks; that is the problem it exists to solve. A background
@@ -62,25 +62,51 @@ export async function resolveReserveBytes(dataDir) {
  * `vault.ts` assumed agent transcripts compress about 2x. Measured on a real
  * 1.6 GB Codex rollout it is 1.5x — the sealed copy is 68.8% of the source —
  * because these files carry a lot of base64 and tool output that has already
- * been compressed once. Planning space against 2x would under-reserve on every
- * real file, so the number here is the one that was observed, rounded against
- * our own favour.
+ * been compressed once. That remains useful when describing expected storage,
+ * but it cannot decide whether arbitrary not-yet-compressed input is safe to
+ * start.
  */
 export const OBSERVED_COMPRESSION = 0.7;
+/** The normal worker seals one independently searchable zstd frame at a time. */
+export const LOCAL_SEAL_CHUNK_BYTES = 64 * 1024 * 1024;
+const ZSTD_SMALL_INPUT_BYTES = 128 * 1024;
+const ARCHIVE_AUTH_TAG_BYTES = 16;
+/**
+ * Zstd's documented one-pass upper bound for one input buffer.
+ *
+ * This mirrors `ZSTD_COMPRESSBOUND`: unlike an observed compression ratio it
+ * remains true for already-compressed or adversarial input. The worker calls
+ * the one-shot codec once per chunk, then encryption appends one authentication
+ * tag to that chunk.
+ */
+function zstdCompressedBound(bytes) {
+    return bytes
+        + Math.floor(bytes / 256)
+        + (bytes < ZSTD_SMALL_INPUT_BYTES ? Math.floor((ZSTD_SMALL_INPUT_BYTES - bytes) / 2048) : 0);
+}
+/** Maximum bytes the current local chunk-seal can add to the archive volume. */
+export function maximumArchiveOutputBytes(sourceBytes) {
+    const bytes = Math.max(0, Math.ceil(sourceBytes));
+    if (!Number.isFinite(bytes))
+        return Number.POSITIVE_INFINITY;
+    const completeChunks = Math.floor(bytes / LOCAL_SEAL_CHUNK_BYTES);
+    const remainder = bytes - completeChunks * LOCAL_SEAL_CHUNK_BYTES;
+    const chunks = Math.max(1, completeChunks + (remainder > 0 ? 1 : 0));
+    const compressed = completeChunks * zstdCompressedBound(LOCAL_SEAL_CHUNK_BYTES)
+        + (remainder > 0 || completeChunks === 0 ? zstdCompressedBound(remainder) : 0);
+    return compressed + chunks * ARCHIVE_AUTH_TAG_BYTES;
+}
 /**
  * What one archive of this size needs before it is safe to start.
  *
- * The gzip scratch and the sealed object both exist at once, so it is two
- * compressed copies, plus the reserve. Incompressible input is the worst case
- * and it is not rare enough to ignore, so the ratio is capped at 1: a file that
- * does not shrink is planned for as if it will not.
+ * The source already exists, and the chunked seal writes one new partial object
+ * beside it. Incompressible input is the worst case: the output can be larger
+ * than the source by the codec's documented bound plus one authentication tag
+ * per chunk. The measured 70% ratio above describes typical storage, never a
+ * safe admission threshold.
  */
 export function spaceNeededFor(sourceBytes, reserveBytes = DISK_RESERVE_BYTES) {
-    // One ciphertext, roughly the compressed size, plus the standing reserve.
-    // The ×2 that used to live here paid for the legacy layout's staged gzip
-    // body coexisting with the ciphertext; gzip-chunk seals in a single pass
-    // and the staging is gone. A 5 GB session now asks for ~5.5 GB free, not 9.
-    return Math.ceil(sourceBytes * Math.min(1, OBSERVED_COMPRESSION)) + reserveBytes;
+    return maximumArchiveOutputBytes(sourceBytes) + Math.max(0, Math.ceil(reserveBytes));
 }
 /** Free bytes on the volume holding `path`, or undefined where that cannot be asked. */
 export async function freeBytes(path) {

package/dist/src/doctor.d.ts

@@ -8,4 +8,38 @@ export type DoctorReport = {
     ok: boolean;
     checks: Check[];
 };
-export declare function runDoctor(dataDir: string, env?: NodeJS.ProcessEnv): Promise<DoctorReport>;
+/**
+ * The archive-store fact shared by Doctor and the dashboard status endpoint.
+ *
+ * Counts are deliberately metadata-only: this check never opens ciphertext or
+ * transcript files. `detail` contains at most the first affected filename,
+ * matching Doctor's existing safe diagnostic and never the storage directory.
+ */
+export type ArchiveIntegritySummary = {
+    ok: boolean;
+    /** Backward-compatible total of metadata files that could not be used. */
+    unreadableMetadataCount: number;
+    /** Files whose stable contents are not a valid archive record. */
+    invalidMetadataCount: number;
+    /** Files that still could not be read after bounded retries. */
+    transientMetadataReadErrorCount: number;
+    detachedArchiveCount: number;
+    /** The directory kept changing, so no coherent read-only snapshot was available. */
+    scanIncomplete: boolean;
+    detail: string;
+};
+export type ArchiveIntegrityScanOptions = {
+    /** Dependency seams keep descriptor-pressure and concurrent-change tests deterministic. */
+    readMetadata?: (path: string) => Promise<string>;
+    listDirectory?: (path: string) => Promise<string[]>;
+    concurrency?: number;
+    readAttempts?: number;
+    snapshotAttempts?: number;
+};
+/** Runtime context supplied by the local API when Doctor runs beside Autopilot. */
+export type DoctorOptions = {
+    /** Native service-manager registration is present and running right now. */
+    nativeServicePresent?: boolean;
+};
+export declare function archiveIntegritySummary(directory: string, options?: ArchiveIntegrityScanOptions): Promise<ArchiveIntegritySummary>;
+export declare function runDoctor(dataDir: string, env?: NodeJS.ProcessEnv, home?: string, options?: DoctorOptions): Promise<DoctorReport>;