/**
 * 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` | global `cleo.db` → `accounts.secret_enc` / `refresh_enc`; legacy `<cleoHome>/llm-credentials.json` | global KDF, id `account:<provider>:<label>` (T13715); the legacy file is plaintext |
 * | `agent-registry` | global `cleo.db` → `agent_registry_agents.api_key_encrypted` | global KDF, id `agent:<agentId>` (T12352) |
 *
 * The LLM pool moved from a plaintext 0600 file into the synced `accounts`
 * table (T13715, superseding the T12326 decision to keep the file), so it
 * travels on the home stream. An unmigrated legacy file is still read. The
 * pool never enters an unencrypted bundle: it is either sealed or listed for
 * re-entry, and its ciphertext is blanked in staged snapshots.
 *
 * 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;
    /**
     * Ids the project was keyed by before a re-key (T12716); ciphertexts under
     * them are opened and re-wrapped under {@link CredentialSources.projectId}.
     */
    readonly previousProjectIds?: readonly 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 pool: the `accounts` table of
     * {@link CredentialTargets.globalDbPath} when given (T13715), else the
     * ambient home's pool. Default `true`. Without a global store, 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` (likewise the `accounts`
 * secrets); 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' | 'previousProjectIds' | '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;
}
/**
 * The id that keys a project's credentials, plus the ids it was keyed by
 * before (T12716).
 *
 * The id is the declared one — tracked `.cleo/project.json` /
 * `.cleo/project-id` first, then the `project-info.json` cache — the same
 * order every identity reader uses. The previous ids are the cache when it
 * disagrees (a conflict not yet resolved), the cache's `previousProjectIds`
 * receipts (a conflict `cleo doctor project-identity --resolve` already
 * re-keyed), and every id the global registry aliases to the declared one
 * (`nexus_project_id_aliases`), so credentials sealed under any of them open.
 * The alias read never creates the global store.
 *
 * @param projectRoot - Project root.
 * @param cleoHome - Global CLEO home whose alias table is read (defaults to the current one).
 * @returns The declared id (`null` when none) and the previous ids.
 * @example
 * ```ts
 * const { projectId, previousProjectIds } = await readProjectCredentialIdentity(root);
 * ```
 * @task T12716
 */
export declare function readProjectCredentialIdentity(projectRoot: string, cleoHome?: string): Promise<{
    projectId: string | null;
    previousProjectIds: string[];
}>;
/**
 * Migrate a project's stored credentials off the path-bound KDF (and off any
 * id the project was re-keyed away from — T12716), resolving everything from
 * the project root: the store is `<root>/.cleo/cleo.db`, the identity is
 * {@link readProjectCredentialIdentity}, 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