sealkeep 0.5.0

package/dist/src/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Stable machine-readable failure classes. Human-facing messages may change
+ * between releases; these codes are a contract for the CLI, local API, and MCP.
+ * Details are operational only: never place plaintext, phrases, or keys here.
+ */
+export type VaultlineErrorCode = "invalid_argument" | "vault_not_initialized" | "vault_already_initialized" | "config_unsupported_version" | "recovery_phrase_missing" | "recovery_phrase_mismatch" | "archive_not_found" | "source_unreadable" | "destination_exists" | "destination_unwritable" | "path_not_permitted" | "native_restore_unavailable" | "ciphertext_integrity_failed" | "plaintext_integrity_failed" | "hook_payload_invalid" | "queue_job_not_found" | "queue_lease_invalid" | "queue_lease_expired" | "queue_job_exhausted" | "storage_not_configured" | "provider_unsupported" | "signer_not_configured" | "lease_expired" | "unauthorized" | "forbidden" | "internal";
+export declare class VaultlineError extends Error {
+    readonly code: VaultlineErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: VaultlineErrorCode, message: string, details?: Record<string, unknown>);
+    toJSON(): {
+        error: {
+            code: VaultlineErrorCode;
+            message: string;
+        };
+    };
+}
+export declare function fail(code: VaultlineErrorCode, message: string, details?: Record<string, unknown>): never;
+export declare function isVaultlineError(value: unknown): value is VaultlineError;
+/** Safe wire/log shape. Unknown failures are never echoed with a stack. */
+export declare function errorPayload(error: unknown): {
+    error: {
+        code: VaultlineErrorCode;
+        message: string;
+    };
+};

package/dist/src/errors.js

@@ -0,0 +1,23 @@
+export class VaultlineError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "VaultlineError";
+        this.code = code;
+        this.details = details;
+    }
+    toJSON() { return { error: { code: this.code, message: this.message, ...this.details } }; }
+}
+export function fail(code, message, details) {
+    throw new VaultlineError(code, message, details);
+}
+export function isVaultlineError(value) {
+    return value instanceof VaultlineError;
+}
+/** Safe wire/log shape. Unknown failures are never echoed with a stack. */
+export function errorPayload(error) {
+    if (isVaultlineError(error))
+        return error.toJSON();
+    return { error: { code: "internal", message: error instanceof Error ? error.message : "Unexpected error" } };
+}

package/dist/src/heartbeat.d.ts

@@ -0,0 +1,89 @@
+import type { UploadOptions, UploadOutcome } from "./upload.js";
+import type { offloadArchives } from "./offload.js";
+/**
+ * The background service's sign of life.
+ *
+ * A service you cannot see is one you cannot trust, especially one that moves your
+ * files. This is the single fact every surface reads to answer "is it running, and
+ * what did it just do" — the CLI, the local API, the dashboard, and any menu-bar
+ * shell built later all read this one file rather than inventing their own idea of
+ * liveness.
+ */
+export type Heartbeat = {
+    version: 1;
+    pid: number;
+    startedAt: string;
+    lastTickAt: string;
+    /** Wall-clock gap the service aims for, so a reader can judge whether it is late. */
+    intervalMs: number;
+    totals: {
+        archived: number;
+        uploaded: number;
+        reclaimed: number;
+        failed: number;
+    };
+    last: {
+        archived: number;
+        uploaded: number;
+        reclaimed: number;
+        failed: number;
+        notes: string[];
+    };
+    paused: boolean;
+    watching: string[];
+};
+export declare const heartbeatPath: (dataDir: string) => string;
+export declare function writeHeartbeat(dataDir: string, beat: Heartbeat): Promise<void>;
+export declare function readHeartbeat(dataDir: string): Promise<Heartbeat | null>;
+export type Liveness = {
+    state: "running" | "late" | "stopped" | "never-started";
+    /** Human-facing sentence. Same wording everywhere it appears. */
+    detail: string;
+    lastTickAt?: string;
+    secondsSinceTick?: number;
+    paused?: boolean;
+    totals?: Heartbeat["totals"];
+};
+/** True when a process with this id exists and we may signal it. */
+export declare function processAlive(pid: number): boolean;
+/**
+ * Judges liveness from the heartbeat alone, so it works across processes and
+ * reboots. A tick more than three intervals old counts as late rather than running:
+ * better to say "something is wrong" than to imply everything is fine.
+ */
+export declare function liveness(beat: Heartbeat | null, now?: number, alive?: typeof processAlive): Liveness;
+export type UploadOffloadOutcome = {
+    uploaded: UploadOutcome[];
+    failed: {
+        archiveId: string;
+        error: string;
+    }[];
+    skipped: number;
+    /** Archives whose local sealed blob was removed because the verify just landed. */
+    offloaded: string[];
+    /** Local bytes given back by offloading verified copies as the pass went. */
+    freedBytes: number;
+};
+/**
+ * The daemon's upload pass, finished properly: upload, verify, then offload.
+ *
+ * `uploadPending` alone leaves a sealed local copy of every archive it just
+ * proved the bucket holds — on the machines this product is for, that is the
+ * disk staying exactly as full as before. The dashboard's push already does
+ * the whole job (see `runUploads` in local-api.ts): the moment an archive's
+ * verify lands, its local blob is a duplicate, and offloading it right then
+ * lets a full disk breathe with each verify instead of never.
+ *
+ * Offload failure is tolerated per archive: the upload is still verified and
+ * recorded, and the next offload sweep gets another chance. `freshlyVerified`
+ * is what keeps this cheap — the verify happened milliseconds ago, so the
+ * usual fetch-and-hash re-proof would double the egress of every push.
+ *
+ * Integration note: src/daemon.ts's tick still calls bare `uploadPending`;
+ * switching it to this function is the remaining wiring (daemon.ts is outside
+ * this change's file list).
+ */
+export declare function uploadAndOffloadPending(dataDir: string, options?: UploadOptions & {
+    offload?: typeof offloadArchives;
+}): Promise<UploadOffloadOutcome>;
+export declare function describeGap(seconds: number): string;

