@cleocode/core 2026.9.15 → 2026.9.17

package/dist/store/agent-api-key.d.ts

@@ -0,0 +1,114 @@
+/**
+ * agent-api-key.ts — at-rest storage of agent API keys in
+ * `agent_registry_agents.api_key_encrypted` (global `cleo.db`).
+ *
+ * ## What went wrong (T12352)
+ *
+ * ADR-037 §5 specified the global KDF as
+ * `apiKey = HMAC-SHA256(machine-key ‖ global-salt, agentId)`. That output is an
+ * ENCRYPTION KEY: the same section says the migration "MUST decrypt each
+ * existing key … and re-encrypt using the new KDF", and the `AgentCredential`
+ * contract says the key is "stored encrypted at rest". But the variable was
+ * named `apiKey`, and T355 implemented it literally. `createProjectAgent`,
+ * `update` and `rotateKey` in `agent-registry-accessor.ts` stored the hex of
+ * the HMAC in `api_key_encrypted` and DISCARDED the real key, including the
+ * fresh key the cloud returned from `rotate-key`. The reader then returned hex
+ * of that hex as `apiKey`. Every consumer sends it as `Authorization: Bearer`
+ * to SignalDock (`cleo agent …`, `conduit` dispatch, the HTTP/SSE transports),
+ * and every one of them needs the real key.
+ *
+ * ## What is stored now
+ *
+ * `api_key_encrypted` holds `gk1:` followed by {@link encryptGlobal}
+ * ciphertext of the real key, under the global KDF ADR-037 intended, with
+ * credential id `agent:<agentId>`. It is recoverable after a restart. It moves
+ * to another device via the passphrase-sealed credential transfer
+ * (`store/credential-transfer.ts`), never by copying the machine-key.
+ *
+ * ## Rows written before the fix
+ *
+ * They hold 64 hex characters (the HMAC) or an unrecognised legacy value.
+ * Neither contains the real key, so neither can be migrated. To avoid changing
+ * behaviour for anything that depends on today's value, they are read back
+ * exactly as before, but flagged `requiresReauth` with the command that
+ * re-registers the agent's real key.
+ *
+ * @task T12352
+ * @module store/agent-api-key
+ */
+import { type CredentialKeyOptions } from '../crypto/credentials.js';
+/** Prefix marking an `api_key_encrypted` value as a T12352 global-KDF ciphertext. */
+export declare const AGENT_KEY_CIPHERTEXT_PREFIX = "gk1:";
+/**
+ * The global-KDF credential id for an agent's API key. The `agent:` prefix
+ * separates agent keys from other global credentials (`service:<p>:<l>`).
+ *
+ * @param agentId - Agent business identifier.
+ * @returns The id passed to {@link encryptGlobal} / {@link decryptGlobal}.
+ * @task T12352
+ */
+export declare function agentKeyCredentialId(agentId: string): string;
+/**
+ * How an `api_key_encrypted` value was written.
+ *
+ * - `none` — empty / NULL.
+ * - `ciphertext` — a T12352 `gk1:` global-KDF ciphertext (recoverable).
+ * - `legacy-derived` — the pre-T12352 hex HMAC (the real key was discarded).
+ * - `legacy-unknown` — anything else (e.g. a pre-T310 path-KDF ciphertext).
+ *
+ * @task T12352
+ */
+export type StoredAgentKeyKind = 'none' | 'ciphertext' | 'legacy-derived' | 'legacy-unknown';
+/**
+ * Classify a stored `api_key_encrypted` value without decrypting it.
+ *
+ * @param stored - Raw column value.
+ * @returns Its kind.
+ * @task T12352
+ */
+export declare function classifyStoredAgentKey(stored: string | null | undefined): StoredAgentKeyKind;
+/**
+ * Encrypt an agent API key for `api_key_encrypted`.
+ *
+ * @param apiKey - The real key (e.g. `sk_live_…`). Empty yields `null`.
+ * @param agentId - Agent business identifier (binds the key derivation).
+ * @param options - Which CLEO home's machine-key + salt (defaults to ambient).
+ * @returns `gk1:<ciphertext>`, or `null` when there is no key to store.
+ * @task T12352
+ */
+export declare function sealAgentApiKey(apiKey: string, agentId: string, options?: CredentialKeyOptions): Promise<string | null>;
+/**
+ * Result of reading a stored agent API key.
+ *
+ * @task T12352
+ */
+export interface AgentApiKeyRead {
+    /** The value to expose as `AgentCredential.apiKey`. */
+    readonly apiKey: string;
+    /** Kind of the stored value. */
+    readonly kind: StoredAgentKeyKind;
+    /**
+     * True when the real key is not recoverable from storage and must be
+     * re-registered: legacy values, or a ciphertext this device cannot decrypt.
+     */
+    readonly requiresReauth: boolean;
+    /** Why re-registration is needed (absent when not). */
+    readonly reason?: string;
+}
+/**
+ * Read an agent API key from `api_key_encrypted`.
+ *
+ * A `gk1:` ciphertext is decrypted to the real key. Legacy values are returned
+ * exactly as the pre-T12352 reader returned them, so nothing that works today
+ * changes, but they are flagged `requiresReauth`. A ciphertext that does not
+ * decrypt here (another device's key) is flagged too; it never throws, because
+ * a listing must not fail on one bad row.
+ *
+ * @param stored - Raw column value.
+ * @param agentId - Agent business identifier.
+ * @param options - Which CLEO home's machine-key + salt (defaults to ambient).
+ * @returns The key to expose, its kind, and whether re-registration is needed.
+ * @task T12352
+ */
+export declare function openAgentApiKey(stored: string | null | undefined, agentId: string, options?: CredentialKeyOptions): Promise<AgentApiKeyRead>;
+//# sourceMappingURL=agent-api-key.d.ts.map

