sealkeep 0.5.0

package/dist/src/mnemonic.js

@@ -0,0 +1,134 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { fail } from "./errors.js";
+import { BIP39_ENGLISH } from "./bip39-wordlist.js";
+/**
+ * Transcribable recovery phrases, in the format the rest of the world already
+ * uses.
+ *
+ * A recovery phrase is written on paper by a person under stress, months before
+ * it matters, and typed back on a different machine. Base64 fails all three
+ * tests. Words do not: they survive bad handwriting, they can be read aloud,
+ * and a checksum catches the transcription mistakes people actually make.
+ *
+ * This used to be a bespoke 256-word list, which worked but left the phrase
+ * marooned in one program. BIP-39 is the same idea with an installed base:
+ * hardware wallets, steel backup plates, password managers and phone apps all
+ * know how to hold these words, and people who have done this before recognise
+ * them on sight. Twenty-four words carry 256 bits of entropy; twelve carry 128
+ * and are accepted for people who want a shorter thing to write down.
+ *
+ * What this does *not* mean is that a wallet can open an archive. A wallet is
+ * somewhere to keep the words, not a second key: Sealkeep still derives its
+ * key from the phrase with scrypt and a per-vault salt, which is deliberately
+ * slower and better salted than BIP-39's own seed derivation. Anyone claiming
+ * otherwise is selling something.
+ *
+ * The list is frozen by the specification and verified by test rather than
+ * trusted, because one altered word would produce phrases no other tool reads.
+ */
+export const WORDS = BIP39_ENGLISH;
+/** 256 bits, so twenty-four words. Twelve-word phrases are read but not issued. */
+export const ENTROPY_BYTES = 32;
+export const PHRASE_WORDS = 24;
+/** The entropy sizes BIP-39 defines, and the word count each produces. */
+const SIZES = [16, 20, 24, 28, 32].map((bytes) => ({ bytes, words: (bytes * 8 + (bytes * 8) / 32) / 11 }));
+const INDEX = new Map(WORDS.map((word, index) => [word, index]));
+/** Normalizes what a person actually types: stray case, punctuation, and runs of spaces. */
+export function normalize(phrase) {
+    return phrase.toLowerCase().replace(/[^a-z\s-]/g, " ").split(/[\s-]+/).filter(Boolean);
+}
+/** The BIP-39 checksum: the leading ENT/32 bits of SHA-256 over the entropy. */
+function checksumBits(entropy) {
+    const bits = (entropy.length * 8) / 32;
+    const digest = createHash("sha256").update(entropy).digest();
+    return [...digest].map((byte) => byte.toString(2).padStart(8, "0")).join("").slice(0, bits);
+}
+export function entropyToPhrase(entropy) {
+    if (!SIZES.some((size) => size.bytes === entropy.length)) {
+        fail("invalid_argument", `A recovery phrase needs ${SIZES.map((size) => size.bytes).join(", ")} bytes of entropy, not ${entropy.length}`);
+    }
+    const bits = [...entropy].map((byte) => byte.toString(2).padStart(8, "0")).join("") + checksumBits(entropy);
+    const words = [];
+    for (let at = 0; at < bits.length; at += 11)
+        words.push(WORDS[parseInt(bits.slice(at, at + 11), 2)]);
+    return words.join(" ");
+}
+export function generateRecoveryPhrase() {
+    return entropyToPhrase(randomBytes(ENTROPY_BYTES));
+}
+/** Words within one edit of the given word, so a typo gets a suggestion rather than a shrug. */
+export function suggestions(word, limit = 3) {
+    const distance = (a, b) => {
+        const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+        for (let column = 0; column <= b.length; column += 1)
+            rows[0][column] = column;
+        for (let i = 1; i <= a.length; i += 1) {
+            for (let j = 1; j <= b.length; j += 1) {
+                rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            }
+        }
+        return rows[a.length][b.length];
+    };
+    // BIP-39 guarantees the first four letters identify a word, so a prefix match
+    // is a better guess than raw edit distance and is tried first.
+    const prefix = word.slice(0, 4);
+    const byPrefix = prefix.length === 4 ? WORDS.filter((candidate) => candidate.startsWith(prefix)) : [];
+    const byDistance = WORDS.map((candidate) => ({ candidate, score: distance(word, candidate) }))
+        .filter((entry) => entry.score <= 2)
+        .sort((a, b) => a.score - b.score || a.candidate.localeCompare(b.candidate))
+        .map((entry) => entry.candidate);
+    return [...new Set([...byPrefix, ...byDistance])].slice(0, limit);
+}
+/**
+ * Explains exactly what is wrong with a phrase, because "invalid" is useless to
+ * someone holding a piece of paper. Unknown words get spelling suggestions; a
+ * checksum failure means a word is in the wrong place or was misread.
+ */
+export function inspectPhrase(phrase) {
+    const words = normalize(phrase);
+    const problems = [];
+    const size = SIZES.find((candidate) => candidate.words === words.length);
+    if (!size) {
+        // Leads with 24 because that is what this build issues, so it is what the
+        // reader almost certainly has on paper. The shorter lengths are accepted
+        // from other tools and are mentioned second rather than as equal options.
+        const others = SIZES.map((candidate) => candidate.words).filter((count) => count !== PHRASE_WORDS);
+        problems.push(`Expected ${PHRASE_WORDS} words, found ${words.length}. (${others.join(", ")} are also accepted.)`);
+    }
+    for (const [position, word] of words.entries()) {
+        if (INDEX.has(word))
+            continue;
+        const near = suggestions(word);
+        problems.push(`Word ${position + 1} "${word}" is not in the list.${near.length ? ` Did you mean ${near.join(", ")}?` : ""}`);
+    }
+    if (problems.length > 0)
+        return { valid: false, words, problems };
+    const bits = words.map((word) => INDEX.get(word).toString(2).padStart(11, "0")).join("");
+    const entropy = Buffer.from((bits.slice(0, size.bytes * 8).match(/.{8}/g) ?? []).map((byte) => parseInt(byte, 2)));
+    const expected = Buffer.from(checksumBits(entropy));
+    const presented = Buffer.from(bits.slice(size.bytes * 8));
+    if (expected.length !== presented.length || !timingSafeEqual(expected, presented)) {
+        problems.push("The words are all valid but the checksum does not match, so one is misread or out of order.");
+        return { valid: false, words, problems };
+    }
+    return { valid: true, words, problems };
+}
+/** True when a phrase is one this build generated. Older free-text phrases return false. */
+export function isMnemonic(phrase) {
+    return inspectPhrase(phrase).valid;
+}
+/**
+ * The form a phrase takes before any key is derived from it.
+ *
+ * People read words off paper and type them back with different capitalisation and
+ * spacing. Deriving a key from the raw string would reject a correct phrase for
+ * cosmetic reasons — the worst possible failure for a recovery flow. A recognised
+ * word phrase is therefore reduced to canonical lowercase, single-spaced form.
+ *
+ * Anything that is not a valid word phrase passes through untouched, because vaults
+ * created before the word list hold arbitrary text whose exact bytes are the secret.
+ */
+export function canonicalPhrase(phrase) {
+    const candidate = normalize(phrase).join(" ");
+    return inspectPhrase(candidate).valid ? candidate : phrase;
+}

