sealkeep 0.5.0

package/dist/src/types.js

@@ -0,0 +1,3 @@
+export function isV2(record) {
+    return record.version === 2;
+}

package/dist/src/ui-server.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The name to show a person, as opposed to the address to bind.
+ *
+ * `http://127.0.0.1:54142` is a correct URL and a terrible one: it looks like
+ * something has gone wrong, it cannot be read out loud, and the port changed
+ * every run because the server asked the kernel for whatever was free. The
+ * server still binds the loopback address — nothing is exposed by naming it —
+ * but the URL people see, bookmark and type is a name and a fixed port.
+ *
+ * `localhost` rather than something prettier because it is the only name that
+ * resolves everywhere without touching the system. `vault.localhost` is
+ * resolved internally by Chrome but not by the macOS resolver, so Safari would
+ * fail on it; `vault.line` needs an /etc/hosts line, which needs a password,
+ * which is not something this should take. `sealkeep ui hostname` prints that
+ * line for anyone who wants the nicer name and is happy to install it.
+ */
+export declare const DISPLAY_HOST = "localhost";
+/**
+ * A fixed default port, so the address is the same tomorrow as it was today.
+ *
+ * 7477 spells "VLIN"-ish on a keypad, sits well above the privileged range, and
+ * is not claimed by anything in the IANA registry. When it is busy the server
+ * still falls back to a free port rather than refusing to start: a working
+ * window on an odd port beats a correct error.
+ */
+export declare const DEFAULT_UI_PORT = 7477;
+/** The hostnames this service answers to, mirrored by ALLOWED_HOSTS in local-api.ts. */
+export declare const UI_HOSTNAMES: readonly ["localhost", "127.0.0.1", "vault.line", "vault.localhost"];
+/**
+ * Where a running server announces itself, so a second `sealkeep ui` finds it.
+ *
+ * It lives in the vault's own data dir, which is what makes it per-vault: two
+ * vaults on one machine have two data dirs and never see each other's server.
+ * It holds a port and a pid — no secret — but keeps the 0600 of everything
+ * else in there rather than being the one loose file.
+ */
+export declare const uiRecordPath: (dataDir: string) => string;
+export type UiRecord = {
+    port: number;
+    pid: number;
+    startedAt: string;
+};
+/** Anything unreadable, truncated, or not describing a usable port reads as "no server", never as an error. */
+export declare function readUiRecord(dataDir: string): Promise<UiRecord | null>;
+/**
+ * Written in place rather than through a temp file and a rename: a half-written
+ * record fails to parse, and failing to parse already means "start a fresh
+ * server", which is the safe answer. Atomicity would buy nothing.
+ */
+export declare function writeUiRecord(dataDir: string, record: UiRecord): Promise<void>;
+/**
+ * Removes the record only when it still names this server's port. Two servers
+ * can exist at once (a second one starts whenever the first is unreachable),
+ * and the first to shut down must not delete the survivor's announcement.
+ */
+export declare function clearUiRecord(dataDir: string, port?: number): Promise<void>;
+/** Where a person goes. Bound on loopback, named so it can be read and typed. */
+export declare const uiOrigin: (port: number, host?: string) => string;
+/** Where this process talks to itself. Always the address, never a name that has to resolve. */
+export declare const uiProbeOrigin: (port: number) => string;
+/**
+ * How the browser gets authenticated: the token rides in the URL fragment.
+ *
+ * A fragment is the only part of a URL a browser never transmits. It is not in
+ * the request line, so it cannot reach an access log, a proxy, or a Referer
+ * header on any link the page later follows — and `web/app.js` reads it once,
+ * moves it into sessionStorage, and history.replaceState()s it out of the
+ * address bar, so it does not survive in browser history either. A `?token=`
+ * query string would have failed every one of those.
+ *
+ * The alternative — print the token and have someone paste it into the gate —
+ * is the terminal step this whole command exists to remove, and it puts the
+ * secret in scrollback, in `script` logs, and in any pasted transcript.
+ *
+ * What this does cost: the URL is an argv of the opener process, so it is
+ * visible to `ps` for the few milliseconds that process lives. That is
+ * accepted rather than overlooked — the token grants nothing that a local
+ * process running as this user does not already have, since it can read
+ * <data-dir>/local-api-token directly. Scrollback is the leak that outlives
+ * the session; argv is not.
+ */
+export declare const uiUrl: (port: number, token: string) => string;
+export type BrowserResult = {
+    opened: boolean;
+    /** The opener that ran, for a message that names what failed rather than "something went wrong". */
+    command: string | null;
+    problem?: string;
+    /** True when no browser was wanted (`--no-browser`), which is a choice, not a failure to warn about. */
+    declined?: boolean;
+};
+/**
+ * Which command opens a URL here.
+ *
+ * Three platforms, three answers, and one of them is not an executable:
+ * Windows `start` is a cmd.exe builtin, so it has to be invoked through cmd —
+ * spawning "start" directly fails with ENOENT. The empty "" that follows is
+ * `start`'s window-title argument, which it would otherwise take from a quoted
+ * URL and then open nothing.
+ *
+ * `BROWSER` is honoured first because it is the existing convention for
+ * exactly this (xdg-open reads it, as do most tools that open pages), and
+ * `BROWSER=none` is how a headless box or a CI job says "do not launch
+ * anything" — answered here with null, which callers degrade to printing the
+ * URL.
+ */
+export declare function openerFor(url: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+} | null;
+/**
+ * Launches a browser without ever waiting for it.
+ *
+ * The child is detached and unref'd because `xdg-open` can stay in the
+ * foreground for the browser's entire life on some desktops: waiting for it
+ * would hold "here is your URL, Ctrl-C to stop" hostage until the person
+ * closed their browser, and killing it on a timeout could take the browser
+ * with it. So only an *immediate* failure is worth listening for — a missing
+ * opener (ENOENT) or one that gives up straight away (xdg-open's exit 3, "no
+ * method available") — and after a short grace period the window is assumed to
+ * be on its way.
+ *
+ * Nothing here throws. A browser that will not open is a message to print, not
+ * a reason to fail a command that has already started a working server.
+ */
+export declare function openInBrowser(url: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    graceMs?: number;
+}): Promise<BrowserResult>;
+/**
+ * Is a Sealkeep local API still listening on `port`, and is it *this* vault's?
+ *
+ * Two questions, because a recorded port answers neither. A port is reused by
+ * whatever process grabs it next, so `/health` first establishes that the
+ * listener is one of ours at all. Then a `/v1/status` call carrying this
+ * vault's token establishes that it reads the same token file — that is, that
+ * it serves this data dir and not a second vault's. 401 is the only answer
+ * that means "not this vault": every other status got past the token check,
+ * including the 404 a data dir with no vault yet would return.
+ */
+export declare function servesThisVault(port: number, token: string, fetchImpl?: typeof fetch): Promise<boolean>;
+export type UiHandle = {
+    port: number;
+    origin: string;
+    /**
+     * The address actually bound, which is the thing that decides who can reach
+     * this — as opposed to `origin`, which is only the name shown to a person.
+     * Exposed so "loopback only" can be asserted rather than inferred from how
+     * the URL happens to be spelled.
+     */
+    address: string;
+    /** The full URL including the token fragment. Print it only when no browser could be opened. */
+    url: string;
+    /** True when an already-running server was reused; nothing new was started and close() is a no-op. */
+    reused: boolean;
+    /** Set when reused, so a caller can say who owns the server it just pointed at. */
+    running: UiRecord | null;
+    browser: BrowserResult;
+    close: () => Promise<void>;
+};
+export type UiOptions = {
+    /** 0 — the default — asks the OS for an ephemeral port, so two vaults never fight over one. */
+    port?: number;
+    /** False for a headless surface that serves the API but has no window to open. */
+    openBrowser?: boolean;
+    /** Injected by tests so a suite never launches a real browser. */
+    open?: (url: string) => Promise<BrowserResult>;
+    /** Injected by tests that need to control what the reuse probe sees. */
+    fetchImpl?: typeof fetch;
+    /**
+     * False for `sealkeep api`, whose port is a stable address other tools are
+     * pointed at — handing it back an ephemeral one because a window happened to
+     * be open would break the thing that makes it useful. It still announces
+     * itself, so a later `sealkeep ui` finds it rather than starting a second.
+     */
+    reuse?: boolean;
+};
+/**
+ * Starts the local UI, or points at the one already running for this vault.
+ *
+ * Reuse is not an optimisation: a second server would mint no second token but
+ * would leave two listeners and two records for one vault, and whichever one
+ * the person closed first would look like "the UI stopped working". Finding
+ * the running one and opening a browser at it is the behaviour that matches
+ * what someone typing the command twice actually meant.
+ */
+export declare function startUi(dataDir: string, options?: UiOptions): Promise<UiHandle>;

