@codemation/host 0.6.0 → 0.8.0

package/src/pairing/HmacRequestSigner.ts

@@ -0,0 +1,32 @@
+import { createHmac, createHash, randomBytes } from "node:crypto";
+import { inject, injectable } from "@codemation/core";
+import type { PairingConfig } from "./pairing.types";
+import { PairingConfigToken } from "./PairingConfigToken";
+
+export interface SignedHeaders {
+  readonly Authorization: string;
+}
+
+@injectable()
+export class HmacRequestSigner {
+  constructor(@inject(PairingConfigToken) private readonly config: PairingConfig) {}
+
+  sign(method: string, urlOrPath: string, body: string): SignedHeaders {
+    const ts = Math.floor(Date.now() / 1000);
+    const nonce = randomBytes(16).toString("base64");
+
+    const parsed = new URL(urlOrPath, "http://placeholder");
+    const path = (parsed.pathname + parsed.search).toLowerCase();
+
+    const bodyHash = createHash("sha256").update(body, "utf8").digest("hex");
+    const baseString = [method.toUpperCase(), path, ts, nonce, bodyHash].join("\n");
+
+    // eslint-disable-next-line codemation/no-buffer-everything -- pairing secret is 32 bytes, never large
+    const secretBytes = Buffer.from(this.config.pairingSecret, "base64");
+    const sig = createHmac("sha256", secretBytes).update(baseString, "utf8").digest("base64");
+
+    return {
+      Authorization: `Codemation-Hmac v=1,workspaceId=${this.config.workspaceId},ts=${ts},nonce=${nonce},sig=${sig}`,
+    };
+  }
+}

package/src/pairing/IncomingHmacVerifier.ts

