@codemation/host 0.5.1 → 0.7.0

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<
@@ -36,6 +42,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 +57,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 +67,15 @@ 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 } = options;
+    const workflowDiscovery = this.mergeWorkflowDiscovery(options.workflowDiscovery, options.workflowsDir);
     return {
       workflows,
       workflowDiscovery,
       plugins,
       runtime,
       log,
+      mcpServers,
       app: appDefinition,
       credentialTypes,
       register,
@@ -70,6 +86,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 +129,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 +147,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";
@@ -80,6 +81,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;
   }
 }

package/src/presentation/frontend/PublicFrontendBootstrapJsonCodec.ts

@@ -15,7 +15,7 @@ export class PublicFrontendBootstrapJsonCodec {
       if (!parsed || typeof parsed !== "object") {
         return null;
       }
-      return {
+      const base: PublicFrontendBootstrap = {
         credentialsEnabled: parsed.credentialsEnabled === true,
         logoUrl: typeof parsed.logoUrl === "string" && parsed.logoUrl.trim().length > 0 ? parsed.logoUrl : null,
         oauthProviders: this.resolveOauthProviders(parsed.oauthProviders),
@@ -25,6 +25,9 @@ export class PublicFrontendBootstrapJsonCodec {
             : "Codemation",
         uiAuthEnabled: parsed.uiAuthEnabled !== false,
       };
+      const cpWebOrigin =
+        typeof parsed.cpWebOrigin === "string" && parsed.cpWebOrigin.trim().length > 0 ? parsed.cpWebOrigin : undefined;
+      return cpWebOrigin ? { ...base, cpWebOrigin } : base;
     } catch {
       return null;
     }

package/src/presentation/http/ApiPaths.ts

@@ -145,10 +145,6 @@ export class ApiPaths {
     return `${this.apiBasePath}/credential-bindings`;
   }
 
-  static oauth2Auth(instanceId: string): string {
-    return `${this.oauth2BasePath}/auth?instanceId=${encodeURIComponent(instanceId)}`;
-  }
-
   static oauth2RedirectUri(): string {
     return `${this.oauth2BasePath}/redirect-uri`;
   }
@@ -157,6 +153,10 @@ export class ApiPaths {
     return `${this.oauth2BasePath}/disconnect?instanceId=${encodeURIComponent(instanceId)}`;
   }
 
+  static credentialOAuthStart(): string {
+    return `${this.credentialsBasePath}/oauth/start`;
+  }
+
   static workflowWebsocket(): string {
     return `${this.workflowsBasePath}/ws`;
   }

package/src/presentation/http/ServerHttpErrorResponseFactory.ts

@@ -1,13 +1,50 @@
 import { ApplicationRequestError } from "../../application/ApplicationRequestError";
 
+/**
+ * Shape of the JSON body returned on an unhandled 500. The canvas (and any other client)
+ * reads `message` + optional `stack` + optional `cause` to surface a copy/pastable error
+ * dialog. Generic "Internal server error" with no detail makes operator triage impossible
+ * — this contract preserves the diagnostic information the CLI logs anyway.
+ */
+export type ServerHttpUnhandledErrorPayload = Readonly<{
+  error: "Internal server error";
+  message: string;
+  name?: string;
+  stack?: string;
+  cause?: string;
+}>;
+
 export class ServerHttpErrorResponseFactory {
   static fromUnknown(error: unknown): Response {
     if (error instanceof ApplicationRequestError) {
       return Response.json(error.payload, { status: error.status });
     }
     this.logUnexpectedError(error);
-    const message = error instanceof Error ? error.message : String(error);
-    return Response.json({ error: message }, { status: 500 });
+    return Response.json(this.toUnhandledPayload(error), { status: 500 });
+  }
+
+  private static toUnhandledPayload(error: unknown): ServerHttpUnhandledErrorPayload {
+    if (error instanceof Error) {
+      return {
+        error: "Internal server error",
+        message: error.message || `${error.name}: <no message>`,
+        name: error.name,
+        stack: error.stack,
+        cause: this.formatCauseValue(error),
+      };
+    }
+    return { error: "Internal server error", message: String(error) };
+  }
+
+  private static formatCauseValue(error: Error): string | undefined {
+    if (!("cause" in error) || !error.cause) {
+      return undefined;
+    }
+    const cause = error.cause;
+    if (cause instanceof Error) {
+      return cause.stack ?? `${cause.name}: ${cause.message}`;
+    }
+    return String(cause);
   }
 
   private static logUnexpectedError(error: unknown): void {

package/src/presentation/http/hono/CodemationHonoApiAppFactory.ts

@@ -5,7 +5,9 @@ import { ApplicationTokens } from "../../../applicationTokens";
 import { BinaryHttpRouteHandler } from "../routeHandlers/BinaryHttpRouteHandlerFactory";
 import { ServerHttpErrorResponseFactory } from "../ServerHttpErrorResponseFactory";
 import type { HonoApiRouteRegistrar } from "./HonoApiRouteRegistrar";
+import type { InternalHonoApiRouteRegistrar } from "./InternalHonoApiRouteRegistrar";
 import { HonoHttpAnonymousRoutePolicy } from "./HonoHttpAnonymousRoutePolicyRegistry";
+import { ManagedCorsMiddleware } from "../../../auth/managed/ManagedCorsMiddleware";
 
 @injectable()
 export class CodemationHonoApiApp {
@@ -18,10 +20,21 @@ export class CodemationHonoApiApp {
     registrars: ReadonlyArray<HonoApiRouteRegistrar>,
     @inject(BinaryHttpRouteHandler)
     binaryHttpRouteHandler: BinaryHttpRouteHandler,
+    @injectAll(ApplicationTokens.InternalHonoApiRouteRegistrar, { isOptional: true })
+    internalRegistrars: ReadonlyArray<InternalHonoApiRouteRegistrar>,
+    @injectAll(ApplicationTokens.ManagedCorsMiddleware, { isOptional: true })
+    corsMiddlewareList: ReadonlyArray<ManagedCorsMiddleware>,
   ) {
-    const app = new Hono().basePath("/api");
-    app.onError((error, _c) => ServerHttpErrorResponseFactory.fromUnknown(error));
-    app.use("*", async (c, next) => {
+    // Root app — composes /api/* (auth-gated) and /internal/* (HMAC-gated) sub-apps.
+    const root = new Hono();
+    const corsMiddleware = corsMiddlewareList[0] ?? null;
+    if (corsMiddleware) {
+      root.use("*", corsMiddleware.handle());
+    }
+
+    const api = new Hono().basePath("/api");
+    api.onError((error, _c) => ServerHttpErrorResponseFactory.fromUnknown(error));
+    api.use("*", async (c, next) => {
       if (HonoHttpAnonymousRoutePolicy.isAnonymousRoute(c.req.raw)) {
         await next();
         return;
@@ -33,25 +46,37 @@ export class CodemationHonoApiApp {
       await next();
     });
     for (const registrar of registrars) {
-      registrar.register(app);
+      registrar.register(api);
     }
-    app.get("/workflows/:workflowId/debugger-overlay/binary/:binaryId/content", (c) =>
+    api.get("/workflows/:workflowId/debugger-overlay/binary/:binaryId/content", (c) =>
       binaryHttpRouteHandler.getWorkflowOverlayBinaryContent(c.req.raw, {
         workflowId: c.req.param("workflowId"),
         binaryId: c.req.param("binaryId"),
       }),
     );
-    app.post("/workflows/:workflowId/debugger-overlay/binary/upload", (c) =>
+    api.post("/workflows/:workflowId/debugger-overlay/binary/upload", (c) =>
       binaryHttpRouteHandler.postWorkflowDebuggerOverlayBinaryUpload(c.req.raw, {
         workflowId: c.req.param("workflowId"),
       }),
     );
-    app.notFound((c) => {
+    api.notFound((c) => {
       const method = c.req.method.toUpperCase();
       const url = new URL(c.req.url);
       return c.json({ error: `Unknown API route: ${method} ${url.pathname}` }, 404);
     });
-    this.app = app;
+
+    root.route("/", api);
+
+    // /internal/* routes — only mounted when pairing is configured.
+    if (internalRegistrars.length > 0) {
+      const internal = new Hono();
+      for (const registrar of internalRegistrars) {
+        registrar.register(internal);
+      }
+      root.route("/", internal);
+    }
+
+    this.app = root;
   }
 
   getHono(): Hono {

package/src/presentation/http/hono/InternalHonoApiRouteRegistrar.ts

@@ -0,0 +1,12 @@
+import type { Hono } from "hono";
+
+/**
+ * Registrar interface for routes mounted on the installation's internal Hono app
+ * (no `/api` prefix). All routes registered here are accessible at `/internal/<path>`
+ * and are protected by HMAC auth middleware.
+ *
+ * See docs/pairing-protocol.md for the wire format and auth requirements.
+ */
+export interface InternalHonoApiRouteRegistrar {
+  register(app: Hono): void;
+}

package/src/presentation/http/hono/registrars/ManagedMeHonoApiRouteRegistrar.ts

@@ -0,0 +1,35 @@
+import { inject, injectable } from "@codemation/core";
+import { Hono } from "hono";
+import type { HonoApiRouteRegistrar } from "../HonoApiRouteRegistrar";
+import type { SessionVerifier } from "../../../../application/auth/SessionVerifier";
+import { ApplicationTokens } from "../../../../applicationTokens";
+
+/**
+ * Exposes `GET /api/me` in managed-auth mode.
+ *
+ * Reads the JWT principal by re-verifying the Bearer token, and returns
+ * `{ userId, workspaceId }`. No DB lookup needed — the JWT is the source of truth.
+ *
+ * Only registered when `auth.kind === "managed"`.
+ */
+@injectable()
+export class ManagedMeHonoApiRouteRegistrar implements HonoApiRouteRegistrar {
+  constructor(
+    @inject(ApplicationTokens.SessionVerifier)
+    private readonly sessionVerifier: SessionVerifier,
+  ) {}
+
+  register(app: Hono): void {
+    app.get("/me", async (c) => {
+      try {
+        const principal = await this.sessionVerifier.verify(c.req.raw);
+        if (!principal) {
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+        return c.json({ userId: principal.id, workspaceId: principal.workspaceId ?? null });
+      } catch {
+        return c.json({ error: "Unauthorized" }, 401);
+      }
+    });
+  }
+}

package/src/presentation/http/hono/registrars/OAuth2HonoApiRouteRegistrar.ts

@@ -8,8 +8,8 @@ export class OAuth2HonoApiRouteRegistrar implements HonoApiRouteRegistrar {
   constructor(@inject(OAuth2HttpRouteHandler) private readonly handler: OAuth2HttpRouteHandler) {}
 
   register(app: Hono): void {
-    app.get("/oauth2/auth", (c) => this.handler.getAuthRedirect(c.req.raw));
-    app.get("/oauth2/callback", (c) => this.handler.getCallback(c.req.raw));
+    app.post("/credentials/oauth/start", (c) => this.handler.postOAuthStart(c.req.raw));
+    app.get("/oauth2/callback", (c) => this.handler.getOAuthCallback(c.req.raw));
     app.get("/oauth2/redirect-uri", (c) => this.handler.getRedirectUri(c.req.raw));
     app.post("/oauth2/disconnect", (c) => this.handler.postDisconnect(c.req.raw));
   }

package/src/presentation/http/routeHandlers/CredentialHttpRouteHandler.ts

@@ -2,6 +2,7 @@ import { inject, injectable } from "@codemation/core";
 import { HttpRequestJsonBodyReader } from "../HttpRequestJsonBodyReader";
 import type { CommandBus } from "../../../application/bus/CommandBus";
 import type { QueryBus } from "../../../application/bus/QueryBus";
+import type { SessionVerifier } from "../../../application/auth/SessionVerifier";
 import {
   CreateCredentialInstanceCommand,
   DeleteCredentialInstanceCommand,
@@ -23,6 +24,8 @@ import {
   ListCredentialTypesQuery,
 } from "../../../application/queries/CredentialQueryHandlers";
 import { ApplicationTokens } from "../../../applicationTokens";
+import type { PairingConfig } from "../../../pairing/pairing.types";
+import { PairingConfigToken } from "../../../pairing/PairingConfigToken";
 import { ServerHttpErrorResponseFactory } from "../ServerHttpErrorResponseFactory";
 import type { ServerHttpRouteParams } from "../ServerHttpRouteParams";
 
@@ -33,6 +36,10 @@ export class CredentialHttpRouteHandler {
     private readonly queryBus: QueryBus,
     @inject(ApplicationTokens.CommandBus)
     private readonly commandBus: CommandBus,
+    @inject(ApplicationTokens.SessionVerifier)
+    private readonly sessionVerifier: SessionVerifier,
+    @inject(PairingConfigToken, { isOptional: true })
+    private readonly pairingConfig: PairingConfig | null,
   ) {}
 
   async getCredentialTypes(): Promise<Response> {
@@ -62,6 +69,27 @@ export class CredentialHttpRouteHandler {
   async getCredentialInstance(request: Request, params: ServerHttpRouteParams): Promise<Response> {
     try {
       const withSecrets = new URL(request.url).searchParams.get("withSecrets") === "1";
+
+      if (withSecrets) {
+        // Ownership check: fail-closed.
+        // - If the session verifier returns null (unauthenticated), reject.
+        // - In managed-JWT mode the principal's workspaceId must match the
+        //   installation's own workspaceId (from PairingConfig).
+        // - In local-auth mode (pairingConfig absent) a valid non-null principal
+        //   is sufficient — no cross-workspace check is possible or needed.
+        const principal = await this.sessionVerifier.verify(request);
+        if (!principal) {
+          return Response.json({ error: "Forbidden" }, { status: 403 });
+        }
+        if (
+          principal.source === "managed-jwt" &&
+          this.pairingConfig !== null &&
+          principal.workspaceId !== this.pairingConfig.workspaceId
+        ) {
+          return Response.json({ error: "Forbidden" }, { status: 403 });
+        }
+      }
+
       const instance = withSecrets
         ? await this.queryBus.execute(new GetCredentialInstanceWithSecretsQuery(params.instanceId!))
         : await this.queryBus.execute(new GetCredentialInstanceQuery(params.instanceId!));