@opengeni/api-router 0.11.2 → 0.12.0

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,
@@ -138,11 +144,14 @@ import {
 } from "./session-view";
 import type { ToolspaceMcpSurface } from "./toolspace";
 import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../sandbox/viewer";
+import {
+  createOpenGeniSlackBotClient,
+  resolveSlackBotConnectionForTool,
+} from "../integrations/slack-bot";
 
 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;
@@ -214,6 +223,7 @@ export function buildOpenGeniMcpServer(
   }
   if (!toolspaceMode) {
     registerRigTools(server, deps, grant, can, sessionId, json);
+    registerSlackBotTools(server, deps, grant, sessionId, json);
   }
 
   // Orchestration, variableSet, and GitHub status/token tools are permission-gated
@@ -229,7 +239,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.
@@ -647,6 +657,121 @@ export function buildOpenGeniMcpServer(
   return server;
 }
 
+function registerSlackBotTools(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  sessionId: string | null,
+  json: JsonResult,
+): void {
+  const clientFor = async (connectionId?: string) => {
+    const resolved = await resolveSlackBotConnectionForTool({
+      db: deps.db,
+      grant,
+      sessionId,
+      ...(connectionId ? { requestedConnectionId: connectionId } : {}),
+    });
+    return createOpenGeniSlackBotClient(deps, resolved);
+  };
+
+  server.registerTool(
+    "slack_bot_list_channels",
+    {
+      description:
+        "List public and bot-visible private Slack channels through the workspace-shared OpenGeni bot. isMember identifies channels the bot may read/post in; the bot never joins channels automatically.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        cursor: z4.string().max(1024).optional(),
+        limit: z4.number().int().min(1).max(200).optional(),
+      },
+    },
+    async ({ connectionId, cursor, limit }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).listChannels({
+          ...(cursor ? { cursor } : {}),
+          ...(limit !== undefined ? { limit } : {}),
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "slack_bot_channel_history",
+    {
+      description:
+        "Read Slack channel history as the workspace-shared OpenGeni bot. Public and private channels both require bot membership; invite the bot to private channels first.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        channelId: z4.string().min(1).max(64),
+        cursor: z4.string().max(1024).optional(),
+        limit: z4.number().int().min(1).max(100).optional(),
+      },
+    },
+    async ({ connectionId, channelId, cursor, limit }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).channelHistory({
+          channelId,
+          ...(cursor ? { cursor } : {}),
+          ...(limit !== undefined ? { limit } : {}),
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "slack_bot_list_users",
+    {
+      description: "List Slack workspace users through the workspace-shared OpenGeni bot.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        cursor: z4.string().max(1024).optional(),
+        limit: z4.number().int().min(1).max(200).optional(),
+      },
+    },
+    async ({ connectionId, cursor, limit }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).listUsers({
+          ...(cursor ? { cursor } : {}),
+          ...(limit !== undefined ? { limit } : {}),
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "slack_bot_post_message",
+    {
+      description:
+        "Post as the workspace-shared OpenGeni bot. Pass channelId for a channel where the bot is already a member, or userId to open/post a DM; pass exactly one. Generate one operationId UUID per intended message and reuse that same UUID on every retry.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        operationId: z4.string().uuid(),
+        channelId: z4.string().min(1).max(64).optional(),
+        userId: z4.string().min(1).max(64).optional(),
+        text: z4.string().min(1).max(40_000),
+      },
+    },
+    async ({ connectionId, operationId, channelId, userId, text }) => {
+      if (Boolean(channelId) === Boolean(userId)) {
+        throw new Error("exactly one of channelId or userId is required");
+      }
+      return json(
+        await (
+          await clientFor(connectionId)
+        ).postMessage({
+          operationId,
+          ...(channelId ? { channelId } : {}),
+          ...(userId ? { userId } : {}),
+          text,
+        }),
+      );
+    },
+  );
+}
+
 function registerToolspaceProxyTools(server: McpServer, surface: ToolspaceMcpSurface | null): void {
   if (!surface) {
     return;
@@ -2031,15 +2156,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 +2177,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: [],
       });
     },

package/src/routes/connections.ts

@@ -1,4 +1,5 @@
 import {
+  ConnectOpenGeniSlackBotRequest,
   ConnectionResponse,
   CreateConnectionRequest,
   IntegrationClientMetadata,
@@ -7,12 +8,19 @@ import {
   OAuthStartResponse,
   UpdateConnectionRequest,
 } from "@opengeni/contracts";
-import { requireAccessGrant, requireEnvironmentEncryption } from "@opengeni/core";
+import {
+  hasReservedOpenGeniSlackBotMetadata,
+  isOpenGeniSlackBotConnection,
+  openGeniSlackBotMetadata,
+  requireAccessGrant,
+  requireEnvironmentEncryption,
+} from "@opengeni/core";
 import {
   createConnection,
   encryptEnvironmentValue,
   getConnectionMetadata,
   listConnectionsMetadata,
+  recordAuditEvent,
   revokeConnection,
   updateConnection,
 } from "@opengeni/db";
@@ -25,6 +33,11 @@ import {
   startMcpOAuth,
 } from "../integrations/oauth-client";
 import { canonicalProviderDomain } from "../integrations/provider-domain";
+import { verifyOpenGeniSlackBotCredential } from "../integrations/slack-bot";
+import {
+  OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
+  OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
+} from "@opengeni/contracts";
 
 export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { db, settings, observability } = deps;
@@ -49,6 +62,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
     const payload = CreateConnectionRequest.parse(await c.req.json());
+    assertNotReservedSlackBotMetadata(payload.metadata);
     const key = requireEnvironmentEncryption(settings);
     const subjectId = writableSubjectId(payload.subjectId, grant.subjectId);
     const connection = await createConnection(db, {
@@ -66,6 +80,102 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(ConnectionResponse.parse({ connection }), 201);
   });
 
+  app.post("/v1/workspaces/:workspaceId/connections/slack-bot", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const payload = ConnectOpenGeniSlackBotRequest.parse(await c.req.json());
+    const verified = await verifyOpenGeniSlackBotCredential(
+      payload.token,
+      deps.slackFetch ?? fetch,
+    );
+    const key = requireEnvironmentEncryption(settings);
+    const credentialEncrypted = encryptCredentialBundle(
+      key,
+      slackBotCredentialBundle(payload.token),
+    );
+    const existing = payload.connectionId
+      ? await getConnectionMetadata(db, workspaceId, payload.connectionId, grant.subjectId)
+      : null;
+    if (payload.connectionId && !existing) {
+      throw new HTTPException(404, { message: "connection not found" });
+    }
+    if (existing && !isOpenGeniSlackBotConnection(existing)) {
+      throw new HTTPException(422, {
+        message: "connectionId is not an OpenGeni Slack bot connection",
+      });
+    }
+    const existingMetadata = existing ? openGeniSlackBotMetadata(existing.metadata) : null;
+    if (existingMetadata && existingMetadata.slackTeamId !== verified.metadata.slackTeamId) {
+      throw new HTTPException(409, {
+        message: "a Slack bot connection can only be reinstalled for its original Slack workspace",
+      });
+    }
+    if (
+      existingMetadata &&
+      (existingMetadata.botId !== verified.metadata.botId ||
+        existingMetadata.botUserId !== verified.metadata.botUserId)
+    ) {
+      throw new HTTPException(409, {
+        message:
+          "a different Slack bot requires a new connection and explicit scheduled-task rebinding",
+      });
+    }
+    const verifiedInstallAt = new Date(verified.metadata.verifiedAt);
+    const connection = existing
+      ? await updateConnection(db, {
+          workspaceId,
+          connectionId: existing.id,
+          visibleToSubjectId: grant.subjectId,
+          expectedVersion: existing.version,
+          subjectId: null,
+          providerDomain: "slack.com",
+          kind: "app_install",
+          status: "active",
+          credentialEncrypted,
+          grantedScopes: verified.grantedScopes,
+          expiresAt: null,
+          verifiedInstallAt,
+          verifiedInstallVersion: existing.version + 1,
+          metadata: verified.metadata,
+          updatedBySubjectId: grant.subjectId,
+        })
+      : await createConnection(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: null,
+          providerDomain: "slack.com",
+          kind: "app_install",
+          credentialEncrypted,
+          grantedScopes: verified.grantedScopes,
+          expiresAt: null,
+          verifiedInstallAt,
+          verifiedInstallVersion: 1,
+          metadata: verified.metadata,
+          createdBySubjectId: grant.subjectId,
+        });
+    if (!connection) {
+      throw new HTTPException(409, {
+        message: "Slack bot connection changed during reinstall; retry with the current connection",
+      });
+    }
+    await recordAuditEvent(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      action: existing ? "slack_bot.reinstalled" : "slack_bot.connected",
+      targetType: "connection",
+      targetId: connection.id,
+      metadata: {
+        credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
+        credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
+        connectionId: connection.id,
+        slackTeamId: verified.metadata.slackTeamId,
+        outcome: "succeeded",
+      },
+    });
+    return c.json(ConnectionResponse.parse({ connection }), existing ? 200 : 201);
+  });
+
   app.get("/v1/workspaces/:workspaceId/connections/:connectionId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
@@ -85,6 +195,18 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
     const payload = UpdateConnectionRequest.parse(await c.req.json());
+    assertNotReservedSlackBotMetadata(payload.metadata);
+    const existing = await getConnectionMetadata(
+      db,
+      workspaceId,
+      c.req.param("connectionId"),
+      grant.subjectId,
+    );
+    if (existing && isOpenGeniSlackBotConnection(existing)) {
+      throw new HTTPException(422, {
+        message: "use the dedicated OpenGeni Slack bot reinstall flow to update this connection",
+      });
+    }
     // Status is not a free-form field: revocation goes through DELETE, and the
     // broker owns needs_reauth/error. Reactivating a connection is only
     // meaningful together with a fresh credential bundle — otherwise a PATCH
@@ -144,6 +266,24 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!connection) {
       throw new HTTPException(404, { message: "connection not found" });
     }
