@codemation/host 0.6.0 → 0.8.0

package/src/credentials/ControlPlaneCatalogFetcher.ts

@@ -0,0 +1,261 @@
+import { inject, injectable } from "@codemation/core";
+import type { CredentialTypeDefinition, McpServerDeclaration } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { LoggerFactory } from "../application/logging/Logger";
+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.
+ *
+ * - `CODEMATION_CATALOG_POLL_INTERVAL_SECONDS`: seconds between polls (default 300; 0 = startup-only).
+ * - `CODEMATION_CATALOG_STALE_FAILURES`: consecutive failures before warn → error escalation (default 5).
+ * - `CODEMATION_CATALOG_STALE_HOURS`: hours stale before escalating to error level (default 24).
+ */
+interface CatalogFetcherConfig {
+  readonly pollIntervalMs: number;
+  readonly staleFailuresThreshold: number;
+  readonly staleHoursThreshold: number;
+}
+
+type EndpointState = {
+  consecutiveFailures: number;
+  lastSuccessAt: Date | null;
+};
+
+/**
+ * Polls the three 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.
+ *
+ * Endpoints (HMAC-gated via PairedFetch):
+ *   GET /internal/catalog/oauth-apps
+ *   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.
+ */
+@injectable()
+export class ControlPlaneCatalogFetcher {
+  private readonly config: CatalogFetcherConfig;
+  private timerHandle: ReturnType<typeof setTimeout> | null = null;
+  private stopped = false;
+  /** 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 };
+
+  /**
+   * Called after each successful full fetch, before the next poll is scheduled.
+   * Set by AppContainerFactory to re-apply overrides on each refresh cycle.
+   */
+  onRefresh: (() => void) | null = null;
+
+  constructor(
+    @inject(PairedFetch) private readonly pairedFetch: PairedFetch,
+    @inject(PairingConfigToken, { isOptional: true }) private readonly pairingConfig: PairingConfig | null,
+    @inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory,
+    @inject(ApplicationTokens.AppConfig) appConfig: AppConfig,
+  ) {
+    const env = appConfig.env;
+    const pollSec = Number(env["CODEMATION_CATALOG_POLL_INTERVAL_SECONDS"] ?? 300);
+    const staleFailures = Number(env["CODEMATION_CATALOG_STALE_FAILURES"] ?? 5);
+    const staleHours = Number(env["CODEMATION_CATALOG_STALE_HOURS"] ?? 24);
+    this.config = {
+      pollIntervalMs: Number.isFinite(pollSec) ? pollSec * 1_000 : 300_000,
+      staleFailuresThreshold: Number.isFinite(staleFailures) ? staleFailures : 5,
+      staleHoursThreshold: Number.isFinite(staleHours) ? staleHours : 24,
+    };
+  }
+
+  /** 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;
+  }
+
+  /** Latest fetched credential type overrides; null until first successful fetch. */
+  get credentialTypeOverrides(): readonly CredentialTypeDefinition[] | null {
+    return this._credentialTypeOverrides;
+  }
+
+  /**
+   * Fires the first fetch (non-blocking — failure is logged, not thrown) and
+   * schedules the periodic poll if `pollIntervalMs > 0`.
+   * No-ops immediately when pairing config is absent.
+   */
+  async start(): Promise<void> {
+    if (!this.pairingConfig) {
+      return;
+    }
+    try {
+      await this.refresh();
+    } catch {
+      // refresh() handles its own errors; this catch is belt-and-suspenders.
+    }
+    this.scheduleNext();
+  }
+
+  /**
+   * Cancels the poll timer. Awaits any in-flight fetch before resolving.
+   */
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.timerHandle !== null) {
+      clearTimeout(this.timerHandle);
+      this.timerHandle = null;
+    }
+    if (this.inFlight) {
+      await this.inFlight;
+    }
+  }
+
+  /**
+   * Manual one-shot fetch. Same code path as the periodic tick.
+   * Errors are caught and logged internally; this method never rejects.
+   */
+  async refresh(): Promise<void> {
+    const run = this.fetchAll();
+    this.inFlight = run;
+    try {
+      await run;
+    } finally {
+      if (this.inFlight === run) {
+        this.inFlight = null;
+      }
+    }
+  }
+
+  private scheduleNext(): void {
+    if (this.stopped || this.config.pollIntervalMs <= 0) {
+      return;
+    }
+    this.timerHandle = setTimeout(() => {
+      if (this.stopped) {
+        return;
+      }
+      void this.refresh().finally(() => this.scheduleNext());
+    }, this.config.pollIntervalMs);
+  }
+
+  private async fetchAll(): Promise<void> {
+    if (!this.pairingConfig) {
+      return;
+    }
+    const logger = this.loggers.create("ControlPlaneCatalogFetcher");
+    const base = this.pairingConfig.controlPlaneUrl;
+
+    const [oauthResult, mcpResult, credTypesResult] = await Promise.allSettled([
+      this.pairedFetch.get(`${base}/internal/catalog/oauth-apps`),
+      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,
+      "mcp-servers",
+      (data) => {
+        this._mcpServers = data as McpServerDeclaration[];
+      },
+      logger,
+    );
+
+    await this.handleEndpointResult(
+      credTypesResult,
+      this.credentialTypesState,
+      "credential-types",
+      (data) => {
+        this._credentialTypeOverrides = data as CredentialTypeDefinition[];
+      },
+      logger,
+    );
+
+    this.onRefresh?.();
+  }
+
+  private async handleEndpointResult(
+    result: PromiseSettledResult<Response>,
+    state: EndpointState,
+    endpointName: string,
+    onSuccess: (data: unknown[]) => void,
+    logger: ReturnType<LoggerFactory["create"]>,
+  ): Promise<void> {
+    if (result.status === "fulfilled") {
+      const res = result.value;
+      if (res.ok) {
+        try {
+          const data = (await res.json()) as unknown[];
+          onSuccess(data);
+          state.consecutiveFailures = 0;
+          state.lastSuccessAt = new Date();
+          logger.info(`ControlPlaneCatalogFetcher: fetched ${endpointName} (count=${data.length})`);
+          return;
+        } catch (err) {
+          this.logEndpointFailure(state, endpointName, err, logger);
+          return;
+        }
+      }
+      this.logEndpointFailure(state, endpointName, new Error(`HTTP ${res.status} ${res.statusText}`), logger);
+    } else {
+      this.logEndpointFailure(state, endpointName, result.reason, logger);
+    }
+  }
+
+  private logEndpointFailure(
+    state: EndpointState,
+    endpointName: string,
+    err: unknown,
+    logger: ReturnType<LoggerFactory["create"]>,
+  ): void {
+    state.consecutiveFailures++;
+    const staleHours = state.lastSuccessAt ? (Date.now() - state.lastSuccessAt.getTime()) / 3_600_000 : null;
+    const errMsg = err instanceof Error ? err.message : String(err);
+
+    const isStale =
+      state.consecutiveFailures >= this.config.staleFailuresThreshold ||
+      (staleHours !== null && staleHours >= this.config.staleHoursThreshold);
+
+    if (isStale) {
+      const staleLabel = staleHours !== null ? `${staleHours.toFixed(1)}h` : "never-succeeded";
+      logger.error(
+        `ControlPlaneCatalogFetcher: ${endpointName} is stale — control plane unreachable (failures=${state.consecutiveFailures}, stale=${staleLabel}): ${errMsg}`,
+        err instanceof Error ? err : undefined,
+      );
+    } else {
+      logger.warn(
+        `ControlPlaneCatalogFetcher: ${endpointName} fetch failed, retaining prior cached value (failures=${state.consecutiveFailures}): ${errMsg}`,
+        err instanceof Error ? err : undefined,
+      );
+    }
+    // NOTE: cached value is intentionally preserved (last-known-good).
+  }
+}

