@codemation/host 0.5.1 → 0.7.0

package/src/mcp/McpConnectionPool.ts

@@ -0,0 +1,184 @@
+import { inject, injectable } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { LoggerFactory } from "../application/logging/Logger";
+import { McpServerCatalog } from "./McpServerCatalog";
+import { DefaultMcpClientFactory } from "./McpClientFactory";
+import type { McpClientFactory } from "./McpClientFactory";
+import { CredentialOAuth2MaterialReader } from "../credentials/CredentialOAuth2MaterialReader";
+import type { MCPClient, McpToolSet } from "./McpConnectionPool.types";
+
+/** Mutable internal pool entry (toolsCache may be filled lazily). */
+type MutablePoolEntry = {
+  client: MCPClient;
+  toolsCache: McpToolSet | null;
+  openedAt: Date;
+};
+
+@injectable()
+export class McpConnectionPool {
+  /** Key: `${credentialInstanceId}:${serverId}` */
+  private readonly pool = new Map<string, MutablePoolEntry>();
+  /**
+   * In-flight open promises — prevents a double-open race when two callers request
+   * the same (credentialInstanceId, serverId) pair concurrently.
+   */
+  private readonly inFlight = new Map<string, Promise<MutablePoolEntry>>();
+
+  constructor(
+    @inject(McpServerCatalog) private readonly catalog: McpServerCatalog,
+    @inject(CredentialOAuth2MaterialReader) private readonly oauth2Material: CredentialOAuth2MaterialReader,
+    @inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory,
+    @inject(DefaultMcpClientFactory) private readonly clientFactory: McpClientFactory,
+  ) {}
+
+  /**
+   * Returns a live MCP client for the given credential instance + server.
+   * Opens a new connection lazily; subsequent calls with the same pair return the cached client.
+   * Two concurrent calls for the same pair share a single open operation (single-flight).
+   */
+  async getClient(credentialInstanceId: string, serverId: string): Promise<MCPClient> {
+    const entry = await this.getOrOpenEntry(credentialInstanceId, serverId);
+    return entry.client;
+  }
+
+  /**
+   * Returns the tools/list result for the given credential instance + server,
+   * with toolDescriptionOverrides from the declaration applied.
+   * Fetches and caches once per pool entry; subsequent calls return the cached value.
+   * Used by Story 10's BM25 indexer.
+   */
+  async getTools(credentialInstanceId: string, serverId: string): Promise<McpToolSet> {
+    const entry = await this.getOrOpenEntry(credentialInstanceId, serverId);
+    if (!entry.toolsCache) {
+      const raw = await entry.client.tools();
+      const decl = this.catalog.get(serverId);
+      entry.toolsCache = this.applyOverrides(raw, decl?.toolDescriptionOverrides);
+    }
+    return entry.toolsCache;
+  }
+
+  /**
+   * Closes all pool entries for a credential instance.
+   * Call this when the credential is revoked or disconnected.
+   * Token refresh does NOT require closing — OAuthFlowExecutor
+   * keeps the stored token fresh; the next open will read the current token.
+   *
+   * Resolves after all matched clients have completed close(), so callers can
+   * await this before re-connecting or cleaning up downstream state.
+   *
+   * TODO(story-credential-lifecycle): Wire this method to the credential lifecycle event.
+   * CredentialDisconnectedError (packages/host/src/credentials/refresh/CredentialDisconnectedError.ts)
+   * is thrown on dead refresh tokens but is an error, not a broadcast event — there is no
+   * event bus for credential lifecycle today. When a credential-disconnected event mechanism
+   * is introduced, call closeForCredential(credentialInstanceId) from its handler so that
+   * stale MCP pool entries are cleaned up on credential revocation.
+   */
+  async closeForCredential(credentialInstanceId: string): Promise<void> {
+    const logger = this.loggers.create("McpConnectionPool");
+    const prefix = `${credentialInstanceId}:`;
+    const toClose: Array<[string, MutablePoolEntry]> = [];
+    for (const [key, entry] of this.pool.entries()) {
+      if (key.startsWith(prefix)) {
+        toClose.push([key, entry]);
+        this.pool.delete(key);
+        logger.info(`McpConnectionPool: closed pool entry on credential revocation (key=${key})`);
+      }
+    }
+    await Promise.allSettled(
+      toClose.map(([key, entry]) =>
+        entry.client.close().catch((e: unknown) => {
+          logger.warn(
+            `McpConnectionPool: error closing client on credential revocation (key=${key})`,
+            e instanceof Error ? e : undefined,
+          );
+        }),
+      ),
+    );
+  }
+
+  /**
+   * Closes all pool entries. Called on host shutdown.
+   */
+  async closeAll(): Promise<void> {
+    await Promise.allSettled([...this.pool.values()].map((e) => e.client.close()));
+    this.pool.clear();
+    this.inFlight.clear();
+  }
+
+  private async getOrOpenEntry(credentialInstanceId: string, serverId: string): Promise<MutablePoolEntry> {
+    const key = this.poolKey(credentialInstanceId, serverId);
+    const cached = this.pool.get(key);
+    if (cached) {
+      return cached;
+    }
+    const existing = this.inFlight.get(key);
+    if (existing) {
+      return existing;
+    }
+    const openPromise = this.open(credentialInstanceId, serverId, key).finally(() => {
+      this.inFlight.delete(key);
+    });
+    this.inFlight.set(key, openPromise);
+    return openPromise;
+  }
+
+  private async open(credentialInstanceId: string, serverId: string, key: string): Promise<MutablePoolEntry> {
+    const decl = this.catalog.get(serverId);
+    if (!decl) {
+      throw new Error(`McpConnectionPool: MCP server "${serverId}" not found in catalog`);
+    }
+    // D1: HTTP-only in managed mode. The catalog already blocks stdio at merge time, but we
+    // double-check here as a defensive guard in case a declaration bypasses the catalog (e.g.
+    // a future in-memory test harness or a dynamically injected server that skips catalog
+    // validation). Transport is an attribute of the declaration, not the env var.
+    if (decl.transport !== "http") {
+      throw new Error(
+        `McpConnectionPool: MCP server "${serverId}" uses transport "${decl.transport}" which is not allowed in managed mode. ` +
+          `Only "http" transport is supported. For stdio, set CODEMATION_ALLOW_STDIO_MCP=true in a self-hosted environment.`,
+      );
+    }
+
+    // Read OAuth material directly. The bearer is baked into the client's headers at open
+    // time (per-open, not per-call) — @ai-sdk/mcp v1.0.42 does not support per-request header
+    // injection. LIMITATION: a pool entry uses a stale bearer after the access token expires;
+    // OAuthFlowExecutor refreshes stored material in the background, but the entry must be
+    // closed via closeForCredential and re-opened for the refreshed token to take effect.
+    const accessToken = await this.readAccessToken(credentialInstanceId, serverId);
+    const headers: Record<string, string> = {
+      ...(decl.staticHeaders ?? {}),
+      authorization: `Bearer ${accessToken}`,
+    };
+
+    const client = await this.clientFactory.open({ url: decl.url, headers });
+    const entry: MutablePoolEntry = { client, toolsCache: null, openedAt: new Date() };
+    this.pool.set(key, entry);
+    return entry;
+  }
+
+  private poolKey(credentialInstanceId: string, serverId: string): string {
+    return `${credentialInstanceId}:${serverId}`;
+  }
+
+  private async readAccessToken(credentialInstanceId: string, serverId: string): Promise<string> {
+    const material = await this.oauth2Material.readMaterial(credentialInstanceId);
+    if (!material.accessToken) {
+      throw new Error(
+        `McpConnectionPool: credential instance "${credentialInstanceId}" has no access token — reconnect the credential bound to MCP server "${serverId}"`,
+      );
+    }
+    return material.accessToken;
+  }
+
+  private applyOverrides(tools: McpToolSet, overrides?: Record<string, string>): McpToolSet {
+    if (!overrides) {
+      return tools;
+    }
+    const result = { ...tools };
+    for (const [name, description] of Object.entries(overrides)) {
+      if (result[name]) {
+        result[name] = { ...result[name], description };
+      }
+    }
+    return result;
+  }
+}