+    if (isOpenGeniSlackBotConnection(connection)) {
+      const metadata = openGeniSlackBotMetadata(connection.metadata)!;
+      await recordAuditEvent(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        action: "slack_bot.disconnected",
+        targetType: "connection",
+        targetId: connection.id,
+        metadata: {
+          credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
+          credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
+          connectionId: connection.id,
+          slackTeamId: metadata.slackTeamId,
+          outcome: "succeeded",
+        },
+      });
+    }
     return c.json(ConnectionResponse.parse({ connection }));
   });
 
@@ -200,6 +340,14 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 }
 
+function assertNotReservedSlackBotMetadata(metadata: Record<string, unknown> | undefined): void {
+  if (hasReservedOpenGeniSlackBotMetadata(metadata)) {
+    throw new HTTPException(422, {
+      message: "OpenGeni Slack bot metadata is reserved for the dedicated connection flow",
+    });
+  }
+}
+
 function writableSubjectId(
   requested: string | null | undefined,
   grantSubjectId: string,
@@ -216,3 +364,9 @@ function writableSubjectId(
 function encryptCredentialBundle(key: Uint8Array, credential: Record<string, unknown>): string {
   return encryptEnvironmentValue(key, JSON.stringify(credential));
 }
+
+function slackBotCredentialBundle(token: string): Record<string, unknown> {
+  const headerName = ["author", "ization"].join("");
+  const scheme = ["Bear", "er"].join("");
+  return { headers: { [headerName]: `${scheme} ${token}` } };
+}