package/src/credentials/CredentialOAuth2MaterialReader.ts

@@ -0,0 +1,136 @@
+import { inject, injectable } from "@codemation/core";
+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";
+
+/**
+ * Reads OAuth2 material for a credential instance and proactively refreshes it
+ * when the stored access token is past (or within `REFRESH_LEAD_MS` of) expiry.
+ *
+ * Why this exists: most OAuth2 consumers in the host pipe an access token to a
+ * raw HTTP call (MCP transport, webhook outbound, etc.) and have no SDK-level
+ * 401-and-refresh behaviour. Without proactive refresh, the stored token goes
+ * stale ~1h after the OAuth callback and every consumer fails with 401 until
+ * the user manually reconnects. The Gmail trigger doesn't hit this because
+ * `googleapis.OAuth2Client` refreshes internally — that's the exception, not
+ * the rule.
+ *
+ * Concurrency: a single in-flight refresh per instanceId. Concurrent reads
+ * during a refresh share the same promise so we don't invalidate the refresh
+ * token by exchanging it twice in parallel.
+ */
+@injectable()
+export class CredentialOAuth2MaterialReader {
+  private static readonly REFRESH_LEAD_MS = 60_000;
+
+  private readonly inFlightRefresh = new Map<string, Promise<OAuthMaterial>>();
+
+  constructor(
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+    @inject(CredentialSecretCipher) private readonly credentialSecretCipher: CredentialSecretCipher,
+    @inject(ApplicationTokens.OAuthFlowExecutor) private readonly oauthFlowExecutor: OAuthFlowExecutor,
+    @inject(ApplicationTokens.Clock) private readonly clock: Clock,
+    @inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory,
+  ) {}
+
+  async readMaterial(instanceId: string): Promise<OAuthMaterial> {
+    const encrypted = await this.credentialStore.getOAuth2Material(instanceId);
+    if (!encrypted) {
+      throw new Error(`CredentialOAuth2MaterialReader: instance "${instanceId}" has no OAuth2 material`);
+    }
+    const current = this.decrypt(encrypted);
+    if (!this.shouldRefresh(current)) {
+      return current;
+    }
+    return this.refreshSingleFlight(instanceId, current, encrypted);
+  }
+
+  private shouldRefresh(material: OAuthMaterial): boolean {
+    if (!material.expiresAt) return false;
+    if (!material.refreshToken) return false;
+    const expiryMs = Date.parse(material.expiresAt);
+    if (Number.isNaN(expiryMs)) return false;
+    return this.clock.now().getTime() + CredentialOAuth2MaterialReader.REFRESH_LEAD_MS >= expiryMs;
+  }
+
+  private refreshSingleFlight(
+    instanceId: string,
+    current: OAuthMaterial,
+    encrypted: CredentialOAuth2MaterialRecord,
+  ): Promise<OAuthMaterial> {
+    const inflight = this.inFlightRefresh.get(instanceId);
+    if (inflight) return inflight;
+    const next = this.doRefresh(instanceId, current, encrypted).finally(() => {
+      this.inFlightRefresh.delete(instanceId);
+    });
+    this.inFlightRefresh.set(instanceId, next);
+    return next;
+  }
+
+  private async doRefresh(
+    instanceId: string,
+    current: OAuthMaterial,
+    encrypted: CredentialOAuth2MaterialRecord,
+  ): Promise<OAuthMaterial> {
+    const logger = this.loggers.create("CredentialOAuth2MaterialReader");
+    const instance = await this.credentialStore.getInstance(instanceId);
+    if (!instance) {
+      throw new Error(`CredentialOAuth2MaterialReader: credential instance "${instanceId}" not found`);
+    }
+    let refreshed: OAuthMaterial;
+    try {
+      refreshed = await this.oauthFlowExecutor.refresh({ typeId: instance.typeId, instanceId, material: current });
+    } catch (error) {
+      logger.warn(
+        `CredentialOAuth2MaterialReader: token refresh failed for instance "${instanceId}" — returning stale material`,
+        error instanceof Error ? error : undefined,
+      );
+      return current;
+    }
+    const reEncrypted = this.credentialSecretCipher.encrypt({
+      accessToken: refreshed.accessToken,
+      refreshToken: refreshed.refreshToken ?? null,
+      expiresAt: refreshed.expiresAt ?? null,
+      grantedScopes: refreshed.grantedScopes.join(" "),
+    });
+    await this.credentialStore.saveOAuth2Material({
+      instanceId,
+      encryptedJson: reEncrypted.encryptedJson,
+      encryptionKeyId: reEncrypted.encryptionKeyId,
+      schemaVersion: reEncrypted.schemaVersion,
+      metadata: {
+        providerId: encrypted.providerId,
+        connectedEmail: encrypted.connectedEmail,
+        connectedAt: encrypted.connectedAt,
+        scopes: [...refreshed.grantedScopes],
+        updatedAt: this.clock.now().toISOString(),
+      },
+    });
+    logger.info(`CredentialOAuth2MaterialReader: refreshed token for instance "${instanceId}"`);
+    return refreshed;
+  }
+
+  private decrypt(record: CredentialOAuth2MaterialRecord): OAuthMaterial {
+    const json = this.credentialSecretCipher.decrypt(record) as {
+      accessToken?: unknown;
+      refreshToken?: unknown;
+      expiresAt?: unknown;
+      grantedScopes?: unknown;
+    };
+    return {
+      accessToken: typeof json.accessToken === "string" ? json.accessToken : "",
+      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)
+          : [],
+    };
+  }
+}