package/src/mcp/McpConnectionPool.types.ts

@@ -0,0 +1,12 @@
+import type { MCPClient } from "@ai-sdk/mcp";
+
+export type { MCPClient };
+
+/** The ToolSet shape returned by MCPClient.tools() with 'automatic' schema resolution. */
+export type McpToolSet = Awaited<ReturnType<MCPClient["tools"]>>;
+
+export type McpPoolEntry = Readonly<{
+  client: MCPClient;
+  toolsCache: McpToolSet | null;
+  openedAt: Date;
+}>;

package/src/mcp/McpServerCatalog.ts

@@ -0,0 +1,104 @@
+import { inject, injectable } from "@codemation/core";
+import type { McpServerDeclaration } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { LoggerFactory } from "../application/logging/Logger";
+import type { AppConfig } from "../presentation/config/AppConfig";
+
+export type McpServerDeclarationSource = "plugin" | "config" | "controlPlane";
+
+const SOURCE_PRIORITY: Record<McpServerDeclarationSource, number> = {
+  plugin: 0,
+  config: 1,
+  controlPlane: 2,
+};
+
+const ID_PATTERN = /^[a-z0-9-]+$/;
+
+type CatalogEntry = Readonly<{
+  decl: McpServerDeclaration;
+  source: McpServerDeclarationSource;
+}>;
+
+@injectable()
+export class McpServerCatalog {
+  private readonly entries = new Map<string, CatalogEntry>();
+  private readonly bySource = new Map<McpServerDeclarationSource, Set<string>>();
+  private readonly env: NodeJS.ProcessEnv;
+
+  constructor(
+    @inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory,
+    @inject(ApplicationTokens.AppConfig) appConfig: AppConfig,
+  ) {
+    this.env = appConfig.env;
+  }
+
+  merge(source: McpServerDeclarationSource, declarations: ReadonlyArray<McpServerDeclaration>): void {
+    const logger = this.loggers.create("McpServerCatalog");
+    for (const decl of declarations) {
+      if (!this.validate(decl, source, logger)) {
+        continue;
+      }
+      const existing = this.entries.get(decl.id);
+      if (existing) {
+        if (SOURCE_PRIORITY[source] <= SOURCE_PRIORITY[existing.source]) {
+          logger.warn(
+            `McpServerCatalog: id collision — lower-priority source "${source}" ignored for id "${decl.id}" (current source: "${existing.source}")`,
+          );
+          continue;
+        }
+        logger.warn(
+          `McpServerCatalog: id "${decl.id}" shadowed — "${existing.source}" overridden by higher-priority source "${source}"`,
+        );
+        this.bySource.get(existing.source)?.delete(decl.id);
+      }
+      this.entries.set(decl.id, { decl, source });
+      if (!this.bySource.has(source)) {
+        this.bySource.set(source, new Set());
+      }
+      this.bySource.get(source)!.add(decl.id);
+    }
+  }
+
+  get(id: string): McpServerDeclaration | undefined {
+    return this.entries.get(id)?.decl;
+  }
+
+  getAll(): readonly McpServerDeclaration[] {
+    return [...this.entries.values()].map((entry) => entry.decl);
+  }
+
+  clear(source: McpServerDeclarationSource): void {
+    const ids = this.bySource.get(source);
+    if (!ids) {
+      return;
+    }
+    for (const id of ids) {
+      this.entries.delete(id);
+    }
+    this.bySource.delete(source);
+  }
+
+  private validate(
+    decl: McpServerDeclaration,
+    source: McpServerDeclarationSource,
+    logger: ReturnType<LoggerFactory["create"]>,
+  ): boolean {
+    if (!ID_PATTERN.test(decl.id)) {
+      logger.warn(
+        `McpServerCatalog: declaration from "${source}" has invalid id "${decl.id}" (must match /^[a-z0-9-]+$/) — skipped`,
+      );
+      return false;
+    }
+
+    if ((decl.transport as string) === "stdio") {
+      if (this.env.CODEMATION_ALLOW_STDIO_MCP !== "true") {
+        logger.warn(
+          `McpServerCatalog: declaration "${decl.id}" from "${source}" uses stdio transport which is disabled (set CODEMATION_ALLOW_STDIO_MCP=true to allow) — skipped`,
+        );
+        return false;
+      }
+    }
+
+    return true;
+  }
+}

package/src/mcp/index.ts

@@ -0,0 +1,5 @@
+export { McpServerCatalog, type McpServerDeclarationSource } from "./McpServerCatalog";
+export { McpConnectionPool } from "./McpConnectionPool";
+export type { McpPoolEntry, McpToolSet, MCPClient } from "./McpConnectionPool.types";
+export { DefaultMcpClientFactory, type McpClientFactory, type McpClientOpenArgs } from "./McpClientFactory";
+export { AgentMcpIntegrationImpl } from "./AgentMcpIntegrationImpl";

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"]>,