package/dist/src/net.d.ts

@@ -0,0 +1,2 @@
+/** Picks the first free port at or above `preferred` so local services never fight over one. */
+export declare function freePort(preferred: number, host?: string, attempts?: number): Promise<number>;

package/dist/src/net.js

@@ -0,0 +1,16 @@
+import { createConnection } from "node:net";
+function isBusy(port, host) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host, port });
+        socket.once("connect", () => { socket.destroy(); resolve(true); });
+        socket.once("error", () => resolve(false));
+    });
+}
+/** Picks the first free port at or above `preferred` so local services never fight over one. */
+export async function freePort(preferred, host = "127.0.0.1", attempts = 100) {
+    for (let offset = 0; offset < attempts; offset += 1) {
+        if (!(await isBusy(preferred + offset, host)))
+            return preferred + offset;
+    }
+    throw new Error(`No free port found between ${preferred} and ${preferred + attempts - 1}`);
+}

package/dist/src/notify.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Native notifications, with no dependency and no daemon of its own.
+ *
+ * These are the only moments the product interrupts you, so they are rationed:
+ * something was preserved, disk came back, or something needs a decision. Text is
+ * counts and outcomes — never a file's contents, never a path from a transcript,
+ * never a secret — because a notification lands on a lock screen where anyone can
+ * read it.
+ */
+export type Notification = {
+    title: string;
+    body: string;
+};
+export type NotifyOptions = {
+    enabled?: boolean;
+    platform?: NodeJS.Platform;
+    /** Injected in tests so no real notification is raised. */
+    exec?: (file: string, args: string[]) => Promise<unknown>;
+    env?: NodeJS.ProcessEnv;
+};
+/** Off by an explicit opt-out, and off automatically where there is no desktop session. */
+export declare function notificationsEnabled(env?: NodeJS.ProcessEnv, target?: NodeJS.Platform): boolean;
+/** Nothing here is interpolated into a shell; every value is passed as an argument. */
+export declare function notify(notification: Notification, options?: NotifyOptions): Promise<boolean>;
+export type TickSummary = {
+    archived: number;
+    uploaded: number;
+    reclaimed: number;
+    failed: number;
+    freedBytes?: number;
+};
+/**
+ * Decides whether a round of work is worth interrupting someone for.
+ *
+ * Routine sealing is not: it happens constantly and saying so would train people to
+ * ignore the product. Reclaimed disk is, because a file moved. A failure is, because
+ * it needs a decision.
+ */
+export declare function summarize(tick: TickSummary): Notification | null;
+/** Keeps a quiet period between notifications so a busy machine cannot spam. */
+export declare class NotificationGate {
+    private readonly quietMs;
+    private lastAt;
+    constructor(quietMs?: number);
+    allow(now: number, urgent?: boolean): boolean;
+}

