@cleocode/core 2026.9.16 → 2026.9.17

package/dist/store/credential-transfer.d.ts

@@ -0,0 +1,303 @@
+/**
+ * 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 type { CredentialDescriptor, CredentialReentry, ProjectCredentialMigrationResult, SealCredentialsResult, UnsealCredentialsResult } from '@cleocode/contracts';
+/**
+ * Where to read credentials from. Every field is optional; an omitted store is
+ * skipped.
+ *
+ * @task T12326
+ */
+export interface CredentialSources {
+    /** Project `cleo.db` (live, or a staged snapshot). */
+    readonly projectDbPath?: string;
+    /** Project identity keying the project KDF. Required when the project store has rows. */
+    readonly projectId?: string;
+    /** Candidate paths for legacy path-bound project ciphertexts (usually the project root). */
+    readonly legacyProjectPaths?: readonly string[];
+    /** Global `cleo.db` (live, or a staged snapshot). */
+    readonly globalDbPath?: string;
+    /** LLM credential pool file. Defaults to none; pass `credentialsStorePath()` for the live pool. */
+    readonly llmStorePath?: string;
+    /** CLEO home whose machine-key (and global-salt) decrypt the stores. Defaults to the ambient home. */
+    readonly cleoHome?: string;
+}
+/**
+ * Where {@link unsealCredentials} writes. The restored database files must
+ * already be in place — rows are updated, never created.
+ *
+ * @task T12326
+ */
+export interface CredentialTargets {
+    /** Restored project `cleo.db`. */
+    readonly projectDbPath?: string;
+    /** Identity of the restored project (its `.cleo/project-info.json` `projectId`). */
+    readonly projectId?: string;
+    /** Restored global `cleo.db`. */
+    readonly globalDbPath?: string;
+    /**
+     * Write `llm-pool` entries into the local pool (`<cleoHome>/llm-credentials.json`).
+     * Default `true`. Only the AMBIENT home's pool can be written; with a
+     * different `cleoHome` the entries are reported for re-entry instead.
+     */
+    readonly restoreLlmPool?: boolean;
+    /**
+     * CLEO home whose machine-key (and global-salt) re-encrypt the credentials —
+     * the home being restored INTO. Defaults to the ambient home.
+     */
+    readonly cleoHome?: string;
+}
+/**
+ * Error codes raised by this module.
+ *
+ * - `E_CREDENTIAL_PASSPHRASE` — the passphrase did not open the sealed payload.
+ * - `E_CREDENTIAL_PAYLOAD` — the payload opened but is not a credential payload.
+ * - `E_CREDENTIAL_PROJECT_ID` — a project store has credentials but no project id was given.
+ * - `E_CREDENTIAL_LIVE_STORE` — {@link redactCredentialCiphertexts} was pointed at a live store.
+ *
+ * @task T12326
+ */
+export type CredentialTransferErrorCode = 'E_CREDENTIAL_PASSPHRASE' | 'E_CREDENTIAL_PAYLOAD' | 'E_CREDENTIAL_PROJECT_ID' | 'E_CREDENTIAL_LIVE_STORE';
+/**
+ * Error thrown by credential transfer. Raised BEFORE any write, so a caller
+ * that catches it knows no store was modified.
+ *
+ * @task T12326
+ */
+export declare class CredentialTransferError extends Error {
+    /** Machine-readable failure code. */
+    readonly code: CredentialTransferErrorCode;
+    /**
+     * @param code - Failure code.
+     * @param message - Human-readable explanation, including the remedy.
+     */
+    constructor(code: CredentialTransferErrorCode, message: string);
+}
+/**
+ * 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 declare function reentryFor(descriptor: CredentialDescriptor, reason: string): CredentialReentry;
+/**
+ * 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 declare function listCredentialsForReentry(sources: CredentialSources, reason?: string): CredentialReentry[];
+/**
+ * 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 declare function redactCredentialCiphertexts(sources: CredentialSources): CredentialReentry[];
+/**
+ * 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 declare function sealCredentials(sources: CredentialSources, passphrase: string): Promise<SealCredentialsResult>;
+/**
+ * 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 declare function unsealCredentials(sealed: Uint8Array, passphrase: string, targets: CredentialTargets): Promise<UnsealCredentialsResult>;
+/**
+ * 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 declare function migrateProjectCredentials(sources: Pick<CredentialSources, 'projectDbPath' | 'projectId' | 'legacyProjectPaths' | 'cleoHome'>, options?: {
+    readonly dryRun?: boolean;
+}): Promise<ProjectCredentialMigrationResult>;
+/**
+ * Outcome of {@link migrateProjectCredentialsAtRoot}.
+ *
+ * @task T12326
+ */
+export interface ProjectRootCredentialMigration extends ProjectCredentialMigrationResult {
+    /** Project store examined. */
+    readonly projectDbPath: string;
+    /** Project identity keying the new KDF (null when project-info.json has none). */
+    readonly projectId: string | null;
+    /** Whether this was a dry run (nothing written). */
+    readonly dryRun: boolean;
+}
+/**
+ * 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 declare function migrateProjectCredentialsAtRoot(projectRoot: string, options?: {
+    readonly dryRun?: boolean;
+    readonly cleoHome?: string;
+}): Promise<ProjectRootCredentialMigration>;
+/**
+ * Outcome of {@link auditAgentRegistryKeys}.
+ *
+ * @task T12352
+ */
+export interface AgentRegistryKeyAudit {
+    /** Global store examined. */
+    readonly globalDbPath: string;
+    /** Agents whose stored key decrypts to the real key. */
+    readonly current: readonly CredentialDescriptor[];
+    /** Agents whose real key is not recoverable, each with the re-register command. */
+    readonly reentry: readonly CredentialReentry[];
+    /** Rows newly flagged `requires_reauth = 1` (0 on a dry run). */
+    readonly flagged: number;
+    /** Whether this was a dry run. */
+    readonly dryRun: boolean;
+}
+/**
+ * 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 declare function auditAgentRegistryKeys(globalDbPath: string, options?: {
+    readonly dryRun?: boolean;
+    readonly cleoHome?: string;
+}): Promise<AgentRegistryKeyAudit>;
+/**
+ * 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 declare function liveLlmCredentialStorePath(): string;
+//# sourceMappingURL=credential-transfer.d.ts.map

package/dist/store/credential-transfer.d.ts.map

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