@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/routes/connect.ts

@@ -1,26 +1,28 @@
 import { createHash, createHmac, randomUUID } from "node:crypto";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { getConnectBeginReplay } from "@opengeni/db/connect-attempts";
 import {
   AdvanceConnectRequest,
   BeginConnectRequest,
   ConnectOperationRequest,
   ConnectProvider,
   ConnectAccount,
+  preparedMcpHeaders,
 } from "@opengeni/contracts/connect";
 import {
   API_INTEGRATION_OAUTH_CREDENTIAL_ROLE,
   InstallApiIntegrationRequest,
   stableJson,
+  assertOrganizationIntegrationAllowed,
   OPENGENI_PERSONAL_SLACK_MCP_URL,
-  OPENGENI_PR_REVIEW_PACK_ID,
 } from "@opengeni/contracts";
 import {
   CORE_INTEGRATION_DEFINITIONS,
   createPinnedIntegrationTransport,
 } from "@opengeni/capabilities";
 import {
-  beginConnectAttempt,
+  beginConnectAttempt as persistConnectAttempt,
   getConnectAttempt,
   listPendingConnectAttempts,
   withWorkspaceSubjectRls,
@@ -30,9 +32,8 @@ import {
   createConnection,
   updateConnection,
   encryptEnvironmentValue,
-  normalizedHostCredentialHeaders,
+  normalizedCredentialHeaders,
   listGitHubInstallationAccessForWorkspace,
-  getPackInstallation,
   listPrReviewAppRegistrations,
   listSocialConnections,
   getSocialConnection,
@@ -45,7 +46,9 @@ import {
   isFikenConnection,
   isOpenGeniSlackBotConnection,
   prepareCapabilityEnable,
+  prepareMcpConnectionActivation,
   buildCapabilityCatalog,
+  integrationKeyForConnectProvider,
   type ApiRouteDeps,
 } from "@opengeni/core";
 import { isPersonalConnectionOwnerPrincipal } from "../connection-ownership";
@@ -67,20 +70,28 @@ import {
   GOOGLE_DRIVE_CREDENTIAL_ROLE,
   googleDriveScopesAllowCapability,
 } from "@opengeni/contracts/google-drive";
-import { ATLASSIAN_CREDENTIAL_ROLE } from "@opengeni/contracts/atlassian";
+import { ATLASSIAN_NATIVE_RETIRED_MESSAGE } from "@opengeni/contracts/atlassian-native-retirement";
 import {
   curatedOAuthReadiness,
   startApiIntegrationProviderOAuth,
 } from "../integrations/provider-oauth";
 import { resolveForRoute, validatedIntegrationInstallInput } from "./api-integrations";
 import { executeConnectOperation } from "@opengeni/core";
-import { startMcpOAuth, requireIntegrationsStateSecret } from "../integrations/oauth-client";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import {
+  startMcpOAuth,
+  requireIntegrationsStateSecret,
+  gmailOAuthClientConfigured,
+} from "../integrations/oauth-client";
 import { OFFICIAL_GMAIL_MCP_URL } from "../integrations/oauth-profiles";
 import { z } from "zod";
 import {
   WORKSPACE_OPENROUTER_CONNECTION_DOMAIN,
+  WORKSPACE_OPPER_CONNECTION_DOMAIN,
   VERCEL_AI_GATEWAY_CONNECTION_DOMAIN,
 } from "@opengeni/config";
+import { parseRequestJson } from "../http/request-body";
+import { connectRequestActor, assertAgentPreparedConnect } from "../prepared-mcp-actor";
 
 /** Shared durable setup entry. Provider completion is distinct from
  * subsequent preview/install; never report an OAuth token as a ready integration. */
@@ -101,13 +112,13 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
       "workspace:read",
     );
     const external = authorization.contextIntegrity;
-    const canWrite = hasPermission(authorization.grant.permissions, "connections:write");
-    const personal = isPersonalConnectionOwnerPrincipal(authorization);
-    const lensPack = await getPackInstallation(
+    const policy = await withOrganizationIntegrationPolicyFence(
       deps.db,
-      authorization.grant.workspaceId,
-      OPENGENI_PR_REVIEW_PACK_ID,
+      authorization.grant,
+      async (_tx, current) => current,
     );
+    const canWrite = hasPermission(authorization.grant.permissions, "connections:write");
+    const personal = isPersonalConnectionOwnerPrincipal(authorization);
     let mcpConfigured = false;
     let credentialConfigured = false;
     try {
@@ -118,7 +129,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
     } catch {
       /* Missing operator configuration is catalog readiness, not actor authority. */
     }
-    return c.json([
+    const providers = [
       ...(["x", "reddit"] as const).map((providerId) => {
         let configured = mcpConfigured;
         try {
@@ -197,21 +208,6 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
           setup: [protocol, "installation"],
         }),
       ),
-      ConnectProvider.parse({
-        id: "atlassian",
-        label: "Atlassian (Jira and Confluence)",
-        family: "atlassian",
-        readiness:
-          !external || !canWrite || !personal
-            ? "unsupported"
-            : mcpConfigured &&
-                deps.settings.atlassianClientId?.trim() &&
-                deps.settings.atlassianClientSecret?.trim()
-              ? "available"
-              : "needs_configuration",
-        ownership: personal ? ["personal"] : [],
-        setup: ["oauth"],
-      }),
       ConnectProvider.parse({
         id: "slack-bot",
         label: "Slack workspace bot",
@@ -235,7 +231,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
         readiness:
           !external || !canWrite || !personal
             ? "unsupported"
-            : mcpConfigured
+            : mcpConfigured && gmailOAuthClientConfigured(deps.settings)
               ? "available"
               : "needs_configuration",
         ownership: personal ? ["personal"] : [],
@@ -243,17 +239,17 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
       }),
       ConnectProvider.parse({
         id: "slack-personal",
-        label: "My Slack account",
+        label: "Slack account",
         family: "slack",
         readiness:
-          !external || !canWrite || !personal
+          !external || !canWrite
             ? "unsupported"
             : mcpConfigured &&
                 deps.settings.slackClientId?.trim() &&
                 deps.settings.slackClientSecret?.trim()
               ? "available"
               : "needs_configuration",
-        ownership: personal ? ["personal"] : [],
+        ownership: personal ? ["workspace", "personal"] : ["workspace"],
         setup: ["oauth"],
       }),
       ConnectProvider.parse({
@@ -288,7 +284,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
       }),
       ConnectProvider.parse({
         id: "github-lens",
-        label: "OpenGeni Lens PR review",
+        label: "Opengeni Lens PR review",
         family: "github-lens",
         readiness:
           !external ||
@@ -296,7 +292,6 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
           !hasPermission(authorization.grant.permissions, "secrets:write")
             ? "unsupported"
             : credentialConfigured &&
-                lensPack?.status === "active" &&
                 deps.settings.sandboxBackend !== "selfhosted" &&
                 prReviewGitHubAppMissingSettings(deps.settings).length === 0
               ? "available"
@@ -391,7 +386,16 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
         ownership: personal ? ["workspace", "personal"] : ["workspace"],
         setup: ["credentials"],
       }),
-    ]);
+    ];
+    return c.json(
+      providers.filter(
+        (provider) =>
+          policy.mode === "unrestricted" ||
+          policy.allowedIntegrationKeys.includes(
+            integrationKeyForConnectProvider(provider.id) ?? "",
+          ),
+      ),
+    );
   });
   app.get("/v1/workspaces/:workspaceId/connect/accounts", async (c) => {
     const workspaceId = c.req.param("workspaceId");
@@ -508,22 +512,6 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
                     : "auth_needed",
             }),
           ];