package/dist/src/notify.js

@@ -0,0 +1,84 @@
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+const run = (file, args) => new Promise((resolve) => execFile(file, args, () => resolve()));
+/** Off by an explicit opt-out, and off automatically where there is no desktop session. */
+export function notificationsEnabled(env = process.env, target = platform()) {
+    if (env.VAULTLINE_NOTIFICATIONS === "off")
+        return false;
+    if (target === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return false;
+    return target === "darwin" || target === "linux" || target === "win32";
+}
+/** Nothing here is interpolated into a shell; every value is passed as an argument. */
+export async function notify(notification, options = {}) {
+    const target = options.platform ?? platform();
+    const env = options.env ?? process.env;
+    if (options.enabled === false || (options.enabled === undefined && !notificationsEnabled(env, target)))
+        return false;
+    const exec = options.exec ?? run;
+    const title = notification.title.slice(0, 120);
+    const body = notification.body.slice(0, 240);
+    if (target === "darwin") {
+        const quote = (value) => value.replace(/[\\"]/g, "\\$&");
+        await exec("osascript", ["-e", `display notification "${quote(body)}" with title "${quote(title)}"`]);
+        return true;
+    }
+    if (target === "linux") {
+        await exec("notify-send", ["--app-name=Sealkeep", "--icon=drive-harddisk", title, body]);
+        return true;
+    }
+    if (target === "win32") {
+        const script = `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
+$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode($env:VL_TITLE)) > $null
+$xml.GetElementsByTagName('text')[1].AppendChild($xml.CreateTextNode($env:VL_BODY)) > $null
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Sealkeep').Show([Windows.UI.Notifications.ToastNotification]::new($xml))`;
+        await exec("powershell", ["-NoProfile", "-NonInteractive", "-Command", script]);
+        return true;
+    }
+    return false;
+}
+function bytes(value) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let size = value;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? size : size.toFixed(1)} ${units[unit]}`;
+}
+/**
+ * Decides whether a round of work is worth interrupting someone for.
+ *
+ * Routine sealing is not: it happens constantly and saying so would train people to
+ * ignore the product. Reclaimed disk is, because a file moved. A failure is, because
+ * it needs a decision.
+ */
+export function summarize(tick) {
+    if (tick.failed > 0) {
+        return { title: "Sealkeep needs attention", body: `${tick.failed} session${tick.failed === 1 ? "" : "s"} could not be archived. Run \`sealkeep doctor\`.` };
+    }
+    if (tick.reclaimed > 0) {
+        const freed = tick.freedBytes ? ` and freed ${bytes(tick.freedBytes)}` : "";
+        return { title: "Disk reclaimed", body: `Moved ${tick.reclaimed} archived session${tick.reclaimed === 1 ? "" : "s"} to the trash${freed}. The archives are safe.` };
+    }
+    if (tick.archived >= 5) {
+        return { title: "Sessions preserved", body: `Sealed ${tick.archived} agent sessions${tick.uploaded ? `, ${tick.uploaded} copied off this machine` : ""}.` };
+    }
+    return null;
+}
+/** Keeps a quiet period between notifications so a busy machine cannot spam. */
+export class NotificationGate {
+    quietMs;
+    lastAt = 0;
+    constructor(quietMs = 15 * 60_000) {
+        this.quietMs = quietMs;
+    }
+    allow(now, urgent = false) {
+        if (!urgent && now - this.lastAt < this.quietMs)
+            return false;
+        this.lastAt = now;
+        return true;
+    }
+}

package/dist/src/offload.d.ts

