@codemation/host 0.6.0 → 0.8.0

package/src/credentials/LocalOAuthFlowExecutor.ts

@@ -0,0 +1,316 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import { inject, injectable } from "@codemation/core";
+import type {
+  Clock,
+  OAuthFlowCallbackArgs,
+  OAuthFlowExecutor,
+  OAuthFlowStartArgs,
+  OAuthFlowStartResult,
+  OAuthMaterial,
+} from "@codemation/core";
+
+import { ApplicationTokens } from "../applicationTokens";
+import { CredentialFieldEnvOverlayService } from "../domain/credentials/CredentialFieldEnvOverlayService";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+import { CredentialMaterialResolver } from "../domain/credentials/CredentialMaterialResolver";
+import { CredentialTypeRegistryImpl } from "../domain/credentials/CredentialTypeRegistryImpl";
+import { OAuth2ProviderRegistry } from "../domain/credentials/OAuth2ProviderRegistry";
+
+type PendingState = Readonly<{
+  stateToken: string;
+  codeVerifier: string;
+  instanceId: string;
+  typeId: string;
+  redirectUri: string;
+  expiresAt: number;
+}>;
+
+/**
+ * OAuthFlowExecutor for framework (OSS / standalone) mode.
+ *
+ * Reads clientId from the credential instance's publicConfig and clientSecret
+ * from the instance's secret material. Does NOT write tokens back — that is
+ * the responsibility of the callback route (a later story).
+ */
+@injectable()
+export class LocalOAuthFlowExecutor implements OAuthFlowExecutor {
+  private static readonly stateTtlMs = 10 * 60 * 1_000;
+
+  private readonly pendingStates = new Map<string, PendingState>();
+
+  constructor(
+    @inject(CredentialTypeRegistryImpl)
+    private readonly credentialTypeRegistry: CredentialTypeRegistryImpl,
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CredentialMaterialResolver)
+    private readonly credentialMaterialResolver: CredentialMaterialResolver,
+    @inject(OAuth2ProviderRegistry)
+    private readonly oauth2ProviderRegistry: OAuth2ProviderRegistry,
+    @inject(CredentialFieldEnvOverlayService)
+    private readonly credentialFieldEnvOverlayService: CredentialFieldEnvOverlayService,
+    @inject(ApplicationTokens.Clock)
+    private readonly clock: Clock,
+  ) {}
+
+  async start(args: OAuthFlowStartArgs): Promise<OAuthFlowStartResult> {
+    const { instanceId } = args;
+    if (!instanceId) {
+      throw new Error("LocalOAuthFlowExecutor.start requires instanceId; create the credential instance first");
+    }
+
+    const instance = await this.credentialStore.getInstance(instanceId);
+    if (!instance) {
+      throw new Error(`LocalOAuthFlowExecutor: credential instance not found: ${instanceId}`);
+    }
+
+    const credentialType = this.credentialTypeRegistry.getCredentialType(instance.typeId);
+    if (!credentialType) {
+      throw new Error(`LocalOAuthFlowExecutor: unknown credential type: ${instance.typeId}`);
+    }
+    if (credentialType.definition.auth?.kind !== "oauth2") {
+      throw new Error(`LocalOAuthFlowExecutor: credential type ${instance.typeId} is not an OAuth2 type`);
+    }
+
+    const auth = credentialType.definition.auth;
+    const rawMaterial = await this.credentialMaterialResolver.resolveMaterial(instance);
+    const { resolvedPublicConfig, resolvedMaterial: material } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material: rawMaterial,
+    });
+    const provider = this.oauth2ProviderRegistry.resolve(credentialType.definition, resolvedPublicConfig);
+    const clientId = this.oauth2ProviderRegistry.resolveClientId(auth, resolvedPublicConfig);
+
+    const scopes = args.scopes.length > 0 ? [...args.scopes] : [...auth.scopes];
+
+    const stateToken = this.createOpaqueValue();
+    const codeVerifier = this.createOpaqueValue();
+    const codeChallenge = this.createPkceCodeChallenge(codeVerifier);
+
+    const nowMs = this.clock.now().getTime();
+
+    // Evict expired entries on each start call to keep the map bounded.
+    this.evictExpired(nowMs);
+
+    const expiresAt = nowMs + LocalOAuthFlowExecutor.stateTtlMs;
+    this.pendingStates.set(stateToken, {
+      stateToken,
+      codeVerifier,
+      instanceId,
+      typeId: instance.typeId,
+      redirectUri: args.redirectUri,
+      expiresAt,
+    });
+
+    // Suppress unused-variable lint for material — it's loaded to validate that the
+    // clientSecret field is present before starting the flow, but clientSecret itself is
+    // only needed at completeCallback / refresh time.
+    void material;
+
+    const url = new URL(provider.authorizeUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", clientId);
+    url.searchParams.set("redirect_uri", args.redirectUri);
+    url.searchParams.set("scope", scopes.join(" "));
+    url.searchParams.set("state", stateToken);
+    url.searchParams.set("code_challenge", codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("access_type", "offline");
+    url.searchParams.set("prompt", "consent");
+
+    return { consentUrl: url.toString(), stateToken };
+  }
+
+  lookupInstanceId(stateToken: string): string | undefined {
+    return this.pendingStates.get(stateToken)?.instanceId;
+  }
+
+  async completeCallback(args: OAuthFlowCallbackArgs): Promise<OAuthMaterial> {
+    const pending = this.pendingStates.get(args.stateToken);
+    if (!pending) {
+      throw new Error(`LocalOAuthFlowExecutor: state token not found or already used: ${args.stateToken}`);
+    }
+    if (this.clock.now().getTime() > pending.expiresAt) {
+      this.pendingStates.delete(args.stateToken);
+      throw new Error("LocalOAuthFlowExecutor: OAuth state token has expired");
+    }
+    this.pendingStates.delete(args.stateToken);
+
+    const instance = await this.credentialStore.getInstance(pending.instanceId);
+    if (!instance) {
+      throw new Error(`LocalOAuthFlowExecutor: credential instance not found: ${pending.instanceId}`);
+    }
+
+    const credentialType = this.credentialTypeRegistry.getCredentialType(instance.typeId);
+    if (!credentialType || credentialType.definition.auth?.kind !== "oauth2") {
+      throw new Error(`LocalOAuthFlowExecutor: credential type ${instance.typeId} is not an OAuth2 type`);
+    }
+
+    const auth = credentialType.definition.auth;
+    const rawMaterial = await this.credentialMaterialResolver.resolveMaterial(instance);
+    const { resolvedPublicConfig, resolvedMaterial: material } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material: rawMaterial,
+    });
+    const provider = this.oauth2ProviderRegistry.resolve(credentialType.definition, resolvedPublicConfig);
+    const clientId = this.oauth2ProviderRegistry.resolveClientId(auth, resolvedPublicConfig);
+    const clientSecretFieldKey = this.oauth2ProviderRegistry.resolveClientSecretFieldKey(auth);
+    const clientSecret = String(material[clientSecretFieldKey] ?? "");
+    if (!clientSecret) {
+      throw new Error(`LocalOAuthFlowExecutor: clientSecret missing from secret field "${clientSecretFieldKey}"`);
+    }
+
+    const body = this.buildFormBody({
+      grant_type: "authorization_code",
+      code: args.code,
+      code_verifier: pending.codeVerifier,
+      client_id: clientId,
+      client_secret: clientSecret,
+      redirect_uri: pending.redirectUri,
+    });
+
+    const response = await fetch(provider.tokenUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    const text = await response.text();
+    const json = this.parseJson(text);
+
+    if (!response.ok) {
+      const msg =
+        typeof json.error_description === "string"
+          ? json.error_description
+          : typeof json.error === "string"
+            ? json.error
+            : text || "OAuth2 token exchange failed";
+      throw new Error(`LocalOAuthFlowExecutor: token exchange failed: ${msg}`);
+    }
+
+    return this.toOAuthMaterial(json);
+  }
+
+  async refresh(args: { typeId: string; instanceId: string; material: OAuthMaterial }): Promise<OAuthMaterial> {
+    const { typeId, instanceId, material } = args;
+
+    const instance = await this.credentialStore.getInstance(instanceId);
+    if (!instance) {
+      throw new Error(`LocalOAuthFlowExecutor: credential instance not found: ${instanceId}`);
+    }
+
+    const credentialType = this.credentialTypeRegistry.getCredentialType(typeId);
+    if (!credentialType || credentialType.definition.auth?.kind !== "oauth2") {
+      throw new Error(`LocalOAuthFlowExecutor: credential type ${typeId} is not an OAuth2 type`);
+    }
+
+    const auth = credentialType.definition.auth;
+    const rawMaterial = await this.credentialMaterialResolver.resolveMaterial(instance);
+    const { resolvedPublicConfig, resolvedMaterial: secretMaterial } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material: rawMaterial,
+    });
+    const provider = this.oauth2ProviderRegistry.resolve(credentialType.definition, resolvedPublicConfig);
+    const clientId = this.oauth2ProviderRegistry.resolveClientId(auth, resolvedPublicConfig);
+    const clientSecretFieldKey = this.oauth2ProviderRegistry.resolveClientSecretFieldKey(auth);
+    const clientSecret = String(secretMaterial[clientSecretFieldKey] ?? "");
+    if (!clientSecret) {
+      throw new Error(`LocalOAuthFlowExecutor: clientSecret missing from secret field "${clientSecretFieldKey}"`);
+    }
+
+    if (!material.refreshToken) {
+      throw new Error("LocalOAuthFlowExecutor: no refresh token available");
+    }
+
+    const body = this.buildFormBody({
+      grant_type: "refresh_token",
+      refresh_token: material.refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret,
+    });
+
+    const response = await fetch(provider.tokenUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    const text = await response.text();
+    const json = this.parseJson(text);
+
+    if (!response.ok) {
+      const msg =
+        typeof json.error_description === "string"
+          ? json.error_description
+          : typeof json.error === "string"
+            ? json.error
+            : text || "OAuth2 refresh failed";
+      throw new Error(`LocalOAuthFlowExecutor: token refresh failed: ${msg}`);
+    }
+
+    const refreshed = this.toOAuthMaterial(json);
+    // Preserve the existing refresh token if the provider omits it from the response.
+    if (!refreshed.refreshToken) {
+      return { ...refreshed, refreshToken: material.refreshToken };
+    }
+    return refreshed;
+  }
+
+  private toOAuthMaterial(json: Record<string, unknown>): OAuthMaterial {
+    const accessToken = String(json.access_token ?? "");
+    if (!accessToken) {
+      throw new Error("LocalOAuthFlowExecutor: token response missing access_token");
+    }
+    const refreshToken =
+      typeof json.refresh_token === "string" && json.refresh_token.length > 0 ? json.refresh_token : undefined;
+    const expiresAt = this.resolveExpiresAt(json);
+    const grantedScopes =
+      typeof json.scope === "string" && json.scope.length > 0
+        ? json.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    return Object.freeze({ accessToken, refreshToken, expiresAt, grantedScopes });
+  }
+
+  private resolveExpiresAt(json: Record<string, unknown>): string | undefined {
+    const expiresIn = Number(json.expires_in);
+    if (Number.isFinite(expiresIn) && expiresIn > 0) {
+      return new Date(this.clock.now().getTime() + expiresIn * 1000).toISOString();
+    }
+    return undefined;
+  }
+
+  private parseJson(text: string): Record<string, unknown> {
+    try {
+      const parsed = JSON.parse(text) as unknown;
+      return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  private buildFormBody(fields: Readonly<Record<string, string>>): string {
+    return Object.entries(fields)
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+      .join("&");
+  }
+
+  private createOpaqueValue(): string {
+    return randomBytes(32).toString("base64url");
+  }
+
+  private createPkceCodeChallenge(codeVerifier: string): string {
+    return createHash("sha256").update(codeVerifier).digest("base64url");
+  }
+
+  private evictExpired(nowMs: number): void {
+    for (const [key, entry] of this.pendingStates) {
+      if (nowMs > entry.expiresAt) {
+        this.pendingStates.delete(key);
+      }
+    }
+  }
+}

package/src/credentials/ManagedOAuthFlowExecutor.ts

@@ -0,0 +1,94 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  OAuthFlowCallbackArgs,
+  OAuthFlowExecutor,
+  OAuthFlowStartArgs,
+  OAuthFlowStartResult,
+  OAuthMaterial,
+} from "@codemation/core";
+import type { LoggerFactory } from "../application/logging/Logger";
+
+import { ApplicationTokens } from "../applicationTokens";
+import { PairedFetch } from "../pairing/PairedFetch";
+import { PairingConfigToken } from "../pairing/PairingConfigToken";
+import type { PairingConfig } from "../pairing/pairing.types";
+import { ManagedOAuthRefreshInvalidGrantError } from "./ManagedOAuthRefreshInvalidGrantError";
+
+/**
+ * OAuthFlowExecutor for managed mode (paired with a control plane).
+ *
+ * Delegates the entire OAuth dance to the control plane over HMAC-signed calls.
+ * Client secrets never leave the control plane.
+ */
+@injectable()
+export class ManagedOAuthFlowExecutor implements OAuthFlowExecutor {
+  constructor(
+    @inject(PairedFetch) private readonly pairedFetch: PairedFetch,
+    @inject(PairingConfigToken) private readonly pairingConfig: PairingConfig,
+    @inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory,
+  ) {}
+
+  async start(args: OAuthFlowStartArgs): Promise<OAuthFlowStartResult> {
+    const logger = this.loggers.create("codemation.credentials.managed-oauth");
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/oauth/start`;
+    const response = await this.pairedFetch.post(url, {
+      typeId: args.typeId,
+      scopes: args.scopes,
+      redirectUri: args.redirectUri,
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const excerpt = body.slice(0, 200);
+      logger.warn(`ManagedOAuthFlowExecutor.start failed: ${response.status} ${excerpt}`);
+      throw new Error(`ManagedOAuthFlowExecutor.start failed: ${response.status} ${excerpt}`);
+    }
+    const json = (await response.json()) as { consentUrl: string; stateToken: string };
+    return { consentUrl: json.consentUrl, stateToken: json.stateToken };
+  }
+
+  lookupInstanceId(_stateToken: string): string | undefined {
+    // Managed mode — state is owned by the control plane, not the host.
+    return undefined;
+  }
+
+  async completeCallback(args: OAuthFlowCallbackArgs): Promise<OAuthMaterial> {
+    const logger = this.loggers.create("codemation.credentials.managed-oauth");
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/oauth/complete`;
+    const response = await this.pairedFetch.post(url, {
+      stateToken: args.stateToken,
+      code: args.code,
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const excerpt = body.slice(0, 200);
+      logger.warn(`ManagedOAuthFlowExecutor.completeCallback failed: ${response.status} ${excerpt}`);
+      throw new Error(`ManagedOAuthFlowExecutor.completeCallback failed: ${response.status} ${excerpt}`);
+    }
+    return (await response.json()) as OAuthMaterial;
+  }
+
+  async refresh(args: { typeId: string; instanceId: string; material: OAuthMaterial }): Promise<OAuthMaterial> {
+    const { typeId, instanceId, material } = args;
+    if (!material.refreshToken) {
+      throw new Error("ManagedOAuthFlowExecutor.refresh: no refresh token available");
+    }
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/oauth/refresh`;
+    const response = await this.pairedFetch.post(url, {
+      typeId,
+      instanceId,
+      refreshToken: material.refreshToken,
+    });
+    if (response.status === 410) {
+      throw new ManagedOAuthRefreshInvalidGrantError(instanceId);
+    }
+    if (!response.ok) {
+      throw new Error(`ManagedOAuthFlowExecutor.refresh failed: ${response.status}`);
+    }
+    const refreshed = (await response.json()) as OAuthMaterial;
+    // Preserve the existing refresh token if the control plane omits it from the response.
+    if (!refreshed.refreshToken) {
+      return { ...refreshed, refreshToken: material.refreshToken };
+    }
+    return refreshed;
+  }
+}

package/src/credentials/ManagedOAuthRefreshInvalidGrantError.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown when the control plane returns HTTP 410 (invalid_grant) during a refresh.
+ * The refresh token is dead — user revoked, token rotated away, etc.
+ * The credential cannot be auto-recovered; the user must reconnect via the Connect flow.
+ */
+export class ManagedOAuthRefreshInvalidGrantError extends Error {
+  constructor(readonly credentialInstanceId: string) {
+    super(
+      `Credential ${credentialInstanceId}: refresh token is invalid or revoked (invalid_grant). Reconnect required.`,
+    );
+    this.name = "ManagedOAuthRefreshInvalidGrantError";
+  }
+}

package/src/credentials/catalogTypes.ts

@@ -0,0 +1,4 @@
+export type OAuthAppCatalogEntry = Readonly<{
+  appId: string;
+  displayName: string;
+}>;

package/src/credentials/refresh/CredentialDisconnectedError.ts

@@ -0,0 +1,11 @@
+/**
+ * Thrown when the credential's refresh token is dead (user revoked the grant,
+ * or the token was rotated away). The installation cannot auto-recover; the user
+ * must reconnect via the broker Connect flow.
+ */
+export class CredentialDisconnectedError extends Error {
+  constructor(readonly credentialInstanceId: string) {
+    super(`Credential ${credentialInstanceId}: refresh token is invalid or revoked. Reconnect via the Connect flow.`);
+    this.name = "CredentialDisconnectedError";
+  }
+}

package/src/domain/credentials/CredentialBindingService.ts

@@ -7,7 +7,7 @@ import type {
   WorkflowRepository,
 } from "@codemation/core";
 
-import { CoreTokens, inject, injectable } from "@codemation/core";
+import { CoreTokens, CredentialUnboundError, inject, injectable } from "@codemation/core";
 
 import { ApplicationRequestError } from "../../application/ApplicationRequestError";
 
@@ -17,6 +17,7 @@ import type {
 } from "../../application/contracts/CredentialContractsRegistry";
 
 import { ApplicationTokens } from "../../applicationTokens";
+import type { Logger, LoggerFactory } from "../../application/logging/Logger";
 
 import { WorkflowCredentialNodeResolver } from "./WorkflowCredentialNodeResolver";
 import { CredentialInstanceService } from "./CredentialInstanceService";
@@ -24,6 +25,8 @@ import type { CredentialStore, MutableCredentialSessionService } from "./Credent
 
 @injectable()
 export class CredentialBindingService {
+  private readonly logger: Logger;
+
   constructor(
     @inject(ApplicationTokens.CredentialStore)
     private readonly credentialStore: CredentialStore,
@@ -35,7 +38,11 @@ export class CredentialBindingService {
     private readonly credentialSessionService: MutableCredentialSessionService,
     @inject(WorkflowCredentialNodeResolver)
     private readonly workflowCredentialNodeResolver: WorkflowCredentialNodeResolver,
-  ) {}
+    @inject(ApplicationTokens.LoggerFactory)
+    loggerFactory: LoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("CredentialBindingService");
+  }
 
   async upsertBinding(
     args: Readonly<{ workflowId: string; nodeId: string; slotKey: string; instanceId: CredentialInstanceId }>,
@@ -63,6 +70,51 @@ export class CredentialBindingService {
     return binding;
   }
 
+  async assertRequiredCredentialsBound(workflowId: string): Promise<void> {
+    const workflow = this.requireWorkflow(workflowId);
+    const bindings = await this.credentialStore.listBindingsByWorkflowId(workflowId);
+    const boundKeys = new Set(bindings.map((b) => this.toBindingKeyString(b.key)));
+    const unboundByDb = this.workflowCredentialNodeResolver
+      .listSlots(workflow)
+      .filter((slot) => !slot.requirement.optional)
+      .filter(
+        (slot) =>
+          !boundKeys.has(
+            this.toBindingKeyString({ workflowId, nodeId: slot.nodeId, slotKey: slot.requirement.slotKey }),
+          ),
+      );
+    if (unboundByDb.length === 0) return;
+    // Confirm each apparently-unbound slot by attempting session resolution. A custom
+    // CredentialSessionService (e.g. a test harness) can satisfy slots that have no DB
+    // binding row; only slots that still fail are truly unresolvable.
+    const confirmed = [];
+    for (const slot of unboundByDb) {
+      try {
+        await this.credentialSessionService.getSession({
+          workflowId,
+          nodeId: slot.nodeId,
+          slotKey: slot.requirement.slotKey,
+        });
+      } catch (error) {
+        if (!(error instanceof CredentialUnboundError)) {
+          this.logger.debug(
+            `CredentialBindingService: unexpected error resolving session for slot ${slot.requirement.slotKey} on ${slot.nodeId}`,
+            error instanceof Error ? error : undefined,
+          );
+        }
+        confirmed.push(slot);
+      }
+    }
+    if (confirmed.length === 0) return;
+    const descriptions = confirmed
+      .map((slot) => `"${slot.requirement.label}" on ${slot.nodeName ?? slot.nodeId}`)
+      .join(", ");
+    throw new ApplicationRequestError(
+      400,
+      `Cannot run workflow: required credential slot${confirmed.length > 1 ? "s" : ""} not bound: ${descriptions}`,
+    );
+  }
+
   async listWorkflowHealth(workflowId: string): Promise<WorkflowCredentialHealthDto> {
     const workflow = this.requireWorkflow(workflowId);
     const bindings = await this.credentialStore.listBindingsByWorkflowId(workflowId);

package/src/domain/credentials/CredentialKeyRotatedError.ts

@@ -0,0 +1,22 @@
+/**
+ * Thrown by {@link CredentialSecretCipher.decrypt} when the credential's stored
+ * `encryptionKeyId` does not match the current master key's id.
+ *
+ * This indicates the `CODEMATION_CREDENTIALS_MASTER_KEY` environment variable has
+ * been rotated since the credential was encrypted. The operator must re-bind the
+ * affected credential (which re-encrypts it with the new key).
+ *
+ * See {@link docs/security-boundary.md} for the key rotation contract.
+ */
+export class CredentialKeyRotatedError extends Error {
+  readonly storedKeyId: string;
+
+  constructor(storedKeyId: string) {
+    super(
+      `Credential was encrypted with key "${storedKeyId}" but the current master key produces a different id. ` +
+        `Re-bind the credential to re-encrypt it with the active key.`,
+    );
+    this.name = "CredentialKeyRotatedError";
+    this.storedKeyId = storedKeyId;
+  }
+}

package/src/domain/credentials/CredentialSecretCipher.ts

@@ -1,4 +1,4 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
 
 import { inject, injectable } from "@codemation/core";
 
@@ -6,13 +6,26 @@ import { ApplicationTokens } from "../../applicationTokens";
 import type { AppConfig } from "../../presentation/config/AppConfig";
 
 import type { JsonRecord } from "./CredentialServices";
+import { CredentialKeyRotatedError } from "./CredentialKeyRotatedError";
 
+/**
+ * Schema versions:
+ *   1 — key = SHA-256(rawValue)                  (legacy, read-only support retained for migration)
+ *   2 — key = HKDF-SHA-256(rawKey32Bytes, ...)   (current)
+ *
+ * All new encryptions are written as v2. Existing v1 records can still be
+ * decrypted so operators can re-encrypt at their own pace (re-bind the
+ * credential in the UI, or run the one-shot re-encrypt script).
+ */
 @injectable()
 export class CredentialSecretCipher {
   private static readonly algorithm = "aes-256-gcm";
-  private static readonly schemaVersion = 1;
+  private static readonly currentSchemaVersion = 2;
   private static readonly ivLength = 12;
 
+  private static readonly HKDF_SALT = "codemation/credential-cipher/v1";
+  private static readonly HKDF_INFO = "aes-256-gcm-key";
+
   constructor(
     @inject(ApplicationTokens.AppConfig)
     private readonly appConfig: AppConfig,
@@ -24,7 +37,7 @@ export class CredentialSecretCipher {
     schemaVersion: number;
   }> {
     const iv = randomBytes(CredentialSecretCipher.ivLength);
-    const cipher = createCipheriv(CredentialSecretCipher.algorithm, this.resolveKeyMaterial(), iv);
+    const cipher = createCipheriv(CredentialSecretCipher.algorithm, this.resolveKeyMaterialV2(), iv);
     const plaintext = Buffer.from(JSON.stringify(value), "utf8");
     // eslint-disable-next-line codemation/no-buffer-everything -- AES-GCM credential cipher operates on bounded KB-sized JSON payloads; streaming crypto is not applicable here.
     const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
@@ -33,7 +46,7 @@ export class CredentialSecretCipher {
       // eslint-disable-next-line codemation/no-buffer-everything -- AES-GCM credential cipher operates on bounded KB-sized JSON payloads; streaming crypto is not applicable here.
       encryptedJson: Buffer.concat([iv, authTag, encrypted]).toString("base64"),
       encryptionKeyId: this.resolveKeyId(),
-      schemaVersion: CredentialSecretCipher.schemaVersion,
+      schemaVersion: CredentialSecretCipher.currentSchemaVersion,
     };
   }
 
@@ -44,19 +57,48 @@ export class CredentialSecretCipher {
       schemaVersion: number;
     }>,
   ): JsonRecord {
+    // resolveKeyMaterialV2 / resolveKeyMaterialV1 both throw if env is missing
+    // — that check must come before the key-id comparison.
+    const keyMaterial = (record.schemaVersion ?? 1) >= 2 ? this.resolveKeyMaterialV2() : this.resolveKeyMaterialV1();
+
+    const currentKeyId = this.resolveKeyId();
+    if (record.encryptionKeyId !== currentKeyId) {
+      throw new CredentialKeyRotatedError(record.encryptionKeyId);
+    }
     // eslint-disable-next-line codemation/no-buffer-everything -- AES-GCM credential cipher operates on bounded KB-sized JSON payloads; streaming crypto is not applicable here.
     const packed = Buffer.from(record.encryptedJson, "base64");
     const iv = packed.subarray(0, CredentialSecretCipher.ivLength);
     const authTag = packed.subarray(CredentialSecretCipher.ivLength, CredentialSecretCipher.ivLength + 16);
     const encrypted = packed.subarray(CredentialSecretCipher.ivLength + 16);
-    const decipher = createDecipheriv(CredentialSecretCipher.algorithm, this.resolveKeyMaterial(), iv);
+    const decipher = createDecipheriv(CredentialSecretCipher.algorithm, keyMaterial, iv);
     decipher.setAuthTag(authTag);
     // eslint-disable-next-line codemation/no-buffer-everything -- AES-GCM credential cipher operates on bounded KB-sized JSON payloads; streaming crypto is not applicable here.
     const plaintext = Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
     return JSON.parse(plaintext) as JsonRecord;
   }
 
-  private resolveKeyMaterial(): Buffer {
+  /**
+   * Current (v2) key derivation: HKDF-SHA-256 with a fixed application salt and info label.
+   * Input must be a base64-encoded 32-byte value (`CODEMATION_CREDENTIALS_MASTER_KEY`).
+   */
+  private resolveKeyMaterialV2(): Buffer {
+    const ikm = this.resolveBase64Key32Bytes();
+    return Buffer.from(
+      hkdfSync(
+        "sha256",
+        ikm,
+        Buffer.from(CredentialSecretCipher.HKDF_SALT, "utf8"),
+        Buffer.from(CredentialSecretCipher.HKDF_INFO, "utf8"),
+        32,
+      ),
+    );
+  }
+
+  /**
+   * Legacy (v1) key derivation: SHA-256 of the raw env string.
+   * Retained for decrypt-side backward compatibility only.
+   */
+  private resolveKeyMaterialV1(): Buffer {
     const rawValue = this.appConfig.env.CODEMATION_CREDENTIALS_MASTER_KEY;
     if (!rawValue || rawValue.trim().length === 0) {
       throw new Error("CODEMATION_CREDENTIALS_MASTER_KEY is required to encrypt database-managed credentials.");
@@ -64,6 +106,26 @@ export class CredentialSecretCipher {
     return createHash("sha256").update(rawValue).digest();
   }
 
+  /**
+   * Validates and returns the raw 32-byte key material from the env var.
+   * Throws if the env var is absent or does not decode to exactly 32 bytes.
+   */
+  private resolveBase64Key32Bytes(): Buffer {
+    const rawValue = this.appConfig.env.CODEMATION_CREDENTIALS_MASTER_KEY;
+    if (!rawValue || rawValue.trim().length === 0) {
+      throw new Error("CODEMATION_CREDENTIALS_MASTER_KEY is required to encrypt database-managed credentials.");
+    }
+    // eslint-disable-next-line codemation/no-buffer-everything -- key material is always 32 bytes; bounded by validation below.
+    const decoded = Buffer.from(rawValue.trim(), "base64");
+    if (decoded.length !== 32) {
+      throw new Error(
+        `CODEMATION_CREDENTIALS_MASTER_KEY must be a base64-encoded 32-byte value (got ${decoded.length} bytes). ` +
+          `Generate a valid key with: openssl rand -base64 32`,
+      );
+    }
+    return decoded;
+  }
+
   private resolveKeyId(): string {
     const rawValue = this.appConfig.env.CODEMATION_CREDENTIALS_MASTER_KEY;
     return createHash("sha256")