package/dist/src/ui-server.js

@@ -0,0 +1,293 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createLocalApiServer, localApiToken } from "./local-api.js";
+/**
+ * The GUI, reachable without typing a command.
+ *
+ * PRODUCT_ARCHITECTURE.md §5: the terminal is the free tier's interface, not
+ * the product's. `src/local-api.ts` already serves the settings surface and
+ * `web/` already draws it — what was missing was a way to get a browser
+ * pointed at it, authenticated, without a person copying a token by hand.
+ *
+ * This module is the plumbing for that and nothing else. It starts (or finds)
+ * the loopback server, builds the URL that carries the token, and launches a
+ * browser. Every line printed to a terminal lives in cli.ts, so this stays
+ * usable by any surface that is not a terminal — the native shell in §5 v2
+ * being the obvious one.
+ */
+const LOOPBACK_HOST = "127.0.0.1";
+/**
+ * The name to show a person, as opposed to the address to bind.
+ *
+ * `http://127.0.0.1:54142` is a correct URL and a terrible one: it looks like
+ * something has gone wrong, it cannot be read out loud, and the port changed
+ * every run because the server asked the kernel for whatever was free. The
+ * server still binds the loopback address — nothing is exposed by naming it —
+ * but the URL people see, bookmark and type is a name and a fixed port.
+ *
+ * `localhost` rather than something prettier because it is the only name that
+ * resolves everywhere without touching the system. `vault.localhost` is
+ * resolved internally by Chrome but not by the macOS resolver, so Safari would
+ * fail on it; `vault.line` needs an /etc/hosts line, which needs a password,
+ * which is not something this should take. `sealkeep ui hostname` prints that
+ * line for anyone who wants the nicer name and is happy to install it.
+ */
+export const DISPLAY_HOST = "localhost";
+/**
+ * A fixed default port, so the address is the same tomorrow as it was today.
+ *
+ * 7477 spells "VLIN"-ish on a keypad, sits well above the privileged range, and
+ * is not claimed by anything in the IANA registry. When it is busy the server
+ * still falls back to a free port rather than refusing to start: a working
+ * window on an odd port beats a correct error.
+ */
+export const DEFAULT_UI_PORT = 7477;
+/** The hostnames this service answers to, mirrored by ALLOWED_HOSTS in local-api.ts. */
+export const UI_HOSTNAMES = ["localhost", "127.0.0.1", "vault.line", "vault.localhost"];
+/** Loopback round trips are sub-millisecond; anything slower is a listener that has stopped answering. */
+const PROBE_TIMEOUT_MS = 1_500;
+/** How long to wait for an opener to fail before assuming the window is on its way. See openInBrowser. */
+const OPENER_GRACE_MS = 400;
+/**
+ * Where a running server announces itself, so a second `sealkeep ui` finds it.
+ *
+ * It lives in the vault's own data dir, which is what makes it per-vault: two
+ * vaults on one machine have two data dirs and never see each other's server.
+ * It holds a port and a pid — no secret — but keeps the 0600 of everything
+ * else in there rather than being the one loose file.
+ */
+export const uiRecordPath = (dataDir) => join(dataDir, "ui-server.json");
+/** Anything unreadable, truncated, or not describing a usable port reads as "no server", never as an error. */
+export async function readUiRecord(dataDir) {
+    try {
+        const saved = JSON.parse(await readFile(uiRecordPath(dataDir), "utf8"));
+        const port = Number(saved?.port);
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+            return null;
+        return { port, pid: Number(saved?.pid) || 0, startedAt: String(saved?.startedAt ?? "") };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Written in place rather than through a temp file and a rename: a half-written
+ * record fails to parse, and failing to parse already means "start a fresh
+ * server", which is the safe answer. Atomicity would buy nothing.
+ */
+export async function writeUiRecord(dataDir, record) {
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    await writeFile(uiRecordPath(dataDir), JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
+}
+/**
+ * Removes the record only when it still names this server's port. Two servers
+ * can exist at once (a second one starts whenever the first is unreachable),
+ * and the first to shut down must not delete the survivor's announcement.
+ */
+export async function clearUiRecord(dataDir, port) {
+    if (port !== undefined) {
+        const recorded = await readUiRecord(dataDir);
+        if (recorded && recorded.port !== port)
+            return;
+    }
+    await rm(uiRecordPath(dataDir), { force: true });
+}
+/** Where a person goes. Bound on loopback, named so it can be read and typed. */
+export const uiOrigin = (port, host = DISPLAY_HOST) => `http://${host}:${port}`;
+/** Where this process talks to itself. Always the address, never a name that has to resolve. */
+export const uiProbeOrigin = (port) => `http://${LOOPBACK_HOST}:${port}`;
+/**
+ * How the browser gets authenticated: the token rides in the URL fragment.
+ *
+ * A fragment is the only part of a URL a browser never transmits. It is not in
+ * the request line, so it cannot reach an access log, a proxy, or a Referer
+ * header on any link the page later follows — and `web/app.js` reads it once,
+ * moves it into sessionStorage, and history.replaceState()s it out of the
+ * address bar, so it does not survive in browser history either. A `?token=`
+ * query string would have failed every one of those.
+ *
+ * The alternative — print the token and have someone paste it into the gate —
+ * is the terminal step this whole command exists to remove, and it puts the
+ * secret in scrollback, in `script` logs, and in any pasted transcript.
+ *
+ * What this does cost: the URL is an argv of the opener process, so it is
+ * visible to `ps` for the few milliseconds that process lives. That is
+ * accepted rather than overlooked — the token grants nothing that a local
+ * process running as this user does not already have, since it can read
+ * <data-dir>/local-api-token directly. Scrollback is the leak that outlives
+ * the session; argv is not.
+ */
+export const uiUrl = (port, token) => `${uiOrigin(port)}/#token=${encodeURIComponent(token)}`;
+/**
+ * Which command opens a URL here.
+ *
+ * Three platforms, three answers, and one of them is not an executable:
+ * Windows `start` is a cmd.exe builtin, so it has to be invoked through cmd —
+ * spawning "start" directly fails with ENOENT. The empty "" that follows is
+ * `start`'s window-title argument, which it would otherwise take from a quoted
+ * URL and then open nothing.
+ *
+ * `BROWSER` is honoured first because it is the existing convention for
+ * exactly this (xdg-open reads it, as do most tools that open pages), and
+ * `BROWSER=none` is how a headless box or a CI job says "do not launch
+ * anything" — answered here with null, which callers degrade to printing the
+ * URL.
+ */
+export function openerFor(url, env = process.env, platform = process.platform) {
+    const preference = env.BROWSER?.trim();
+    if (preference)
+        return preference.toLowerCase() === "none" ? null : { command: preference, args: [url] };
+    if (platform === "darwin")
+        return { command: "open", args: [url] };
+    if (platform === "win32")
+        return { command: "cmd", args: ["/c", "start", "", url] };
+    return { command: "xdg-open", args: [url] };
+}
+/**
+ * Launches a browser without ever waiting for it.
+ *
+ * The child is detached and unref'd because `xdg-open` can stay in the
+ * foreground for the browser's entire life on some desktops: waiting for it
+ * would hold "here is your URL, Ctrl-C to stop" hostage until the person
+ * closed their browser, and killing it on a timeout could take the browser
+ * with it. So only an *immediate* failure is worth listening for — a missing
+ * opener (ENOENT) or one that gives up straight away (xdg-open's exit 3, "no
+ * method available") — and after a short grace period the window is assumed to
+ * be on its way.
+ *
+ * Nothing here throws. A browser that will not open is a message to print, not
+ * a reason to fail a command that has already started a working server.
+ */
+export async function openInBrowser(url, options = {}) {
+    const opener = openerFor(url, options.env ?? process.env, options.platform ?? process.platform);
+    if (!opener)
+        return { opened: false, command: null, problem: "BROWSER is set to none, so nothing was launched" };
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
+        };
+        let child;
+        try {
+            child = spawn(opener.command, opener.args, { detached: true, stdio: "ignore", windowsHide: true });
+        }
+        catch (error) {
+            finish({ opened: false, command: opener.command, problem: error instanceof Error ? error.message : "could not start a browser" });
+            return;
+        }
+        timer = setTimeout(() => finish({ opened: true, command: opener.command }), options.graceMs ?? OPENER_GRACE_MS);
+        child.once("error", (error) => finish({ opened: false, command: opener.command, problem: error.message }));
+        child.once("exit", (code) => {
+            if (code !== null && code !== 0)
+                finish({ opened: false, command: opener.command, problem: `${opener.command} exited ${code}` });
+        });
+        child.unref();
+    });
+}
+/**
+ * Is a Sealkeep local API still listening on `port`, and is it *this* vault's?
+ *
+ * Two questions, because a recorded port answers neither. A port is reused by
+ * whatever process grabs it next, so `/health` first establishes that the
+ * listener is one of ours at all. Then a `/v1/status` call carrying this
+ * vault's token establishes that it reads the same token file — that is, that
+ * it serves this data dir and not a second vault's. 401 is the only answer
+ * that means "not this vault": every other status got past the token check,
+ * including the 404 a data dir with no vault yet would return.
+ */
+export async function servesThisVault(port, token, fetchImpl = fetch) {
+    try {
+        const health = await fetchImpl(`${uiProbeOrigin(port)}/health`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        if (!health.ok)
+            return false;
+        const body = await health.json().catch(() => null);
+        if (body?.mode !== "local-api")
+            return false;
+        const authorized = await fetchImpl(`${uiProbeOrigin(port)}/v1/status`, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+        });
+        return authorized.status !== 401;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Starts the local UI, or points at the one already running for this vault.
+ *
+ * Reuse is not an optimisation: a second server would mint no second token but
+ * would leave two listeners and two records for one vault, and whichever one
+ * the person closed first would look like "the UI stopped working". Finding
+ * the running one and opening a browser at it is the behaviour that matches
+ * what someone typing the command twice actually meant.
+ */
+export async function startUi(dataDir, options = {}) {
+    const token = await localApiToken(dataDir);
+    const open = options.open ?? ((url) => openInBrowser(url));
+    const wantsBrowser = options.openBrowser ?? true;
+    const noBrowser = { opened: false, command: null, declined: true };
+    /**
+     * A browser is the last step and the least important one: by the time it
+     * runs there is a working server that a person can still reach by hand. So
+     * no failure here — not even an opener that throws rather than reporting —
+     * is allowed to escape and leave that server running with nobody told about it.
+     */
+    const launch = async (url) => {
+        if (!wantsBrowser)
+            return noBrowser;
+        try {
+            return await open(url);
+        }
+        catch (error) {
+            return { opened: false, command: null, problem: error instanceof Error ? error.message : "could not open a browser" };
+        }
+    };
+    const recorded = (options.reuse ?? true) ? await readUiRecord(dataDir) : null;
+    if (recorded && await servesThisVault(recorded.port, token, options.fetchImpl ?? fetch)) {
+        const url = uiUrl(recorded.port, token);
+        return {
+            port: recorded.port, origin: uiOrigin(recorded.port), address: LOOPBACK_HOST, url, reused: true, running: recorded,
+            browser: await launch(url),
+            // Another process owns that server; stopping it from here would close a
+            // window somebody else's terminal claims to be holding open.
+            close: async () => { }
+        };
+    }
+    const server = createLocalApiServer(dataDir, token);
+    // The stable port is a preference, not a requirement. Something else holding
+    // 7477 is not this user's problem to solve before they can see their vault,
+    // so a busy port falls back to whatever is free rather than failing.
+    const wanted = options.port ?? DEFAULT_UI_PORT;
+    await new Promise((ready, broken) => {
+        const settle = () => { server.off("error", retry); ready(); };
+        const retry = (error) => {
+            if (wanted === 0 || (error.code !== "EADDRINUSE" && error.code !== "EACCES")) {
+                broken(error);
+                return;
+            }
+            server.once("error", broken);
+            server.listen(0, LOOPBACK_HOST, settle);
+        };
+        server.once("error", retry);
+        server.listen(wanted, LOOPBACK_HOST, settle);
+    });
+    const { port } = server.address();
+    await writeUiRecord(dataDir, { port, pid: process.pid, startedAt: new Date().toISOString() });
+    const url = uiUrl(port, token);
+    return {
+        port, origin: uiOrigin(port), address: server.address().address, url, reused: false, running: null,
+        browser: await launch(url),
+        close: async () => {
+            await clearUiRecord(dataDir, port);
+            await new Promise((done) => server.close(() => done()));
+        }
+    };
+}

package/dist/src/ui.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Terminal presentation.
+ *
+ * Every command prints for a person by default and for a machine with `--json`.
+ * Colour is used to encode one thing only — state — so output stays readable when
+ * it is piped, redirected, or read by someone who cannot distinguish the hues.
+ */
+export declare const bold: (value: string) => string;
+export declare const dim: (value: string) => string;
+export declare const blue: (value: string) => string;
+export declare const green: (value: string) => string;
+export declare const amber: (value: string) => string;
+export declare const red: (value: string) => string;
+export declare const underline: (value: string) => string;
+/** State markers. Text-first so they survive `NO_COLOR` and screen readers. */
+export declare const mark: {
+    ok: () => string;
+    warn: () => string;
+    fail: () => string;
+    bullet: () => string;
+};
+export declare function heading(text: string): string;
+/** The recurring device: the line past which plaintext does not travel. */
+export declare function vaultline(label?: string): string;
+export declare function keyValue(pairs: [string, string][], indent?: string): string;
+export declare function bytes(value: number): string;
+export declare function relativeTime(iso: string): string;
+/** Shortens a path from the left, so the filename always survives. */
+export declare function shortPath(path: string, width?: number): string;
+export type Column<T> = {
+    header: string;
+    get: (row: T) => string;
+    align?: "left" | "right";
+};
+export declare function table<T>(rows: readonly T[], columns: Column<T>[], empty: string): string;
+export declare function stripAnsi(value: string): string;
+/** Frames something the user must copy down before continuing. */
+export declare function callout(title: string, body: string[]): string;
+export declare function steps(items: string[]): string;
+export declare function hint(text: string): string;
+export declare function command(text: string): string;

package/dist/src/ui.js

@@ -0,0 +1,102 @@
+/**
+ * Terminal presentation.
+ *
+ * Every command prints for a person by default and for a machine with `--json`.
+ * Colour is used to encode one thing only — state — so output stays readable when
+ * it is piped, redirected, or read by someone who cannot distinguish the hues.
+ */
+const NO_COLOR = process.env.NO_COLOR !== undefined || process.env.TERM === "dumb";
+const useColor = () => process.stdout.isTTY === true && !NO_COLOR;
+const wrap = (open, close) => (value) => (useColor() ? `[${open}m${value}[${close}m` : value);
+export const bold = wrap("1", "22");
+export const dim = wrap("2", "22");
+export const blue = wrap("38;5;33", "39");
+export const green = wrap("38;5;29", "39");
+export const amber = wrap("38;5;172", "39");
+export const red = wrap("38;5;160", "39");
+export const underline = wrap("4", "24");
+/** State markers. Text-first so they survive `NO_COLOR` and screen readers. */
+export const mark = {
+    ok: () => green("ok"),
+    warn: () => amber("warn"),
+    fail: () => red("fail"),
+    bullet: () => dim("·")
+};
+export function heading(text) {
+    return `\n${bold(text)}\n${dim("─".repeat(Math.min(text.length + 12, 60)))}`;
+}
+/** The recurring device: the line past which plaintext does not travel. */
+export function vaultline(label = "plaintext ends here") {
+    return `${dim("─".repeat(4))}${dim("┤")} ${blue(label)} ${dim("├")}${dim("─".repeat(Math.max(4, 52 - label.length)))}`;
+}
+export function keyValue(pairs, indent = "  ") {
+    const width = Math.max(...pairs.map(([key]) => key.length));
+    return pairs.map(([key, value]) => `${indent}${dim(key.padEnd(width))}  ${value}`).join("\n");
+}
+export function bytes(value) {
+    if (!Number.isFinite(value))
+        return "—";
+    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]}`;
+}
+export function relativeTime(iso) {
+    const delta = Date.now() - Date.parse(iso);
+    if (!Number.isFinite(delta))
+        return "—";
+    const minutes = Math.round(delta / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.round(hours / 24);
+    return days < 30 ? `${days}d ago` : `${Math.round(days / 30)}mo ago`;
+}
+/** Shortens a path from the left, so the filename always survives. */
+export function shortPath(path, width = 46) {
+    const home = process.env.HOME;
+    const display = home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+    return display.length <= width ? display : `…${display.slice(-(width - 1))}`;
+}
+export function table(rows, columns, empty) {
+    if (rows.length === 0)
+        return `  ${dim(empty)}`;
+    const cells = rows.map((row) => columns.map((column) => column.get(row)));
+    const widths = columns.map((column, index) => Math.max(column.header.length, ...cells.map((row) => stripAnsi(row[index]).length)));
+    const pad = (value, width, align) => {
+        const padding = " ".repeat(Math.max(0, width - stripAnsi(value).length));
+        return align === "right" ? padding + value : value + padding;
+    };
+    const header = `  ${columns.map((column, index) => dim(pad(column.header.toUpperCase(), widths[index], column.align))).join("  ")}`;
+    const body = cells.map((row) => `  ${row.map((value, index) => pad(value, widths[index], columns[index].align)).join("  ")}`);
+    return [header, ...body].join("\n");
+}
+export function stripAnsi(value) {
+    // eslint-disable-next-line no-control-regex
+    return value.replace(/\[[0-9;]*m/g, "");
+}
+/** Frames something the user must copy down before continuing. */
+export function callout(title, body) {
+    const width = Math.max(title.length, ...body.map((line) => stripAnsi(line).length)) + 4;
+    const top = `┌${"─".repeat(width)}┐`;
+    const bottom = `└${"─".repeat(width)}┘`;
+    const line = (value) => `│  ${value}${" ".repeat(Math.max(0, width - stripAnsi(value).length - 4))}  │`;
+    return [blue(top), line(bold(title)), line(""), ...body.map(line), blue(bottom)].join("\n");
+}
+export function steps(items) {
+    return items.map((item, index) => `  ${blue(String(index + 1))}  ${item}`).join("\n");
+}
+export function hint(text) {
+    return `${dim("→")} ${text}`;
+}
+export function command(text) {
+    return bold(text);
+}

package/dist/src/update.d.ts

@@ -0,0 +1,30 @@
+export type UpdateArtifact = {
+    name: string;
+    sha256: string;
+    bytes: number;
+};
+export type UpdateManifest = {
+    version: 1;
+    product: "vaultline";
+    release: string;
+    publishedAt: string;
+    artifacts: UpdateArtifact[];
+};
+export type SignedManifest = {
+    manifest: UpdateManifest;
+    keyId: string;
+    algorithm: "ed25519";
+    signature: string;
+};
+/** Deterministic bytes to sign: object keys sorted, no incidental whitespace. */
+export declare function canonicalize(value: unknown): string;
+export declare function signManifest(manifest: UpdateManifest, privateKeyPem: string, keyId: string): SignedManifest;
+/**
+ * Verifies a release manifest against a pinned key set. An unknown key id fails
+ * closed: a signature is only meaningful against a key the client already trusts.
+ */
+export declare function verifyManifest(signed: SignedManifest, trustedKeys: Record<string, string>): UpdateManifest;
+/** Blocks rollback: a signed but older manifest must never be applied automatically. */
+export declare function assertNotDowngrade(candidate: string, current: string): void;
+/** Confirms a downloaded artifact matches the signed manifest entry byte for byte. */
+export declare function verifyArtifact(path: string, entry: UpdateArtifact): Promise<void>;