@@ -0,0 +1,82 @@
+import { createHmac, createHash, timingSafeEqual } from "node:crypto";
+import { inject, injectable } from "@codemation/core";
+import type { PairingConfig, PairingVerificationResult } from "./pairing.types";
+import { PairingConfigToken } from "./PairingConfigToken";
+
+/**
+ * Verifies incoming HMAC-signed requests from the control plane.
+ * Mirrors the control-plane HmacVerifier — both sides follow docs/pairing-protocol.md.
+ */
+@injectable()
+export class IncomingHmacVerifier {
+  private readonly usedNonces = new Map<string, number>();
+  private readonly nonceTtlSeconds = 600; // 10 minutes
+
+  constructor(@inject(PairingConfigToken) private readonly config: PairingConfig) {}
+
+  verify(method: string, url: string, body: string, authHeader: string | null): PairingVerificationResult {
+    if (!this.config.pairingSecret || this.config.pairingSecret.trim().length === 0) {
+      throw new Error("IncomingHmacVerifier: pairingSecret is not configured — cannot verify HMAC requests.");
+    }
+
+    if (!authHeader?.startsWith("Codemation-Hmac ")) {
+      return { failure: "missing" };
+    }
+
+    const parts = this.parseHeader(authHeader);
+    if (!parts) return { failure: "missing" };
+    if (parts.v !== "1") return { failure: "version" };
+
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (Math.abs(nowSec - parts.ts) > 300) return { failure: "expired" };
+
+    if (parts.workspaceId !== this.config.workspaceId) return { failure: "workspace" };
+
+    const parsed = new URL(url, "http://placeholder");
+    const path = (parsed.pathname + parsed.search).toLowerCase();
+    const bodyHash = createHash("sha256").update(body, "utf8").digest("hex");
+    const baseString = [method.toUpperCase(), path, parts.ts, parts.nonce, bodyHash].join("\n");
+
+    // eslint-disable-next-line codemation/no-buffer-everything -- pairing secret is 32 bytes, never large
+    const secretBytes = Buffer.from(this.config.pairingSecret, "base64");
+    const expected = createHmac("sha256", secretBytes).update(baseString, "utf8").digest("base64");
+
+    const expectedBuf = Buffer.from(expected);
+    const actualBuf = Buffer.from(parts.sig);
+    if (expectedBuf.length !== actualBuf.length || !timingSafeEqual(expectedBuf, actualBuf)) {
+      return { failure: "signature" };
+    }
+
+    this.pruneExpiredNonces(nowSec);
+    const nonceKey = `${parts.workspaceId}:${parts.nonce}`;
+    if (this.usedNonces.has(nonceKey)) return { failure: "replay" };
+    this.usedNonces.set(nonceKey, nowSec + this.nonceTtlSeconds);
+
+    return { workspaceId: parts.workspaceId };
+  }
+
+  private parseHeader(header: string): {
+    v: string;
+    workspaceId: string;
+    ts: number;
+    nonce: string;
+    sig: string;
+  } | null {
+    const payload = header.slice("Codemation-Hmac ".length);
+    const fields: Record<string, string> = {};
+    for (const part of payload.split(",")) {
+      const eq = part.indexOf("=");
+      if (eq === -1) return null;
+      fields[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+    }
+    const { v, workspaceId, ts, nonce, sig } = fields;
+    if (!v || !workspaceId || !ts || !nonce || !sig) return null;
+    return { v, workspaceId, ts: Number(ts), nonce, sig };
+  }
+
+  private pruneExpiredNonces(nowSec: number): void {
+    for (const [key, expiry] of this.usedNonces.entries()) {
+      if (expiry <= nowSec) this.usedNonces.delete(key);
+    }
+  }
+}

package/src/pairing/InternalHmacAuthMiddleware.ts

@@ -0,0 +1,33 @@
+import { inject, injectable } from "@codemation/core";
+import type { Context, MiddlewareHandler, Next } from "hono";
+import { IncomingHmacVerifier } from "./IncomingHmacVerifier";
+
+/**
+ * Hono middleware that verifies HMAC-signed requests on /internal/* routes.
+ * Rejects with 401 on any auth failure (failure mode is never leaked).
+ *
+ * Downstream handlers read the consumed body from `c.get("body")` when needed —
+ * do NOT call `c.req.text()` again after this middleware runs.
+ */
+@injectable()
+export class InternalHmacAuthMiddleware {
+  constructor(@inject(IncomingHmacVerifier) private readonly verifier: IncomingHmacVerifier) {}
+
+  handle(): MiddlewareHandler {
+    return async (c: Context, next: Next) => {
+      const body = c.req.method === "GET" || c.req.method === "HEAD" ? "" : await c.req.text();
+
+      const result = this.verifier.verify(c.req.method, c.req.url, body, c.req.header("authorization") ?? null);
+
+      if ("failure" in result) {
+        return c.json({ error: "Unauthorized" }, 401);
+      }
+
+      // Body stored for downstream handlers that need it (e.g., credential push).
+      // Access via c.get("body") — do NOT call c.req.text() again.
+      // workspaceId is available from PairingConfig since installation has a single workspace.
+      c.set("body" as never, body);
+      await next();
+    };
+  }
+}

package/src/pairing/InternalPingRegistrar.ts

@@ -0,0 +1,25 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import { InternalHmacAuthMiddleware } from "./InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+import type { PairingConfig } from "./pairing.types";
+import { PairingConfigToken } from "./PairingConfigToken";
+
+/**
+ * Registers GET /internal/ping — a smoke-test endpoint for verifying workspace pairing.
+ * Returns { pong: true, workspaceId } when the HMAC signature validates correctly.
+ */
+@injectable()
+export class InternalPingRegistrar implements InternalHonoApiRouteRegistrar {
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(PairingConfigToken) private readonly pairingConfig: PairingConfig,
+  ) {}
+
+  register(app: Hono): void {
+    const { workspaceId } = this.pairingConfig;
+    app.get("/internal/ping", this.hmacMiddleware.handle(), (c) => {
+      return c.json({ pong: true, workspaceId });
+    });
+  }
+}

package/src/pairing/PairedFetch.ts

