@opengeni/api-router 0.11.2 → 0.12.0

package/src/app.ts

@@ -6,10 +6,13 @@ import {
 } from "@opengeni/config";
 import {
   ClientConfig,
+  ErrorEnvelope,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   resolveWorkspaceMemoryEnabled,
   type AccessGrant,
+  type ErrorCode,
 } from "@opengeni/contracts";
 import {
   createDocumentServices,
@@ -24,6 +27,7 @@ import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { cors } from "hono/cors";
 import { HTTPException } from "hono/http-exception";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
 import type { ApiRouteDeps, AppDependencies } from "@opengeni/core";
 import {
   hasPermission,
@@ -59,6 +63,7 @@ import { registerScheduledTaskRoutes } from "./routes/scheduled-tasks";
 import { registerSessionRoutes } from "./routes/sessions";
 import { registerSocialRoutes } from "./routes/social";
 import { registerWorkspaceRoutes } from "./routes/workspaces";
+import { registerWorkspaceInstructionPolicyRoutes } from "./routes/workspace-instruction-policies";
 import { projectClientModel } from "./model-catalog";
 
 export type {
@@ -83,6 +88,7 @@ export { workflowIdForSession } from "@opengeni/core";
 export { replaySessionEvents, sseSessionStream, sseWorkspaceControlStream } from "./http/sse";
 
 export const API_MAX_REQUEST_BODY_BYTES = 8 * 1024 * 1024;
+const API_PUBLIC_ERROR_MESSAGE_MAX_BYTES = 512;
 
 export function createApp(deps: AppDependencies): Hono {
   const managedAuth = deps.managedAuth ?? createManagedAuth(deps.settings, deps.db);
@@ -148,6 +154,15 @@ export function createApp(deps: AppDependencies): Hono {
     resumeBoxById,
   };
   const app = new Hono();
+  const correlationIds = new WeakMap<Request, string>();
+
+  app.use("*", async (c, next) => {
+    const correlationId =
+      boundedCorrelationId(c.req.header(OPENGENI_CORRELATION_HEADER)) ?? crypto.randomUUID();
+    correlationIds.set(c.req.raw, correlationId);
+    c.header(OPENGENI_CORRELATION_HEADER, correlationId);
+    await next();
+  });
 
   app.use(
     "*",
@@ -159,9 +174,10 @@ export function createApp(deps: AppDependencies): Hono {
         "Content-Type",
         "X-OpenGeni-Access-Key",
         "X-OpenGeni-Api-Contract",
+        "X-OpenGeni-Correlation-Id",
         "X-OpenGeni-Subject",
       ],
-      exposeHeaders: ["X-OpenGeni-Api-Contract"],
+      exposeHeaders: ["X-OpenGeni-Api-Contract", "X-OpenGeni-Correlation-Id"],
       origin: (origin) => {
         if (!origin) {
           return null;
@@ -183,6 +199,7 @@ export function createApp(deps: AppDependencies): Hono {
   app.use("*", async (c, next) => {
     const url = new URL(c.req.url);
     const route = routeLabel(url.pathname);
+    const correlationId = correlationIds.get(c.req.raw) ?? crypto.randomUUID();
     const start = performance.now();
     const span = observability.startSpan(`HTTP ${c.req.method} ${route}`, {
       "http.request.method": c.req.method,
@@ -212,9 +229,11 @@ export function createApp(deps: AppDependencies): Hono {
         durationMs: Math.round(durationSeconds * 1000),
         traceId: span.traceId,
         spanId: span.spanId,
+        correlationId,
       });
     } catch (error) {
       const status = httpStatusForError(error);
+      const errorCode = errorCodeForStatus(status);
       const durationSeconds = (performance.now() - start) / 1000;
       observability.recordHttpRequest({
         method: c.req.method,
@@ -222,6 +241,11 @@ export function createApp(deps: AppDependencies): Hono {
         status,
         durationSeconds,
       });
+      observability.incrementCounter({
+        name: "opengeni_http_errors_total",
+        help: "Total OpenGeni HTTP request failures by bounded route, status, and stable code.",
+        labels: { route, status: String(status), code: errorCode },
+      });
       span.end({
         attributes: {
           "http.response.status_code": status,
@@ -236,7 +260,9 @@ export function createApp(deps: AppDependencies): Hono {
         durationMs: Math.round(durationSeconds * 1000),
         traceId: span.traceId,
         spanId: span.spanId,
-        error: error instanceof Error ? error.message : String(error),
+        correlationId,
+        errorCode,
+        errorClass: error instanceof Error ? error.name : "NonErrorThrown",
       });
       throw error;
     }
@@ -282,6 +308,12 @@ export function createApp(deps: AppDependencies): Hono {
     return c.json(result, result.ok ? 200 : 503);
   });
 
+  app.get("/traffic-readyz", async (c) => {
+    const { db } = readinessChecks(deps);
+    const result = await runReadinessChecks({ db }, 2_000);
+    return c.json(result, result.ok ? 200 : 503);
+  });
+
   app.get("/metrics", async (c) =>
     c.text(await observability.prometheusMetrics(), 200, {
       "content-type": "text/plain; version=0.0.4; charset=utf-8",
@@ -392,6 +424,7 @@ export function createApp(deps: AppDependencies): Hono {
   registerGitHubRoutes(app, routeDeps);
   registerInstallRoutes(app, routeDeps);
   registerWorkspaceRoutes(app, routeDeps);
+  registerWorkspaceInstructionPolicyRoutes(app, routeDeps);
   registerSocialRoutes(app, routeDeps);
   registerConnectionRoutes(app, routeDeps);
   registerCapabilityRoutes(app, routeDeps);
@@ -405,6 +438,43 @@ export function createApp(deps: AppDependencies): Hono {
   registerScheduledTaskRoutes(app, routeDeps);
   registerCodexRoutes(app, routeDeps);
 
+  app.notFound((c) => {
+    if (!new URL(c.req.url).pathname.startsWith("/v1/")) return c.text("Not Found", 404);
+    const requestId = correlationIds.get(c.req.raw) ?? crypto.randomUUID();
+    return c.json(
+      ErrorEnvelope.parse({
+        error: {
+          status: 404,
+          code: "not_found",
+          message: "Resource not found.",
+          retryable: false,
+          requestId,
+        },
+      }),
+      404,
+    );
+  });
+
+  app.onError((error, c) => {
+    const status = httpStatusForError(error);
+    const code = errorCodeForStatus(status);
+    const requestId = correlationIds.get(c.req.raw) ?? crypto.randomUUID();
+    c.header(OPENGENI_CORRELATION_HEADER, requestId);
+    if (new URL(c.req.url).pathname.startsWith("/v1/")) {
+      c.header(OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION);
+    }
+    const envelope = ErrorEnvelope.parse({
+      error: {
+        status,
+        code,
+        message: publicErrorMessage(error, status),
+        retryable: retryableHttpStatus(status),
+        requestId,
+      },
+    });
+    return c.json(envelope, status as ContentfulStatusCode);
+  });
+
   return app;
 }
 
@@ -467,8 +537,54 @@ export function httpStatusForError(error: unknown): number {
   return 500;
 }
 
+export function errorCodeForStatus(status: number): ErrorCode {
+  if (status === 401) return "unauthenticated";
+  if (status === 403) return "forbidden";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status === 413 || status === 422 || status === 400) return "validation_failed";
+  if (status === 429) return "limit_exceeded";
+  if (status === 502 || status === 503 || status === 504) return "upstream_unavailable";
+  return "internal_error";
+}
+
+function retryableHttpStatus(status: number): boolean {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function publicErrorMessage(error: unknown, status: number): string {
+  if (status === 502 || status === 503 || status === 504) {
+    return "OpenGeni is temporarily unavailable — retry.";
+  }
+  if (status >= 500) {
+    return "OpenGeni could not complete the request.";
+  }
+  if (error instanceof HTTPException) {
+    return boundedPublicMessage(error.message) ?? "Request failed.";
+  }
+  if (error instanceof McpPayloadTooLargeError) {
+    return "Request payload is too large.";
+  }
+  return "Request failed.";
+}
+
+function boundedPublicMessage(value: string): string | null {
+  const normalized = value.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+  if (!normalized) return null;
+  const bytes = new TextEncoder().encode(normalized);
+  if (bytes.byteLength <= API_PUBLIC_ERROR_MESSAGE_MAX_BYTES) return normalized;
+  return new TextDecoder().decode(bytes.slice(0, API_PUBLIC_ERROR_MESSAGE_MAX_BYTES)).trim();
+}
+
+function boundedCorrelationId(value: string | undefined): string | null {
+  if (!value || value.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(value)) return null;
+  return value;
+}
+
 type ReadinessCheckName = "db" | "nats" | "temporal";
-type ReadinessChecks = Record<ReadinessCheckName, () => Promise<void> | void>;
+type ReadinessCheck = () => Promise<void> | void;
+type ReadinessChecks = Record<ReadinessCheckName, ReadinessCheck>;
+type ReadinessCheckResult = { ok: boolean; error?: string };
 
 function readinessChecks(deps: AppDependencies): ReadinessChecks {
   return {
@@ -493,35 +609,30 @@ function readinessChecks(deps: AppDependencies): ReadinessChecks {
   };
 }
 
-async function runReadinessChecks(
-  checks: ReadinessChecks,
+async function runReadinessChecks<const Checks extends Readonly<Record<string, ReadinessCheck>>>(
+  checks: Checks,
   timeoutMs: number,
 ): Promise<{
   ok: boolean;
-  checks: Record<ReadinessCheckName, { ok: boolean; error?: string }>;
+  checks: { [Name in keyof Checks]: ReadinessCheckResult };
 }> {
   const entries = await Promise.all(
-    (Object.entries(checks) as Array<[ReadinessCheckName, () => Promise<void> | void]>).map(
-      async ([name, check]) => {
-        try {
-          await withTimeout(Promise.resolve().then(check), timeoutMs);
-          return [name, { ok: true }] as const;
-        } catch (error) {
-          return [
-            name,
-            {
-              ok: false,
-              error: error instanceof Error ? error.message : String(error),
-            },
-          ] as const;
-        }
-      },
-    ),
+    (Object.entries(checks) as Array<[keyof Checks, ReadinessCheck]>).map(async ([name, check]) => {
+      try {
+        await withTimeout(Promise.resolve().then(check), timeoutMs);
+        return [name, { ok: true }] as const;
+      } catch (error) {
+        return [
+          name,
+          {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        ] as const;
+      }
+    }),
   );
-  const result = Object.fromEntries(entries) as Record<
-    ReadinessCheckName,
-    { ok: boolean; error?: string }
-  >;
+  const result = Object.fromEntries(entries) as { [Name in keyof Checks]: ReadinessCheckResult };
   return {
     ok: Object.values(result).every((check) => check.ok),
     checks: result,
@@ -550,6 +661,7 @@ async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T
 const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
   { pattern: /^\/healthz$/, label: "/healthz" },
   { pattern: /^\/readyz$/, label: "/readyz" },
+  { pattern: /^\/traffic-readyz$/, label: "/traffic-readyz" },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/codex\/connect\/start$/,
     label: "/v1/workspaces/:workspaceId/codex/connect/start",
@@ -844,6 +956,10 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/workspaces\/[^/]+\/connections\/oauth\/start$/,
     label: "/v1/workspaces/:workspaceId/connections/oauth/start",
   },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/connections\/slack-bot$/,
+    label: "/v1/workspaces/:workspaceId/connections/slack-bot",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/connections\/[^/]+$/,
     label: "/v1/workspaces/:workspaceId/connections/:connectionId",

package/src/github-access.ts

@@ -1,6 +1,13 @@
-import type { GitHubInstallationBinding, GitHubRepository } from "@opengeni/contracts";
-import { listGitHubInstallationAccessForWorkspace } from "@opengeni/db";
-import { listGitHubAppRepositories } from "@opengeni/github";
+import type {
+  GitHubBindingStatus,
+  GitHubInstallationBinding,
+  GitHubRepository,
+} from "@opengeni/contracts";
+import {
+  hasAuditableGitHubInstallationAuthority,
+  listGitHubInstallationAccessForWorkspace,
+} from "@opengeni/db";
+import { listGitHubAppInstallationSummaries, listGitHubAppRepositories } from "@opengeni/github";
 import type { ApiRouteDeps } from "@opengeni/core";
 
 export async function listWorkspaceGitHubInstallationBindings(
@@ -8,10 +15,53 @@ export async function listWorkspaceGitHubInstallationBindings(
   workspaceId: string,
 ): Promise<GitHubInstallationBinding[]> {
   const installations = await listGitHubInstallationAccessForWorkspace(deps.db, workspaceId);
+  if (installations.length === 0) {
+    return [];
+  }
+  let liveById = new Map<number, LiveGitHubInstallation | null>();
+  let lifecycleVerified = false;
+  try {
+    if (deps.githubAppApi?.getInstallation) {
+      liveById = new Map(
+        await Promise.all(
+          installations.map(
+            async (installation) =>
+              [
+                installation.installationId,
+                await deps.githubAppApi!.getInstallation!({
+                  installationId: installation.installationId,
+                }),
+              ] as const,
+          ),
+        ),
+      );
+      lifecycleVerified = true;
+    } else if (!deps.githubAppApi) {
+      liveById = new Map(
+        (await listGitHubAppInstallationSummaries(deps.settings)).map((installation) => [
+          installation.installationId,
+          installation,
+        ]),
+      );
+      lifecycleVerified = true;
+    }
+  } catch {
+    // A provider outage cannot make a stored row healthy. Preserve the row for
+    // audit/unlink but project it as unverified and keep workspace status
+    // unbound until GitHub can be checked again.
+    liveById = new Map();
+  }
   return installations.map((installation) => ({
     installationId: installation.installationId,
+    githubAccountId: installation.githubAccountId,
     accountLogin: installation.accountLogin,
     accountType: installation.accountType,
+    lifecycle: githubInstallationBindingLifecycle(
+      installation,
+      liveById,
+      installation.installationId,
+      lifecycleVerified,
+    ),
     repositoryScope: installation.repositoryScope,
     repositoryCount: installation.repositoryIds.length,
     createdAt: installation.createdAt,
@@ -19,28 +69,86 @@ export async function listWorkspaceGitHubInstallationBindings(
   }));
 }
 
+export function githubBindingStatus(
+  configured: boolean,
+  installations: GitHubInstallationBinding[],
+): GitHubBindingStatus {
+  if (!configured) {
+    return "disabled";
+  }
+  return installations.some((installation) => installation.lifecycle === "active")
+    ? "bound"
+    : "unbound";
+}
+
+export type LiveGitHubInstallation = {
+  installationId: number;
+  accountId: number;
+  suspended: boolean;
+};
+
+export function githubInstallationBindingLifecycle(
+  stored: Awaited<ReturnType<typeof listGitHubInstallationAccessForWorkspace>>[number],
+  liveById: Map<number, LiveGitHubInstallation | null>,
+  installationId: number,
+  lifecycleVerified: boolean,
+): GitHubInstallationBinding["lifecycle"] {
+  if (!hasAuditableGitHubInstallationAuthority(stored)) {
+    return "unverified";
+  }
+  if (!lifecycleVerified) {
+    return "unverified";
+  }
+  if (!liveById.has(installationId)) {
+    return "deleted";
+  }
+  const live = liveById.get(installationId);
+  if (!live) {
+    return "deleted";
+  }
+  if (live.suspended) {
+    return "suspended";
+  }
+  if (live.installationId !== installationId || stored.githubAccountId !== live.accountId) {
+    return "unverified";
+  }
+  return "active";
+}
+
 export async function listWorkspaceGitHubRepositories(
   deps: ApiRouteDeps,
   workspaceId: string,
 ): Promise<GitHubRepository[]> {
+  const bindings = await listWorkspaceGitHubInstallationBindings(deps, workspaceId);
+  const activeInstallationIds = new Set(
+    bindings
+      .filter((installation) => installation.lifecycle === "active")
+      .map((installation) => installation.installationId),
+  );
+  if (activeInstallationIds.size === 0) {
+    return [];
+  }
   const access = await listGitHubInstallationAccessForWorkspace(deps.db, workspaceId);
-  if (access.length === 0) {
+  const authorizedAccess = access.filter(
+    (installation) =>
+      activeInstallationIds.has(installation.installationId) &&
+      hasAuditableGitHubInstallationAuthority(installation),
+  );
+  if (authorizedAccess.length === 0) {
     return [];
   }
-  const installationIds = access.map((installation) => installation.installationId);
+  const installationIds = authorizedAccess.map((installation) => installation.installationId);
   const repositories = deps.githubAppApi?.listRepositories
     ? await deps.githubAppApi.listRepositories({ installationIds })
     : await listGitHubAppRepositories(deps.settings, { installationIds });
   const accessByInstallation = new Map(
-    access.map((installation) => [installation.installationId, installation]),
+    authorizedAccess.map((installation) => [installation.installationId, installation]),
   );
   return repositories.filter((repository) => {
     const installation = accessByInstallation.get(repository.installationId);
     if (!installation) {
       return false;
     }
-    return (
-      installation.repositoryScope === "all" || installation.repositoryIds.includes(repository.id)
-    );
+    return installation.repositoryIds.includes(repository.id);
   });
 }

package/src/github-browser-flow.ts

@@ -4,10 +4,10 @@ import { hasPermission } from "@opengeni/core";
 import type { GitHubSignedStatePayload } from "@opengeni/github";
 
 /**
- * Dormant compatibility helpers for tests and decoding already-issued browser
- * handoffs. No production route imports this module. Its signed claims preserve
- * a prior OpenGeni grant across a redirect; they do not prove that GitHub
- * authorizes the human to install, configure, or bind an App installation.
+ * Bounded configured-token browser handoff. These signed claims preserve only
+ * the exact OpenGeni github:manage grant across GitHub redirects; the callback
+ * independently proves current GitHub personal/organization ownership. This
+ * state must never be interpreted as GitHub installation authority.
  */
 export const githubBrowserGrantMaxAgeSeconds = 10 * 60;
 

package/src/http/auth.ts

@@ -59,9 +59,8 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (path.startsWith("/v1/catalog-assets/")) {
     return true;
   }
-  // Compatibility entry for already-issued GitHub install/link URLs. It stays
-  // public like the callbacks above, verifies signed workspace-bound state,
-  // and then terminates with 410 while new installation binding is disabled.
+  // The GitHub owner-consent entry remains public like the callbacks above; it
+  // verifies fresh signed workspace-bound state before redirecting to GitHub.
   if (githubConnectPathPattern.test(path)) {
     return true;
   }
@@ -78,7 +77,10 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (installExactPaths.has(path) || isInstallRedirectPath(path)) {
     return true;
   }
-  if (settings.authAllowHealth && (path === "/healthz" || path === "/readyz")) {
+  if (
+    settings.authAllowHealth &&
+    (path === "/healthz" || path === "/readyz" || path === "/traffic-readyz")
+  ) {
     return true;
   }
   if (settings.authAllowMetrics && path === "/metrics") {

package/src/index.ts

@@ -12,7 +12,13 @@ import type {
   ScheduledTaskOverlapPolicy,
   ScheduledTaskScheduleSpec,
 } from "@opengeni/contracts";
-import { createDb, markSessionWorkflowWakeDelivered, type Database } from "@opengeni/db";
+import {
+  assertRuntimeDatabasePosture,
+  createDb,
+  markSessionWorkflowWakeDelivered,
+  runtimeDatabaseReadyCheck,
+  type Database,
+} from "@opengeni/db";
 import { createNatsEventBus, type ResponderConnection } from "@opengeni/events";
 import { createObservability, logStartupDependencyRetry } from "@opengeni/observability";
 import { SESSION_WORKFLOW_WAKE_DISPATCHER_SCHEDULE_ID } from "@opengeni/core";
@@ -253,11 +259,21 @@ export async function startApi() {
   const retryOptions = startupRetryOptions(settings);
   const onRetry = (event: Parameters<typeof logStartupDependencyRetry>[1]) =>
     logStartupDependencyRetry(observability, event);
+  const databasePosture = {
+    rlsStrategy: settings.rlsStrategy,
+    expectedRole: settings.runtimeDatabaseRole,
+    targetSchema: settings.dbSchema.trim() || "public",
+  } as const;
   // The PRIVILEGED control-plane NATS login (M-AUTH): when the server runs with
   // auth_callout, api/worker authenticate as a static account user permitted to
   // request `agent.*.rpc`. Null in local dev (anonymous connect — the bus default).
   const controlPlaneAuth = resolveNatsControlPlaneAuth(settings);
   try {
+    await retryStartupDependency(
+      "PostgreSQL runtime posture",
+      () => assertRuntimeDatabasePosture(dbClient.db, databasePosture),
+      { ...retryOptions, onRetry },
+    );
     bus = await retryStartupDependency(
       "NATS",
       () =>
@@ -296,6 +312,9 @@ export async function startApi() {
     workflowClient: workflowClient.client,
     documentIndexer: workflowClient.documentIndexer,
     observability,
+    readinessChecks: {
+      db: runtimeDatabaseReadyCheck(dbClient.db, databasePosture),
+    },
   });
   const server = Bun.serve({
     hostname: settings.apiHost,