@cleocode/core 2026.9.16 → 2026.9.17

package/dist/store/credential-transfer.js

@@ -0,0 +1,774 @@
+/**
+ * credential-transfer.ts — move stored credentials between devices without
+ * moving the device key.
+ *
+ * Every stored credential is encrypted under a key derived from the local
+ * `machine-key` (`crypto/credentials.ts`). Copying that key to another device
+ * would make the two devices one trust domain, so it is never exported. A
+ * credential crosses devices one of two ways instead:
+ *
+ * - **Sealed** (encrypted backups) — {@link sealCredentials} decrypts every
+ *   local credential and seals the plaintexts under a passphrase-derived key
+ *   (scrypt + AES-256-GCM, the same envelope as encrypted bundles).
+ *   {@link unsealCredentials} on the target device opens that payload and
+ *   re-encrypts each credential under the TARGET machine-key.
+ * - **Re-entered** (unencrypted backups) — {@link redactCredentialCiphertexts}
+ *   blanks the device-bound ciphertexts in the STAGED snapshot (they are
+ *   useless elsewhere) and {@link listCredentialsForReentry} names every
+ *   credential with the one command that re-enters it.
+ *
+ * This module also migrates project credentials from the legacy path-bound
+ * KDF to the project-identity KDF ({@link migrateProjectCredentials}), so a
+ * moved project directory keeps its credentials.
+ *
+ * Stores covered:
+ *
+ * | Store | Location | Encryption |
+ * |-------|----------|------------|
+ * | `project-agent` | project `cleo.db` → `tasks_agent_credentials.api_key_encrypted` | project KDF |
+ * | `service-connection` | global `cleo.db` → `service_connections.credentials_enc` | global KDF, id `service:<provider>:<label>` |
+ * | `llm-pool` | `<cleoHome>/llm-credentials.json` | none (0600 plaintext file) |
+ * | `agent-registry` | global `cleo.db` → `agent_registry_agents.api_key_encrypted` | global KDF, id `agent:<agentId>` (T12352) |
+ *
+ * The LLM pool stays a plaintext 0600 file on purpose (T12326 decision).
+ * Encrypting it under the machine-key would add little on-device protection,
+ * because the key sits in the same directory with the same mode. It would also
+ * force a key read into the synchronous resolver hot path
+ * (`pickCredentialForProviderSync`) and break the tools that read the file
+ * directly. What matters is that the pool never enters an unencrypted bundle,
+ * and this module guarantees that: the pool is either sealed or listed for
+ * re-entry.
+ *
+ * Callers pass FILE PATHS (live stores, or a backup's staged snapshots); the
+ * module opens short-lived raw handles and closes them before returning.
+ *
+ * @task T12326
+ * @module store/credential-transfer
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { decryptGlobal, decryptProjectSecret, encryptGlobal, encryptProjectSecret, } from '../crypto/credentials.js';
+import { addCredential, credentialsStorePath, isStoredCredential, } from '../llm/credentials-store.js';
+import { getCleoHome } from '../paths.js';
+import { openAgentApiKey, sealAgentApiKey } from './agent-api-key.js';
+import { decryptBundle, encryptBundle } from './backup-crypto.js';
+// ---------------------------------------------------------------------------
+// node:sqlite interop (createRequire — Vitest strips `node:` prefix)
+// ---------------------------------------------------------------------------
+const _require = createRequire(import.meta.url);
+const { DatabaseSync } = _require('node:sqlite');
+/**
+ * Error thrown by credential transfer. Raised BEFORE any write, so a caller
+ * that catches it knows no store was modified.
+ *
+ * @task T12326
+ */
+export class CredentialTransferError extends Error {
+    /** Machine-readable failure code. */
+    code;
+    /**
+     * @param code - Failure code.
+     * @param message - Human-readable explanation, including the remedy.
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = 'CredentialTransferError';
+        this.code = code;
+    }
+}
+// ---------------------------------------------------------------------------
+// Sealed payload shape
+// ---------------------------------------------------------------------------
+/** Discriminator written into every sealed payload. */
+const PAYLOAD_FORMAT = 'cleo-credential-transfer';
+/** Payload schema version. */
+const PAYLOAD_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Re-entry commands
+// ---------------------------------------------------------------------------
+/** Quote a shell argument only when it needs quoting. */
+function shellArg(value) {
+    return /^[A-Za-z0-9_./:@-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build the re-entry record for a credential: its identity, why it must be
+ * re-entered, and the one command that re-enters it.
+ *
+ * @param descriptor - The credential.
+ * @param reason - Why it could not be carried over.
+ * @returns The re-entry record.
+ * @task T12326
+ */
+export function reentryFor(descriptor, reason) {
+    return { ...descriptor, reason, reentryCommand: reentryCommandFor(descriptor) };
+}
+/**
+ * The one command that re-enters a credential. Secrets appear as a
+ * placeholder, never a value.
+ */
+function reentryCommandFor(descriptor) {
+    switch (descriptor.store) {
+        case 'project-agent':
+        case 'agent-registry':
+            return `cleo agent register --id ${shellArg(descriptor.id)} --name ${shellArg(descriptor.label)} --api-key <API_KEY>`;
+        case 'service-connection': {
+            const { provider, label } = splitProviderLabel(descriptor.id);
+            return `cleo service connect ${shellArg(provider)} --label ${shellArg(label)} --token <TOKEN>`;
+        }
+        case 'llm-pool': {
+            const { provider, label } = splitProviderLabel(descriptor.id);
+            return `printf '%s' "$API_KEY" | cleo llm add ${shellArg(provider)} --label ${shellArg(label)} --api-key-stdin`;
+        }
+    }
+}
+/** Split a `<provider>:<label>` id (labels may contain `:`). */
+function splitProviderLabel(id) {
+    const idx = id.indexOf(':');
+    return idx < 0
+        ? { provider: id, label: 'default' }
+        : { provider: id.slice(0, idx), label: id.slice(idx + 1) };
+}
+/** Open a database file, run `fn`, always close. Returns `fallback` when the file is absent. */
+function withDb(dbPath, fallback, fn) {
+    if (dbPath === undefined || !fs.existsSync(dbPath))
+        return fallback;
+    const db = new DatabaseSync(dbPath);
+    try {
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * True when `table` exists in `db` and has every one of `columns`. Stores in
+ * the wild include older or partial schemas; a table without the columns this
+ * module reads is treated as holding no credentials rather than failing the
+ * caller (a backup must not abort on it).
+ */
+function hasTable(db, table, columns = []) {
+    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table) ===
+        undefined) {
+        return false;
+    }
+    if (columns.length === 0)
+        return true;
+    const present = new Set(db.prepare(`PRAGMA table_info("${table}")`).all().map((c) => c.name));
+    return columns.every((c) => present.has(c));
+}
+/** Read `tasks_agent_credentials` rows that carry ciphertext. */
+function readProjectAgentRows(dbPath) {
+    return withDb(dbPath, [], (db) => {
+        if (!hasTable(db, 'tasks_agent_credentials', ['agent_id', 'display_name', 'api_key_encrypted'])) {
+            return [];
+        }
+        const rows = db
+            .prepare("SELECT agent_id, display_name, api_key_encrypted FROM tasks_agent_credentials WHERE api_key_encrypted <> '' ORDER BY agent_id")
+            .all();
+        return rows.map((r) => ({
+            descriptor: { store: 'project-agent', id: r.agent_id, label: r.display_name },
+            material: r.api_key_encrypted,
+        }));
+    });
+}
+/** Read `service_connections` rows that carry ciphertext. */
+function readServiceConnectionRows(dbPath) {
+    return withDb(dbPath, [], (db) => {
+        if (!hasTable(db, 'service_connections', ['provider', 'label', 'credentials_enc']))
+            return [];
+        const rows = db
+            .prepare("SELECT provider, label, credentials_enc FROM service_connections WHERE credentials_enc IS NOT NULL AND credentials_enc <> '' ORDER BY provider, label")
+            .all();
+        return rows.map((r) => ({
+            descriptor: {
+                store: 'service-connection',
+                id: `${r.provider}:${r.label}`,
+                label: `${r.provider} service connection "${r.label}"`,
+            },
+            material: r.credentials_enc,
+        }));
+    });
+}
+/** Read `agent_registry_agents` rows that carry a stored key (any format). */
+function readAgentRegistryRows(dbPath) {
+    return withDb(dbPath, [], (db) => {
+        if (!hasTable(db, 'agent_registry_agents', ['agent_id', 'name', 'api_key_encrypted'])) {
+            return [];
+        }
+        const rows = db
+            .prepare("SELECT agent_id, name, api_key_encrypted FROM agent_registry_agents WHERE api_key_encrypted IS NOT NULL AND api_key_encrypted <> '' ORDER BY agent_id")
+            .all();
+        return rows.map((r) => ({
+            descriptor: { store: 'agent-registry', id: r.agent_id, label: r.name },
+            material: r.api_key_encrypted,
+        }));
+    });
+}
+/** Read the LLM pool file's entries. A missing or malformed file yields none. */
+function readLlmPoolRows(storePath) {
+    if (storePath === undefined || !fs.existsSync(storePath))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(storePath, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== 'object' || parsed === null || !('credentials' in parsed))
+        return [];
+    const credentials = parsed.credentials;
+    if (!Array.isArray(credentials))
+        return [];
+    return credentials.filter(isStoredCredential).map((c) => ({
+        descriptor: {
+            store: 'llm-pool',
+            id: `${c.provider}:${c.label}`,
+            label: `${c.provider} LLM credential "${c.label}"`,
+        },
+        material: JSON.stringify(c),
+    }));
+}
+/** Every credential row across the given sources, still encrypted. */
+function readAllRows(sources) {
+    return [
+        ...readProjectAgentRows(sources.projectDbPath),
+        ...readServiceConnectionRows(sources.globalDbPath),
+        ...readAgentRegistryRows(sources.globalDbPath),
+        ...readLlmPoolRows(sources.llmStorePath),
+    ];
+}
+// ---------------------------------------------------------------------------
+// Unencrypted-bundle path: list + redact
+// ---------------------------------------------------------------------------
+/**
+ * List every credential in `sources` with the command that re-enters it.
+ * Reads identities only — nothing is decrypted.
+ *
+ * Use for an UNENCRYPTED backup: its import cannot carry credentials, so the
+ * import report prints this list.
+ *
+ * @param sources - Stores to enumerate.
+ * @param reason - Why the credentials must be re-entered (shown per entry).
+ * @returns One re-entry record per credential.
+ * @task T12326
+ */
+export function listCredentialsForReentry(sources, reason = 'unencrypted backups do not carry credentials') {
+    return readAllRows(sources).map((row) => reentryFor(row.descriptor, reason));
+}
+/** Resolve a path for comparison, following symlinks when the file exists. */
+function canonicalPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * Refuse to redact anything that looks like a live store: the global
+ * `cleo.db`, or any database directly inside a `.cleo/` directory.
+ */
+function assertStagedCopy(dbPath) {
+    const resolved = canonicalPath(dbPath);
+    const liveGlobal = canonicalPath(path.join(getCleoHome(), 'cleo.db'));
+    if (resolved === liveGlobal || path.basename(path.dirname(resolved)) === '.cleo') {
+        throw new CredentialTransferError('E_CREDENTIAL_LIVE_STORE', `Refusing to redact credentials in a live store (${resolved}). ` +
+            'Redaction applies only to staged backup snapshots.');
+    }
+}
+/**
+ * Blank the device-bound ciphertexts in STAGED snapshot databases and report
+ * what was removed.
+ *
+ * An unencrypted bundle must not carry credential ciphertext: it cannot be
+ * decrypted on another device, and it would be decryptable by anyone who
+ * later obtains this device's machine-key. Sets
+ * `tasks_agent_credentials.api_key_encrypted = ''` (the column is NOT NULL)
+ * and `service_connections.credentials_enc = NULL`; every non-secret column
+ * is kept. The LLM pool FILE is not touched — the bundle writer must exclude
+ * it, and can take its entries from the returned list.
+ *
+ * @param sources - Staged snapshot paths (`projectDbPath` / `globalDbPath`);
+ *   `llmStorePath` is listed, not modified.
+ * @returns Re-entry records for every redacted or excluded credential.
+ * @throws {CredentialTransferError} `E_CREDENTIAL_LIVE_STORE` when a path is
+ *   a live store.
+ * @task T12326
+ */
+export function redactCredentialCiphertexts(sources) {
+    if (sources.projectDbPath !== undefined)
+        assertStagedCopy(sources.projectDbPath);
+    if (sources.globalDbPath !== undefined)
+        assertStagedCopy(sources.globalDbPath);
+    const listed = listCredentialsForReentry(sources);
+    withDb(sources.projectDbPath, undefined, (db) => {
+        if (hasTable(db, 'tasks_agent_credentials', ['api_key_encrypted'])) {
+            db.prepare("UPDATE tasks_agent_credentials SET api_key_encrypted = ''").run();
+        }
+    });
+    withDb(sources.globalDbPath, undefined, (db) => {
+        if (hasTable(db, 'service_connections', ['credentials_enc'])) {
+            db.prepare('UPDATE service_connections SET credentials_enc = NULL WHERE credentials_enc IS NOT NULL').run();
+        }
+        if (hasTable(db, 'agent_registry_agents', ['api_key_encrypted'])) {
+            db.prepare('UPDATE agent_registry_agents SET api_key_encrypted = NULL WHERE api_key_encrypted IS NOT NULL').run();
+        }
+    });
+    return listed;
+}
+// ---------------------------------------------------------------------------
+// Encrypted-bundle path: seal + unseal
+// ---------------------------------------------------------------------------
+/** Require a project id when project credentials are present. */
+function requireProjectId(projectId, action) {
+    if (projectId === undefined || projectId.length === 0) {
+        throw new CredentialTransferError('E_CREDENTIAL_PROJECT_ID', `Cannot ${action} project credentials without the project's id ` +
+            '(the projectId in .cleo/project-info.json).');
+    }
+    return projectId;
+}
+/** Decrypt one stored row with the LOCAL keys. */
+async function openRow(row, sources) {
+    switch (row.descriptor.store) {
+        case 'project-agent': {
+            const projectId = requireProjectId(sources.projectId, 'seal');
+            const result = await decryptProjectSecret(row.material, {
+                projectId,
+                legacyProjectPaths: sources.legacyProjectPaths,
+                cleoHome: sources.cleoHome,
+            });
+            return result.plaintext;
+        }
+        case 'service-connection':
+            return decryptGlobal(row.material, `service:${row.descriptor.id}`, {
+                cleoHome: sources.cleoHome,
+            });
+        case 'agent-registry': {
+            const key = await openAgentApiKey(row.material, row.descriptor.id, {
+                cleoHome: sources.cleoHome,
+            });
+            if (key.requiresReauth)
+                throw new Error(key.reason ?? 'the stored key is not recoverable');
+            return key.apiKey;
+        }
+        case 'llm-pool':
+            return row.material;
+    }
+}
+/**
+ * Seal every credential in `sources` under a passphrase.
+ *
+ * Each credential is decrypted with THIS device's keys and the plaintexts are
+ * sealed together (scrypt-derived key, AES-256-GCM — {@link encryptBundle}).
+ * The payload carries credentials, never key material: the machine-key and
+ * global-salt stay on this device. A credential this device cannot decrypt is
+ * not sealed; it is reported in `reentry` (and carried into the payload so
+ * the importing device reports it too).
+ *
+ * @param sources - Stores to read (live stores or staged snapshots).
+ * @param passphrase - User passphrase; the same one opens the payload.
+ * @returns Sealed bytes plus what was sealed and what needs re-entry. A
+ *   project credential with no `sources.projectId` is reported for re-entry.
+ * @task T12326
+ */
+export async function sealCredentials(sources, passphrase) {
+    const rows = readAllRows(sources);
+    const entries = [];
+    const reentry = [];
+    for (const row of rows) {
+        try {
+            entries.push({ ...row.descriptor, secret: await openRow(row, sources) });
+        }
+        catch (err) {
+            reentry.push(reentryFor(row.descriptor, `not decryptable on the exporting device: ${err instanceof Error ? err.message : String(err)}`));
+        }
+    }
+    const payload = {
+        format: PAYLOAD_FORMAT,
+        version: PAYLOAD_VERSION,
+        createdAt: new Date().toISOString(),
+        entries,
+        reentry,
+    };
+    const plaintext = Buffer.from(JSON.stringify(payload), 'utf8');
+    try {
+        return {
+            sealed: encryptBundle(plaintext, passphrase),
+            sealedCredentials: entries.map(({ store, id, label }) => ({ store, id, label })),
+            reentry,
+        };
+    }
+    finally {
+        plaintext.fill(0);
+    }
+}
+/** Type guard for a credential descriptor field set. */
+function isDescriptor(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const store = 'store' in value ? value.store : undefined;
+    return ((store === 'project-agent' ||
+        store === 'service-connection' ||
+        store === 'llm-pool' ||
+        store === 'agent-registry') &&
+        'id' in value &&
+        typeof value.id === 'string' &&
+        'label' in value &&
+        typeof value.label === 'string');
+}
+/** Type guard for a sealed entry. */
+function isSealedEntry(value) {
+    return isDescriptor(value) && 'secret' in value && typeof value.secret === 'string';
+}
+/** Type guard for a carried re-entry record. */
+function isReentry(value) {
+    return (isDescriptor(value) &&
+        'reason' in value &&
+        typeof value.reason === 'string' &&
+        'reentryCommand' in value &&
+        typeof value.reentryCommand === 'string');
+}
+/** Parse and validate a decrypted payload. */
+function parsePayload(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('format' in parsed) ||
+        parsed.format !== PAYLOAD_FORMAT ||
+        !('version' in parsed) ||
+        parsed.version !== PAYLOAD_VERSION ||
+        !('entries' in parsed) ||
+        !Array.isArray(parsed.entries) ||
+        !parsed.entries.every(isSealedEntry) ||
+        !('reentry' in parsed) ||
+        !Array.isArray(parsed.reentry) ||
+        !parsed.reentry.every(isReentry)) {
+        throw new CredentialTransferError('E_CREDENTIAL_PAYLOAD', 'The sealed credential payload opened but is not a supported credential payload.');
+    }
+    return {
+        format: PAYLOAD_FORMAT,
+        version: PAYLOAD_VERSION,
+        createdAt: 'createdAt' in parsed && typeof parsed.createdAt === 'string' ? parsed.createdAt : '',
+        entries: parsed.entries,
+        reentry: parsed.reentry,
+    };
+}
+/**
+ * Update one ciphertext cell in `table`; returns whether a row matched. A
+ * table missing any of `columns` matches nothing (reported, never thrown).
+ */
+function updateCell(dbPath, table, columns, sql, params) {
+    return withDb(dbPath, false, (db) => {
+        if (!hasTable(db, table, columns))
+            return false;
+        return Number(db.prepare(sql).run(...params).changes) > 0;
+    });
+}
+/**
+ * Open a sealed payload and write every credential into the local stores,
+ * re-encrypted under THIS device's machine-key.
+ *
+ * Order of operations: the passphrase is checked and the payload validated
+ * BEFORE anything is written — a wrong passphrase leaves every store
+ * untouched. Database rows are updated in place (the restore must already
+ * have put the rows there); a credential whose row is absent, or whose store
+ * has no target, is reported for re-entry instead of being dropped silently.
+ *
+ * Call after the restored database files and any restored `global-salt` are in
+ * place: the global KDF reads the salt. Pass `targets.cleoHome` so the salt is
+ * read fresh from that home rather than from the process memo.
+ *
+ * @param sealed - Bytes from {@link sealCredentials}.
+ * @param passphrase - The passphrase used to seal.
+ * @param targets - Restored stores to write into.
+ * @returns What was restored and what must be re-entered (with commands).
+ * @throws {CredentialTransferError} `E_CREDENTIAL_PASSPHRASE` (wrong
+ *   passphrase or corrupted payload) or `E_CREDENTIAL_PAYLOAD` — nothing written.
+ * @task T12326
+ */
+export async function unsealCredentials(sealed, passphrase, targets) {
+    let opened;
+    try {
+        opened = decryptBundle(Buffer.from(sealed), passphrase);
+    }
+    catch {
+        throw new CredentialTransferError('E_CREDENTIAL_PASSPHRASE', 'Cannot open the sealed credentials: wrong passphrase, or the payload is corrupted. ' +
+            'Nothing was written. Re-run the import with the passphrase used for the export.');
+    }
+    let payload;
+    try {
+        payload = parsePayload(opened);
+    }
+    finally {
+        opened.fill(0);
+    }
+    // Phase 1 — encrypt everything under the local keys (no writes yet).
+    const writes = [];
+    const reentry = [...payload.reentry];
+    for (const entry of payload.entries) {
+        const descriptor = {
+            store: entry.store,
+            id: entry.id,
+            label: entry.label,
+        };
+        switch (entry.store) {
+            case 'project-agent': {
+                const { projectDbPath, projectId } = targets;
+                if (projectDbPath === undefined || projectId === undefined || projectId === '') {
+                    reentry.push(reentryFor(descriptor, 'no project store to restore into'));
+                    break;
+                }
+                const ciphertext = await encryptProjectSecret(entry.secret, projectId, {
+                    cleoHome: targets.cleoHome,
+                });
+                writes.push({
+                    entry,
+                    apply: async () => updateCell(projectDbPath, 'tasks_agent_credentials', ['agent_id', 'api_key_encrypted'], 'UPDATE tasks_agent_credentials SET api_key_encrypted = ? WHERE agent_id = ?', [ciphertext, entry.id]),
+                });
+                break;
+            }
+            case 'service-connection': {
+                const { globalDbPath } = targets;
+                if (globalDbPath === undefined) {
+                    reentry.push(reentryFor(descriptor, 'no global store to restore into'));
+                    break;
+                }
+                const ciphertext = await encryptGlobal(entry.secret, `service:${entry.id}`, {
+                    cleoHome: targets.cleoHome,
+                });
+                const { provider, label } = splitProviderLabel(entry.id);
+                writes.push({
+                    entry,
+                    apply: async () => updateCell(globalDbPath, 'service_connections', ['provider', 'label', 'credentials_enc'], 'UPDATE service_connections SET credentials_enc = ? WHERE provider = ? AND label = ?', [ciphertext, provider, label]),
+                });
+                break;
+            }
+            case 'agent-registry': {
+                const { globalDbPath } = targets;
+                if (globalDbPath === undefined) {
+                    reentry.push(reentryFor(descriptor, 'no global store to restore into'));
+                    break;
+                }
+                const stored = await sealAgentApiKey(entry.secret, entry.id, {
+                    cleoHome: targets.cleoHome,
+                });
+                writes.push({
+                    entry,
+                    apply: async () => updateCell(globalDbPath, 'agent_registry_agents', ['agent_id', 'api_key_encrypted', 'requires_reauth'], 'UPDATE agent_registry_agents SET api_key_encrypted = ?, requires_reauth = 0 WHERE agent_id = ?', [stored ?? '', entry.id]),
+                });
+                break;
+            }
+            case 'llm-pool': {
+                if (targets.restoreLlmPool === false) {
+                    reentry.push(reentryFor(descriptor, 'LLM pool restore was not requested'));
+                    break;
+                }
+                if (targets.cleoHome !== undefined &&
+                    canonicalPath(targets.cleoHome) !== canonicalPath(getCleoHome())) {
+                    reentry.push(reentryFor(descriptor, 'the LLM pool of a non-active CLEO home cannot be written'));
+                    break;
+                }
+                let credential;
+                try {
+                    credential = JSON.parse(entry.secret);
+                }
+                catch {
+                    credential = undefined;
+                }
+                if (!isStoredCredential(credential)) {
+                    reentry.push(reentryFor(descriptor, 'sealed LLM entry is malformed'));
+                    break;
+                }
+                const stored = credential;
+                writes.push({
+                    entry,
+                    apply: async () => {
+                        await addCredential(stored);
+                        return true;
+                    },
+                });
+                break;
+            }
+        }
+    }
+    // Phase 2 — write.
+    const restored = [];
+    for (const { entry, apply } of writes) {
+        const descriptor = {
+            store: entry.store,
+            id: entry.id,
+            label: entry.label,
+        };
+        if (await apply())
+            restored.push(descriptor);
+        else
+            reentry.push(reentryFor(descriptor, 'the restored store has no row for it'));
+    }
+    return { restored, reentry };
+}
+// ---------------------------------------------------------------------------
+// Project KDF migration (path-bound → project identity)
+// ---------------------------------------------------------------------------
+/**
+ * Re-encrypt project credentials from the legacy path-bound KDF to the
+ * project-identity KDF, in place.
+ *
+ * Each ciphertext is opened with {@link decryptProjectSecret}; a legacy one is
+ * rewritten with the re-wrapped ciphertext it returns. Current ciphertexts are
+ * left alone. A credential no candidate key opens is left UNTOUCHED (never
+ * deleted) and reported with its re-entry command — typically because it was
+ * encrypted at a path not in `legacyProjectPaths`, or on another device.
+ * Idempotent: a second run reports everything as `current`. With `dryRun`
+ * nothing is written and `migrated` lists what WOULD be migrated.
+ *
+ * @param sources - `projectDbPath`, `projectId`, and `legacyProjectPaths`.
+ * @param options - `dryRun` to report without writing.
+ * @returns Migrated, already-current, and unrecoverable credentials.
+ * @throws {CredentialTransferError} `E_CREDENTIAL_PROJECT_ID` when rows exist
+ *   and `projectId` is missing.
+ * @task T12326
+ */
+export async function migrateProjectCredentials(sources, options = {}) {
+    const rows = readProjectAgentRows(sources.projectDbPath);
+    const migrated = [];
+    const current = [];
+    const reentry = [];
+    if (rows.length === 0 || sources.projectDbPath === undefined) {
+        return { migrated, current, reentry };
+    }
+    const projectId = requireProjectId(sources.projectId, 'migrate');
+    const dbPath = sources.projectDbPath;
+    for (const row of rows) {
+        let result;
+        try {
+            result = await decryptProjectSecret(row.material, {
+                projectId,
+                legacyProjectPaths: sources.legacyProjectPaths,
+                cleoHome: sources.cleoHome,
+            });
+        }
+        catch (err) {
+            reentry.push(reentryFor(row.descriptor, err instanceof Error ? err.message : String(err)));
+            continue;
+        }
+        if (result.rewrapped === null) {
+            current.push(row.descriptor);
+            continue;
+        }
+        if (options.dryRun === true) {
+            migrated.push(row.descriptor);
+            continue;
+        }
+        // Compare-and-swap on the old ciphertext: a concurrent writer wins.
+        const swapped = updateCell(dbPath, 'tasks_agent_credentials', ['agent_id', 'api_key_encrypted'], 'UPDATE tasks_agent_credentials SET api_key_encrypted = ? WHERE agent_id = ? AND api_key_encrypted = ?', [result.rewrapped, row.descriptor.id, row.material]);
+        (swapped ? migrated : current).push(row.descriptor);
+    }
+    return { migrated, current, reentry };
+}
+/**
+ * Migrate a project's stored credentials off the path-bound KDF, resolving
+ * everything from the project root: the store is `<root>/.cleo/cleo.db`, the
+ * identity is `projectId` from `.cleo/project-info.json`, and the legacy
+ * candidates are the root as given and its real path.
+ *
+ * This is the trigger used by `cleo upgrade` and `cleo doctor credentials`.
+ * It is idempotent and never deletes; unrecoverable rows come back in
+ * `reentry` with the command that re-enters each one. A project with no
+ * credential rows returns empty lists without opening anything for write.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param options - `dryRun` to report without writing; `cleoHome` to key with another home.
+ * @returns What was (or would be) migrated, what is current, and what must be re-entered.
+ * @throws {CredentialTransferError} `E_CREDENTIAL_PROJECT_ID` when credential
+ *   rows exist but project-info.json has no `projectId`.
+ * @task T12326
+ */
+export async function migrateProjectCredentialsAtRoot(projectRoot, options = {}) {
+    const root = path.resolve(projectRoot);
+    const cleoDir = path.join(root, '.cleo');
+    const projectDbPath = path.join(cleoDir, 'cleo.db');
+    let projectId = null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cleoDir, 'project-info.json'), 'utf-8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'projectId' in parsed &&
+            typeof parsed.projectId === 'string' &&
+            parsed.projectId.length > 0) {
+            projectId = parsed.projectId;
+        }
+    }
+    catch {
+        projectId = null;
+    }
+    const result = await migrateProjectCredentials({
+        projectDbPath,
+        ...(projectId !== null ? { projectId } : {}),
+        legacyProjectPaths: [root, canonicalPath(root)],
+        ...(options.cleoHome !== undefined ? { cleoHome: options.cleoHome } : {}),
+    }, { dryRun: options.dryRun === true });
+    return { ...result, projectDbPath, projectId, dryRun: options.dryRun === true };
+}
+/**
+ * Find agents whose stored API key cannot be recovered and, unless `dryRun`,
+ * flag them `requires_reauth = 1` (T12352).
+ *
+ * Before T12352 `api_key_encrypted` held a derived HMAC instead of the key.
+ * The real key was discarded, so those rows cannot be migrated, only flagged
+ * and listed with the command that re-registers the key. Never modifies the
+ * stored value; idempotent.
+ *
+ * @param globalDbPath - Global `cleo.db`.
+ * @param options - `dryRun` to report without flagging; `cleoHome` for the keys.
+ * @returns Recoverable agents, agents to re-register, and how many were flagged.
+ * @task T12352
+ */
+export async function auditAgentRegistryKeys(globalDbPath, options = {}) {
+    const current = [];
+    const reentry = [];
+    const unrecoverable = [];
+    for (const row of readAgentRegistryRows(globalDbPath)) {
+        const key = await openAgentApiKey(row.material, row.descriptor.id, {
+            ...(options.cleoHome !== undefined ? { cleoHome: options.cleoHome } : {}),
+        });
+        if (key.requiresReauth) {
+            reentry.push(reentryFor(row.descriptor, key.reason ?? 'the stored key is not recoverable'));
+            unrecoverable.push(row.descriptor.id);
+        }
+        else {
+            current.push(row.descriptor);
+        }
+    }
+    let flagged = 0;
+    if (options.dryRun !== true && unrecoverable.length > 0) {
+        flagged = withDb(globalDbPath, 0, (db) => {
+            if (!hasTable(db, 'agent_registry_agents', ['agent_id', 'requires_reauth']))
+                return 0;
+            const stmt = db.prepare('UPDATE agent_registry_agents SET requires_reauth = 1 WHERE agent_id = ? AND requires_reauth = 0');
+            let n = 0;
+            for (const id of unrecoverable)
+                n += Number(stmt.run(id).changes);
+            return n;
+        });
+    }
+    return { globalDbPath, current, reentry, flagged, dryRun: options.dryRun === true };
+}
+/**
+ * The live LLM pool path, re-exported so a bundle writer need not import the
+ * LLM module to fill {@link CredentialSources.llmStorePath}.
+ *
+ * @returns `<cleoHome>/llm-credentials.json`.
+ * @task T12326
+ */
+export function liveLlmCredentialStorePath() {
+    return credentialsStorePath();
+}
+//# sourceMappingURL=credential-transfer.js.map