@@ -0,0 +1,33 @@
+import { inject, injectable } from "@codemation/core";
+import { HmacRequestSigner } from "./HmacRequestSigner";
+
+/**
+ * Thin fetch wrapper that automatically HMAC-signs outgoing requests
+ * to the control plane using the workspace's pairing secret.
+ *
+ * Use this for any server-to-server request from the installation to the CP.
+ */
+@injectable()
+export class PairedFetch {
+  constructor(@inject(HmacRequestSigner) private readonly signer: HmacRequestSigner) {}
+
+  async get(url: string): Promise<Response> {
+    const headers = this.signer.sign("GET", url, "");
+    return fetch(url, { method: "GET", headers: { ...headers } });
+  }
+
+  async post(url: string, body: unknown): Promise<Response> {
+    const bodyString = JSON.stringify(body);
+    const headers = this.signer.sign("POST", url, bodyString);
+    return fetch(url, {
+      method: "POST",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: bodyString,
+    });
+  }
+
+  async delete(url: string): Promise<Response> {
+    const headers = this.signer.sign("DELETE", url, "");
+    return fetch(url, { method: "DELETE", headers: { ...headers } });
+  }
+}

package/src/pairing/PairingConfigFactory.ts

@@ -0,0 +1,35 @@
+import type { PairingConfig } from "./pairing.types";
+
+/**
+ * Reads pairing configuration from environment variables.
+ *
+ * Required env vars when pairing is enabled:
+ *   WORKSPACE_ID               — the workspace's database ID
+ *   WORKSPACE_PAIRING_SECRET   — base64-encoded 32-byte shared secret
+ *   CONTROL_PLANE_URL          — base URL of the control plane API
+ *
+ * Returns null if any required variable is absent (pairing disabled).
+ * See docs/pairing-protocol.md for full bootstrap instructions.
+ */
+export class PairingConfigFactory {
+  create(env: Readonly<NodeJS.ProcessEnv>): PairingConfig | null {
+    const workspaceId = env["WORKSPACE_ID"];
+    const pairingSecret = env["WORKSPACE_PAIRING_SECRET"];
+    const controlPlaneUrl = env["CONTROL_PLANE_URL"];
+
+    if (!workspaceId || !pairingSecret || !controlPlaneUrl) {
+      return null;
+    }
+
+    // eslint-disable-next-line codemation/no-buffer-everything -- pairing secret is always 32 bytes; bounded by validation below.
+    const decoded = Buffer.from(pairingSecret, "base64");
+    if (decoded.length !== 32) {
+      throw new Error(
+        `WORKSPACE_PAIRING_SECRET must be a base64-encoded 32-byte value (got ${decoded.length} bytes). ` +
+          `Generate a valid secret with: openssl rand -base64 32`,
+      );
+    }
+
+    return { workspaceId, pairingSecret, controlPlaneUrl };
+  }
+}

package/src/pairing/PairingConfigToken.ts

@@ -0,0 +1,6 @@
+import type { TypeToken } from "@codemation/core";
+import type { PairingConfig } from "./pairing.types";
+
+// Symbol token so the DI container can inject PairingConfig.
+// Registered by PairingConfigFactory in the composition root.
+export const PairingConfigToken = Symbol.for("codemation.pairing.PairingConfig") as TypeToken<PairingConfig>;

package/src/pairing/index.ts

@@ -0,0 +1,14 @@
+export { HmacRequestSigner } from "./HmacRequestSigner";
+export type { SignedHeaders } from "./HmacRequestSigner";
+export { PairedFetch } from "./PairedFetch";
+export { IncomingHmacVerifier } from "./IncomingHmacVerifier";
+export { InternalHmacAuthMiddleware } from "./InternalHmacAuthMiddleware";
+export { InternalPingRegistrar } from "./InternalPingRegistrar";
+export { PairingConfigFactory } from "./PairingConfigFactory";
+export { PairingConfigToken } from "./PairingConfigToken";
+export type {
+  PairingConfig,
+  PairingVerificationResult,
+  PairingVerificationFailure,
+  PairingVerificationSuccess,
+} from "./pairing.types";

package/src/pairing/pairing.types.ts