package/dist/store/agent-api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-api-key.d.ts","sourceRoot":"","sources":["../../src/store/agent-api-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,KAAK,oBAAoB,EAAgC,MAAM,0BAA0B,CAAC;AAEnG,qFAAqF;AACrF,eAAO,MAAM,2BAA2B,SAAS,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,YAAY,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE7F;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,CAK5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,eAAe,CAAC,CA+B1B"}

package/dist/store/agent-api-key.js

@@ -0,0 +1,136 @@
+/**
+ * agent-api-key.ts — at-rest storage of agent API keys in
+ * `agent_registry_agents.api_key_encrypted` (global `cleo.db`).
+ *
+ * ## What went wrong (T12352)
+ *
+ * ADR-037 §5 specified the global KDF as
+ * `apiKey = HMAC-SHA256(machine-key ‖ global-salt, agentId)`. That output is an
+ * ENCRYPTION KEY: the same section says the migration "MUST decrypt each
+ * existing key … and re-encrypt using the new KDF", and the `AgentCredential`
+ * contract says the key is "stored encrypted at rest". But the variable was
+ * named `apiKey`, and T355 implemented it literally. `createProjectAgent`,
+ * `update` and `rotateKey` in `agent-registry-accessor.ts` stored the hex of
+ * the HMAC in `api_key_encrypted` and DISCARDED the real key, including the
+ * fresh key the cloud returned from `rotate-key`. The reader then returned hex
+ * of that hex as `apiKey`. Every consumer sends it as `Authorization: Bearer`
+ * to SignalDock (`cleo agent …`, `conduit` dispatch, the HTTP/SSE transports),
+ * and every one of them needs the real key.
+ *
+ * ## What is stored now
+ *
+ * `api_key_encrypted` holds `gk1:` followed by {@link encryptGlobal}
+ * ciphertext of the real key, under the global KDF ADR-037 intended, with
+ * credential id `agent:<agentId>`. It is recoverable after a restart. It moves
+ * to another device via the passphrase-sealed credential transfer
+ * (`store/credential-transfer.ts`), never by copying the machine-key.
+ *
+ * ## Rows written before the fix
+ *
+ * They hold 64 hex characters (the HMAC) or an unrecognised legacy value.
+ * Neither contains the real key, so neither can be migrated. To avoid changing
+ * behaviour for anything that depends on today's value, they are read back
+ * exactly as before, but flagged `requiresReauth` with the command that
+ * re-registers the agent's real key.
+ *
+ * @task T12352
+ * @module store/agent-api-key
+ */
+import { decryptGlobal, encryptGlobal } from '../crypto/credentials.js';
+/** Prefix marking an `api_key_encrypted` value as a T12352 global-KDF ciphertext. */
+export const AGENT_KEY_CIPHERTEXT_PREFIX = 'gk1:';
+/** Shape of a pre-T12352 value: the hex HMAC the old code stored instead of the key. */
+const LEGACY_DERIVED_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * The global-KDF credential id for an agent's API key. The `agent:` prefix
+ * separates agent keys from other global credentials (`service:<p>:<l>`).
+ *
+ * @param agentId - Agent business identifier.
+ * @returns The id passed to {@link encryptGlobal} / {@link decryptGlobal}.
+ * @task T12352
+ */
+export function agentKeyCredentialId(agentId) {
+    return `agent:${agentId}`;
+}
+/**
+ * Classify a stored `api_key_encrypted` value without decrypting it.
+ *
+ * @param stored - Raw column value.
+ * @returns Its kind.
+ * @task T12352
+ */
+export function classifyStoredAgentKey(stored) {
+    if (stored === null || stored === undefined || stored === '')
+        return 'none';
+    if (stored.startsWith(AGENT_KEY_CIPHERTEXT_PREFIX))
+        return 'ciphertext';
+    if (LEGACY_DERIVED_PATTERN.test(stored))
+        return 'legacy-derived';
+    return 'legacy-unknown';
+}
+/**
+ * Encrypt an agent API key for `api_key_encrypted`.
+ *
+ * @param apiKey - The real key (e.g. `sk_live_…`). Empty yields `null`.
+ * @param agentId - Agent business identifier (binds the key derivation).
+ * @param options - Which CLEO home's machine-key + salt (defaults to ambient).
+ * @returns `gk1:<ciphertext>`, or `null` when there is no key to store.
+ * @task T12352
+ */
+export async function sealAgentApiKey(apiKey, agentId, options = {}) {
+    if (apiKey.length === 0)
+        return null;
+    return (AGENT_KEY_CIPHERTEXT_PREFIX +
+        (await encryptGlobal(apiKey, agentKeyCredentialId(agentId), options)));
+}
+/**
+ * The value pre-T12352 readers returned for a stored string: its UTF-8 bytes
+ * as hex. Kept for legacy rows so their observable `apiKey` does not change.
+ */
+function legacyReadValue(stored) {
+    return Buffer.from(stored).toString('hex');
+}
+/**
+ * Read an agent API key from `api_key_encrypted`.
+ *
+ * A `gk1:` ciphertext is decrypted to the real key. Legacy values are returned
+ * exactly as the pre-T12352 reader returned them, so nothing that works today
+ * changes, but they are flagged `requiresReauth`. A ciphertext that does not
+ * decrypt here (another device's key) is flagged too; it never throws, because
+ * a listing must not fail on one bad row.
+ *
+ * @param stored - Raw column value.
+ * @param agentId - Agent business identifier.
+ * @param options - Which CLEO home's machine-key + salt (defaults to ambient).
+ * @returns The key to expose, its kind, and whether re-registration is needed.
+ * @task T12352
+ */
+export async function openAgentApiKey(stored, agentId, options = {}) {
+    const kind = classifyStoredAgentKey(stored);
+    if (kind === 'none' || stored === null || stored === undefined) {
+        return { apiKey: '', kind, requiresReauth: false };
+    }
+    if (kind === 'ciphertext') {
+        try {
+            const apiKey = await decryptGlobal(stored.slice(AGENT_KEY_CIPHERTEXT_PREFIX.length), agentKeyCredentialId(agentId), options);
+            return { apiKey, kind, requiresReauth: false };
+        }
+        catch (err) {
+            return {
+                apiKey: '',
+                kind,
+                requiresReauth: true,
+                reason: `stored key does not decrypt on this device: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    return {
+        apiKey: legacyReadValue(stored),
+        kind,
+        requiresReauth: true,
+        reason: kind === 'legacy-derived'
+            ? 'stored before T12352: the column holds a derived HMAC, not the API key, which was discarded'
+            : 'stored in an unrecognised legacy format that does not contain a recoverable API key',
+    };
+}
+//# sourceMappingURL=agent-api-key.js.map

package/dist/store/agent-api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-api-key.js","sourceRoot":"","sources":["../../src/store/agent-api-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAA6B,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEnG,qFAAqF;AACrF,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAElD,wFAAwF;AACxF,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,SAAS,OAAO,EAAE,CAAC;AAC5B,CAAC;AAcD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAiC;IACtE,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,MAAM,CAAC;IAC5E,IAAI,MAAM,CAAC,UAAU,CAAC,2BAA2B,CAAC;QAAE,OAAO,YAAY,CAAC;IACxE,IAAI,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACjE,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,OAAe,EACf,UAAgC,EAAE;IAElC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,CACL,2BAA2B;QAC3B,CAAC,MAAM,aAAa,CAAC,MAAM,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CACtE,CAAC;AACJ,CAAC;AAqBD;;;GAGG;AACH,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAiC,EACjC,OAAe,EACf,UAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,IAAI,KAAK,MAAM,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/D,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAChC,MAAM,CAAC,KAAK,CAAC,2BAA2B,CAAC,MAAM,CAAC,EAChD,oBAAoB,CAAC,OAAO,CAAC,EAC7B,OAAO,CACR,CAAC;YACF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,MAAM,EAAE,EAAE;gBACV,IAAI;gBACJ,cAAc,EAAE,IAAI;gBACpB,MAAM,EAAE,+CAA+C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;aAC1G,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO;QACL,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC;QAC/B,IAAI;QACJ,cAAc,EAAE,IAAI;QACpB,MAAM,EACJ,IAAI,KAAK,gBAAgB;YACvB,CAAC,CAAC,6FAA6F;YAC/F,CAAC,CAAC,qFAAqF;KAC5F,CAAC;AACJ,CAAC"}

package/dist/store/agent-registry-accessor.d.ts

@@ -174,7 +174,9 @@ export declare function listAgentsForProject(projectRoot: string, opts?: {
  * Write order: global first, then project ref. If the project ref write fails,
  * the global row remains (recoverable via `cleo agent attach <id>`).
  *
- * API key derivation: HMAC-SHA256(machineKey || globalSalt, agentId) per ADR-037 §5.
+ * API key storage (T12352): the real `spec.apiKey` is stored encrypted under the
+ * global KDF (ADR-037 §5) — see `agent-api-key.ts`. An empty key on re-register
+ * keeps the stored one.
  *
  * @param projectRoot - Absolute path to the project root directory.
  * @param spec        - Agent creation spec (without createdAt/updatedAt).
@@ -338,7 +340,7 @@ export declare class AgentRegistryAccessor implements AgentRegistryAPI {
         force?: boolean;
     }): Promise<void>;
     /**
-     * Rotate API key via cloud endpoint and re-encrypt with the new T310 KDF
+     * Rotate API key via cloud endpoint and store the NEW key encrypted (T12352)
      * in global cleo.db (Agent Registry).
      *
      * @param agentId - Agent business identifier.

package/dist/store/agent-registry-accessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-registry-accessor.d.ts","sourceRoot":"","sources":["../../src/store/agent-registry-accessor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-registry-accessor.d.ts","sourceRoot":"","sources":["../../src/store/agent-registry-accessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAGhB,wBAAwB,EACxB,eAAe,EACf,aAAa,EAEd,MAAM,qBAAqB,CAAC;AAuB7B;;;;;;;;;;;;;GAaG;AACH,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAGlB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IAEnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAsHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI,CAkBxE;AAqID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CA8C1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5D,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAkDrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,WAAW,CAAC,GACrD,OAAO,CAAC,wBAAwB,CAAC,CAoHnC;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACpE,IAAI,CA0BN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAgBpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAW/F;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAOhD,OAAO,CAAC,QAAQ,CAAC,WAAW;IANxC;;;;;OAKG;gBAC0B,WAAW,EAAE,MAAM;IAEhD;;;;;OAKG;YACW,SAAS;IAOvB;;;;;;;;OAQG;IACG,QAAQ,CACZ,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,WAAW,CAAC,GAC3D,OAAO,CAAC,eAAe,CAAC;IAK3B;;;;;;;;OAQG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAK/F;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAShE;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAetE;;;;;;;;;;OAUG;IACG,MAAM,CACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC,GAC/D,OAAO,CAAC,eAAe,CAAC;IAkF3B;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5C;;;;;;;;OAQG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC9E;;;;;;;;OAQG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAsCjF;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAmClD;;;;;;;OAOG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAwB/C"}

package/dist/store/agent-registry-accessor.js

@@ -42,15 +42,10 @@
  * @epic T310
  * @epic T11249
  */
-import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
-import { getCleoHome } from '../paths.js';
+import { openAgentApiKey, sealAgentApiKey } from './agent-api-key.js';
 import { ensureGlobalAgentRegistryDb, getGlobalAgentRegistryNativeDb, } from './agent-registry-store.js';
-import { deriveApiKey } from './api-key-kdf.js';
 import { ensureConduitDb, getConduitDbPath } from './conduit-sqlite.js';
-import { getGlobalSalt } from './global-salt.js';
 import { applyPerfPragmas } from './sqlite-pragmas.js';
 // ---------------------------------------------------------------------------
 // node:sqlite interop (createRequire for ESM / Vitest compat)
@@ -58,45 +53,6 @@ import { applyPerfPragmas } from './sqlite-pragmas.js';
 const _require = createRequire(import.meta.url);
 const { DatabaseSync } = _require('node:sqlite');
 // ---------------------------------------------------------------------------
-// Machine-key helper (internal — mirrors credentials.ts private getMachineKey)
-// ---------------------------------------------------------------------------
-/** Machine-key constants. */
-const MACHINE_KEY_LENGTH = 32;
-/**
- * Read or auto-generate the machine key (32 bytes).
- * Machine key lives at `getCleoHome()/machine-key` (same XDG root as the global salt).
- *
- * @returns A 32-byte Buffer.
- * @task T355
- * @epic T310
- */
-function readMachineKey() {
-    const keyPath = join(getCleoHome(), 'machine-key');
-    if (!existsSync(keyPath)) {
-        const cleoHome = getCleoHome();
-        if (!existsSync(cleoHome)) {
-            mkdirSync(cleoHome, { recursive: true });
-        }
-        const key = randomBytes(MACHINE_KEY_LENGTH);
-        writeFileSync(keyPath, key, { mode: 0o600 });
-        return key;
-    }
-    // Validate permissions on POSIX
-    if (process.platform !== 'win32') {
-        const stat = statSync(keyPath);
-        const mode = stat.mode & 0o777;
-        if (mode !== 0o600) {
-            throw new Error(`Machine key at ${keyPath} has wrong permissions: expected 0o600, got 0o${mode.toString(8)}. ` +
-                `Fix with: chmod 600 ${keyPath}`);
-        }
-    }
-    const key = readFileSync(keyPath);
-    if (key.length !== MACHINE_KEY_LENGTH) {
-        throw new Error(`Machine key at ${keyPath} has wrong length: expected ${MACHINE_KEY_LENGTH} bytes, got ${key.length}.`);
-    }
-    return key;
-}
-// ---------------------------------------------------------------------------
 // Row-to-type converters
 // ---------------------------------------------------------------------------
 /**
@@ -118,24 +74,26 @@ function rowToProjectRef(row) {
     };
 }
 /**
- * Convert a global cleo.db:agent_registry_agents row to an `AgentCredential`.
- * API key is stored as binary (derived via KDF) — returned as hex string.
- * Legacy encrypted values (pre-T310) are left as-is; the reauth flag handles
- * forced re-authentication at the CLI layer.
+ * Convert a global cleo.db:agent_registry_agents row to an `AgentCredential`,
+ * decrypting the stored API key (T12352).
+ *
+ * `api_key_encrypted` holds a `gk1:` global-KDF ciphertext of the real key.
+ * Rows written before T12352 hold a derived HMAC instead (the real key was
+ * discarded); they read back exactly as before and carry `requiresReauth`.
  *
  * @param row - Raw SQLite row from global cleo.db:agent_registry_agents.
- * @returns Typed `AgentCredential` (apiKey is hex-encoded derived bytes or empty).
+ * @returns Typed `AgentCredential`.
  * @task T355
+ * @task T12352
  * @epic T310
  */
-function rowToCredential(row) {
+async function rowToCredential(row) {
+    const key = await openAgentApiKey(row.api_key_encrypted, row.agent_id);
     return {
         agentId: row.agent_id,
         displayName: row.name,
-        // api_key_encrypted stores the KDF-derived key as binary or a legacy ciphertext.
-        // Return as hex-encoded bytes for callers that need the raw key.
-        // The reauth flow in `cleo agent auth` handles re-keying (T358).
-        apiKey: row.api_key_encrypted ? Buffer.from(row.api_key_encrypted).toString('hex') : '',
+        apiKey: key.apiKey,
+        ...(key.requiresReauth ? { requiresReauth: true } : {}),
         apiBaseUrl: row.api_base_url,
         classification: row.classification ?? undefined,
         privacyTier: row.privacy_tier,
@@ -239,9 +197,9 @@ export function rowToResolvedAgent(row) {
  * @task T355
  * @epic T310
  */
-function mergeToAgentWithOverride(agentRow, refRow) {
+async function mergeToAgentWithOverride(agentRow, refRow) {
     return {
-        ...rowToCredential(agentRow),
+        ...(await rowToCredential(agentRow)),
         projectRef: refRow ? rowToProjectRef(refRow) : null,
     };
 }
@@ -397,11 +355,11 @@ export async function lookupAgent(projectRoot, agentId, opts) {
             // INNER JOIN semantics: must have a project ref with enabled=1
             if (!refRow || refRow.enabled === 0)
                 return null;
-            return mergeToAgentWithOverride(agentRow, refRow);
+            return await mergeToAgentWithOverride(agentRow, refRow);
         }
         // includeGlobal=true: return global agent; populate projectRef only when enabled=1
         const effectiveRef = refRow && refRow.enabled === 1 ? refRow : null;
-        return mergeToAgentWithOverride(agentRow, effectiveRef);
+        return await mergeToAgentWithOverride(agentRow, effectiveRef);
     }
     finally {
         // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
@@ -464,7 +422,7 @@ export async function listAgentsForProject(projectRoot, opts) {
             if (includeGlobal) {
                 // Return all global agents; populate projectRef only for attached ones
                 const effectiveRef = ref && ref.enabled === 1 ? ref : null;
-                result.push(mergeToAgentWithOverride(agentRow, effectiveRef));
+                result.push(await mergeToAgentWithOverride(agentRow, effectiveRef));
             }
             else {
                 // INNER JOIN: only agents with a project ref row
@@ -472,7 +430,7 @@ export async function listAgentsForProject(projectRoot, opts) {
                     continue;
                 if (!includeDisabled && ref.enabled === 0)
                     continue;
-                result.push(mergeToAgentWithOverride(agentRow, ref));
+                result.push(await mergeToAgentWithOverride(agentRow, ref));
             }
         }
         return result;
@@ -489,7 +447,9 @@ export async function listAgentsForProject(projectRoot, opts) {
  * Write order: global first, then project ref. If the project ref write fails,
  * the global row remains (recoverable via `cleo agent attach <id>`).
  *
- * API key derivation: HMAC-SHA256(machineKey || globalSalt, agentId) per ADR-037 §5.
+ * API key storage (T12352): the real `spec.apiKey` is stored encrypted under the
+ * global KDF (ADR-037 §5) — see `agent-api-key.ts`. An empty key on re-register
+ * keeps the stored one.
  *
  * @param projectRoot - Absolute path to the project root directory.
  * @param spec        - Agent creation spec (without createdAt/updatedAt).
@@ -506,16 +466,9 @@ export async function createProjectAgent(projectRoot, spec) {
     await ensureConduitDb(projectRoot);
     const nowTs = Math.floor(Date.now() / 1000);
     const nowIso = new Date(nowTs * 1000).toISOString();
-    // Derive API key using the T310 KDF
-    const machineKey = readMachineKey();
-    const globalSalt = getGlobalSalt();
-    const derivedKey = deriveApiKey({
-        machineKey,
-        globalSalt,
-        agentId: spec.agentId,
-    });
-    // Store as hex string in the encrypted column
-    const apiKeyEncrypted = derivedKey.toString('hex');
+    // T12352: store the REAL key, encrypted under the global KDF (ADR-037 §5).
+    // null = no key supplied: a re-register keeps the stored key.
+    const apiKeyEncrypted = await sealAgentApiKey(spec.apiKey, spec.agentId);
     // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
     const globalDb = await openGlobalDb();
     {
@@ -540,9 +493,11 @@ export async function createProjectAgent(projectRoot, spec) {
             // Update identity in global DB (idempotent re-register)
             globalDb
                 .prepare(`UPDATE agent_registry_agents SET name = ?, class = ?, privacy_tier = ?, capabilities = ?, skills = ?,
-           transport_type = ?, api_key_encrypted = ?, api_base_url = ?, classification = ?,
+           transport_type = ?, api_key_encrypted = COALESCE(?, api_key_encrypted),
+           requires_reauth = CASE WHEN ? IS NULL THEN requires_reauth ELSE 0 END,
+           api_base_url = ?, classification = ?,
            transport_config = ?, is_active = ?, updated_at = ? WHERE agent_id = ?`)
-                .run(spec.displayName, spec.classification ?? 'custom', spec.privacyTier, JSON.stringify(spec.capabilities), JSON.stringify(spec.skills), spec.transportType ?? 'http', apiKeyEncrypted, spec.apiBaseUrl, spec.classification ?? null, JSON.stringify(spec.transportConfig), spec.isActive ? 1 : 0, nowIso, spec.agentId);
+                .run(spec.displayName, spec.classification ?? 'custom', spec.privacyTier, JSON.stringify(spec.capabilities), JSON.stringify(spec.skills), spec.transportType ?? 'http', apiKeyEncrypted, apiKeyEncrypted, spec.apiBaseUrl, spec.classification ?? null, JSON.stringify(spec.transportConfig), spec.isActive ? 1 : 0, nowIso, spec.agentId);
             syncJunctionTables(globalDb, agentUuid, spec.capabilities, spec.skills);
         }
     }
@@ -779,7 +734,7 @@ export class AgentRegistryAccessor {
             : globalDb
                 .prepare('SELECT * FROM agent_registry_agents ORDER BY name ASC')
                 .all();
-        return rows.map(rowToCredential);
+        return Promise.all(rows.map(rowToCredential));
     }
     /**
      * Update agent identity fields in global cleo.db (Agent Registry).
@@ -841,12 +796,9 @@ export class AgentRegistryAccessor {
                 params.push(updates.isActive ? 1 : 0);
             }
             if (updates.apiKey !== undefined) {
-                // Re-derive using new T310 KDF
-                const machineKey = readMachineKey();
-                const globalSalt = getGlobalSalt();
-                const derivedKey = deriveApiKey({ machineKey, globalSalt, agentId });
-                sets.push('api_key_encrypted = ?');
-                params.push(derivedKey.toString('hex'));
+                // T12352: store the supplied key itself, encrypted (was: a derived HMAC).
+                sets.push('api_key_encrypted = ?', 'requires_reauth = 0');
+                params.push(await sealAgentApiKey(updates.apiKey, agentId));
             }
             params.push(agentId);
             globalDb
@@ -933,7 +885,7 @@ export class AgentRegistryAccessor {
         // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
     }
     /**
-     * Rotate API key via cloud endpoint and re-encrypt with the new T310 KDF
+     * Rotate API key via cloud endpoint and store the NEW key encrypted (T12352)
      * in global cleo.db (Agent Registry).
      *
      * @param agentId - Agent business identifier.
@@ -960,17 +912,15 @@ export class AgentRegistryAccessor {
         const newApiKey = data.data?.apiKey;
         if (!newApiKey)
             throw new Error('Cloud API did not return a new API key');
-        // Re-derive and store using T310 KDF
-        const machineKey = readMachineKey();
-        const globalSalt = getGlobalSalt();
-        const derivedKey = deriveApiKey({ machineKey, globalSalt, agentId });
+        // T12352: keep the key the cloud just issued (it was discarded before).
+        const sealedKey = await sealAgentApiKey(newApiKey, agentId);
         // T11622 cutover: `updated_at` is TEXT ISO-8601 (GLOB CHECK).
         const nowIso = new Date().toISOString();
         // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
         const globalDb = await openGlobalDb();
         globalDb
             .prepare('UPDATE agent_registry_agents SET api_key_encrypted = ?, updated_at = ?, requires_reauth = 0 WHERE agent_id = ?')
-            .run(derivedKey.toString('hex'), nowIso, agentId);
+            .run(sealedKey, nowIso, agentId);
         // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
         return { agentId, newApiKey: `${newApiKey.substring(0, 8)}...rotated` };
     }
@@ -996,7 +946,7 @@ export class AgentRegistryAccessor {
                     .prepare('SELECT * FROM agent_registry_agents WHERE agent_id = ? AND is_active = 1')
                     .get(ref.agent_id);
                 if (agentRow)
-                    return rowToCredential(agentRow);
+                    return await rowToCredential(agentRow);
             }
             // Fall back to global last_used_at if no project-local activity recorded
             const row = globalDb
@@ -1004,7 +954,7 @@ export class AgentRegistryAccessor {
                 .get();
             if (!row)
                 return null;
-            return rowToCredential(row);
+            return await rowToCredential(row);
         }
         finally {
             // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).