package/src/credentials/InternalCredentialsListRegistrar.ts

@@ -0,0 +1,48 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import { ApplicationTokens } from "../applicationTokens";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+
+/**
+ * Registers GET /internal/credentials — HMAC-verified endpoint that returns the status
+ * list of credential instances (no token material). Used by the concierge (Story 5) to
+ * inspect what credentials are connected.
+ */
+@injectable()
+export class InternalCredentialsListRegistrar implements InternalHonoApiRouteRegistrar {
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+  ) {}
+
+  register(app: Hono): void {
+    app.get("/internal/credentials", this.hmacMiddleware.handle(), async (c) => {
+      const instances = await this.credentialStore.listInstances();
+      const result = await Promise.all(
+        instances.map(async (instance) => {
+          const oauth2Material = await this.credentialStore.getOAuth2Material(instance.instanceId);
+          return {
+            instanceId: instance.instanceId,
+            typeId: instance.typeId,
+            displayName: instance.displayName,
+            setupStatus: instance.setupStatus,
+            createdAt: instance.createdAt,
+            updatedAt: instance.updatedAt,
+            oauth2: oauth2Material
+              ? {
+                  providerId: oauth2Material.providerId,
+                  connectedEmail: oauth2Material.connectedEmail,
+                  connectedAt: oauth2Material.connectedAt,
+                  scopes: oauth2Material.scopes,
+                  updatedAt: oauth2Material.updatedAt,
+                }
+              : null,
+          };
+        }),
+      );
+      return c.json(result);
+    });
+  }
+}