@@ -0,0 +1,18 @@
+export interface PairingConfig {
+  /** The workspace's database ID. */
+  readonly workspaceId: string;
+  /** Base64-encoded 32-byte raw secret shared with the control plane. */
+  readonly pairingSecret: string;
+  /** Base URL of the control plane API, e.g. https://api.codemation.io */
+  readonly controlPlaneUrl: string;
+}
+
+export type PairingVerificationFailure = {
+  readonly failure: "missing" | "version" | "expired" | "workspace" | "signature" | "replay";
+};
+
+export type PairingVerificationSuccess = {
+  readonly workspaceId: string;
+};
+
+export type PairingVerificationResult = PairingVerificationSuccess | PairingVerificationFailure;

package/src/pairing.ts

@@ -0,0 +1,17 @@
+// Subpath entry point: @codemation/host/pairing
+export {
+  HmacRequestSigner,
+  PairedFetch,
+  IncomingHmacVerifier,
+  InternalHmacAuthMiddleware,
+  InternalPingRegistrar,
+  PairingConfigFactory,
+  PairingConfigToken,
+} from "./pairing/index";
+export type {
+  PairingConfig,
+  PairingVerificationResult,
+  PairingVerificationFailure,
+  PairingVerificationSuccess,
+  SignedHeaders,
+} from "./pairing/index";

package/src/persistenceServer.ts

@@ -2,4 +2,5 @@ export { CodemationPostgresPrismaClientFactory } from "./infrastructure/persiste
 export type { AppPersistenceConfig } from "./presentation/config/AppConfig";
 export { AppConfigFactory } from "./bootstrap/runtime/AppConfigFactory";
 export { PrismaMigrationDeployer } from "./infrastructure/persistence/PrismaMigrationDeployer";
+export { CodemationDatabaseUrlParser } from "./infrastructure/persistence/CodemationDatabaseUrlParser";
 export type { PrismaDatabaseClient as PrismaClient } from "./infrastructure/persistence/PrismaDatabaseClient";

package/src/presentation/config/AppConfig.ts