package/dist/src/heartbeat.js

@@ -0,0 +1,120 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+export const heartbeatPath = (dataDir) => join(dataDir, "daemon-state.json");
+export async function writeHeartbeat(dataDir, beat) {
+    const path = heartbeatPath(dataDir);
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(beat, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, path);
+}
+export async function readHeartbeat(dataDir) {
+    try {
+        return JSON.parse(await readFile(heartbeatPath(dataDir), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a process with this id exists and we may signal it. */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * Judges liveness from the heartbeat alone, so it works across processes and
+ * reboots. A tick more than three intervals old counts as late rather than running:
+ * better to say "something is wrong" than to imply everything is fine.
+ */
+export function liveness(beat, now = Date.now(), alive = processAlive) {
+    // Phrased as a fact rather than an instruction, because this string is read
+    // in a browser as often as in a terminal, and "never started" is not a
+    // problem to fix — archiving by hand from the Sessions page is a complete way
+    // to use this. The command is offered as the alternative it is.
+    if (!beat)
+        return { state: "never-started", detail: "Automatic archiving is off — Sealkeep only archives what you choose. Turn it on in Settings." };
+    const secondsSinceTick = Math.max(0, Math.round((now - Date.parse(beat.lastTickAt)) / 1000));
+    const late = now - Date.parse(beat.lastTickAt) > Math.max(beat.intervalMs * 3, 90_000);
+    const running = alive(beat.pid);
+    if (!running) {
+        return { state: "stopped", detail: `Not running. It last checked ${describeGap(secondsSinceTick)}.`, lastTickAt: beat.lastTickAt, secondsSinceTick, paused: beat.paused, totals: beat.totals };
+    }
+    if (late) {
+        return { state: "late", detail: `Running, but its last check was ${describeGap(secondsSinceTick)} — longer than expected.`, lastTickAt: beat.lastTickAt, secondsSinceTick, paused: beat.paused, totals: beat.totals };
+    }
+    return {
+        state: "running",
+        detail: beat.paused ? "Running but paused; no work is being done." : `Running. Last checked ${describeGap(secondsSinceTick)}.`,
+        lastTickAt: beat.lastTickAt, secondsSinceTick, paused: beat.paused, totals: beat.totals
+    };
+}
+/**
+ * The daemon's upload pass, finished properly: upload, verify, then offload.
+ *
+ * `uploadPending` alone leaves a sealed local copy of every archive it just
+ * proved the bucket holds — on the machines this product is for, that is the
+ * disk staying exactly as full as before. The dashboard's push already does
+ * the whole job (see `runUploads` in local-api.ts): the moment an archive's
+ * verify lands, its local blob is a duplicate, and offloading it right then
+ * lets a full disk breathe with each verify instead of never.
+ *
+ * Offload failure is tolerated per archive: the upload is still verified and
+ * recorded, and the next offload sweep gets another chance. `freshlyVerified`
+ * is what keeps this cheap — the verify happened milliseconds ago, so the
+ * usual fetch-and-hash re-proof would double the egress of every push.
+ *
+ * Integration note: src/daemon.ts's tick still calls bare `uploadPending`;
+ * switching it to this function is the remaining wiring (daemon.ts is outside
+ * this change's file list).
+ */
+export async function uploadAndOffloadPending(dataDir, options = {}) {
+    // Imported lazily, like the paths local-api takes: this module is read by
+    // every surface that asks "is the service alive", none of which should pay
+    // for the provider stack.
+    const [{ uploadArchive }, { listArchives }, { isV2 }] = await Promise.all([
+        import("./upload.js"), import("./vault.js"), import("./types.js")
+    ]);
+    const { offload: injectedOffload, ...uploadOptions } = options;
+    const offload = injectedOffload ?? (await import("./offload.js")).offloadArchives;
+    const records = await listArchives(dataDir);
+    const uploaded = [];
+    const failed = [];
+    const offloaded = [];
+    let freedBytes = 0;
+    for (const record of records) {
+        if (isV2(record) && record.remote?.verifiedAt)
+            continue;
+        try {
+            uploaded.push(await uploadArchive(dataDir, record.id, uploadOptions));
+        }
+        catch (error) {
+            failed.push({ archiveId: record.id, error: error instanceof Error ? error.message : "upload failed" });
+            continue;
+        }
+        try {
+            const outcome = await offload(dataDir, { confirm: true, only: new Set([record.id]), freshlyVerified: new Set([record.id]) });
+            if (outcome.mode === "apply") {
+                freedBytes += outcome.freedBytes;
+                offloaded.push(...outcome.offloaded.map((item) => item.id));
+            }
+        }
+        catch { /* offload is a bonus on this pass; the sweep gets another chance */ }
+    }
+    return { uploaded, failed, skipped: records.length - uploaded.length - failed.length, offloaded, freedBytes };
+}
+export function describeGap(seconds) {
+    if (seconds < 5)
+        return "just now";
+    if (seconds < 90)
+        return `${seconds}s ago`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 90)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    return hours < 48 ? `${hours}h ago` : `${Math.round(hours / 24)}d ago`;
+}

package/dist/src/index-sync.d.ts

@@ -0,0 +1,53 @@
+import type { Envelope } from "../packages/vaultline-crypto/src/index.js";
+import { type ChunkStoreClient } from "./chunk-store.js";
+/**
+ * The content index travels, sealed — Paul's question answered structurally.
+ *
+ * The index is what makes search a ranged fetch instead of a bulk restore,
+ * and it is built locally because building it requires the phrase. Locally
+ * built used to mean locally trapped: a second machine — or a teammate on the
+ * same storage — had nothing to search until it downloaded and decrypted the
+ * whole history to rebuild its own. So the index now syncs like everything
+ * else does: as ciphertext. Two small objects in the storage —
+ *
+ *   …/index.vlmeta     the index's ENVELOPE (tiny; carries builtAt, so
+ *                      "is theirs newer than mine" costs one small GET)
+ *   …/index.vlindex    the sealed index itself
+ *
+ * — and the recovery phrase, which every machine of the vault holds, opens
+ * them. The provider learns that an index exists and when it changed;
+ * never a token of it.
+ *
+ * Free / Pro Lite (own bucket): the two objects live under the configured
+ * prefix, in a segment that follows the vault's naming mode (hashed vaults
+ * hash it). Pro (managed): the control plane vends signed PUT/GET for a
+ * per-account index slot — same signer, known lengths — via cloud.ts.
+ */
+export type RemoteIndexStore = {
+    /** The remote envelope, or null when no index was ever pushed. */
+    meta(): Promise<Envelope | null>;
+    pull(): Promise<Buffer>;
+    push(envelope: Envelope, ciphertext: Buffer): Promise<void>;
+};
+/** The store for an own-bucket vault, over the provider's plain object verbs. */
+export declare function byoIndexStore(dataDir: string, phrase: string, injected?: ChunkStoreClient, targetOverride?: {
+    provider: "s3" | "r2" | "b2" | "gcs" | "gdrive" | "vaultline";
+    bucket: string;
+    prefix: string;
+    region?: string;
+}): Promise<RemoteIndexStore>;
+/** The store for a managed vault, through the control plane's signed index slot. */
+export declare function managedIndexStore(dataDir: string): Promise<RemoteIndexStore>;
+/** Picks the right store for this vault, or null when there is nowhere to sync. */
+export declare function remoteIndexStoreFor(dataDir: string, phrase: string, injected?: ChunkStoreClient): Promise<RemoteIndexStore | null>;
+/**
+ * Pulls the remote index when it is newer than what this machine holds.
+ * Freshness is the envelope's own createdAt — one tiny GET decides, and the
+ * blob only moves when it would change something.
+ */
+export declare function pullIndexIfNewer(dataDir: string, store: RemoteIndexStore, localBuiltAt: string | null, save: (envelope: Envelope, ciphertext: Buffer) => Promise<void>): Promise<{
+    pulled: boolean;
+    remoteBuiltAt: string | null;
+}>;
+/** Reads the local sealed index's envelope, for freshness comparison. */
+export declare function localIndexBuiltAt(envelopePath: string): Promise<string | null>;

package/dist/src/index-sync.js

@@ -0,0 +1,147 @@
+import { readFile } from "node:fs/promises";
+import { fail } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { readConfig } from "./vault.js";
+import { uploadClientFromStore } from "./providers/index.js";
+import { folderNamingKey, storageScopeOf } from "./chunk-store.js";
+import { createHmac } from "node:crypto";
+const INDEX_SEGMENT = "vaultline-index";
+function indexKeys(prefix, naming, namingKey) {
+    const clean = prefix.replace(/^\/+|\/+$/g, "");
+    const segment = naming === "hashed" && namingKey
+        ? createHmac("sha256", namingKey).update("segment:vaultline-index").digest("hex").slice(0, 16)
+        : INDEX_SEGMENT;
+    return { meta: `${clean}/${segment}/index.vlmeta`, blob: `${clean}/${segment}/index.vlindex` };
+}
+/** The store for an own-bucket vault, over the provider's plain object verbs. */
+export async function byoIndexStore(dataDir, phrase, injected, targetOverride) {
+    const config = await readConfig(dataDir);
+    const remoteStorage = targetOverride ?? config.remoteStorage ?? fail("storage_not_configured", "No remote target configured, so the index has nowhere to sync");
+    if (remoteStorage.provider === "vaultline")
+        fail("invalid_argument", "Managed vaults sync their index through the control plane, not the object store");
+    const raw = injected ?? (await uploadClientFromStore(dataDir, config.vaultId, remoteStorage));
+    if (typeof raw.putObject !== "function" || typeof raw.getObject !== "function" || typeof raw.headObject !== "function") {
+        fail("invalid_argument", `The ${remoteStorage.provider} client cannot sync the index`);
+    }
+    const naming = config.remoteNaming ?? "hashed";
+    const keys = indexKeys(remoteStorage.prefix, naming, naming === "hashed" ? folderNamingKey(phrase, storageScopeOf(remoteStorage)) : null);
+    return {
+        meta: async () => {
+            const head = await raw.headObject(keys.meta);
+            if (!head.exists)
+                return null;
+            return JSON.parse((await raw.getObject(keys.meta)).toString("utf8"));
+        },
+        pull: () => raw.getObject(keys.blob),
+        push: async (envelope, ciphertext) => {
+            // Blob first, envelope second: a reader that sees the new envelope can
+            // always fetch the blob it describes; the reverse order has a window
+            // where the meta promises an index the bucket does not hold yet.
+            await raw.putObject(keys.blob, ciphertext);
+            await raw.putObject(keys.meta, Buffer.from(JSON.stringify(envelope), "utf8"));
+        }
+    };
+}
+/** The store for a managed vault, through the control plane's signed index slot. */
+export async function managedIndexStore(dataDir) {
+    const cloud = await import("./cloud.js");
+    if (typeof cloud.pullIndexObject !== "function" || typeof cloud.pushIndexObject !== "function") {
+        fail("invalid_argument", "This build's control plane client cannot sync the index yet");
+    }
+    return {
+        meta: async () => {
+            const body = await cloud.pullIndexObject(dataDir, "meta");
+            return body ? JSON.parse(body.toString("utf8")) : null;
+        },
+        pull: async () => {
+            const body = await cloud.pullIndexObject(dataDir, "blob");
+            if (!body)
+                fail("archive_not_found", "No index has been pushed to managed storage yet");
+            return body;
+        },
+        push: async (envelope, ciphertext) => {
+            await cloud.pushIndexObject(dataDir, "blob", ciphertext);
+            await cloud.pushIndexObject(dataDir, "meta", Buffer.from(JSON.stringify(envelope), "utf8"));
+        }
+    };
+}
+/** Picks the right store for this vault, or null when there is nowhere to sync. */
+export async function remoteIndexStoreFor(dataDir, phrase, injected) {
+    const config = await readConfig(dataDir);
+    // Multi-target vaults keep ONE phonebook, on the most durable target:
+    // managed when present, else the first bucket that can hold objects.
+    if (config.storageTargets && config.storageTargets.length > 0) {
+        const managed = config.storageTargets.find((target) => target.provider === "vaultline");
+        if (managed) {
+            try {
+                return await managedIndexStore(dataDir);
+            }
+            catch {
+                return null;
+            }
+        }
+        const byo = config.storageTargets.find((target) => target.provider !== "gdrive");
+        if (!byo)
+            return null;
+        try {
+            return await byoIndexStore(dataDir, phrase, injected, { provider: byo.provider, bucket: byo.bucket ?? "", prefix: byo.prefix ?? "vaultline", ...(byo.region ? { region: byo.region } : {}) });
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!config.remoteStorage) {
+        // An enrolled managed vault has a cloud token and no remoteStorage entry —
+        // same rule as storedCopiesMode. Without the token there is nowhere to sync.
+        try {
+            const { cloudToken } = await import("./cloud.js");
+            await cloudToken(dataDir);
+            return await managedIndexStore(dataDir);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (config.remoteStorage.provider === "vaultline") {
+        try {
+            return await managedIndexStore(dataDir);
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        return await byoIndexStore(dataDir, phrase, injected);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pulls the remote index when it is newer than what this machine holds.
+ * Freshness is the envelope's own createdAt — one tiny GET decides, and the
+ * blob only moves when it would change something.
+ */
+export async function pullIndexIfNewer(dataDir, store, localBuiltAt, save) {
+    const envelope = await store.meta();
+    if (!envelope)
+        return { pulled: false, remoteBuiltAt: null };
+    const remoteBuiltAt = envelope.manifest?.createdAt ?? null;
+    if (!remoteBuiltAt || (localBuiltAt && Date.parse(remoteBuiltAt) <= Date.parse(localBuiltAt))) {
+        return { pulled: false, remoteBuiltAt };
+    }
+    const ciphertext = await store.pull();
+    await save(envelope, ciphertext);
+    await recordAudit(dataDir, "archive.restore", "allowed", { indexPulled: true, remoteBuiltAt }).catch(() => undefined);
+    return { pulled: true, remoteBuiltAt };
+}
+/** Reads the local sealed index's envelope, for freshness comparison. */
+export async function localIndexBuiltAt(envelopePath) {
+    try {
+        const envelope = JSON.parse(await readFile(envelopePath, "utf8"));
+        return envelope.manifest?.createdAt ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/leakscan.d.ts

@@ -0,0 +1,48 @@
+export type Finding = {
+    kind: string;
+    /** 1-based, matching what editors and `sed -n` call a line. */
+    line: number;
+    /** 1-based offset of the secret itself, not of any surrounding assignment. */
+    column: number;
+    /** Masked — see maskSecret. Never the secret. */
+    preview: string;
+    severity: "high" | "medium";
+};
+export type FileFinding = Finding & {
+    file: string;
+};
+export type ScanReport = {
+    files: number;
+    findings: FileFinding[];
+    high: number;
+    medium: number;
+    /** 1 when any high finding exists, so `sealkeep scan … && seal` works as a gate. */
+    exitCode: 0 | 1;
+};
+/**
+ * First four characters, then only the length. A leak report that repeats the
+ * leak is a second leak: findings travel further than the transcript did —
+ * terminals, CI logs, screenshots, phase-2 metadata — so the preview carries
+ * just enough to locate the match and never enough to use it.
+ */
+export declare function maskSecret(secret: string): string;
+/** Character-frequency Shannon entropy, in bits per character. */
+export declare function shannonEntropy(value: string): number;
+/** Tests derive their vectors from these rather than restating the numbers. */
+export declare const GENERIC_MIN_LENGTH = 24;
+export declare const GENERIC_ENTROPY_THRESHOLD = 4.2;
+export declare function scanText(text: string): Finding[];
+/**
+ * Line-by-line over a read stream: memory is bounded by the longest single
+ * line, never by the file, so a multi-GB jsonl scans in the same footprint as
+ * a small one. An unreadable input rejects — a scanner that swallows a read
+ * error would be reporting "clean" about bytes it never saw.
+ */
+export declare function scanFileStreaming(path: string, onFinding?: (finding: Finding) => void): Promise<Finding[]>;
+/**
+ * A file is scanned as pointed at, whatever its name; a directory means every
+ * *.jsonl beneath it. Only high findings set the exit code — failing a script
+ * over a "medium" suspicion is exactly the cry-wolf behaviour the severity
+ * split exists to avoid.
+ */
+export declare function scanPath(target: string, onFinding?: (finding: FileFinding) => void): Promise<ScanReport>;