@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/singleton-lock.js

@@ -0,0 +1,219 @@
+/**
+ * DOD-SINGLE-DAEMON-1 — the daemon singleton, enforced by the kernel.
+ *
+ * `daemon.lock` is a JSON file, and a file cannot answer "is a daemon running?". Anyone may delete
+ * it; a `kill -9` leaves it behind naming a pid that is dead — or, worse, one the OS has since REUSED
+ * for an unrelated process, which makes `isProcessAlive()` say "yes" forever. Every stale-lock
+ * heuristic ever written is an attempt to guess what only the kernel actually knows.
+ *
+ * So we ask the kernel. The daemon takes a real POSIX write lock (`fcntl`) on a dedicated file and
+ * holds it for its entire lifetime. Two processes cannot hold it at once, and the kernel drops it the
+ * instant the holder dies — SIGKILL, panic, `kill -9`, however it goes. There is no stale state to
+ * clean up and no recovery step to get wrong.
+ *
+ * ## Why SQLite is the lock
+ *
+ * Node has no `flock`. `fs.constants.O_EXLOCK` exists only on macOS/BSD — using it would leave every
+ * Linux operator (including the EC2 demo agent) with NO lock at all, which is worse than none because
+ * it looks like one. A native `flock` addon (`fs-ext`) compiles from source, and install time is a
+ * cost every operator pays on every version bump (see CLAUDE.md — the client is a heavy local node,
+ * not a thin wrapper).
+ *
+ * `@signalapp/sqlcipher` is already a daemon dependency, ships prebuilt (no compile), and SQLite's
+ * whole business is taking correct `fcntl` locks on every POSIX platform. `locking_mode = exclusive`
+ * plus one header write acquires the exclusive lock and holds it until the connection closes. A
+ * second process gets SQLITE_BUSY immediately (`busy_timeout = 0`). SQLite also tracks locks per
+ * inode inside the process, so this correctly refuses a second daemon in the SAME process too —
+ * which raw `fcntl`, whose locks are per-process, would not.
+ *
+ * The lock database holds no rows and never will. It is a mutex that happens to be spelled in SQL.
+ *
+ * ## The division of labour with daemon.lock (AC4)
+ *
+ * The OS lock DECIDES whether a daemon may start. `daemon.lock` only SUPPLIES METADATA — it is how we
+ * learn the holder's pid to name in the error, because `fcntl` will not tell us. If the JSON is
+ * missing, stale, or lying, the worst outcome is a less specific error message. It can never admit a
+ * second daemon, and it can never wedge a legitimate one out.
+ *
+ * ## The one constraint
+ *
+ * `~/.cello` must live on a LOCAL filesystem. POSIX `fcntl` locks are advisory-but-honoured on local
+ * filesystems (APFS, ext4, xfs — macOS and the Linux hosts we run on); on NFSv3 without a working
+ * `lockd`, and on some 9p/WSL2 setups, they can silently degrade to no-ops. There, two daemons would
+ * both "acquire" and the singleton would be absent while appearing present. We do not attempt to
+ * detect this — a real self-test needs a second process, which is far too much to do at every startup.
+ * The lock path is logged in `daemon.singleton.acquired` so an operator debugging a two-daemon
+ * situation can see exactly which file the kernel was asked about.
+ */
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { loadSignalModule } from "./sqlcipher-db.js";
+import { extractErrorMessage } from "./error-message.js";
+/** The file the kernel lock is taken on. Holds no data — see the note above. */
+export const SINGLETON_LOCK_FILENAME = "daemon.singleton";
+export class DaemonAlreadyRunningError extends Error {
+    /** The pid from `daemon.lock`, or null when that file is absent/unreadable/malformed. */
+    holderPid;
+    constructor(holderPid) {
+        super(holderPid === null
+            ? "another daemon is already running (pid unknown — daemon.lock is missing or unreadable)"
+            : `another daemon is already running (pid ${holderPid})`);
+        this.name = "DaemonAlreadyRunningError";
+        this.holderPid = holderPid;
+    }
+}
+/**
+ * Read the holder's pid from the advisory `daemon.lock`. METADATA ONLY (AC4): this pid is used to
+ * write a better error message and for nothing else. It never decides anything, so a stale or absent
+ * file costs us a specific error message, never correctness.
+ */
+function readHolderPid(celloDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(celloDir, "daemon.lock"), "utf-8"));
+        return typeof parsed.pid === "number" ? parsed.pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isBusy(err) {
+    const code = err?.code;
+    return typeof code === "string" && code.startsWith("SQLITE_BUSY");
+}
+/**
+ * Take the exclusive OS lock for `celloDir`, or throw `DaemonAlreadyRunningError` if another process
+ * holds it. Returns a handle that holds the lock until `release()` (or process death).
+ *
+ * Call this BEFORE opening the database, registering agents, or connecting to the directory (AC2):
+ * a daemon that loses the race must do NONE of those things.
+ */
+/**
+ * How long a STARTING daemon will wait for a contended lock before giving up.
+ *
+ * Not zero, and the reason is subtle. `probeSingletonLock()` does not read the lock — it TAKES it and
+ * drops it. That means a probe (a concurrent `cello login`, a shim, a status check) holds the
+ * exclusive lock for the few milliseconds it takes to open the file and write the header. With a zero
+ * timeout, a daemon that reaches its acquisition inside that window would get SQLITE_BUSY and exit
+ * "another daemon is already running" — when no other daemon exists at all. A read-only question must
+ * never be able to kill the thing it is asking about.
+ *
+ * A genuine second daemon still loses within this bound, which is what AC2's "immediately" is for.
+ */
+const DAEMON_ACQUIRE_BUSY_TIMEOUT_MS = 3000;
+/**
+ * How long a PROBE waits before concluding the lock is held.
+ *
+ * Also not zero, and for the mirror of the reason above. A probe takes the lock too, so two probes
+ * can collide with each other: a second `cello login`, or the MCP shim autostarting while the
+ * operator types `cello login`. With a zero timeout the loser of that collision would report "held"
+ * — i.e. "a daemon is already running" — when there is no daemon at all, and the caller would sit in
+ * connectWithRetry for ten seconds before failing with a confident lie. That is precisely the class
+ * of wrong-but-certain statement this whole story exists to abolish.
+ *
+ * A REAL daemon holds the lock forever, so waiting a little costs a probe nothing in the case that
+ * matters — it still times out and still correctly answers "held". A transient probe-vs-probe
+ * collision, meanwhile, resolves in milliseconds. Strictly better than zero in both directions.
+ */
+const PROBE_BUSY_TIMEOUT_MS = 500;
+/** The daemon binary's exit code when it loses the singleton race — distinct from 1 = "broken". */
+export const EXIT_ALREADY_RUNNING = 3;
+function openLockDb(lockDbPath) {
+    const mod = loadSignalModule();
+    const Ctor = mod.Database ?? mod.default;
+    try {
+        return new Ctor(lockDbPath);
+    }
+    catch (err) {
+        // The file could not be opened at all (permissions, unwritable dir). NOT a contended lock —
+        // never let this be mistaken for "a daemon is running".
+        throw new Error(`Could not open the daemon singleton lock at ${lockDbPath}: ${extractErrorMessage(err)}`);
+    }
+}
+export function acquireSingletonLock(celloDir, logger, busyTimeoutMs = DAEMON_ACQUIRE_BUSY_TIMEOUT_MS) {
+    const lockDbPath = join(celloDir, SINGLETON_LOCK_FILENAME);
+    const db = openLockDb(lockDbPath);
+    try {
+        db.pragma(`busy_timeout = ${busyTimeoutMs}`);
+        db.pragma("locking_mode = exclusive");
+        // SQLite defers the actual lock acquisition until it has a reason to write. `user_version` is a
+        // write to the database header — it takes the exclusive lock and stores nothing.
+        db.pragma("user_version = 1");
+    }
+    catch (err) {
+        try {
+            db.close();
+        }
+        catch { /* we are already failing; closing is best-effort */ }
+        if (isBusy(err)) {
+            const holderPid = readHolderPid(celloDir);
+            logger.info("daemon.singleton.contended", { holderPid, lockPath: lockDbPath });
+            throw new DaemonAlreadyRunningError(holderPid);
+        }
+        // Some other SQLite failure. Keep the frame — a bare SQLITE_* error here reads as a database
+        // problem, when what actually failed was taking the singleton lock.
+        throw new Error(`Could not take the daemon singleton lock at ${lockDbPath}: ${extractErrorMessage(err)}`, { cause: err });
+    }
+    logger.info("daemon.singleton.acquired", { pid: process.pid, lockPath: lockDbPath });
+    let released = false;
+    return {
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                db.close();
+            }
+            catch (err) {
+                logger.warn("daemon.singleton.release.failed", {
+                    error: extractErrorMessage(err),
+                });
+            }
+        },
+    };
+}
+/**
+ * Is a daemon holding the lock for `celloDir` right now?
+ *
+ *   "held"    — a daemon is alive. Connect to it; never spawn beside it.
+ *   "free"    — no daemon is running, whatever `daemon.lock` claims. Spawning is correct.
+ *   "unknown" — we could not ask the kernel (native module missing, directory unreadable).
+ *
+ * The third answer is the point. "I could not determine whether a daemon is running" and "no daemon is
+ * running" are different facts, and collapsing them into one boolean means the caller spawns on both —
+ * so the one case where we are blind becomes the one case we start a second daemon. Callers must
+ * refuse to spawn on "unknown" and surface the underlying error instead.
+ *
+ * Asking the kernel rather than trusting `daemon.lock` is also what makes a REUSED pid harmless: a
+ * stale lock file naming a live-but-unrelated process would otherwise wedge `cello login` forever.
+ *
+ * The probe takes the lock and immediately drops it. The gap between the probe and a subsequent spawn
+ * is safe: the daemon we spawn acquires the lock authoritatively and exits EXIT_ALREADY_RUNNING if it
+ * loses that race — and the caller reads that exit code as "someone else won, connect to them", never
+ * as a failure. Two probes can therefore both say "free" and both spawn, and exactly one daemon
+ * survives.
+ */
+export function probeSingletonLock(celloDir, logger) {
+    // The probe genuinely TAKES the lock, so it emits the daemon's own `daemon.singleton.acquired`
+    // — except this call runs in the CLI process, so on a first ever `cello login` that JSON line
+    // lands on the operator's terminal, directly above the welcome text, as the first output of
+    // their first successful command. It reads as a fault. It is also not true in the sense a reader
+    // would take it: nothing acquired anything durably, the probe let go on the next statement.
+    //
+    // So the probe's acquire/contend lines drop to debug. The DAEMON's real acquisition still logs at
+    // info, into ~/.cello/daemon.log, which is the copy an operator debugging a two-daemon situation
+    // actually reads.
+    const quiet = { ...logger, info: logger.debug.bind(logger) };
+    try {
+        acquireSingletonLock(celloDir, quiet, PROBE_BUSY_TIMEOUT_MS).release();
+        return "free";
+    }
+    catch (err) {
+        if (err instanceof DaemonAlreadyRunningError)
+            return "held";
+        logger.warn("daemon.singleton.probe.failed", {
+            error: extractErrorMessage(err),
+        });
+        return "unknown";
+    }
+}
+//# sourceMappingURL=singleton-lock.js.map

