@codemation/host 0.6.0 → 0.7.0

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")

package/src/domain/credentials/CredentialTypeRegistryImpl.ts

@@ -1,29 +1,136 @@
 import type { CredentialTypeDefinition, CredentialTypeId, CredentialTypeRegistry } from "@codemation/core";
 
-import { injectable } from "@codemation/core";
+import { inject, injectable } from "@codemation/core";
 
-import type { AnyCredentialType, CredentialType } from "./CredentialServices";
+import { ApplicationTokens } from "../../applicationTokens";
+import type { LoggerFactory } from "../../application/logging/Logger";
+import type { AnyCredentialType } from "./CredentialServices";
+
+export type CredentialTypeSource = "plugin" | "config" | "controlPlane";
+
+const SOURCE_PRIORITY: Record<CredentialTypeSource, number> = {
+  plugin: 0,
+  config: 1,
+  controlPlane: 2,
+};
+
+type RegistryEntry = Readonly<{
+  type: AnyCredentialType;
+  source: CredentialTypeSource;
+}>;
 
 @injectable()
 export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
-  private readonly credentialTypesById = new Map<CredentialTypeId, AnyCredentialType>();
+  private readonly entries = new Map<CredentialTypeId, RegistryEntry>();
+  private readonly bySource = new Map<CredentialTypeSource, Set<CredentialTypeId>>();
 
