@cleocode/core 2026.4.11 → 2026.4.13

package/dist/store/global-salt.js

@@ -0,0 +1,147 @@
+/**
+ * Global-salt subsystem for the CLEO API key KDF.
+ *
+ * @task T348
+ * @epic T310
+ * @why ADR-037 §5 — API key KDF uses machine-key + global-salt + agentId.
+ *      global-salt must persist across process restarts but is machine-local.
+ * @what Atomic first-run generation, memoized read, permission/size validation.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getCleoHome } from '../paths.js';
+/** Filename for the global salt file under CLEO home. */
+export const GLOBAL_SALT_FILENAME = 'global-salt';
+/** Required size of the global salt in bytes. */
+export const GLOBAL_SALT_SIZE = 32;
+/** Required file permission mode for the global salt file (POSIX). */
+const SALT_FILE_MODE = 0o600;
+/**
+ * In-process memoization. Invalidated only by process restart.
+ * Cleared in tests via `__clearGlobalSaltCache()` (test-only export).
+ */
+let cached = null;
+/**
+ * Returns the absolute path to the global-salt file.
+ *
+ * @returns Absolute path: `{cleoHome}/global-salt`
+ *
+ * @task T348
+ * @epic T310
+ *
+ * @example
+ * ```typescript
+ * const saltPath = getGlobalSaltPath();
+ * // Linux: "/home/user/.local/share/cleo/global-salt"
+ * ```
+ */
+export function getGlobalSaltPath() {
+    return path.join(getCleoHome(), GLOBAL_SALT_FILENAME);
+}
+/**
+ * Returns the 32-byte global salt. Generates and persists atomically on first
+ * call when the file does not exist. Subsequent calls return the memoized value.
+ *
+ * Never overwrites an existing salt — doing so would invalidate every stored
+ * API key derived from it.
+ *
+ * @returns A 32-byte Buffer containing the global salt
+ * @throws {Error} If the salt file exists with wrong size or wrong permissions
+ *
+ * @task T348
+ * @epic T310
+ *
+ * @example
+ * ```typescript
+ * const salt = getGlobalSalt(); // Buffer(32) [...]
+ * ```
+ */
+export function getGlobalSalt() {
+    if (cached !== null)
+        return cached;
+    const saltPath = getGlobalSaltPath();
+    const cleoHome = getCleoHome();
+    if (!fs.existsSync(saltPath)) {
+        // First-run generation: ensure the directory exists
+        if (!fs.existsSync(cleoHome)) {
+            fs.mkdirSync(cleoHome, { recursive: true });
+        }
+        const salt = crypto.randomBytes(GLOBAL_SALT_SIZE);
+        // Atomic write: write to tmp file, chmod, then rename into place
+        const tmpPath = `${saltPath}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmpPath, salt, { mode: SALT_FILE_MODE });
+        // Explicit chmod in case writeFileSync's mode arg is ignored on some FS
+        fs.chmodSync(tmpPath, SALT_FILE_MODE);
+        fs.renameSync(tmpPath, saltPath);
+        cached = salt;
+        return cached;
+    }
+    // Existing file — validate before trusting
+    const stat = fs.statSync(saltPath);
+    if (stat.size !== GLOBAL_SALT_SIZE) {
+        throw new Error(`global-salt at ${saltPath} has wrong size: expected ${GLOBAL_SALT_SIZE} bytes, got ${stat.size}. ` +
+            `Refusing to use a corrupted salt file. Delete the file manually if you intend to regenerate it ` +
+            `(this will invalidate all stored API keys).`);
+    }
+    // Permission check: only meaningful on POSIX; Windows does not support mode bits
+    if (process.platform !== 'win32') {
+        const mode = stat.mode & 0o777;
+        if (mode !== SALT_FILE_MODE) {
+            throw new Error(`global-salt at ${saltPath} has wrong permissions: expected 0o600, got 0o${mode.toString(8)}. ` +
+                `Fix with: chmod 600 ${saltPath}`);
+        }
+    }
+    const salt = fs.readFileSync(saltPath);
+    cached = salt;
+    return cached;
+}
+/**
+ * Runtime validation helper for startup integrity checks.
+ *
+ * Throws if the salt file exists but is malformed (wrong size or permissions).
+ * Safe to call when the file does not yet exist — returns silently in that case
+ * because first-run generation is handled lazily by `getGlobalSalt()`.
+ *
+ * @throws {Error} If the salt file exists with wrong size or wrong permissions
+ *
+ * @task T348
+ * @epic T310
+ *
+ * @example
+ * ```typescript
+ * // Called at process startup to catch accidental salt corruption early
+ * validateGlobalSalt();
+ * ```
+ */
+export function validateGlobalSalt() {
+    const saltPath = getGlobalSaltPath();
+    if (!fs.existsSync(saltPath)) {
+        // Not yet generated — first-run case; no error
+        return;
+    }
+    const stat = fs.statSync(saltPath);
+    if (stat.size !== GLOBAL_SALT_SIZE) {
+        throw new Error(`global-salt validation failed: size ${stat.size}, expected ${GLOBAL_SALT_SIZE}`);
+    }
+    if (process.platform !== 'win32') {
+        const mode = stat.mode & 0o777;
+        if (mode !== SALT_FILE_MODE) {
+            throw new Error(`global-salt validation failed: permissions 0o${mode.toString(8)}, expected 0o600`);
+        }
+    }
+}
+/**
+ * Clears the in-process memoization cache so tests can exercise the
+ * first-call generation path independently.
+ *
+ * @internal TEST ONLY — do NOT export through internal.ts or re-export
+ * from any public barrel. This symbol must never appear in production call paths.
+ *
+ * @task T348
+ * @epic T310
+ */
+export function __clearGlobalSaltCache() {
+    cached = null;
+}
+//# sourceMappingURL=global-salt.js.map

package/dist/store/global-salt.js.map

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

package/dist/store/migrate-signaldock-to-conduit.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Automatic first-run migration executor: project-tier signaldock.db → conduit.db.
+ *
+ * Implements ADR-037 §8 — on the first cleo invocation after upgrading to
+ * v2026.4.12, if a project-tier `.cleo/signaldock.db` exists and
+ * `.cleo/conduit.db` does not, this module migrates all project-local data to
+ * conduit.db and copies global-identity rows to the global-tier signaldock.db.
+ *
+ * Key properties:
+ *   - Idempotent: `needsSignaldockToConduitMigration` returns false once conduit.db exists.
+ *   - Atomic per file: transactions are used for conduit.db and global signaldock.db writes.
+ *   - Non-destructive: legacy signaldock.db is renamed to `.pre-t310.bak`, not deleted.
+ *   - Multi-project safe: `INSERT OR IGNORE` prevents duplicate global rows when multiple
+ *     projects migrate the same agent.
+ *   - Migrated agents flagged `requires_reauth=1` (new KDF scheme, ADR-037 §5).
+ *
+ * @task T358
+ * @epic T310
+ * @why ADR-037 §8 — automatic first-run migration from the pre-T310 project-tier
+ *      signaldock.db to the new T310 topology (conduit.db + global signaldock.db
+ *      + global-salt). Runs once per project on first cleo invocation after upgrade.
+ */
+/**
+ * Result returned by `migrateSignaldockToConduit`.
+ *
+ * @task T358
+ * @epic T310
+ */
+export interface MigrationResult {
+    /** `migrated` = migration ran and succeeded; `no-op` = not needed; `failed` = error occurred. */
+    status: 'migrated' | 'no-op' | 'failed';
+    /** Absolute path to the project root that was migrated. */
+    projectRoot: string;
+    /** Number of agents copied to global signaldock.db. */
+    agentsCopied: number;
+    /** Absolute path to the conduit.db that was created. */
+    conduitPath: string;
+    /** Absolute path to the global signaldock.db. */
+    globalSignaldockPath: string;
+    /** Absolute path to the legacy `.pre-t310.bak` file, or null if rename did not complete. */
+    bakPath: string | null;
+    /** Errors encountered during migration steps. Never thrown — always captured here. */
+    errors: Array<{
+        step: string;
+        error: string;
+    }>;
+}
+/**
+ * Returns true when the legacy migration is needed for the given project.
+ *
+ * Detection heuristic (ADR-037 §8):
+ *   - `.cleo/signaldock.db` EXISTS AND `.cleo/conduit.db` DOES NOT EXIST
+ *
+ * Idempotent: returns false once conduit.db is present, regardless of .bak state.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns True if migration is needed; false otherwise.
+ *
+ * @task T358
+ * @epic T310
+ */
+export declare function needsSignaldockToConduitMigration(projectRoot: string): boolean;
+/**
+ * Runs the signaldock.db → conduit.db migration for the given project.
+ *
+ * The migration is atomic per file (SQLite transactions for DB writes, atomic
+ * rename for the backup step). Failures are captured in `result.errors` and
+ * the function never throws — callers receive a `MigrationResult` with
+ * `status: 'failed'` on error.
+ *
+ * Safe to call when no migration is needed (returns `{status: 'no-op', ...}`).
+ * Safe to call on a partially-migrated install (idempotent via needsMigration check).
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns A `MigrationResult` describing what was done and any errors encountered.
+ *
+ * @task T358
+ * @epic T310
+ */
+export declare function migrateSignaldockToConduit(projectRoot: string): MigrationResult;
+//# sourceMappingURL=migrate-signaldock-to-conduit.d.ts.map

package/dist/store/migrate-signaldock-to-conduit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-signaldock-to-conduit.d.ts","sourceRoot":"","sources":["../../src/store/migrate-signaldock-to-conduit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsBH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACxC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAI9E;AA8GD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAma/E"}