@@ -0,0 +1,117 @@
+import { type ArchiveRecord } from "./types.js";
+import { createActiveLease } from "./providers/index.js";
+/**
+ * Removing the local copy of an archive that lives in a bucket.
+ *
+ * Reclaiming a source is only half of freeing a disk. The sealed archive stays
+ * behind, and on real transcripts it is about two thirds of what it replaced —
+ * measured, not assumed: a 1.6 GB Codex rollout compresses 1.5x. So a machine
+ * with 78 GB of sessions that archives and reclaims all of them keeps roughly
+ * 54 GB of archives and gets back about a quarter of what the product implied.
+ *
+ * Offloading finishes the job: once the bucket has a verified copy, the local
+ * one is redundant, and restoring downloads it back. Nothing is lost — but the
+ * archive stops being reachable while offline, which is a real trade and the
+ * reason this is opt-in and never automatic.
+ *
+ * The bar for removing a local archive is deliberately higher than for
+ * reclaiming a source: a source that was reclaimed can still be recovered from
+ * the trash, while an archive removed without a genuine remote copy is gone.
+ */
+/**
+ * Just enough of a provider client to read an archive back. Injectable for the
+ * same reason `uploadArchive` takes one: the path that decides whether an
+ * offloaded archive can be recovered has to be testable without a bucket.
+ */
+export type FetchClient = {
+    download?: (lease: ReturnType<typeof createActiveLease>) => Promise<Buffer>;
+};
+export type OffloadCandidate = {
+    id: string;
+    agent: string;
+    path: string;
+    /** What removing the local copy would give back. */
+    localBytes: number;
+    provider: string;
+    bucket: string;
+    objectKey: string;
+};
+export type OffloadBlocked = {
+    id: string;
+    reason: string;
+};
+export declare function offloadable(dataDir: string): Promise<{
+    candidates: OffloadCandidate[];
+    blocked: OffloadBlocked[];
+    freeableBytes: number;
+}>;
+/**
+ * Removes local archives that a bucket has a verified copy of.
+ *
+ * A dry run unless confirmed. The candidate list is recomputed here rather than
+ * accepted from a caller, so a page held open since yesterday cannot ask for
+ * the deletion of something that has since become the only copy.
+ */
+export declare function offloadArchives(dataDir: string, options?: {
+    confirm?: boolean;
+    client?: FetchClient;
+    only?: ReadonlySet<string>;
+    freshlyVerified?: ReadonlySet<string>;
+}): Promise<{
+    mode: "preview";
+    wouldOffload: OffloadCandidate[];
+    blocked: OffloadBlocked[];
+    freedBytes: number;
+    offloaded?: undefined;
+    failed?: undefined;
+} | {
+    mode: "apply";
+    offloaded: OffloadCandidate[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+    blocked: OffloadBlocked[];
+    freedBytes: number;
+    wouldOffload?: undefined;
+}>;
+/**
+ * Asks the storage, right now, whether it still holds this archive.
+ *
+ * `remote.verifiedAt` says the copy was proven once; between then and now is
+ * exactly where a bucket lifecycle rule or a fat-fingered console delete
+ * lives. This is the question a person asks before trusting the cloud copy
+ * enough to trash the original — so it goes to the provider, not to our own
+ * records, and it compares the size the provider reports against the size we
+ * recorded. It does not re-download the object: the byte-level proof already
+ * ran when the copy was verified, and runs again on any restore (AEAD refuses
+ * corrupt bytes). What this rules out is the copy being gone or truncated.
+ */
+export type CopyCheck = {
+    ok: boolean;
+    provider: string;
+    bytes: number;
+    checkedAt: string;
+    detail: string;
+};
+export declare function checkRemoteCopy(dataDir: string, archiveId: string, client?: FetchClient): Promise<CopyCheck>;
+/**
+ * The bulk form of `checkRemoteCopy`. Managed rows share ONE control-plane
+ * listing instead of asking per archive — checking a 53-row vault is one call
+ * plus a HEAD per own-bucket object, not 53 round trips.
+ */
+export declare function checkRemoteCopyMany(dataDir: string, ids: readonly string[], client?: FetchClient): Promise<CopyCheck[]>;
+export type Materialised = {
+    path: string;
+    release: () => Promise<void>;
+};
+/**
+ * Gives back a local path holding this archive's ciphertext, fetching it first
+ * if the local copy was offloaded.
+ *
+ * Restoring reads the object twice — once to hash it, once to decrypt it — so
+ * it needs a file, not a buffer. An offloaded archive is written to a temporary
+ * one and removed afterwards, which keeps the disk saving intact: the bytes are
+ * on this machine only for as long as the restore takes.
+ */
+export declare function materialiseArchive(dataDir: string, record: ArchiveRecord, client?: FetchClient): Promise<Materialised>;