@codemation/host 0.7.0 → 0.9.0

package/src/bootstrap/AppContainerFactory.ts

@@ -57,6 +57,7 @@ import {
   UploadOverlayPinnedBinaryCommandHandler,
 } from "../application/commands/WorkflowCommandHandlers";
 import {
+  GetCredentialAppsQueryHandler,
   GetCredentialFieldEnvStatusQueryHandler,
   GetCredentialInstanceQueryHandler,
   GetCredentialInstanceWithSecretsQueryHandler,
@@ -64,6 +65,7 @@ import {
   ListCredentialInstancesQueryHandler,
   ListCredentialTypesQueryHandler,
 } from "../application/queries/CredentialQueryHandlers";
+import { AppGalleryProjector } from "../application/credentials/AppGalleryProjector";
 import {
   ListUserAccountsQueryHandler,
   VerifyUserInviteQueryHandler,
@@ -278,11 +280,18 @@ import { HmacRequestSigner } from "../pairing/HmacRequestSigner";
 import { PairedFetch } from "../pairing/PairedFetch";
 import { IncomingHmacVerifier } from "../pairing/IncomingHmacVerifier";
 import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import { HmacNonceStoreToken } from "../pairing/HmacNonceStoreToken";
+import { PrismaHmacNonceStore } from "../infrastructure/persistence/PrismaHmacNonceStore";
 import { InternalPingRegistrar } from "../pairing/InternalPingRegistrar";
 import { LocalOAuthFlowExecutor } from "../credentials/LocalOAuthFlowExecutor";
+import { LocalCredentialMaterialProvider } from "../credentials/LocalCredentialMaterialProvider";
+import { CachingCredentialMaterialProvider } from "../credentials/CachingCredentialMaterialProvider";
+import { ControlPlaneCredentialMaterialProvider } from "../credentials/ControlPlaneCredentialMaterialProvider";
+import { CompositeCredentialMaterialProvider } from "../credentials/CompositeCredentialMaterialProvider";
 import { CredentialOAuth2MaterialReader } from "../credentials/CredentialOAuth2MaterialReader";
 import { ManagedOAuthFlowExecutor } from "../credentials/ManagedOAuthFlowExecutor";
 import { BrokerClient } from "../credentials/BrokerClient";
+import { InternalCredentialsBindingRegistrar } from "../credentials/InternalCredentialsBindingRegistrar";
 import { InternalCredentialsPushRegistrar } from "../credentials/InternalCredentialsPushRegistrar";
 import { InternalCredentialsListRegistrar } from "../credentials/InternalCredentialsListRegistrar";
 import { InternalWorkflowsListRegistrar } from "../workflows/InternalWorkflowsListRegistrar";
@@ -301,6 +310,23 @@ import { ManagedWebsocketAuthenticator } from "../presentation/websocket/Managed
 import { JwksCache, ManagedJwtVerifier } from "@codemation/managed-auth";
 import { CodemationTsyringeTypeInfoRegistrar } from "../presentation/server/CodemationTsyringeTypeInfoRegistrar";
 import { ControlPlaneCatalogFetcher } from "../credentials/ControlPlaneCatalogFetcher";
+import { PrismaHumanTaskStore } from "../infrastructure/persistence/PrismaHumanTaskStore";
+import { HitlResumeTokenSigner } from "../hitl/HitlResumeTokenSigner";
+import { HitlTimeoutJobScheduler } from "../hitl/HitlTimeoutJobScheduler";
+import { HitlTimeoutWorker } from "../hitl/HitlTimeoutWorker";
+import { DecideHumanTaskCommandHandler } from "../application/hitl/DecideHumanTaskCommandHandler";
+import { DecisionSchemaValidator } from "../application/hitl/DecisionSchemaValidator";
+import { HitlDecideHonoApiRouteRegistrar } from "../presentation/http/hono/registrars/HitlDecideHonoApiRouteRegistrar";
+import { HitlResumeHonoApiRouteRegistrar } from "../presentation/http/hono/registrars/HitlResumeHonoApiRouteRegistrar";
+import { HumanTaskStoreToken } from "@codemation/core";
+import { HitlResumeTokenSignerToken, HitlTimeoutJobSchedulerToken, HitlWorkspaceIdToken } from "@codemation/core";
+import { ControlPlaneInboxChannelToken, InboxChannelResolverToken, LocalInboxChannelToken } from "@codemation/core";
+import { InboxChannelResolver } from "../hitl/InboxChannelResolver";
+import { LocalInboxChannel } from "../hitl/LocalInboxChannel";
+import { ControlPlaneInboxChannel } from "../hitl/ControlPlaneInboxChannel";
+import { HitlCallbackHandler } from "../application/hitl/HitlCallbackHandler";
+import { HitlInternalCallbackHonoApiRouteRegistrar } from "../presentation/http/hono/registrars/HitlInternalCallbackHonoApiRouteRegistrar";
+import { ResumeTelemetryContextForRun } from "../application/telemetry/ResumeTelemetryContextForRun";
 
 type AppContainerInputs = Readonly<{
   appConfig: AppConfig;
@@ -313,6 +339,7 @@ type PrismaOwnership = Readonly<{
 
 export class AppContainerFactory {
   private static readonly queryHandlers = [
+    GetCredentialAppsQueryHandler,
     GetCredentialFieldEnvStatusQueryHandler,
     GetCredentialInstanceQueryHandler,
     GetCredentialInstanceWithSecretsQueryHandler,
@@ -380,6 +407,8 @@ export class AppContainerFactory {
     WhitelabelHonoApiRouteRegistrar,
     WorkflowHonoApiRouteRegistrar,
     CollectionHonoApiRouteRegistrar,
+    HitlDecideHonoApiRouteRegistrar,
+    HitlResumeHonoApiRouteRegistrar,
   ] as const;
 
   constructor(
@@ -393,7 +422,9 @@ export class AppContainerFactory {
     // Register the no-op publisher as a fallback so OtelExecutionTelemetryFactory can always
     // resolve the token. registerOperationalInfrastructure overrides this with the WS relay.
     container.registerInstance(ApplicationTokens.TelemetrySpanPublisher, NoOpTelemetrySpanPublisher);
-    BootTimer.measure("appContainer.registerCoreInfrastructure", () => this.registerCoreInfrastructure(container, inputs));
+    BootTimer.measure("appContainer.registerCoreInfrastructure", () =>
+      this.registerCoreInfrastructure(container, inputs),
+    );
     BootTimer.measure("appContainer.registerRepositoriesAndBuses", () => this.registerRepositoriesAndBuses(container));
     BootTimer.measure("appContainer.registerApplicationServicesAndRoutes", () =>
       this.registerApplicationServicesAndRoutes(container, inputs.appConfig),
@@ -481,7 +512,7 @@ export class AppContainerFactory {
     });
   }
 
-private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void {
+  private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void {
     const catalog = container.resolve(McpServerCatalog);
     catalog.merge("config", appConfig.mcpServers ?? []);
   }
@@ -716,6 +747,7 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
     container.registerSingleton(CredentialRuntimeMaterialService, CredentialRuntimeMaterialService);
     container.registerSingleton(WorkflowCredentialNodeResolver, WorkflowCredentialNodeResolver);
     container.registerSingleton(CredentialInstanceService, CredentialInstanceService);
+    container.registerSingleton(AppGalleryProjector, AppGalleryProjector);
     container.registerSingleton(CredentialBindingService, CredentialBindingService);
     container.registerSingleton(WorkflowActivationPreflightRules, WorkflowActivationPreflightRules);
     container.registerSingleton(WorkflowActivationPreflight, WorkflowActivationPreflight);
@@ -738,6 +770,26 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
       container.registerSingleton(LocalOAuthFlowExecutor, LocalOAuthFlowExecutor);
     }
     container.registerSingleton(CredentialOAuth2MaterialReader, CredentialOAuth2MaterialReader);
+    // Register the local material provider unconditionally. The dispatcher picks
+    // between this and the control-plane provider in managed mode.
+    container.registerSingleton(LocalCredentialMaterialProvider, LocalCredentialMaterialProvider);
+    // In managed mode (paired with a
+    // control plane) wrap the cache around a `CompositeCredentialMaterialProvider`
+    // that dispatches by `ref.source`. In standalone mode the cache wraps the
+    // local provider directly.
+    if (container.isRegistered(PairedFetch, true)) {
+      container.registerSingleton(ControlPlaneCredentialMaterialProvider, ControlPlaneCredentialMaterialProvider);
+      container.registerSingleton(CompositeCredentialMaterialProvider, CompositeCredentialMaterialProvider);
+      container.register(ApplicationTokens.CredentialMaterialInnerProvider, {
+        useFactory: instanceCachingFactory((c) => c.resolve(CompositeCredentialMaterialProvider)),
+      });
+    } else {
+      container.register(ApplicationTokens.CredentialMaterialInnerProvider, {
+        useFactory: instanceCachingFactory((c) => c.resolve(LocalCredentialMaterialProvider)),
+      });
+    }
+    // In-memory TTL cache decorator.
+    container.registerSingleton(CachingCredentialMaterialProvider, CachingCredentialMaterialProvider);
     container.registerSingleton(CodemationFrontendAuthSnapshotFactory, CodemationFrontendAuthSnapshotFactory);
     container.registerSingleton(FrontendAppConfigFactory, FrontendAppConfigFactory);
     container.registerSingleton(PublicFrontendBootstrapFactory, PublicFrontendBootstrapFactory);
@@ -850,6 +902,7 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
       ),
     });
     container.registerSingleton(OtelExecutionTelemetryFactory, OtelExecutionTelemetryFactory);
+    container.registerSingleton(ResumeTelemetryContextForRun, ResumeTelemetryContextForRun);
     container.registerSingleton(InMemoryRunTraceContextRepository, InMemoryRunTraceContextRepository);
     container.registerSingleton(InMemoryTelemetrySpanStore, InMemoryTelemetrySpanStore);
     container.registerSingleton(InMemoryTelemetryArtifactStore, InMemoryTelemetryArtifactStore);
@@ -872,6 +925,32 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
     container.registerSingleton(PrismaWorkflowActivationRepository, PrismaWorkflowActivationRepository);
     container.registerSingleton(InMemoryWorkflowActivationRepository, InMemoryWorkflowActivationRepository);
     container.registerSingleton(PrismaCredentialStore, PrismaCredentialStore);
+    // HITL: token signer + timeout scheduler (persistence wired in registerRuntimeInfrastructure)
+    container.registerSingleton(PrismaHumanTaskStore, PrismaHumanTaskStore);
+    // Default: no HITL store; overridden to PrismaHumanTaskStore in the Prisma path below
+    container.register(HumanTaskStoreToken, { useFactory: () => undefined });
+    container.registerSingleton(HitlResumeTokenSigner, HitlResumeTokenSigner);
+    container.register(HitlResumeTokenSignerToken, {
+      useFactory: instanceCachingFactory((dc) => dc.resolve(HitlResumeTokenSigner)),
+    });
+    container.registerSingleton(HitlTimeoutJobScheduler, HitlTimeoutJobScheduler);
+    container.register(HitlTimeoutJobSchedulerToken, {
+      useFactory: instanceCachingFactory((dc) => dc.resolve(HitlTimeoutJobScheduler)),
+    });
+    container.registerSingleton(HitlTimeoutWorker, HitlTimeoutWorker);
+    container.registerSingleton(DecisionSchemaValidator, DecisionSchemaValidator);
+    container.registerSingleton(DecideHumanTaskCommandHandler, DecideHumanTaskCommandHandler);
+    // HITL: inbox channel resolver (concrete local + control-plane channels registered below)
+    container.registerSingleton(InboxChannelResolver, InboxChannelResolver);
+    container.register(InboxChannelResolverToken, {
+      useFactory: instanceCachingFactory((dc) => dc.resolve(InboxChannelResolver)),
+    });
+    // HITL: local inbox channel — registered unconditionally; the resolver picks it
+    // whenever managed-mode CP channel is not present.
+    container.registerSingleton(LocalInboxChannel, LocalInboxChannel);
+    container.register(LocalInboxChannelToken, {
+      useFactory: instanceCachingFactory((dc) => dc.resolve(LocalInboxChannel)),
+    });
     container.register(ApplicationTokens.WorkflowDefinitionRepository, {
       useFactory: instanceCachingFactory(
         (dependencyContainer) =>
@@ -988,7 +1067,23 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
   }
 
   private registerPairingInfrastructure(container: Container, appConfig: AppConfig): void {
-    const pairingConfig = new PairingConfigFactory().create(appConfig.env);
+    const isManagedMode = appConfig.auth?.kind === "managed";
+    let pairingConfig;
+    try {
+      pairingConfig = new PairingConfigFactory().create(appConfig.env);
+    } catch (err) {
+      if (isManagedMode) {
+        // In managed mode the secret is required — let the error surface.
+        throw err;
+      }
+      // In non-managed mode an invalid-but-present WORKSPACE_PAIRING_SECRET is a misconfiguration
+      // warning, not a fatal error. Log and continue without pairing.
+      const logger = container.resolve(ServerLoggerFactory).create("codemation.pairing");
+      logger.warn(
+        `WORKSPACE_PAIRING_SECRET is set but invalid — pairing disabled. ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return;
+    }
     if (!pairingConfig) {
       // Pairing is optional in non-production environments (local dev without CP integration).
       // Emit a startup warning so operators know the workspace-mcp HMAC channel is inactive.
@@ -1006,18 +1101,33 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
       return;
     }
     container.registerInstance(PairingConfigToken, pairingConfig);
+    // T7: Stamp workspaceId on HumanTaskRecord in managed mode for defense-in-depth workspace check.
+    container.registerInstance(HitlWorkspaceIdToken, pairingConfig.workspaceId);
     container.registerSingleton(HmacRequestSigner, HmacRequestSigner);
     container.registerSingleton(PairedFetch, PairedFetch);
+    // T6: Durable nonce store — PrismaHmacNonceStore survives process restarts.
+    container.registerSingleton(HmacNonceStoreToken, PrismaHmacNonceStore);
     container.registerSingleton(IncomingHmacVerifier, IncomingHmacVerifier);
     container.registerSingleton(InternalHmacAuthMiddleware, InternalHmacAuthMiddleware);
     container.registerSingleton(BrokerClient, BrokerClient);
     container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalPingRegistrar);
     container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalCredentialsPushRegistrar);
+    container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalCredentialsBindingRegistrar);
     container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalCredentialsListRegistrar);
     container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalWorkflowsListRegistrar);
     container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalWorkflowDetailRegistrar);
     container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalWorkflowActivationRegistrar);
     container.registerSingleton(ApplicationTokens.InternalHonoApiRouteRegistrar, InternalWorkflowTestRunRegistrar);
+    // HITL: CP inbox channel + inbound decision callback (managed mode only)
+    container.registerSingleton(ControlPlaneInboxChannel, ControlPlaneInboxChannel);
+    container.register(ControlPlaneInboxChannelToken, {
+      useFactory: instanceCachingFactory((dc) => dc.resolve(ControlPlaneInboxChannel)),
+    });
+    container.registerSingleton(HitlCallbackHandler, HitlCallbackHandler);
+    container.registerSingleton(
+      ApplicationTokens.InternalHonoApiRouteRegistrar,
+      HitlInternalCallbackHonoApiRouteRegistrar,
+    );
   }
 
   private registerOperationalInfrastructure(container: Container): void {
@@ -1104,6 +1214,9 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
           binaryStorage,
           new LazyExecutionTelemetryFactory(() => container.resolve(OtelExecutionTelemetryFactory)),
           new CatalogBackedCostTrackingTelemetryFactory(new StaticCostCatalog(FrameworkCostCatalogEntries)),
+          undefined,
+          undefined,
+          container,
         ),
       );
       this.registerRuntimeNodeActivationScheduler(container);
@@ -1141,6 +1254,8 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
       container.resolve(PrismaWorkflowActivationRepository),
     );
     container.registerInstance(ApplicationTokens.CredentialStore, container.resolve(PrismaCredentialStore));
+    // HITL: wire PrismaHumanTaskStore now that PrismaDatabaseClientToken is available
+    container.registerInstance(HumanTaskStoreToken, container.resolve(PrismaHumanTaskStore));
     container.registerInstance(ApplicationTokens.RunTraceContextRepository, runTraceContextRepository);
     container.registerInstance(ApplicationTokens.TelemetrySpanStore, telemetrySpanStore);
     container.registerInstance(ApplicationTokens.TelemetryArtifactStore, telemetryArtifactStore);
@@ -1153,6 +1268,9 @@ private mergeConfigMcpServers(container: Container, appConfig: AppConfig): void
         binaryStorage,
         new LazyExecutionTelemetryFactory(() => container.resolve(OtelExecutionTelemetryFactory)),
         new CatalogBackedCostTrackingTelemetryFactory(new StaticCostCatalog(FrameworkCostCatalogEntries)),
+        undefined,
+        undefined,
+        container,
       ),
     );
     if (appConfig.scheduler.kind === "bullmq") {

package/src/bootstrap/runtime/HeadlessApiRuntime.ts

@@ -0,0 +1,47 @@
+import type { AppConfig } from "../../presentation/config/AppConfig";
+import type { AppContainerFactory } from "../AppContainerFactory";
+import { FrontendRuntime } from "./FrontendRuntime";
+import { CodemationHonoApiApp } from "../../presentation/http/hono/CodemationHonoApiAppFactory";
+import type { WorkflowWebsocketServerFactory } from "../../presentation/websocket/WorkflowWebsocketServerFactory";
+import type { HeadlessHttpServerFactory } from "../../presentation/http/HeadlessHttpServerFactory";
+import type { Logger } from "../../application/logging/Logger";
+
+/**
+ * Boots the Codemation API + WebSocket servers without the Next.js UI process.
+ * Used by `codemation serve web --headless` for workspace pod containers where the
+ * UI is served externally (e.g. from the control-plane's customer-ui).
+ */
+export class HeadlessApiRuntime {
+  constructor(
+    private readonly appContainerFactory: AppContainerFactory,
+    private readonly websocketServerFactory: WorkflowWebsocketServerFactory,
+    private readonly httpServerFactory: HeadlessHttpServerFactory,
+    private readonly logger: Logger,
+  ) {}
+
+  async start(appConfig: AppConfig): Promise<void> {
+    const port = Number(appConfig.env.PORT ?? 4001);
+
+    this.logger.info(`Starting codemation headless API runtime`);
+    this.logger.info(`HTTP port: ${port}, WS port: ${appConfig.webSocketPort}`);
+
+    const websocketServer = this.websocketServerFactory.create(appConfig);
+
+    const container = await this.appContainerFactory.create({
+      appConfig,
+      sharedWorkflowWebsocketServer: websocketServer,
+    });
+
+    await container.resolve(FrontendRuntime).start();
+
+    const honoApp = container.resolve(CodemationHonoApiApp);
+    const httpServer = this.httpServerFactory.create(honoApp, port, this.logger);
+
+    await new Promise<void>((resolve) => {
+      httpServer.listen(port, () => {
+        this.logger.info(`codemation headless API listening on port ${port}`);
+        resolve();
+      });
+    });
+  }
+}

package/src/credentials/CachingCredentialMaterialProvider.ts

@@ -0,0 +1,96 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  CallerContext,
+  CredentialMaterialProvider,
+  CredentialMaterialRef,
+  MaterialBundle,
+} from "@codemation/core";
+
+import { ApplicationTokens } from "../applicationTokens";
+import type { Logger, LoggerFactory } from "../application/logging/Logger";
+
+type CacheEntry = Readonly<{
+  material: MaterialBundle;
+  expiresAt: number;
+}>;
+
+/**
+ * In-memory TTL cache decorator for `CredentialMaterialProvider`.
+ *
+ * - Hits avoid the wrapped provider (no CP RPC, no audit row).
+ * - Misses/expired entries delegate to the wrapped provider and store the
+ *   result with TTL = `min(material.expiresAt − 60s, now + 5min)`.
+ * - `setMaterial` delegates and then invalidates the entry, so the next
+ *   `getMaterial` re-fetches fresh bytes.
+ *
+ * Cache is process-local only — never serialized, never shared across pods.
+ * See `docs/design/credentials-oauth-unification.md` and
+ * `planning/sprints/credentials-vault/03-in-memory-material-cache.md`.
+ */
+@injectable()
+export class CachingCredentialMaterialProvider implements CredentialMaterialProvider {
+  private static readonly HARD_CAP_MS = 5 * 60 * 1000;
+  private static readonly EXPIRY_SAFETY_WINDOW_MS = 60 * 1000;
+
+  private readonly cache = new Map<string, CacheEntry>();
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(ApplicationTokens.CredentialMaterialInnerProvider) private readonly inner: CredentialMaterialProvider,
+    @inject(ApplicationTokens.LoggerFactory) loggerFactory: LoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("codemation.credentials.material-cache");
+  }
+
+  async getMaterial(ref: CredentialMaterialRef, context: CallerContext): Promise<MaterialBundle> {
+    const key = this.keyFor(ref);
+    const now = Date.now();
+    const entry = this.cache.get(key);
+    if (entry && entry.expiresAt > now) {
+      this.logger.debug(`material-cache hit key=${key}`);
+      return entry.material;
+    }
+    if (entry) {
+      this.logger.debug(`material-cache expired key=${key}`);
+      this.cache.delete(key);
+    } else {
+      this.logger.debug(`material-cache miss key=${key}`);
+    }
+    const material = await this.inner.getMaterial(ref, context);
+    const ttlExpiry = this.computeCacheExpiry(material, Date.now());
+    if (ttlExpiry !== null) {
+      this.cache.set(key, { material, expiresAt: ttlExpiry });
+    }
+    return material;
+  }
+
+  async setMaterial(ref: CredentialMaterialRef, material: MaterialBundle): Promise<void> {
+    await this.inner.setMaterial(ref, material);
+    this.cache.delete(this.keyFor(ref));
+  }
+
+  private keyFor(ref: CredentialMaterialRef): string {
+    return `${ref.source}::${ref.id}`;
+  }
+
+  /**
+   * Returns the absolute epoch-ms at which the cache entry should expire, or
+   * `null` if the entry should not be cached (computed TTL ≤ 0).
+   */
+  private computeCacheExpiry(material: MaterialBundle, now: number): number | null {
+    const hardCapExpiry = now + CachingCredentialMaterialProvider.HARD_CAP_MS;
+    if (material.expiresAt === undefined) {
+      return hardCapExpiry;
+    }
+    const parsed = Date.parse(material.expiresAt);
+    if (Number.isNaN(parsed)) {
+      return hardCapExpiry;
+    }
+    const safeExpiry = parsed - CachingCredentialMaterialProvider.EXPIRY_SAFETY_WINDOW_MS;
+    const clamped = Math.min(safeExpiry, hardCapExpiry);
+    if (clamped <= now) {
+      return null;
+    }
+    return clamped;
+  }
+}

package/src/credentials/CompositeCredentialMaterialProvider.ts

@@ -0,0 +1,47 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  CallerContext,
+  CredentialMaterialProvider,
+  CredentialMaterialRef,
+  MaterialBundle,
+} from "@codemation/core";
+import { ManagedCredentialMaterialWriteError } from "@codemation/core";
+
+import { LocalCredentialMaterialProvider } from "./LocalCredentialMaterialProvider";
+import { ControlPlaneCredentialMaterialProvider } from "./ControlPlaneCredentialMaterialProvider";
+
+/**
+ * Routes `getMaterial` / `setMaterial` to the right inner provider based on
+ * `ref.source`. Registered as the inner of `CachingCredentialMaterialProvider`
+ * in managed mode so workspaces with mixed local + control-plane credential
+ * instances read each through the correct provider.
+ *
+ * Writes against `source: "control-plane"` always throw
+ * `ManagedCredentialMaterialWriteError` — managed credential bytes are owned
+ * by the control plane.
+ *
+ * See `planning/sprints/credentials-vault/02-controlplane-material-provider.md`.
+ */
+@injectable()
+export class CompositeCredentialMaterialProvider implements CredentialMaterialProvider {
+  constructor(
+    @inject(LocalCredentialMaterialProvider) private readonly local: LocalCredentialMaterialProvider,
+    @inject(ControlPlaneCredentialMaterialProvider)
+    private readonly controlPlane: ControlPlaneCredentialMaterialProvider,
+  ) {}
+
+  async getMaterial(ref: CredentialMaterialRef, context: CallerContext): Promise<MaterialBundle> {
+    return this.pick(ref).getMaterial(ref, context);
+  }
+
+  async setMaterial(ref: CredentialMaterialRef, material: MaterialBundle): Promise<void> {
+    if (ref.source === "control-plane") {
+      throw new ManagedCredentialMaterialWriteError();
+    }
+    return this.pick(ref).setMaterial(ref, material);
+  }
+
+  private pick(ref: CredentialMaterialRef): CredentialMaterialProvider {
+    return ref.source === "control-plane" ? this.controlPlane : this.local;
+  }
+}

package/src/credentials/ControlPlaneCatalogFetcher.ts

@@ -6,7 +6,6 @@ import type { AppConfig } from "../presentation/config/AppConfig";
 import { PairedFetch } from "../pairing/PairedFetch";
 import { PairingConfigToken } from "../pairing/PairingConfigToken";
 import type { PairingConfig } from "../pairing/pairing.types";
-import type { OAuthAppCatalogEntry } from "./catalogTypes";
 
 /**
  * Configuration read from env at construction time.
@@ -27,21 +26,20 @@ type EndpointState = {
 };
 
 /**
- * Polls the three control-plane catalog endpoints on a configurable interval,
+ * Polls the control-plane catalog endpoints on a configurable interval,
  * caches the last-known-good responses, and exposes the fetched data for
- * credential-type overrides, MCP server registrations, and OAuth app availability.
+ * credential-type overrides and MCP server registrations.
  *
  * Endpoints (HMAC-gated via PairedFetch):
- *   GET /api/catalog/oauth-apps
- *   GET /api/catalog/mcp-servers
- *   GET /api/catalog/credential-types
+ *   GET /internal/catalog/mcp-servers
+ *   GET /internal/catalog/credential-types
  *
  * Failure semantics: a failure on one endpoint does NOT prevent updating the
  * others. Each endpoint's consecutive-failure counter and staleness escalation
  * are tracked independently.
  *
  * When not paired with a control plane (PairingConfigToken is null),
- * start() returns immediately and all three getters remain null.
+ * start() returns immediately and all getters remain null.
  */
 @injectable()
 export class ControlPlaneCatalogFetcher {
@@ -51,11 +49,9 @@ export class ControlPlaneCatalogFetcher {
   /** Tracks in-flight refresh so stop() can safely await it. */
   private inFlight: Promise<void> | null = null;
 
-  private _oauthApps: readonly OAuthAppCatalogEntry[] | null = null;
   private _mcpServers: readonly McpServerDeclaration[] | null = null;
   private _credentialTypeOverrides: readonly CredentialTypeDefinition[] | null = null;
 
-  private readonly oauthAppsState: EndpointState = { consecutiveFailures: 0, lastSuccessAt: null };
   private readonly mcpServersState: EndpointState = { consecutiveFailures: 0, lastSuccessAt: null };
   private readonly credentialTypesState: EndpointState = { consecutiveFailures: 0, lastSuccessAt: null };
 
@@ -82,11 +78,6 @@ export class ControlPlaneCatalogFetcher {
     };
   }
 
-  /** Latest fetched OAuth app catalog; null until first successful fetch. */
-  get oauthApps(): readonly OAuthAppCatalogEntry[] | null {
-    return this._oauthApps;
-  }
-
   /** Latest fetched MCP server declarations; null until first successful fetch. */
   get mcpServers(): readonly McpServerDeclaration[] | null {
     return this._mcpServers;
@@ -163,22 +154,11 @@ export class ControlPlaneCatalogFetcher {
     const logger = this.loggers.create("ControlPlaneCatalogFetcher");
     const base = this.pairingConfig.controlPlaneUrl;
 
-    const [oauthResult, mcpResult, credTypesResult] = await Promise.allSettled([
-      this.pairedFetch.get(`${base}/api/catalog/oauth-apps`),
-      this.pairedFetch.get(`${base}/api/catalog/mcp-servers`),
-      this.pairedFetch.get(`${base}/api/catalog/credential-types`),
+    const [mcpResult, credTypesResult] = await Promise.allSettled([
+      this.pairedFetch.get(`${base}/internal/catalog/mcp-servers`),
+      this.pairedFetch.get(`${base}/internal/catalog/credential-types`),
     ]);
 
-    await this.handleEndpointResult(
-      oauthResult,
-      this.oauthAppsState,
-      "oauth-apps",
-      (data) => {
-        this._oauthApps = data as OAuthAppCatalogEntry[];
-      },
-      logger,
-    );
-
     await this.handleEndpointResult(
       mcpResult,
       this.mcpServersState,

package/src/credentials/ControlPlaneCredentialMaterialProvider.ts

@@ -0,0 +1,79 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  CallerContext,
+  CredentialMaterialProvider,
+  CredentialMaterialRef,
+  MaterialBundle,
+} from "@codemation/core";
+import {
+  IllegalMaterialSourceError,
+  ManagedCredentialMaterialWriteError,
+  ManagedMaterialFetchError,
+} from "@codemation/core";
+
+import { PairedFetch } from "../pairing/PairedFetch";
+import { PairingConfigToken } from "../pairing/PairingConfigToken";
+import type { PairingConfig } from "../pairing/pairing.types";
+
+/**
+ * Control-plane (managed-mode) implementation of `CredentialMaterialProvider`.
+ *
+ * `getMaterial({ source: "control-plane", id }, callerContext)` HMAC-POSTs to
+ *   `<CP>/internal/credentials/material/:id`
+ * with body `{ callerContext }`. The CP endpoint refreshes upstream tokens as
+ * needed and returns `{ accessToken, expiresAt, scopes, providerAccountId, typeId }`.
+ * The refresh token never crosses this boundary.
+ *
+ * `getMaterial` for `source: "local"` throws `IllegalMaterialSourceError`; a
+ * dispatcher (`CompositeCredentialMaterialProvider`) routes by source.
+ *
+ * `setMaterial` always throws `ManagedCredentialMaterialWriteError` — managed
+ * credential bytes are owned by the control plane.
+ *
+ * See `docs/design/credentials-oauth-unification.md` and
+ * `planning/sprints/credentials-vault/02-controlplane-material-provider.md`.
+ */
+@injectable()
+export class ControlPlaneCredentialMaterialProvider implements CredentialMaterialProvider {
+  constructor(
+    @inject(PairedFetch) private readonly pairedFetch: PairedFetch,
+    @inject(PairingConfigToken) private readonly pairingConfig: PairingConfig,
+  ) {}
+
+  async getMaterial(ref: CredentialMaterialRef, context: CallerContext): Promise<MaterialBundle> {
+    if (ref.source !== "control-plane") {
+      throw new IllegalMaterialSourceError(ref.source, "ControlPlaneCredentialMaterialProvider");
+    }
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/credentials/material/${encodeURIComponent(ref.id)}`;
+    const response = await this.pairedFetch.post(url, { callerContext: context });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new ManagedMaterialFetchError(response.status, body.slice(0, 500));
+    }
+    const json = (await response.json()) as {
+      accessToken?: unknown;
+      expiresAt?: unknown;
+      scopes?: unknown;
+      providerAccountId?: unknown;
+      typeId?: unknown;
+    };
+    if (typeof json.accessToken !== "string" || json.accessToken.length === 0) {
+      throw new ManagedMaterialFetchError(
+        response.status,
+        "missing accessToken in CP response",
+        "Control-plane material response missing accessToken",
+      );
+    }
+    return {
+      accessToken: json.accessToken,
+      // CP intentionally never returns the refresh token to the workspace.
+      refreshToken: undefined,
+      expiresAt: typeof json.expiresAt === "string" ? json.expiresAt : undefined,
+      grantedScopes: Array.isArray(json.scopes) ? json.scopes.filter((s): s is string => typeof s === "string") : [],
+    };
+  }
+
+  async setMaterial(_ref: CredentialMaterialRef, _material: MaterialBundle): Promise<void> {
+    throw new ManagedCredentialMaterialWriteError();
+  }
+}

package/src/credentials/CredentialOAuth2MaterialReader.ts

@@ -4,10 +4,7 @@ import type { Clock, OAuthFlowExecutor, OAuthMaterial } from "@codemation/core";
 import { ApplicationTokens } from "../applicationTokens";
 import type { LoggerFactory } from "../application/logging/Logger";
 import { CredentialSecretCipher } from "../domain/credentials/CredentialSecretCipher";
-import type {
-  CredentialOAuth2MaterialRecord,
-  CredentialStore,
-} from "../domain/credentials/CredentialServices";
+import type { CredentialOAuth2MaterialRecord, CredentialStore } from "../domain/credentials/CredentialServices";
 
 /**
  * Reads OAuth2 material for a credential instance and proactively refreshes it
@@ -128,9 +125,7 @@ export class CredentialOAuth2MaterialReader {
       refreshToken: typeof json.refreshToken === "string" ? json.refreshToken : undefined,
       expiresAt: typeof json.expiresAt === "string" ? json.expiresAt : undefined,
       grantedScopes:
-        typeof json.grantedScopes === "string"
-          ? json.grantedScopes.split(/\s+/).filter((s) => s.length > 0)
-          : [],
+        typeof json.grantedScopes === "string" ? json.grantedScopes.split(/\s+/).filter((s) => s.length > 0) : [],
     };
   }
 }