package/dist/singleton-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton-lock.js","sourceRoot":"","sources":["../src/singleton-lock.ts"],"names":[],"mappings":"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"}

package/dist/sqlcipher-db.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The daemon's single encrypted store.
+ *
+ * The daemon DB is a SQLCipher database (whole-file AES-256 at rest). This module is the ONE
+ * engine site: it loads @signalapp/sqlcipher (prebuilt — never compiled from source), opens the DB with a
+ * PRAGMA key, verifies the key, enables WAL, and presents a thin `DaemonDatabase` adapter so the
+ * rest of the daemon (SessionNodeManager, RetryQueue, NonceDedupStore) keeps its node:sqlite-style
+ * varargs call sites unchanged.
+ *
+ * Why an adapter: node:sqlite's `DatabaseSync` uses varargs (`stmt.run(a, b, c)`); @signalapp's
+ * better-sqlite3-style API takes an array (`stmt.run([a, b, c])`). The `DaemonDatabase` /
+ * `DaemonStatement` interfaces expose the varargs surface — node:sqlite's `DatabaseSync` structurally
+ * satisfies them too (used for in-memory test handles and for reading a legacy plaintext DB during
+ * migration), and `SqlcipherDatabase` implements them by forwarding varargs as an array.
+ *
+ * Key custody: the SQLCipher key is a standalone random 32-byte 0600 key file beside the DB. It is
+ * NOT derived from K_local — that is a chicken-and-egg, since K_local itself lives inside the DB. It
+ * is the ONE plaintext key file on disk.
+ *
+ * FAILS CLOSED: there is no plaintext fallback anywhere. A wrong/missing key on an existing DB throws
+ * `db_encryption_key_mismatch`; the daemon never opens, creates, or migrates to a plaintext store as
+ * a fallback.
+ *
+ * Security invariants:
+ *   - The db key is NEVER logged, serialized, or placed in an error message — only the raw
+ *     `PRAGMA key` string uses the hex, and that string is never logged.
+ *   - WAL mode is enabled only AFTER key verification, so WAL files are encrypted at rest.
+ */
+import type { Logger } from "./types.js";
+export interface DaemonStatement {
+    run(...params: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+export interface DaemonDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): DaemonStatement;
+    close(): void;
+    /**
+     * Optional — present on the SQLCipher adapter, absent on node:sqlite's `DatabaseSync` (which uses
+     * `exec("PRAGMA ...")`). Optional so a plain `DatabaseSync` (in-memory test handles) still
+     * structurally satisfies this interface. Used to read cipher metadata (e.g. cipher_version).
+     */
+    pragma?(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+}
+export type DbErrorCode = "db_encryption_key_mismatch" | "db_sqlcipher_unavailable" | "db_open_failed";
+export declare class DbEncryptionError extends Error {
+    readonly code: DbErrorCode;
+    /** Actionable next step surfaced to the operator (never contains key material). */
+    readonly guidance: string;
+    constructor(code: DbErrorCode, message: string, guidance: string);
+}
+interface SignalRunResult {
+    changes: number;
+    lastInsertRowid: number;
+}
+interface SignalStatement {
+    run(params?: unknown[] | Record<string, unknown>): SignalRunResult;
+    get(params?: unknown[] | Record<string, unknown>): unknown;
+    all(params?: unknown[] | Record<string, unknown>): unknown[];
+}
+export interface SignalDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): SignalStatement;
+    pragma(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    close(): void;
+}
+interface SignalModule {
+    default: new (path: string) => SignalDatabase;
+    Database: new (path: string) => SignalDatabase;
+}
+/** True when the file at `dbPath` exists and is an UNENCRYPTED node:sqlite database. */
+export declare function isPlaintextSqliteFile(dbPath: string): boolean;
+/**
+ * Resolve the SQLCipher key, generating it on a genuinely fresh install only.
+ *
+ * Fail-closed matrix:
+ *   key present                      → load it (must be 32 bytes).
+ *   key absent + DB absent           → generate + persist (0600), proceed (fresh install).
+ *   key absent + DB present          → THROW db_encryption_key_mismatch (never overwrite an
+ *                                      existing DB with a new key — that would be data loss; and
+ *                                      a legacy PLAINTEXT DB must be migrated first, not opened).
+ */
+export declare function resolveDbKey(dbPath: string, keyPath: string): Uint8Array;
+/**
+ * Load the SQLCipher native module. Exported because the daemon's singleton lock needs the same
+ * engine for its kernel-level file lock — one place that knows how to load the prebuilt, and one
+ * error when it will not load.
+ */
+export declare function loadSignalModule(): SignalModule;
+/**
+ * Open `dbPath` as a SQLCipher database keyed by `dbKey`. Verifies the key (reads sqlite_master)
+ * and enables WAL after verification. Throws DbEncryptionError on any failure — never returns a
+ * plaintext handle.
+ */
+export declare function openEncryptedDatabase(dbPath: string, dbKey: Uint8Array, logger?: {
+    warn(event: string, context?: Record<string, unknown>): void;
+}): DaemonDatabase;
+/**
+ * Run a table REBUILD (the create-copy-drop-rename recipe) with foreign keys safely disabled.
+ *
+ * THE TRAP THIS EXISTS TO CLOSE. With `PRAGMA foreign_keys = ON` (M10-D19), SQLite treats
+ * `DROP TABLE parent` as an implicit `DELETE FROM parent` — which **fires `ON DELETE CASCADE` and
+ * silently empties every child table**. No error. No log. The rebuild's own row-count guards count
+ * the table being rebuilt, not its children, so they pass. Measured:
+ *
+ *     children before rebuild: 1
+ *     PRAGMA foreign_keys = OFF  (inside BEGIN)  -> still reports 1   <-- A SILENT NO-OP
+ *     DROP TABLE contacts                        -> children: 0       <-- cascade fired
+ *
+ * And the obvious mitigation does not work: **`PRAGMA foreign_keys` is a no-op inside a
+ * transaction.** SQLite ignores it and says nothing. Since every rebuild in this codebase runs
+ * inside one `BEGIN…COMMIT` (agent-id-migration.ts rebuilds seven tables, `contacts` among them),
+ * a rebuild that "disabled" FKs in the usual place would still cascade.
+ *
+ * So the pragma must be toggled OUTSIDE the transaction, which is what this helper enforces — and it
+ * VERIFIES the toggle took effect rather than assuming it, because the failure is silent by nature.
+ * On the way out it re-enables FKs and runs `PRAGMA foreign_key_check`: a rebuild that left a
+ * dangling reference (e.g. `ALTER TABLE parent RENAME` rewrites children's FK clauses to point at
+ * the renamed table) is a loud failure here rather than a mystery on some later insert.
+ */
+export declare function withForeignKeysOff<T>(db: DaemonDatabase, logger: Logger | undefined, fn: () => T): T;
+/**
+ * Convenience used by tests and tooling: resolve the key file beside `dbPath` and open. Throws if
+ * the key file is absent (it does NOT generate one) — callers inspecting an existing DB always have
+ * the key.
+ */
+export declare function openEncryptedDatabaseAtPath(dbPath: string, keyPath?: string): DaemonDatabase;
+/** The key file path the daemon uses for a given DB path — the one plaintext key file. */
+export declare function dbKeyPathFor(dbPath: string): string;
+export {};
+//# sourceMappingURL=sqlcipher-db.d.ts.map

package/dist/sqlcipher-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlcipher-db.d.ts","sourceRoot":"","sources":["../src/sqlcipher-db.ts"],"names":[],"mappings":"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"}