-  register(type: CredentialType<any, any, unknown>): void {
-    if (this.credentialTypesById.has(type.definition.typeId)) {
-      throw new Error(`Credential type already registered: ${type.definition.typeId}`);
+  constructor(@inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory) {}
+
+  merge(source: CredentialTypeSource, types: ReadonlyArray<AnyCredentialType>): void {
+    const logger = this.loggers.create("CredentialTypeRegistryImpl");
+    for (const type of types) {
+      this.insert(source, type, logger);
+    }
+  }
+
+  mergeDefinitions(source: CredentialTypeSource, definitions: ReadonlyArray<CredentialTypeDefinition>): void {
+    const logger = this.loggers.create("CredentialTypeRegistryImpl");
+    for (const definition of definitions) {
+      const existing = this.entries.get(definition.typeId);
+      const sourcePriority = SOURCE_PRIORITY[source];
+      if (existing) {
+        if (sourcePriority < SOURCE_PRIORITY[existing.source]) {
+          logger.warn(
+            `CredentialTypeRegistryImpl: id collision — lower-priority source "${source}" ignored for typeId "${definition.typeId}" (current source: "${existing.source}")`,
+          );
+          continue;
+        }
+        if (sourcePriority > SOURCE_PRIORITY[existing.source]) {
+          logger.warn(
+            `CredentialTypeRegistryImpl: typeId "${definition.typeId}" shadowed — "${existing.source}" overridden by higher-priority source "${source}"`,
+          );
+          this.bySource.get(existing.source)?.delete(definition.typeId);
+        }
+        const nextType: AnyCredentialType =
+          sourcePriority === SOURCE_PRIORITY[existing.source]
+            ? { ...existing.type, definition }
+            : { definition, createSession: this.createUnsupportedSessionFactory(definition.typeId, source), test: this.createUnsupportedHealthTester(definition.typeId, source) };
+        this.recordEntry(definition.typeId, { type: nextType, source });
+        continue;
+      }
+      const stubType: AnyCredentialType = {
+        definition,
+        createSession: this.createUnsupportedSessionFactory(definition.typeId, source),
+        test: this.createUnsupportedHealthTester(definition.typeId, source),
+      };
+      this.recordEntry(definition.typeId, { type: stubType, source });
+    }
+  }
+
+  clear(source: CredentialTypeSource): void {
+    const ids = this.bySource.get(source);
+    if (!ids) {
+      return;
+    }
+    for (const id of ids) {
+      this.entries.delete(id);
     }
-    this.credentialTypesById.set(type.definition.typeId, type);
+    this.bySource.delete(source);
   }
 
   listTypes(): ReadonlyArray<CredentialTypeDefinition> {
-    return [...this.credentialTypesById.values()].map((entry) => entry.definition);
+    return [...this.entries.values()].map((entry) => entry.type.definition);
   }
 
   getType(typeId: CredentialTypeId): CredentialTypeDefinition | undefined {
-    return this.credentialTypesById.get(typeId)?.definition;
+    return this.entries.get(typeId)?.type.definition;
   }
 
   getCredentialType(typeId: CredentialTypeId): AnyCredentialType | undefined {
-    return this.credentialTypesById.get(typeId);
+    return this.entries.get(typeId)?.type;
+  }
+
+  private insert(source: CredentialTypeSource, type: AnyCredentialType, logger: ReturnType<LoggerFactory["create"]>): void {
+    const typeId = type.definition.typeId;
+    const existing = this.entries.get(typeId);
+    const sourcePriority = SOURCE_PRIORITY[source];
+    if (existing) {
+      if (sourcePriority < SOURCE_PRIORITY[existing.source]) {
+        logger.warn(
+          `CredentialTypeRegistryImpl: id collision — lower-priority source "${source}" ignored for typeId "${typeId}" (current source: "${existing.source}")`,
+        );
+        return;
+      }
+      if (sourcePriority > SOURCE_PRIORITY[existing.source]) {
+        logger.warn(
+          `CredentialTypeRegistryImpl: typeId "${typeId}" shadowed — "${existing.source}" overridden by higher-priority source "${source}"`,
+        );
+        this.bySource.get(existing.source)?.delete(typeId);
+      }
+    }
+    this.recordEntry(typeId, { type, source });
+  }
+
+  private recordEntry(typeId: CredentialTypeId, entry: RegistryEntry): void {
+    this.entries.set(typeId, entry);
+    if (!this.bySource.has(entry.source)) {
+      this.bySource.set(entry.source, new Set());
+    }
+    this.bySource.get(entry.source)!.add(typeId);
+  }
+
+  private createUnsupportedSessionFactory(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["createSession"] {
+    return async () => {
+      throw new Error(
+        `Credential type "${typeId}" (source "${source}") was registered with definition only — no createSession implementation is available in this runtime.`,
+      );
+    };
+  }
+
+  private createUnsupportedHealthTester(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["test"] {
+    return async () => ({
+      status: "unknown" as const,
+      message: `Credential type "${typeId}" (source "${source}") has no local test implementation.`,
+    });
   }
 }

package/src/domain/credentials/OAuth2RedirectUriResolver.ts

@@ -0,0 +1,79 @@
+import { inject, injectable } from "@codemation/core";
+import { ApplicationRequestError } from "../../application/ApplicationRequestError";
+import { ApplicationTokens } from "../../applicationTokens";
+import type { AppConfig } from "../../presentation/config/AppConfig";
+
+/**
+ * Resolves the canonical OAuth2 redirect URI from the public base URL or request origin.
+ * The redirect URI always points to `/api/oauth2/callback`, which is the URL operators
+ * register with their OAuth provider.
+ */
+@injectable()
+export class OAuth2RedirectUriResolver {
+  constructor(
+    @inject(ApplicationTokens.AppConfig)
+    private readonly appConfig: AppConfig,
+  ) {}
+
+  resolve(requestOrigin: string): string {
+    const rawBase = this.appConfig.env.CODEMATION_PUBLIC_BASE_URL?.trim() || requestOrigin.trim();
+    if (!rawBase) {
+      throw new Error("Unable to resolve the public base URL for OAuth2 redirect URI generation.");
+    }
+    const baseUrl = this.ensureAbsoluteUrl(rawBase);
+    try {
+      const callback = new URL("/api/oauth2/callback", this.normalizeBaseUrl(baseUrl));
+      // Several OAuth2 providers (notably Azure AD / Microsoft) reject raw loopback IPs in
+      // redirect URIs and only allow the `localhost` hostname. 127.0.0.1 / [::1] are equivalent
+      // to localhost by definition, so rewriting is lossless.
+      const loopbackHostnames = new Set(["127.0.0.1", "[::1]"]);
+      if (loopbackHostnames.has(callback.hostname)) {
+        callback.hostname = "localhost";
+      }
+      return callback.toString();
+    } catch {
+      throw new ApplicationRequestError(
+        500,
+        `Invalid public base URL for OAuth2 redirect URI generation: "${rawBase}". Use a full URL (e.g. http://localhost:3000) for CODEMATION_PUBLIC_BASE_URL or ensure the request has a valid Host / forwarded headers.`,
+      );
+    }
+  }
+
+  /**
+   * Ensures the base URL has an http/https scheme. Comma-separated values (proxy chains) use
+   * the first segment only.
+   */
+  private ensureAbsoluteUrl(raw: string): string {
+    const segments = raw
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    let candidate = segments[0] ?? raw.trim();
+    if (!candidate) {
+      throw new Error("Unable to resolve the public base URL for OAuth2 redirect URI generation.");
+    }
+    if (!/^https?:\/\//i.test(candidate)) {
+      candidate = `http://${candidate}`;
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(candidate);
+    } catch {
+      throw new ApplicationRequestError(
+        500,
+        `Invalid public base URL for OAuth2 redirect URI generation: "${raw}". Use a single full URL (e.g. http://localhost:3000) for CODEMATION_PUBLIC_BASE_URL.`,
+      );
+    }
+    if (parsed.hostname === "http" || parsed.hostname === "https") {
+      throw new ApplicationRequestError(
+        500,
+        `Invalid OAuth2 public base URL (hostname "${parsed.hostname}"). Set CODEMATION_PUBLIC_BASE_URL to one full URL with a real host, e.g. http://localhost:3000 — not "http,http" or other typos.`,
+      );
+    }
+    return candidate;
+  }
+
+  private normalizeBaseUrl(baseUrl: string): string {
+    return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  }
+}

package/src/domain/credentials/WorkflowCredentialNodeResolver.ts

@@ -4,9 +4,10 @@ import {
   AgentConnectionNodeCollector,
   type AgentConnectionNodeDescriptor,
   ConnectionNodeIdFactory,
+  inject,
+  injectable,
 } from "@codemation/core";
-
-import { injectable } from "@codemation/core";
+import { McpServerCatalog } from "../../mcp/McpServerCatalog";
 
 export type WorkflowCredentialSlotRef = Readonly<{
   workflowId: string;
@@ -20,6 +21,10 @@ export type WorkflowCredentialSlotRef = Readonly<{
  */
 @injectable()
 export class WorkflowCredentialNodeResolver {
+  constructor(
+    @inject(McpServerCatalog)
+    private readonly mcpCatalog?: McpServerCatalog,
+  ) {}
   /**
    * Human-readable label for credential errors (workflow node name or agent › attachment).
    */
@@ -102,7 +107,9 @@ export class WorkflowCredentialNodeResolver {
     agentConfig: Parameters<typeof AgentConnectionNodeCollector.collect>[1],
     slotsByKey: Map<string, WorkflowCredentialSlotRef>,
   ): void {
-    for (const entry of AgentConnectionNodeCollector.collect(rootAgentNodeId, agentConfig)) {
+    const mcpResolver = this.mcpCatalog ? (id: string) => this.mcpCatalog!.get(id) : undefined;
+    const descriptors = AgentConnectionNodeCollector.collect(rootAgentNodeId, agentConfig, mcpResolver);
+    for (const entry of descriptors) {
       this.addSlotsForRequirements(
         workflowId,
         entry.nodeId,
@@ -147,15 +154,17 @@ export class WorkflowCredentialNodeResolver {
     | undefined {
     if (
       !ConnectionNodeIdFactory.isLanguageModelConnectionNodeId(nodeId) &&
-      !ConnectionNodeIdFactory.isToolConnectionNodeId(nodeId)
+      !ConnectionNodeIdFactory.isToolConnectionNodeId(nodeId) &&
+      !ConnectionNodeIdFactory.isMcpConnectionNodeId(nodeId)
     ) {
       return undefined;
     }
+    const mcpResolver = this.mcpCatalog ? (id: string) => this.mcpCatalog!.get(id) : undefined;
     for (const node of workflow.nodes) {
       if (!AgentConfigInspector.isAgentNodeConfig(node.config)) {
         continue;
       }
-      const entries = AgentConnectionNodeCollector.collect(node.id, node.config);
+      const entries = AgentConnectionNodeCollector.collect(node.id, node.config, mcpResolver);
       const entriesById = new Map(entries.map((entry) => [entry.nodeId, entry]));
       const entry = entriesById.get(nodeId);
       if (!entry) {

package/src/domain/telemetry/TelemetryContracts.ts

@@ -86,6 +86,8 @@ export interface TelemetryArtifactRecord {
   readonly previewJson?: unknown;
   readonly payloadText?: string;
   readonly payloadJson?: unknown;
+  /** Set when the payload was offloaded to BinaryStorage (byteLength > 64 KB). */
+  readonly payloadStorageKey?: string;
   readonly bytes?: number;
   readonly truncated?: boolean;
   readonly createdAt: string;
@@ -195,7 +197,11 @@ export interface TelemetrySpanStore {
 export interface TelemetryArtifactStore {
   save(record: TelemetryArtifactWrite): Promise<TelemetryArtifactRecord>;
   listByTraceId(traceId: string): Promise<ReadonlyArray<TelemetryArtifactRecord>>;
-  pruneExpired(args: TelemetryPruneArgs): Promise<number>;
+  /**
+   * Deletes expired artifacts. Returns the count of deleted rows and any
+   * `payloadStorageKey` references that callers must clean up from BinaryStorage.
+   */
+  pruneExpired(args: TelemetryPruneArgs): Promise<{ count: number; storageKeys: ReadonlyArray<string> }>;
 }
 
 export interface TelemetryMetricPointStore {