@opengeni/api-router 0.11.1 → 0.11.8

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;
   }

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,

package/src/mcp/documents.ts

@@ -2,6 +2,7 @@ import {
   getDocumentChunk,
   listDocumentBases,
   searchDocuments,
+  type DocumentAccessFilter,
   type DocumentServices,
 } from "@opengeni/documents";
 import { createKnowledgeMemory, listKnowledgeMemories, type Database } from "@opengeni/db";
@@ -44,12 +45,23 @@ export function buildDocumentsMcpServer(
   accountId: string,
   workspaceId: string,
   documentServices: DocumentServices,
-  options: { createdBySessionId?: string | undefined } = {},
+  options: {
+    createdBySessionId?: string | undefined;
+    /** The human subject whose agent is making this retrieval request. */
+    viewerSubjectId?: string | undefined;
+  } = {},
 ): McpServer {
   const server = new McpServer({
     name: "opengeni-documents",
     version: "1.0.0",
   });
+  // This server is the agent retrieval surface. Agent-disabled documents are
+  // never reachable. Workspace-visible documents are shared; private
+  // documents are available only to the creating subject's agent.
+  const agentAccess: DocumentAccessFilter = {
+    agentOnly: true,
+    ...(options.viewerSubjectId ? { viewerSubjectId: options.viewerSubjectId } : {}),
+  };
 
   server.registerTool(
     "list_document_bases",
@@ -68,7 +80,7 @@ export function buildDocumentsMcpServer(
       description: "Search indexed documents with hybrid, vector, or keyword retrieval.",
       inputSchema: SearchInputSchema,
     },
-    async (input) => searchContent(db, workspaceId, documentServices, input),
+    async (input) => searchContent(db, workspaceId, documentServices, input, agentAccess),
   );
 
   server.registerTool(
@@ -78,7 +90,7 @@ export function buildDocumentsMcpServer(
         "Search company knowledge sources with optional base, source-kind, ACL, and retrieval-mode filters.",
       inputSchema: SearchInputSchema,
     },
-    async (input) => searchContent(db, workspaceId, documentServices, input),
+    async (input) => searchContent(db, workspaceId, documentServices, input, agentAccess),
   );
 
   server.registerTool(
@@ -90,7 +102,7 @@ export function buildDocumentsMcpServer(
       },
     },
     async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, workspaceId, chunkId);
+      const found = await getDocumentChunk(db, workspaceId, chunkId, agentAccess);
       return {
         content: [
           { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` },
@@ -109,7 +121,7 @@ export function buildDocumentsMcpServer(
       },
     },
     async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, workspaceId, chunkId);
+      const found = await getDocumentChunk(db, workspaceId, chunkId, agentAccess);
       return {
         content: [
           { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` },
@@ -214,6 +226,7 @@ async function searchContent(
       | undefined;
     aclTags?: string[] | undefined;
   },
+  access: DocumentAccessFilter,
 ) {
   return {
     content: [
@@ -230,6 +243,7 @@ async function searchContent(
               ...(input.mode ? { mode: input.mode } : {}),
               ...(input.sourceKinds ? { sourceKinds: input.sourceKinds } : {}),
               ...(input.aclTags ? { aclTags: input.aclTags } : {}),
+              access,
             },
             documentServices,
           ),

package/src/mcp/server.ts

@@ -68,6 +68,7 @@ import {
 } from "@opengeni/db";
 import { appendAndPublishEvents, publishDurableSessionEvents } from "@opengeni/events";
 import {
+  createSignedState,
   createGitHubAppInstallationToken,
   GitHubAppConfigurationError,
   githubAppMissingSettings,
@@ -82,7 +83,12 @@ import {
 } from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { listWorkspaceGitHubRepositories } from "../github-access";
+import {
+  githubBindingStatus,
+  listWorkspaceGitHubInstallationBindings,
+  listWorkspaceGitHubRepositories,
+} from "../github-access";
+import { githubBrowserBaseUrl, githubBrowserGrantClaims } from "../github-browser-flow";
 import {
   promoteVerifiedDefinitionEditChangeForApi,
   proposeRigChangeForApi,
@@ -140,9 +146,8 @@ import type { ToolspaceMcpSurface } from "./toolspace";
 import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../sandbox/viewer";
 
 export type McpServerOptions = {
-  // Origin of the HTTP request that reached the MCP route. Retained in the
-  // options ABI for browser-oriented tools; github_connect_link does not use
-  // it or mint state while new installation binding is disabled.
+  // Origin of the HTTP request that reached the MCP route. Browser-oriented
+  // tools use it only when no configured public base URL is available.
   requestOrigin?: string | null;
   toolspace?: ToolspaceMcpSurface | null;
   workspaceMemoryEnabled?: boolean | undefined;
@@ -229,7 +234,7 @@ export function buildOpenGeniMcpServer(
   registerWorkspaceOrchestrationTools(server, deps, grant, can, sessionId, toolspaceMode, json);
   registerVariableSetTools(server, deps, grant, can, json);
   if (can("github:use")) {
-    registerGitHubConnectTool(server, deps, json);
+    registerGitHubConnectTool(server, deps, grant, options, json);
     // TOKEN-BROKER (B1): the agent-refreshable git token. Session-scoped (keys off the
     // worker-signed sessionId claim so it mints for THIS session's repos), gated on
     // the same github:use capability as github_connect_link.
@@ -2031,15 +2036,18 @@ function registerVariableSetTools(
   }
 }
 
-// The tool remains registered for compatibility, but every new installation
-// binding entry point is fail-closed until a provider-supported authority
-// proof stronger than installation visibility is available.
-function registerGitHubConnectTool(server: McpServer, deps: ApiRouteDeps, json: JsonResult): void {
+function registerGitHubConnectTool(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  options: McpServerOptions,
+  json: JsonResult,
+): void {
   server.registerTool(
     "github_connect_link",
     {
       description:
-        "Report GitHub App connection availability. New installation binding is disabled until GitHub installation authority can be proven, so installUrl and linkUrl are null.",
+        "Report truthful GitHub App workspace binding status and, for a human grant with github:manage, return the fresh GitHub owner-consent link. Server App configuration alone is never reported as a usable binding.",
       inputSchema: {},
     },
     async () => {
@@ -2049,17 +2057,35 @@ function registerGitHubConnectTool(server: McpServer, deps: ApiRouteDeps, json:
       if (missing.length > 0 || !slug) {
         return json({
           configured: false,
+          status: "disabled",
           appSlug: slug,
           installUrl: null,
           linkUrl: null,
           missing,
         });
       }
+      const installations = await listWorkspaceGitHubInstallationBindings(deps, grant.workspaceId);
+      const status = githubBindingStatus(true, installations);
+      const baseUrl = githubBrowserBaseUrl(settings, options.requestOrigin);
+      const state =
+        baseUrl && hasPermission(grant.permissions, "github:manage")
+          ? createSignedState(deps.githubStateSecret, {
+              accountId: grant.accountId,
+              workspaceId: grant.workspaceId,
+              intent: "installation_authority",
+              ...githubBrowserGrantClaims(settings, grant),
+            })
+          : null;
+      const connectUrl = state
+        ? `${baseUrl}/v1/workspaces/${grant.workspaceId}/github/connect?state=${encodeURIComponent(state)}`
+        : null;
       return json({
         configured: true,
+        status,
         appSlug: slug,
-        installUrl: null,
-        linkUrl: null,
+        installUrl: connectUrl,
+        linkUrl: connectUrl,
+        installations,
         missing: [],
       });
     },