@cello-protocol/daemon 0.0.3 → 0.0.4

package/dist/registration-persistence.js

@@ -0,0 +1,233 @@
+/**
+ * Daemon registration persistence — CELLO-M7-REGISTRATION.
+ *
+ * The daemon owns each agent's registration material (ML-DSA keypair, FROST key
+ * share, registration state) as per-agent files under ~/.cello/agents/<name>/.
+ * This mirrors the daemon's existing `key`-file model (see agent-loader.ts) and
+ * deliberately does NOT drag the client's SQLCipher ClientStatePersistence into
+ * the daemon — that layer is keyed by agent_pubkey in one shared DB, whereas the
+ * daemon isolates each agent in its own directory (cleaner for multi-agent).
+ *
+ * Security posture: the FROST signing share and ML-DSA secret key are written
+ * with 0o600 permissions, atomically (write-to-tmp + rename), consistent with the
+ * daemon's existing plaintext K_local `key` file. Encryption-at-rest for the
+ * daemon is a separate future concern and is intentionally NOT introduced
+ * piecemeal here. The signing share (SI-001) and secret key blob (SI-002) must
+ * never appear in a log event — only the files hold them.
+ */
+import { mkdir, readFile, rename, chmod, unlink, open as fsOpen } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { join, dirname } from "node:path";
+// ─── On-disk file names (relative to the agent directory) ────────────────────
+const FILE_REGISTRATION_STATE = "registration-state.json";
+const FILE_MLDSA_KEYPAIR = "ml-dsa-keypair.json";
+const FILE_FROST_SHARE = "frost-share.json";
+const FILE_AGENT_USER_LINK = "agent-user-link.json";
+const SECRET_FILE_MODE = 0o600;
+const hex = (b) => Buffer.from(b).toString("hex");
+const unhex = (s) => new Uint8Array(Buffer.from(s, "hex"));
+/**
+ * Required-field accessors. A registration file that exists but is missing or
+ * mistypes a field is corrupt — surface it loudly rather than silently coercing
+ * to NaN / an empty buffer (which would read as "unregistered" or hand crypto a
+ * zero-length key). Atomic writes make this unreachable in normal operation.
+ */
+function reqStr(obj, key, file) {
+    const v = obj[key];
+    if (typeof v !== "string") {
+        throw new Error(`registration file '${file}' is corrupt: missing or non-string field '${key}'`);
+    }
+    return v;
+}
+function reqNum(obj, key, file) {
+    const v = obj[key];
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new Error(`registration file '${file}' is corrupt: missing or non-numeric field '${key}'`);
+    }
+    return v;
+}
+/**
+ * File-backed implementation. One instance is scoped to a single agent's
+ * directory (e.g. ~/.cello/agents/alice/). The directory is created on first
+ * write; load methods on a fresh agent return null (ENOENT is not an error).
+ */
+export class FileRegistrationPersistence {
+    #agentDir;
+    #logger;
+    #tmpCounter = 0;
+    constructor(opts) {
+        this.#agentDir = opts.agentDir;
+        this.#logger = opts.logger;
+    }
+    // ─── Persist ───────────────────────────────────────────────────────────────
+    async persistMlDsaKeypair(opts) {
+        // SI-002: secretKeyBlob is written to disk only — never logged.
+        await this.#writeJsonAtomic(FILE_MLDSA_KEYPAIR, {
+            mlDsaPubkey: opts.mlDsaPubkey,
+            secretKeyBlob: hex(opts.secretKeyBlob),
+            algorithm: "ML-DSA-44",
+        });
+        this.#logger.info("registration.mldsa.persisted", { mlDsaPubkey: opts.mlDsaPubkey });
+    }
+    async persistRegistrationState(opts) {
+        await this.#writeJsonAtomic(FILE_REGISTRATION_STATE, {
+            agentId: opts.agentId,
+            primaryPubkey: opts.primaryPubkey,
+            mlDsaPubkey: opts.mlDsaPubkey,
+            registeredAt: opts.registeredAt,
+            status: "active",
+        });
+        this.#logger.info("registration.state.persisted", {
+            agentId: opts.agentId,
+            primaryPubkey: opts.primaryPubkey,
+        });
+    }
+    async persistFrostKeyShare(opts) {
+        // A daemon agent holds exactly one active FROST share; a new DKG replaces it.
+        await this.#writeJsonAtomic(FILE_FROST_SHARE, {
+            epochId: opts.epochId,
+            primaryPubkey: opts.primaryPubkey,
+            identifier: opts.identifier,
+            signingShare: hex(opts.signingShare), // SI-001: on disk only, never logged
+            threshold: opts.threshold,
+            participants: opts.participants,
+            commitmentsCbor: hex(opts.commitmentsCbor),
+            verifyingSharesCbor: hex(opts.verifyingSharesCbor),
+            dkgMethod: opts.dkgMethod,
+        });
+        // SI-001: signingShare MUST NOT appear in this event.
+        this.#logger.info("registration.frost.share.persisted", {
+            epochId: opts.epochId,
+            threshold: opts.threshold,
+            participants: opts.participants,
+            dkgMethod: opts.dkgMethod,
+        });
+    }
+    /**
+     * Capture the agent→user link at registration (M7 capture-now-or-lose-it). Not
+     * part of the RegistrationManager seam — called by the cello_register handler
+     * after a successful register(), since only the handler holds the pre-auth ticket.
+     */
+    async persistAgentUserLink(opts) {
+        // SI: the preAuthToken is a bearer ticket — written to disk only, never logged.
+        await this.#writeJsonAtomic(FILE_AGENT_USER_LINK, {
+            agentId: opts.agentId,
+            preAuthToken: opts.preAuthToken,
+            linkedAt: opts.linkedAt,
+        });
+        this.#logger.info("registration.user_link.persisted", { agentId: opts.agentId });
+    }
+    // ─── Load (restart rehydration) ──────────────────────────────────────────────
+    async loadRegistrationState() {
+        const obj = await this.#readJson(FILE_REGISTRATION_STATE);
+        if (!obj)
+            return null;
+        return {
+            agentId: reqStr(obj, "agentId", FILE_REGISTRATION_STATE),
+            primaryPubkey: reqStr(obj, "primaryPubkey", FILE_REGISTRATION_STATE),
+            mlDsaPubkey: reqStr(obj, "mlDsaPubkey", FILE_REGISTRATION_STATE),
+            registeredAt: reqNum(obj, "registeredAt", FILE_REGISTRATION_STATE),
+            status: reqStr(obj, "status", FILE_REGISTRATION_STATE),
+        };
+    }
+    async loadMlDsaKeypair() {
+        const obj = await this.#readJson(FILE_MLDSA_KEYPAIR);
+        if (!obj)
+            return null;
+        return {
+            mlDsaPubkey: reqStr(obj, "mlDsaPubkey", FILE_MLDSA_KEYPAIR),
+            secretKeyBlob: unhex(reqStr(obj, "secretKeyBlob", FILE_MLDSA_KEYPAIR)),
+            algorithm: reqStr(obj, "algorithm", FILE_MLDSA_KEYPAIR),
+        };
+    }
+    async loadActiveFrostKeyShare() {
+        const obj = await this.#readJson(FILE_FROST_SHARE);
+        if (!obj)
+            return null;
+        return {
+            epochId: reqStr(obj, "epochId", FILE_FROST_SHARE),
+            primaryPubkey: reqStr(obj, "primaryPubkey", FILE_FROST_SHARE),
+            identifier: reqStr(obj, "identifier", FILE_FROST_SHARE),
+            signingShare: unhex(reqStr(obj, "signingShare", FILE_FROST_SHARE)),
+            threshold: reqNum(obj, "threshold", FILE_FROST_SHARE),
+            participants: reqNum(obj, "participants", FILE_FROST_SHARE),
+            commitmentsCbor: unhex(reqStr(obj, "commitmentsCbor", FILE_FROST_SHARE)),
+            verifyingSharesCbor: unhex(reqStr(obj, "verifyingSharesCbor", FILE_FROST_SHARE)),
+            dkgMethod: reqStr(obj, "dkgMethod", FILE_FROST_SHARE),
+        };
+    }
+    async loadAgentUserLink() {
+        const obj = await this.#readJson(FILE_AGENT_USER_LINK);
+        if (!obj)
+            return null;
+        return {
+            agentId: reqStr(obj, "agentId", FILE_AGENT_USER_LINK),
+            preAuthToken: reqStr(obj, "preAuthToken", FILE_AGENT_USER_LINK),
+            linkedAt: reqNum(obj, "linkedAt", FILE_AGENT_USER_LINK),
+        };
+    }
+    // ─── Internals ───────────────────────────────────────────────────────────────
+    async #readJson(name) {
+        let raw;
+        try {
+            raw = await readFile(join(this.#agentDir, name));
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        return JSON.parse(raw.toString("utf8"));
+    }
+    /** Write JSON atomically (tmp + rename) with 0o600 so partial writes never surface. */
+    async #writeJsonAtomic(name, value) {
+        await mkdir(this.#agentDir, { recursive: true });
+        const finalPath = join(this.#agentDir, name);
+        // Random suffix (not just pid+counter) so two FileRegistrationPersistence
+        // instances sharing an agentDir in one process can never collide on the tmp
+        // path and truncate each other's write.
+        const tmpPath = join(dirname(finalPath), `.cello-reg-tmp-${process.pid}-${++this.#tmpCounter}-${randomBytes(6).toString("hex")}-${name}`);
+        const body = Buffer.from(JSON.stringify(value), "utf8");
+        try {
+            const fd = await fsOpen(tmpPath, "w", SECRET_FILE_MODE);
+            try {
+                await fd.write(body);
+                await fd.chmod(SECRET_FILE_MODE);
+                // fsync the data before rename so a crash between write and rename can't
+                // surface an empty/partial key file on recovery.
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+            await rename(tmpPath, finalPath);
+            // rename preserves the tmp file's mode; chmod the final path defensively in
+            // case it pre-existed with looser permissions.
+            await chmod(finalPath, SECRET_FILE_MODE);
+            // Best-effort durability of the rename itself (parent-dir fsync). Not all
+            // platforms/filesystems support directory fsync — ignore failures.
+            await this.#fsyncDir(this.#agentDir);
+        }
+        catch (err) {
+            // Never leave plaintext secret material (ML-DSA secret / FROST share) as
+            // orphaned tmp litter if the write or rename failed partway.
+            await unlink(tmpPath).catch(() => { });
+            throw err;
+        }
+    }
+    async #fsyncDir(dir) {
+        try {
+            const dh = await fsOpen(dir, "r");
+            try {
+                await dh.sync();
+            }
+            finally {
+                await dh.close();
+            }
+        }
+        catch {
+            // Directory fsync is best-effort; some platforms reject opening a dir for sync.
+        }
+    }
+}
+//# sourceMappingURL=registration-persistence.js.map

package/dist/registration-persistence.js.map

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

package/dist/retry-queue.d.ts

@@ -0,0 +1,144 @@
+/**
+ * CELLO Daemon — RetryQueue
+ *
+ * Per-session FIFO queue of messages awaiting delivery. When a send over a
+ * session node stream fails, the message envelope is added to the queue. When
+ * the peer reconnects, the daemon drains the queue in FIFO order.
+ *
+ * Persistence: SQLCipher table `retry_queue`.
+ * Cap: 1,000 messages per session. On overflow the OLDEST is evicted.
+ *
+ * Pseudocode (SPARC Phase P):
+ *
+ * 1. constructor(db, logger):
+ *    - Store db handle and logger reference
+ *    - Initialize empty per-session Map<sessionId, RetryQueueEntry[]>
+ *    - Create retry_queue table IF NOT EXISTS
+ *    - Create index on (session_id, position ASC)
+ *
+ * 2. loadFromDb():
+ *    - SELECT all rows from retry_queue ordered by session_id, position ASC
+ *    - Group into per-session arrays of RetryQueueEntry
+ *    - Store in in-memory Map
+ *    - Track per-session position counters (MAX position per session)
+ *
+ * 3. enqueue(sessionId, nonce: Uint8Array, contentBlob: Uint8Array):
+ *    - Convert nonce to hex via Buffer.from(nonce).toString('hex')
+ *    - If session queue size >= 1000: evict oldest (lowest position)
+ *      - DELETE from retry_queue WHERE session_id AND position = min
+ *      - Log message.retry.evicted WARN with evicted nonce hex
+ *      - Remove from in-memory array
+ *    - Compute next position: max(existing positions) + 1
+ *    - INSERT into retry_queue (session_id, nonce_hex, content_blob, queued_at, attempts, position)
+ *    - Add to in-memory array
+ *    - Log message.retry.queued INFO
+ *    - Return queueDepth
+ *
+ * 4. drainSession(sessionId, sendFn):
+ *    - Get entries for session in FIFO order (ascending position)
+ *    - For each entry:
+ *      a. Call sendFn(entry.contentBlob) → await result
+ *      b. If success: DELETE from retry_queue, remove from memory,
+ *         log message.retry.delivered INFO with attemptsTotal
+ *      c. If failure: HALT immediately. Do not attempt remaining entries.
+ *         FIFO invariant: M3 must not arrive before M2.
+ *    - Return count of successfully delivered messages
+ *
+ * 5. getTotalDepth():
+ *    - Sum sizes of all per-session arrays
+ *    - Return integer >= 0
+ *
+ * 6. getSessionDepth(sessionId):
+ *    - Return length of session's array (0 if absent)
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { Logger } from "./types.js";
+import type { TranscriptCipher } from "./transcript-cipher.js";
+/** Cap per outline.md Resource Caps. */
+export declare const RETRY_QUEUE_CAP = 1000;
+export interface RetryQueueEntry {
+    sessionId: string;
+    nonceHex: string;
+    contentBlob: Uint8Array;
+    queuedAt: number;
+    attempts: number;
+    position: number;
+}
+/** Result of a resend attempt during drain. */
+export type ResendResult = {
+    delivered: true;
+} | {
+    delivered: false;
+    error: string;
+};
+export type ResendFn = (contentBlob: Uint8Array) => Promise<ResendResult>;
+/**
+ * CELLO-M7-MSG-001: an un-acked content entry awaiting a `persisted` delivery ACK.
+ * Stored in the SAME retry_queue table (awaiting_ack = 1) — no new table. Drains to
+ * the relay store-and-forward queue (park target) instead of direct-P2P resend.
+ */
+export interface AwaitingContentEntry {
+    /** DOD-LOOP-1: the OWNING agent — the original sender. Two of the operator's agents can hold
+     *  awaiting content for the SAME session_id on one daemon (loopback), so the entry is keyed by
+     *  (agentName, sessionId), not sessionId alone. */
+    agentName: string;
+    sessionId: string;
+    contentHashHex: string;
+    contentBlob: Uint8Array;
+    queuedAt: number;
+    position: number;
+}
+/** Result of a park attempt during the awaiting-ACK drain. */
+export type ParkResult = {
+    parked: true;
+} | {
+    parked: false;
+    error: string;
+};
+export type ParkFn = (entry: AwaitingContentEntry) => Promise<ParkResult>;
+export declare class RetryQueue {
+    #private;
+    constructor(db: DatabaseSync, logger: Logger, cipher?: TranscriptCipher);
+    /**
+     * Load all retry queue entries from SQLCipher into memory.
+     * Must complete BEFORE the IPC socket opens (AC-007).
+     */
+    loadFromDb(): void;
+    enqueue(sessionId: string, nonce: Uint8Array, contentBlob: Uint8Array): void;
+    /**
+     * Drain the session's retry queue in FIFO order.
+     * Halts immediately on first failure (FIFO invariant: no out-of-order delivery).
+     * Returns the number of successfully delivered messages.
+     */
+    drainSession(sessionId: string, sendFn: ResendFn): Promise<number>;
+    /** Total retry queue depth across all sessions. */
+    getTotalDepth(): number;
+    /** Retry queue depth for a specific session. */
+    getSessionDepth(sessionId: string): number;
+    /** Get all entries for a session (FIFO ordered, defensive copy). Used by drain_session IPC. */
+    getSessionEntries(sessionId: string): RetryQueueEntry[];
+    /**
+     * Record un-acked content awaiting a `persisted` delivery ACK (TTF-trigger path,
+     * AC-005). Persisted to the SAME retry_queue table (awaiting_ack = 1) so a crash
+     * before the relay park confirms is recoverable at startup (AC-004). Idempotent on
+     * (sessionId, contentHash).
+     */
+    enqueueAwaitingContent(agentName: string, sessionId: string, contentHash: Uint8Array, contentBlob: Uint8Array): void;
+    /** Remove an awaiting-ACK entry once its `persisted` ACK arrives. */
+    markContentAcked(agentName: string, sessionId: string, contentHash: Uint8Array): void;
+    /** Awaiting-ACK depth for a session (un-acked content count). */
+    getAwaitingDepth(agentName: string, sessionId: string): number;
+    /** All (agent, session) pairs that currently hold awaiting-ACK content (for the startup flush). */
+    getAwaitingSessions(): Array<{
+        agentName: string;
+        sessionId: string;
+    }>;
+    /**
+     * Drain a session's awaiting-ACK content to the relay park target (AC-005). Each item
+     * is independent — unlike the direct FIFO resend, a park failure does NOT halt the
+     * rest; the failed item stays queued for the next reconnect / startup flush (DB-001,
+     * AC-019). Returns the number of entries successfully parked.
+     */
+    drainAwaitingToPark(agentName: string, sessionId: string, parkFn: ParkFn): Promise<number>;
+}
+//# sourceMappingURL=retry-queue.d.ts.map

package/dist/retry-queue.d.ts.map

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