@@ -1,4 +1,9 @@
-import type { AnyCredentialType, CollectionDefinition, WorkflowDefinition } from "@codemation/core";
+import type {
+  AnyCredentialType,
+  CollectionDefinition,
+  McpServerDeclaration,
+  WorkflowDefinition,
+} from "@codemation/core";
 import type { CodemationContainerRegistration } from "../../bootstrap/CodemationContainerRegistration";
 import type { CodemationPlugin } from "./CodemationPlugin";
 import type {
@@ -32,6 +37,7 @@ export interface AppConfig {
   readonly collections: ReadonlyArray<CollectionDefinition>;
   readonly plugins: ReadonlyArray<CodemationPlugin>;
   readonly pluginLoadSummary?: ReadonlyArray<AppPluginLoadSummary>;
+  readonly mcpServers: ReadonlyArray<McpServerDeclaration>;
   readonly hasConfiguredCredentialSessionServiceRegistration: boolean;
   readonly log?: CodemationLogConfig;
   readonly engineExecutionLimits?: CodemationEngineExecutionLimitsConfig;

package/src/presentation/config/CodemationAuthConfig.ts

@@ -4,7 +4,7 @@ import type { BetterAuthOptions } from "better-auth";
  * Consumer-declared authentication profile for the hosted UI + HTTP API.
  * Social provider ids intentionally match Better Auth's provider ids so config stays 1:1 with the auth runtime.
  */
-export type CodemationAuthKind = "local" | "oauth" | "oidc";
+export type CodemationAuthKind = "local" | "oauth" | "oidc" | "managed";
 
 export type CodemationAuthOAuthProviderId = Extract<
   keyof NonNullable<BetterAuthOptions["socialProviders"]>,

package/src/presentation/config/CodemationAuthoring.types.ts

@@ -1,4 +1,4 @@
-import type { AnyCredentialType, DefinedCollection, DefinedNode } from "@codemation/core";
+import type { AnyCredentialType, DefinedCollection, DefinedNode, McpServerDeclaration } from "@codemation/core";
 import type { CodemationAppContext } from "./CodemationAppContext";
 import type {
   CodemationAppDefinition,
@@ -12,14 +12,20 @@ import type { CodemationWhitelabelConfig } from "./CodemationWhitelabelConfig";
 export interface FriendlyCodemationDatabaseConfig {
   readonly kind: "postgresql" | "sqlite";
   readonly url?: string;
+  /** Name of an environment variable whose value is the PostgreSQL connection URL. Co-exclusive with `url`. */
+  readonly urlEnv?: string;
   readonly filePath?: string;
 }
 
 export interface FriendlyCodemationExecutionConfig {
   readonly mode?: "inline" | "queue";
+  /** Name of an environment variable whose value is "inline" or "queue". Co-exclusive with `mode`. */
+  readonly modeEnv?: string;
   readonly queuePrefix?: string;
   readonly workerQueues?: ReadonlyArray<string>;
   readonly redisUrl?: string;
+  /** Name of an environment variable whose value is the Redis connection URL. Co-exclusive with `redisUrl`. */
+  readonly redisUrlEnv?: string;
 }
 
 export interface DefineCodemationAppOptions extends Omit<
@@ -27,6 +33,11 @@ export interface DefineCodemationAppOptions extends Omit<
   "app" | "credentialTypes" | "register" | "whitelabel" | "auth" | "collections"
 > {
   readonly name?: string;
+  /**
+   * Reserved compatibility-date field. Declares the Codemation framework version this workspace
+   * targets. No enforcement in 1.0.0 — presence only. See backlog/codemation-version-compatibility-gate.md.
+   */
+  readonly codemationVersion?: string;
   readonly auth?: CodemationConfig["auth"];
   readonly database?: FriendlyCodemationDatabaseConfig;
   readonly execution?: FriendlyCodemationExecutionConfig;
@@ -36,6 +47,13 @@ export interface DefineCodemationAppOptions extends Omit<
   readonly credentials?: ReadonlyArray<AnyCredentialType>;
   readonly register?: (context: CodemationAppContext) => void;
   readonly whitelabel?: CodemationWhitelabelConfig;
+  /**
+   * Path (relative to the consumer project root) to a directory from which workflows are auto-discovered.
+   * All `*.ts` / `*.tsx` files (excluding `*.test.*` and `*.d.ts`) are imported and any exported
+   * `WorkflowDefinition` values are registered. Co-exclusive with providing this directory in
+   * `workflowDiscovery.directories`.
+   */
+  readonly workflowsDir?: string;
 }
 
 export interface DefinePluginOptions {
@@ -44,6 +62,7 @@ export interface DefinePluginOptions {
   readonly nodes?: ReadonlyArray<DefinedNode<string, Record<string, unknown>, unknown, unknown>>;
   readonly collections?: ReadonlyArray<DefinedCollection>;
   readonly credentials?: ReadonlyArray<AnyCredentialType>;
+  readonly mcpServers?: ReadonlyArray<McpServerDeclaration>;
   readonly register?: (context: CodemationPluginContext) => void | Promise<void>;
   readonly sandbox?: CodemationConfig;
 }
@@ -53,13 +72,16 @@ class CodemationAuthoringConfigFactory {
     const appDefinition = this.createAppDefinition(options);
     const credentialTypes = [...(options.credentialTypes ?? []), ...(options.credentials ?? [])];
     const register = this.composeAppRegister(options.register, options.nodes, options.collections);
-    const { workflows, workflowDiscovery, plugins, runtime, log } = options;
+    const { workflows, plugins, runtime, log, mcpServers, codemationVersion } = options;
+    const workflowDiscovery = this.mergeWorkflowDiscovery(options.workflowDiscovery, options.workflowsDir);
     return {
       workflows,
       workflowDiscovery,
       plugins,
       runtime,
       log,
+      mcpServers,
+      codemationVersion,
       app: appDefinition,
       credentialTypes,
       register,
@@ -70,6 +92,7 @@ class CodemationAuthoringConfigFactory {
     return {
       pluginPackageId: options.pluginPackageId,
       sandbox: options.sandbox,
+      mcpServers: options.mcpServers,
       async register(context: CodemationPluginContext): Promise<void> {
         for (const nodeDefinition of options.nodes ?? []) {
           nodeDefinition.register(context);
@@ -112,9 +135,15 @@ class CodemationAuthoringConfigFactory {
         sqliteFilePath: database.filePath,
       };
     }
+    if (database.url !== undefined && database.urlEnv !== undefined) {
+      throw new Error(
+        "defineCodemationApp: database.url and database.urlEnv are mutually exclusive — provide one or the other.",
+      );
+    }
+    const url = database.urlEnv !== undefined ? process.env[database.urlEnv] : database.url;
     return {
       kind: "postgresql",
-      url: database.url,
+      url,
     };
   }
 
@@ -124,11 +153,37 @@ class CodemationAuthoringConfigFactory {
     if (!execution) {
       return undefined;
     }
+    if (execution.mode !== undefined && execution.modeEnv !== undefined) {
+      throw new Error(
+        "defineCodemationApp: execution.mode and execution.modeEnv are mutually exclusive — provide one or the other.",
+      );
+    }
+    if (execution.redisUrl !== undefined && execution.redisUrlEnv !== undefined) {
+      throw new Error(
+        "defineCodemationApp: execution.redisUrl and execution.redisUrlEnv are mutually exclusive — provide one or the other.",
+      );
+    }
+    const rawMode = execution.modeEnv !== undefined ? process.env[execution.modeEnv] : execution.mode;
+    const mode = rawMode === "inline" || rawMode === "queue" ? rawMode : undefined;
+    const redisUrl = execution.redisUrlEnv !== undefined ? process.env[execution.redisUrlEnv] : execution.redisUrl;
     return {
-      kind: execution.mode,
+      kind: mode,
       queuePrefix: execution.queuePrefix,
       workerQueues: execution.workerQueues,
-      redisUrl: execution.redisUrl,
+      redisUrl,
+    };
+  }
+
+  private static mergeWorkflowDiscovery(
+    existing: CodemationConfig["workflowDiscovery"],
+    workflowsDir: string | undefined,
+  ): CodemationConfig["workflowDiscovery"] {
+    if (!workflowsDir) {
+      return existing;
+    }
+    const existingDirectories = existing?.directories ?? [];
+    return {
+      directories: [...existingDirectories, workflowsDir],
     };
   }
 

package/src/presentation/config/CodemationConfig.ts

@@ -3,6 +3,7 @@ import type {
   CollectionDefinition,
   DefinedCollection,
   EngineExecutionLimitsPolicyConfig,
+  McpServerDeclaration,
   WorkflowDefinition,
 } from "@codemation/core";
 import type { CodemationAuthConfig } from "./CodemationAuthConfig";
@@ -73,6 +74,12 @@ export interface CodemationApplicationRuntimeConfig {
 
 export interface CodemationConfig {
   readonly app?: CodemationAppDefinition;
+  /**
+   * Reserved compatibility-date field. Declares the Codemation framework version this workspace
+   * targets. Logged at INFO level on boot. No enforcement in 1.0.0.
+   * See backlog/codemation-version-compatibility-gate.md.
+   */
+  readonly codemationVersion?: string;
   readonly register?: (context: CodemationAppContext) => void;
   readonly runtime?: CodemationApplicationRuntimeConfig;
   readonly workflows?: ReadonlyArray<WorkflowDefinition>;
@@ -80,6 +87,8 @@ export interface CodemationConfig {
   readonly plugins?: ReadonlyArray<CodemationPlugin>;
   /** Consumer-defined `CredentialType` entries (see `@codemation/core`), applied when the host loads config. */
   readonly credentialTypes?: ReadonlyArray<AnyCredentialType>;
+  /** MCP server declarations from this config file (merged with plugin and control-plane sources at startup). */
+  readonly mcpServers?: ReadonlyArray<McpServerDeclaration>;
   /** Declared collections available at runtime via `ctx.collections`. Accepts either raw `CollectionDefinition` or `DefinedCollection` (the result of `defineCollection(...)`). */
   readonly collections?: ReadonlyArray<CollectionDefinition | DefinedCollection>;
   /** Optional shell whitelabel (product name, logo path). */

package/src/presentation/config/CodemationConfigNormalizer.ts

@@ -8,6 +8,7 @@ import type {
 } from "@codemation/core";
 import type { CodemationContainerRegistration } from "../../bootstrap/CodemationContainerRegistration";
 import type { CodemationAppContext } from "./CodemationAppContext";
+import type { CodemationAuthConfig } from "./CodemationAuthConfig";
 import type { CodemationClassToken } from "./CodemationClassToken";
 import type {
   CodemationApplicationRuntimeConfig,
@@ -25,6 +26,9 @@ export type NormalizedCodemationConfig = Omit<CodemationConfig, "collections"> &
 
 export class CodemationConfigNormalizer {
   normalize(config: CodemationConfig): NormalizedCodemationConfig {
+    const auth = config.app?.auth ?? config.auth;
+    this.assertAuthConfig(auth);
+    this.assertManagedModeConstraints(config, auth);
     const collected = this.collectRegistration(config);
     const normalizedRuntime = this.normalizeRuntimeConfig(config);
     const normalizedWorkflowDiscoveryDirectories = [
@@ -34,7 +38,7 @@ export class CodemationConfigNormalizer {
 
     return {
       ...config,
-      auth: config.app?.auth ?? config.auth,
+      auth,
       containerRegistrations: collected.containerRegistrations,
       credentialTypes: [...(config.credentialTypes ?? []), ...collected.credentialTypes],
       collections: [...this.unwrapCollections(config.collections), ...collected.collections],
@@ -49,6 +53,23 @@ export class CodemationConfigNormalizer {
     };
   }
 
+  /**
+   * Enforces managed-mode invariants beyond what `assertAuthConfig` covers:
+   * managed-mode workspaces are always Postgres and always require at least one workflow source.
+   */
+  private assertManagedModeConstraints(config: CodemationConfig, auth: CodemationAuthConfig | undefined): void {
+    if (auth?.kind !== "managed") {
+      return;
+    }
+    const hasWorkflows = (config.workflows?.length ?? 0) > 0;
+    const hasWorkflowDiscovery = (config.workflowDiscovery?.directories?.length ?? 0) > 0;
+    if (!hasWorkflows && !hasWorkflowDiscovery) {
+      throw new Error(
+        'Managed-mode workspaces require at least one workflow source. Provide "workflows" or "workflowsDir" (which maps to workflowDiscovery.directories) in defineCodemationApp.',
+      );
+    }
+  }
+
   private collectRegistration(config: CodemationConfig): Readonly<{
     containerRegistrations: ReadonlyArray<CodemationContainerRegistration<unknown>>;
     credentialTypes: ReadonlyArray<AnyCredentialType>;
@@ -187,6 +208,23 @@ export class CodemationConfigNormalizer {
     };
   }
 
+  private assertAuthConfig(authConfig: CodemationConfig["auth"]): void {
+    if (authConfig?.kind !== "managed") {
+      return;
+    }
+    if (authConfig.oauth && authConfig.oauth.length > 0) {
+      throw new Error('auth.kind "managed" cannot be combined with oauth providers. Remove the oauth config.');
+    }
+    if (authConfig.oidc && authConfig.oidc.length > 0) {
+      throw new Error('auth.kind "managed" cannot be combined with oidc providers. Remove the oidc config.');
+    }
+    if (authConfig.allowUnauthenticatedInDevelopment === true) {
+      throw new Error(
+        'auth.kind "managed" cannot be combined with allowUnauthenticatedInDevelopment. Remove that flag.',
+      );
+    }
+  }
+
   private mergeWorkflows(
     configuredWorkflows: ReadonlyArray<WorkflowDefinition>,
     registeredWorkflows: ReadonlyArray<WorkflowDefinition>,

package/src/presentation/config/CodemationPlugin.ts

@@ -1,4 +1,4 @@
-import type { AnyCredentialType, Container } from "@codemation/core";
+import type { AnyCredentialType, Container, McpServerDeclaration } from "@codemation/core";
 import type { LoggerFactory } from "../../application/logging/Logger";
 import type { AppConfig } from "./AppConfig";
 import type { CodemationRegistrationContextBase } from "./CodemationAppContext";
@@ -13,6 +13,7 @@ export interface CodemationPluginContext extends CodemationRegistrationContextBa
 export interface CodemationPluginConfig {
   readonly pluginPackageId?: string;
   readonly credentialTypes?: ReadonlyArray<AnyCredentialType>;
+  readonly mcpServers?: ReadonlyArray<McpServerDeclaration>;
   readonly register?: (context: CodemationPluginContext) => void | Promise<void>;
   readonly sandbox?: CodemationConfig;
 }

package/src/presentation/frontend/CodemationFrontendAuthSnapshot.ts

@@ -11,4 +11,9 @@ export type CodemationFrontendAuthSnapshot = Readonly<{
   oauthProviders: ReadonlyArray<CodemationFrontendAuthProviderSnapshot>;
   secret: string | null;
   uiAuthEnabled: boolean;
+  /**
+   * Present when auth.kind === "managed". Carries the CP-web origin for CORS
+   * awareness. No UI login flow is rendered in managed mode.
+   */
+  cpWebOrigin?: string;
 }>;

package/src/presentation/frontend/CodemationFrontendAuthSnapshotFactory.ts

@@ -29,13 +29,19 @@ export class CodemationFrontendAuthSnapshotFactory {
       uiAuthEnabled: boolean;
     }>,
   ): CodemationFrontendAuthSnapshot {
-    return {
+    const snapshot = {
       config: args.authConfig,
       credentialsEnabled: args.authConfig?.kind === "local",
       oauthProviders: this.createOauthProviders(args.authConfig),
       secret: this.resolveAuthSecret(args.env),
       uiAuthEnabled: args.uiAuthEnabled,
     };
+    const cpWebOrigin =
+      args.authConfig?.kind === "managed" ? args.env["CP_WEB_ORIGIN"]?.trim() || undefined : undefined;
+    if (cpWebOrigin) {
+      return { ...snapshot, cpWebOrigin };
+    }
+    return snapshot;
   }
 
   private resolveUiAuthEnabled(authConfig: CodemationAuthConfig | undefined, env: NodeJS.ProcessEnv): boolean {

package/src/presentation/frontend/PublicFrontendBootstrap.ts

@@ -9,4 +9,6 @@ export type PublicFrontendBootstrap = Readonly<{
   oauthProviders: ReadonlyArray<CodemationFrontendAuthProviderSnapshot>;
   productName: string;
   uiAuthEnabled: boolean;
+  /** Present in managed mode — the CP web origin. No UI login is rendered when this is set. */
+  cpWebOrigin?: string;
 }>;

package/src/presentation/frontend/PublicFrontendBootstrapFactory.ts

@@ -12,12 +12,16 @@ export class PublicFrontendBootstrapFactory {
 
   create(): PublicFrontendBootstrap {
     const frontendAppConfig = this.frontendAppConfigFactory.create();
-    return {
+    const bootstrap: PublicFrontendBootstrap = {
       credentialsEnabled: frontendAppConfig.auth.credentialsEnabled,
       logoUrl: frontendAppConfig.logoUrl,
       oauthProviders: frontendAppConfig.auth.oauthProviders,
       productName: frontendAppConfig.productName,
       uiAuthEnabled: frontendAppConfig.auth.uiAuthEnabled,
     };
+    if (frontendAppConfig.auth.cpWebOrigin) {
+      return { ...bootstrap, cpWebOrigin: frontendAppConfig.auth.cpWebOrigin };
+    }
+    return bootstrap;
   }
 }