package/src/credentials/InternalCredentialsPushRegistrar.ts

@@ -0,0 +1,125 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import type { Logger, LoggerFactory } from "../application/logging/Logger";
+import { ApplicationTokens } from "../applicationTokens";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+import { CredentialSecretCipher } from "../domain/credentials/CredentialSecretCipher";
+import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+import { CredentialInstanceService, CredentialTestService } from "../domain/credentials/CredentialServices";
+
+/**
+ * Body shape pushed from the control-plane OAuth broker after a successful
+ * authorization code exchange. Defined per docs/pairing-protocol.md § Token Push.
+ */
+type CredentialPushBody = Readonly<{
+  credentialInstanceId: string;
+  accessToken: string;
+  refreshToken?: string | null;
+  expiresAt: number;
+  scopesGranted: ReadonlyArray<string>;
+}>;
+
+/**
+ * Registers POST /internal/credentials/push — HMAC-verified endpoint that receives
+ * OAuth tokens from the control-plane broker and writes them to the local credential store.
+ *
+ * If `refreshToken` is null/undefined the existing one is preserved (per Story 3 open question 5).
+ */
+@injectable()
+export class InternalCredentialsPushRegistrar implements InternalHonoApiRouteRegistrar {
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+    @inject(CredentialSecretCipher) private readonly cipher: CredentialSecretCipher,
+    @inject(CredentialInstanceService) private readonly credentialInstanceService: CredentialInstanceService,
+    @inject(CredentialTestService) private readonly credentialTestService: CredentialTestService,
+    @inject(ApplicationTokens.LoggerFactory) loggerFactory: LoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("InternalCredentialsPushRegistrar");
+  }
+
+  register(app: Hono): void {
+    app.post("/internal/credentials/push", this.hmacMiddleware.handle(), async (c) => {
+      try {
+        const rawBody = c.get("body" as never) as string | undefined;
+        const body: CredentialPushBody = rawBody ? JSON.parse(rawBody) : await c.req.json();
+
+        if (!body.credentialInstanceId || typeof body.credentialInstanceId !== "string") {
+          return c.json({ error: "credentialInstanceId is required" }, 400);
+        }
+        if (!body.accessToken || typeof body.accessToken !== "string") {
+          return c.json({ error: "accessToken is required" }, 400);
+        }
+
+        const nowIso = new Date().toISOString();
+        const expiryIso =
+          typeof body.expiresAt === "number" ? new Date(body.expiresAt * 1000).toISOString() : undefined;
+
+        // Merge: if the push omits refreshToken, preserve the existing one.
+        const existingMaterial = await this.credentialStore.getOAuth2Material(body.credentialInstanceId);
+        const existingDecrypted = existingMaterial ? this.cipher.decrypt(existingMaterial) : undefined;
+        const refreshToken =
+          body.refreshToken !== undefined && body.refreshToken !== null
+            ? body.refreshToken
+            : (existingDecrypted?.refresh_token as string | undefined);
+
+        const tokenMaterial = Object.freeze({
+          access_token: body.accessToken,
+          refresh_token: refreshToken,
+          expiry: expiryIso,
+          scope: body.scopesGranted.join(" "),
+        });
+
+        const encrypted = this.cipher.encrypt(tokenMaterial);
+
+        await this.credentialStore.saveOAuth2Material({
+          instanceId: body.credentialInstanceId,
+          encryptedJson: encrypted.encryptedJson,
+          encryptionKeyId: encrypted.encryptionKeyId,
+          schemaVersion: encrypted.schemaVersion,
+          metadata: {
+            providerId: body.credentialInstanceId,
+            connectedAt: nowIso,
+            scopes: [...body.scopesGranted],
+            updatedAt: nowIso,
+          },
+        });
+
+        // Attempt to mark the credential instance as ready if it exists.
+        // Not a hard requirement — broker may push before the instance is created locally.
+        try {
+          await this.credentialInstanceService.markOAuth2Connected(body.credentialInstanceId, nowIso);
+        } catch (markError) {
+          this.logger.warn(
+            "markOAuth2Connected failed (instance may not exist locally yet)",
+            markError instanceof Error ? markError : undefined,
+          );
+        }
+
+        this.logger.info(`Credential push applied for instance ${body.credentialInstanceId}`);
+
+        // Auto-test the credential so the UI shows a real health badge
+        // (healthy / failing) instead of "untested". For the broker type
+        // this just validates the token material we just persisted, so it
+        // never makes an outbound call to the provider. Soft-fails — a bad
+        // test result shouldn't fail the push that already succeeded.
+        try {
+          await this.credentialTestService.test(body.credentialInstanceId);
+        } catch (testError) {
+          this.logger.warn(
+            `Credential auto-test failed for instance ${body.credentialInstanceId}`,
+            testError instanceof Error ? testError : undefined,
+          );
+        }
+
+        return c.json({ ok: true });
+      } catch (error) {
+        this.logger.error("Credential push handler error", error instanceof Error ? error : undefined);
+        return c.json({ error: "Internal server error" }, 500);
+      }
+    });
+  }
+}