-        if (connection.metadata.credentialRole === ATLASSIAN_CREDENTIAL_ROLE)
-          return [
-            ConnectAccount.parse({
-              id: connection.id,
-              version: connection.version,
-              providerId: "atlassian",
-              label: String(connection.metadata.displayName ?? "Atlassian"),
-              ownership: "personal",
-              status:
-                connection.status === "revoked"
-                  ? "disabled"
-                  : connection.status === "active"
-                    ? "connected"
-                    : "auth_needed",
-            }),
-          ];
         if (isFikenConnection(connection))
           return [
             ConnectAccount.parse({
@@ -579,9 +567,12 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
               status:
                 connection.status === "revoked"
                   ? "disabled"
-                  : connection.status === "active"
-                    ? "connected"
-                    : "auth_needed",
+                  : connection.metadata.mcpUrl === OFFICIAL_GMAIL_MCP_URL &&
+                      connection.subjectId === null
+                    ? "auth_needed"
+                    : connection.status === "active"
+                      ? "connected"
+                      : "auth_needed",
             }),
           ];
         if (connection.metadata.credentialRole !== API_INTEGRATION_OAUTH_CREDENTIAL_ROLE) return [];
@@ -619,7 +610,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
     ...(deps.apiIntegrationSourceFetch ? { fetchImpl: deps.apiIntegrationSourceFetch } : {}),
   });
   app.post("/v1/workspaces/:workspaceId/connect/attempts/:attemptId/advance", async (c) => {
-    const input = AdvanceConnectRequest.parse(await c.req.json());
+    const input = await parseRequestJson(c, AdvanceConnectRequest);
     const action = input.action;
     const workspaceId = c.req.param("workspaceId");
     const permission =
@@ -635,21 +626,19 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
     const continuation = externalActorContinuationForAuthorization(authorization);
     if (!authorization.contextIntegrity)
       throw new HTTPException(403, { message: "Verified Connect authority required" });
-    const scope = {
-      accountId: authorization.grant.accountId,
-      workspaceId,
-      subjectId: authorization.grant.subjectId,
-      personalOwnerVerified: isPersonalConnectionOwnerPrincipal(authorization),
-      ...(continuation ? { externalContinuation: continuation } : {}),
-    };
+    const actor = await connectRequestActor(deps, authorization);
+    const scope = actor.scope;
     // Reject invalid caller selections before taking a durable operation claim.
     // Older revisions still go through the receipt-aware claim path for replay.
     const stored = await getConnectAttempt(deps.db, scope, c.req.param("attemptId"));
     const before = stored.attempt;
+    assertAgentPreparedConnect(actor, before);
     const advancePermission =
       before.providerId === "mcp-install" ? "capabilities:manage" : permission;
     if (!hasPermission(authorization.grant.permissions, advancePermission))
       throw new HTTPException(403, { message: `${advancePermission} required` });
+    if (before.mcpSetup && !hasPermission(authorization.grant.permissions, "capabilities:manage"))
+      throw new HTTPException(403, { message: "capabilities:manage required" });
     if (before.providerId === "mcp-install") {
       if (action.type !== "credentials")
         throw new HTTPException(422, { message: "Choose an MCP capability" });
@@ -717,7 +706,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
             await requireConnectOwnerAuthority(tx, scope, installationPermission, origin);
             if (before.providerId === "github-lens") {
               await requireConnectOwnerAuthority(tx, scope, "secrets:write", origin);
-              await requireGitHubLensConnect({ ...deps, db: tx }, workspaceId);
+              await requireGitHubLensConnect({ ...deps, db: tx });
             }
           },
           execute: async (attempt) =>
@@ -754,6 +743,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
             const resolved = await resolveForRoute({
               deps,
               transport,
+              accountId: scope.accountId,
               workspaceId,
               subjectId: scope.subjectId,
               payload: {
@@ -880,31 +870,43 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (["mcp-bearer", "mcp-headers"].includes(before.providerId)) {
       if (action.type !== "credentials")
         throw new HTTPException(422, { message: "MCP credentials required" });
-      const values =
-        before.providerId === "mcp-headers"
-          ? z
-              .object({
-                mcpUrl: z.string().url().max(4096),
-                headers: z.string().min(2).max(65_536),
-              })
-              .strict()
-              .parse(action.values)
-          : z
-              .object({
-                mcpUrl: z.string().url().max(4096),
-                token: z
-                  .string()
-                  .min(1)
-                  .max(16_384)
-                  .regex(/^[^\u0000-\u0020\u007f]+$/),
-              })
-              .strict()
-              .parse(action.values);
+      let values: { mcpUrl: string; headers: string } | { mcpUrl: string; token: string };
+      if (before.mcpSetup) {
+        try {
+          values = {
+            mcpUrl: before.mcpSetup.endpointUrl,
+            headers: JSON.stringify(preparedMcpHeaders(before.mcpSetup, action.values)),
+          };
+        } catch {
+          throw new HTTPException(422, { message: "Supply exactly the requested secret fields" });
+        }
+      } else {
+        values =
+          before.providerId === "mcp-headers"
+            ? z
+                .object({
+                  mcpUrl: z.string().url().max(4096),
+                  headers: z.string().min(2).max(65_536),
+                })
+                .strict()
+                .parse(action.values)
+            : z
+                .object({
+                  mcpUrl: z.string().url().max(4096),
+                  token: z
+                    .string()
+                    .min(1)
+                    .max(16_384)
+                    .regex(/^[^\u0000-\u0020\u007f]+$/),
+                })
+                .strict()
+                .parse(action.values);
+      }
       let credentialHeaders: Record<string, string>;
       try {
         credentialHeaders =
           "headers" in values
-            ? normalizedHostCredentialHeaders(
+            ? normalizedCredentialHeaders(
                 z.record(z.string(), z.string()).parse(JSON.parse(values.headers)),
               )
             : { authorization: `Bearer ${values.token}` };
@@ -915,9 +917,11 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
       }
       const destination = new URL(values.mcpUrl);
       if (
-        [WORKSPACE_OPENROUTER_CONNECTION_DOMAIN, VERCEL_AI_GATEWAY_CONNECTION_DOMAIN].some(
-          (domain) => domain === destination.hostname,
-        )
+        [
+          WORKSPACE_OPENROUTER_CONNECTION_DOMAIN,
+          VERCEL_AI_GATEWAY_CONNECTION_DOMAIN,
+          WORKSPACE_OPPER_CONNECTION_DOMAIN,
+        ].some((domain) => domain === destination.hostname)
       )
         throw new HTTPException(422, {
           message: "Use the dedicated workspace provider credential flow",
@@ -941,11 +945,43 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
           expectedRevision: input.expectedRevision,
           operationId: input.idempotencyKey,
           inputDigest: createHmac("sha256", encryptionKey).update(stableJson(input)).digest("hex"),
-          authorize: (tx, _attempt, origin) =>
-            requireConnectOwnerAuthority(tx, scope, "connections:write", origin),
+          beforeOperation: actor.beforeOperation,
+          authorize: async (tx, attempt, origin) => {
+            await requireConnectOwnerAuthority(tx, scope, "connections:write", origin);
+            if (attempt.mcpSetup)
+              await requireConnectOwnerAuthority(tx, scope, "capabilities:manage", origin);
+          },
           execute: async (attempt) => {
             if (attempt.state !== "credential_input")
               throw new HTTPException(409, { message: "Reload the current credential setup" });
+            let activation: Awaited<ReturnType<typeof prepareMcpConnectionActivation>> | undefined;
+            if (attempt.mcpSetup) {
+              try {
+                activation = await prepareMcpConnectionActivation({
+                  grant: actor.grant,
+                  settings: deps.settings,
+                  setup: attempt.mcpSetup,
+                  ownership: attempt.ownership,
+                  headers: credentialHeaders,
+                  ...(deps.mcpCapabilityProbe ? { probe: deps.mcpCapabilityProbe } : {}),
+                });
+              } catch {
+                // No credential/catalog write has occurred. Settle this exact
+                // operation without recording provider text or secret values.
+                return {
+                  commit: async (_tx, current) => ({
+                    ...current,
+                    revision: current.revision + 1,
+                    error: {
+                      code: "mcp_verification_failed",
+                      message:
+                        "Could not verify the MCP connection. Check the key and server, then submit again.",
+                      retryable: false,
+                    },
+                  }),
+                };
+              }
+            }
             const credentialEncrypted = encryptEnvironmentValue(
               encryptionKey,
               JSON.stringify({ headers: credentialHeaders }),
@@ -1002,11 +1038,20 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
                       createdBySubjectId: scope.subjectId,
                     });
                 if (!connection) throw new HTTPException(409, { message: "MCP account changed" });
+                if (activation) await activation.commit(tx, connection);
+                const { error: _error, ...settled } = current;
                 return {
-                  ...current,
+                  ...settled,
                   revision: current.revision + 1,
                   state: "complete",
                   credentialsCommitted: true,
+                  ...(activation
+                    ? {
+                        integrationInstalled: true,
+                        completionRequirement: "integration" as const,
+                        mcpCapabilityId: activation.capabilityId,
+                      }
+                    : {}),
                   nextAction: { type: "none" },
                   account: {
                     id: connection.id,
@@ -1052,6 +1097,9 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
               throw new HTTPException(409, { message: "Reload the current connection setup" });
             const started = await startMcpOAuth(deps, {
               ...scope,
+              ...(before.providerId === "gmail" || before.providerId === "slack-personal"
+                ? { integrationKey: before.providerId }
+                : {}),
               ...(continuation ? { externalContinuation: continuation } : {}),
               connectAttemptId: attempt.id,
               personalOwnershipAllowed: isPersonalConnectionOwnerPrincipal(authorization),
@@ -1144,6 +1192,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
           const resolved = await resolveForRoute({
             deps,
             transport,
+            accountId: scope.accountId,
             workspaceId,
             subjectId: scope.subjectId,
             payload: previewRequest,
@@ -1214,19 +1263,11 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
   app.post("/v1/workspaces/:workspaceId/connect/attempts/:attemptId/cancel", async (c) => {
-    const input = ConnectOperationRequest.parse(await c.req.json());
+    const input = await parseRequestJson(c, ConnectOperationRequest);
     const workspaceId = c.req.param("workspaceId");
     const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
-    const continuation = externalActorContinuationForAuthorization(authorization);
-    if (!authorization.contextIntegrity)
-      throw new HTTPException(403, { message: "Verified Connect authority required" });
-    const scope = {
-      accountId: authorization.grant.accountId,
-      workspaceId,
-      subjectId: authorization.grant.subjectId,
-      personalOwnerVerified: isPersonalConnectionOwnerPrincipal(authorization),
-      ...(continuation ? { externalContinuation: continuation } : {}),
-    };
+    const actor = await connectRequestActor(deps, authorization);
+    const scope = actor.scope;
     return c.json(
       await executeConnectOperation({
         db: deps.db,
@@ -1237,7 +1278,10 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
         inputDigest: createHash("sha256")
           .update(stableJson({ ...input, action: "cancel" }))
           .digest("hex"),
+        purpose: "cancellation",
+        beforeOperation: actor.beforeOperation,
         authorize: async (tx, attempt, origin) => {
+          assertAgentPreparedConnect(actor, attempt);
           const permission =
             attempt.providerId === "mcp-install"
               ? "capabilities:manage"
@@ -1275,7 +1319,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!deps.settings.integrationsEnabled)
       throw new HTTPException(403, { message: "integrations disabled" });
     const workspaceId = c.req.param("workspaceId");
-    const input = BeginConnectRequest.parse(await c.req.json());
+    const input = await parseRequestJson(c, BeginConnectRequest);
     const setupPermission =
       input.providerId === "mcp-install"
         ? "capabilities:manage"
@@ -1299,6 +1343,12 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(403, {
         message: "Verified Connect authority required",
       });
+    if (input.mcpSetup && !hasPermission(authorization.grant.permissions, "capabilities:manage"))
+      throw new HTTPException(403, { message: "capabilities:manage required" });
+    if (input.providerId === "atlassian")
+      throw new HTTPException(410, { message: ATLASSIAN_NATIVE_RETIRED_MESSAGE });
+    if (input.providerId === "gmail" && input.ownership !== "personal")
+      throw new HTTPException(422, { message: "Gmail connections must be personal-owned" });
     let target: URL;
     try {
       target = new URL(input.returnUrl);
@@ -1312,16 +1362,69 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
       /[\u0000-\u0020\u007f]/.test(input.returnUrl)
     )
       throw new HTTPException(400, { message: "invalid return URL" });
-    const scope = {
-      accountId: authorization.grant.accountId,
-      workspaceId,
-      subjectId: authorization.grant.subjectId,
-      personalOwnerVerified: isPersonalConnectionOwnerPrincipal(authorization),
-      ...(continuation ? { externalContinuation: continuation } : {}),
-    };
+    const actor = await connectRequestActor(deps, authorization);
+    const scope = actor.scope;
+    assertAgentPreparedConnect(actor, input);
     return c.json(
-      await withWorkspaceSubjectRls(deps.db, workspaceId, scope.subjectId, async (tx) => {
-        await requireConnectOwnerAuthority(tx, scope, setupPermission);
+      await (async () => {
+        // Remote setup preparation stays outside the policy and actor transactions.
+        // Repeat both admissions when persisting the resulting attempt.
+        const tx = deps.db;
+        const admit = () =>
+          withOrganizationIntegrationPolicyFence(deps.db, scope, async (policyTx, policy) => {
+            await actor.beforeOperation?.(policyTx);
+            return withWorkspaceSubjectRls(
+              policyTx,
+              workspaceId,
+              scope.subjectId,
+              async (actorTx) => {
+                await requireConnectOwnerAuthority(actorTx, scope, setupPermission);
+                if (input.mcpSetup)
+                  await requireConnectOwnerAuthority(actorTx, scope, "capabilities:manage");
+                const replay = await getConnectBeginReplay(actorTx, scope, {
+                  idempotencyKey: input.idempotencyKey,
+                  requestDigest: createHash("sha256").update(stableJson(input)).digest("hex"),
+                  returnUrl: input.returnUrl,
+                  ...(continuation ? { externalContinuation: continuation } : {}),
+                });
+                if (replay) return replay;
+                assertOrganizationIntegrationAllowed(
+                  policy,
+                  integrationKeyForConnectProvider(input.providerId),
+                );
+                return null;
+              },
+            );
+          });
+        const replay = await admit();
+        if (replay) return replay;
+        const beginConnectAttempt = async (
+          _db: Parameters<typeof persistConnectAttempt>[0],
+          _scope: Parameters<typeof persistConnectAttempt>[1],
+          attemptInput: Parameters<typeof persistConnectAttempt>[2],
+        ) =>
+          withOrganizationIntegrationPolicyFence(deps.db, scope, async (policyTx, policy) => {
+            await actor.beforeOperation?.(policyTx);
+            return withWorkspaceSubjectRls(
+              policyTx,
+              workspaceId,
+              scope.subjectId,
+              async (actorTx) => {
+                await requireConnectOwnerAuthority(actorTx, scope, setupPermission);
+                if (input.mcpSetup)
+                  await requireConnectOwnerAuthority(actorTx, scope, "capabilities:manage");
+                return persistConnectAttempt(actorTx, scope, {
+                  ...attemptInput,
+                  authorizeAcquisition: async () => {
+                    assertOrganizationIntegrationAllowed(
+                      policy,
+                      integrationKeyForConnectProvider(input.providerId),
+                    );
+                  },
+                });
+              },
+            );
+          });
         const id = randomUUID();
         if (input.providerId === "mcp-install") {
           if (
@@ -1467,7 +1570,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
             if (!hasPermission(authorization.grant.permissions, "secrets:write"))
               throw new HTTPException(403, { message: "secrets:write required" });
             await requireConnectOwnerAuthority(tx, scope, "secrets:write");
-            await requireGitHubLensConnect({ ...deps, db: tx }, workspaceId);
+            await requireGitHubLensConnect({ ...deps, db: tx });
           }
           const navigation = githubAppConnectNavigation(
             deps,
@@ -1501,7 +1604,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
         if (["openapi", "graphql"].includes(input.providerId)) {
           if (input.reconnectAccountId)
             throw new HTTPException(422, { message: "Select the service connection during setup" });
-          if (input.ownership === "personal" && !isPersonalConnectionOwnerPrincipal(authorization))
+          if (input.ownership === "personal" && !scope.personalOwnerVerified)
             throw new HTTPException(403, { message: "personal ownership unavailable" });
           const choices = hasPermission(authorization.grant.permissions, "connections:read")
             ? (await listConnectionsMetadata(tx, workspaceId, scope.subjectId))
@@ -1595,14 +1698,6 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
             "fiken-token",
           ].includes(input.providerId)
         ) {
-          if (input.providerId === "slack-personal" && input.ownership !== "personal")
-            throw new HTTPException(422, {
-              message: "Hosted Slack MCP requires personal ownership",
-            });
-          if (input.providerId === "gmail" && input.ownership !== "personal")
-            throw new HTTPException(422, {
-              message: "Gmail requires personal ownership; each user connects their own account",
-            });
           if (input.providerId === "fiken-token" && input.ownership !== "workspace")
             throw new HTTPException(422, { message: "Fiken is workspace-owned" });
           requireEnvironmentEncryption(deps.settings);
@@ -1633,7 +1728,7 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
               (existing.subjectId === null ? "workspace" : "personal") !== input.ownership)
           )
             throw new HTTPException(404, { message: "MCP account not found for this ownership" });
-          if (input.ownership === "personal" && !isPersonalConnectionOwnerPrincipal(authorization))
+          if (input.ownership === "personal" && !scope.personalOwnerVerified)
             throw new HTTPException(403, { message: "personal ownership unavailable" });
           return beginConnectAttempt(tx, scope, {
             ...(continuation ? { externalContinuation: continuation } : {}),
@@ -1649,7 +1744,8 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
               state: "credential_input",
               credentialsCommitted: false,
               integrationInstalled: false,
-              completionRequirement: "connection",
+              completionRequirement: input.mcpSetup ? "integration" : "connection",
+              ...(input.mcpSetup ? { mcpSetup: input.mcpSetup } : {}),
               ...(existing
                 ? {
                     account: {
@@ -1664,50 +1760,57 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
                 : {}),
               nextAction: {
                 type: "credentials",
-                fields: ["slack-personal", "gmail"].includes(input.providerId)
-                  ? []
-                  : input.providerId === "fiken-token"
-                    ? [
-                        {
-                          name: "apiToken",
-                          label: "Fiken API token",
-                          required: true,
-                          secret: true,
-                        },
-                        {
-                          name: "defaultCompanySlug",
-                          label: "Default company slug (optional)",
-                          required: false,
-                          secret: false,
-                        },
-                      ]
-                    : [
-                        {
-                          name: "mcpUrl",
-                          label: "MCP server URL",
-                          required: true,
-                          secret: false,
-                        },
-                        ...(input.providerId === "mcp-bearer"
-                          ? [
-                              {
-                                name: "token",
-                                label: "Bearer credential",
-                                required: true,
-                                secret: true,
-                              },
-                            ]
-                          : input.providerId === "mcp-headers"
+                fields: input.mcpSetup
+                  ? input.mcpSetup.secretFields.map((field) => ({
+                      name: field.id,
+                      label: field.label,
+                      required: true,
+                      secret: true,
+                    }))
+                  : ["slack-personal", "gmail"].includes(input.providerId)
+                    ? []
+                    : input.providerId === "fiken-token"
+                      ? [
+                          {
+                            name: "apiToken",
+                            label: "Fiken API token",
+                            required: true,
+                            secret: true,
+                          },
+                          {
+                            name: "defaultCompanySlug",
+                            label: "Default company slug (optional)",
+                            required: false,
+                            secret: false,
+                          },
+                        ]
+                      : [
+                          {
+                            name: "mcpUrl",
+                            label: "MCP server URL",
+                            required: true,
+                            secret: false,
+                          },
+                          ...(input.providerId === "mcp-bearer"
                             ? [
                                 {
-                                  name: "headers",
-                                  label: "Credential headers (JSON)",
+                                  name: "token",
+                                  label: "Bearer credential",
                                   required: true,
                                   secret: true,
                                 },
                               ]
-                            : []),
-                      ],
+                            : input.providerId === "mcp-headers"
+                              ? [
+                                  {
+                                    name: "headers",
+                                    label: "Credential headers (JSON)",
+                                    required: true,
+                                    secret: true,
+                                  },
+                                ]
+                              : []),
+                        ],
               },
               expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
             },
@@ -1867,30 +1970,29 @@ export function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void {
             expiresAt: started.expiresAt,
           },
         });
-      }),
+      })(),
     );
   });
   app.get("/v1/workspaces/:workspaceId/connect/attempts", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const { grant } = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const actor = await connectRequestActor(deps, authorization);
+    const { grant } = actor;
     return c.json(
-      (
-        await listPendingConnectAttempts(deps.db, {
-          accountId: grant.accountId,
-          workspaceId,
-          subjectId: grant.subjectId,
-        })
-      ).filter((attempt) => canReadAttempt(grant.permissions, attempt.providerId)),
+      (await listPendingConnectAttempts(deps.db, actor.scope)).filter(
+        (attempt) =>
+          canReadAttempt(grant.permissions, attempt.providerId) &&
+          (!actor.preparedOnly || (attempt.providerId === "mcp-headers" && attempt.mcpSetup)),
+      ),
     );
   });
   app.get("/v1/workspaces/:workspaceId/connect/attempts/:attemptId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const { grant } = await requireAccessGrantAuthorization(c, deps, workspaceId);
-    const { attempt } = await getConnectAttempt(
-      deps.db,
-      { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
-      c.req.param("attemptId"),
-    );
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const actor = await connectRequestActor(deps, authorization);
+    const { grant } = actor;
+    const { attempt } = await getConnectAttempt(deps.db, actor.scope, c.req.param("attemptId"));
+    assertAgentPreparedConnect(actor, attempt);
     if (!canReadAttempt(grant.permissions, attempt.providerId))
       throw new HTTPException(403, { message: "Connect read permission required" });
     return c.json(attempt);