@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/connections.ts

@@ -1,4 +1,36 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
+import { verifyDirectModelAccess } from "@opengeni/core";
+import {
+  assertClaudeWorkspaceCredential,
+  prepareClaudeWorkspaceCredential,
+} from "../claude-workspace-connection";
+import {
+  createConnectionIdempotently,
+  upsertWorkspaceProviderApiKeyConnection,
+  rotateWorkspaceProviderApiKeyConnection,
+  revokeWorkspaceProviderApiKeyConnections,
+  workspaceProviderApiKeyConnectionSpec,
+  type WorkspaceProviderApiKeyConnectionKind,
+  getConnectionCreationResult,
+  ConnectionCreateIdempotencyError,
+} from "@opengeni/db";
+import { sql } from "drizzle-orm";
+import { assertOrganizationIntegrationAllowed } from "@opengeni/contracts";
+import {
+  withOrganizationIntegrationAcquisition,
+  withOrganizationIntegrationPolicyFence,
+} from "@opengeni/db/organization-integration-policy";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import {
+  startSlackBotInstall,
+  requireOpenGeniSlackOAuthSettings,
+} from "../integrations/slack-install";
+import {
+  WORKSPACE_OPENROUTER_CONNECTION_DOMAIN,
+  WORKSPACE_OPENROUTER_CONNECTION_ROLE,
+  VERCEL_AI_GATEWAY_CONNECTION_DOMAIN,
+  VERCEL_AI_GATEWAY_CONNECTION_ROLE,
+} from "@opengeni/config";
 import {
   ATLASSIAN_PROVIDER_DOMAIN,
   AtlassianConnectionMetadata,
@@ -10,22 +42,24 @@ import {
 import {
   API_INTEGRATION_OAUTH_CREDENTIAL_ROLE,
   ApiIntegrationOAuthStartRequest,
+  DirectModelProviderMetadata,
   ConnectionResponse,
   CreateConnectionRequest,
-  FIKEN_CREDENTIAL_LABEL,
-  FIKEN_CREDENTIAL_ROLE,
-  FIKEN_PROVIDER_DOMAIN,
   FikenInstallRequest,
   FikenOAuthStartRequest,
   FikenOAuthStartResponse,
   IntegrationClientMetadata,
   ListSlackInstallationBindingsResponse,
   ListConnectionsResponse,
+  OPENROUTER_CREDENTIAL_OPERATION_DIGEST_METADATA_KEY,
+  OPENROUTER_CREDENTIAL_OPERATION_ID_METADATA_KEY,
   OpenGeniSlackBotInstallRequest,
-  OpenGeniSlackBotInstallStart,
   OAuthStartRequest,
   OAuthStartResponse,
   UpdateConnectionRequest,
+  VERCEL_AI_GATEWAY_CREDENTIAL_OPERATION_DIGEST_METADATA_KEY,
+  VERCEL_AI_GATEWAY_CREDENTIAL_OPERATION_ID_METADATA_KEY,
+  stableJson,
 } from "@opengeni/contracts";
 import {
   bindConnectorDocumentDestination,
@@ -40,24 +74,34 @@ import {
   GoogleDriveOAuthStartResponse,
 } from "@opengeni/contracts/google-drive";
 import {
-  fikenConnectionMetadata,
+  PERSONAL_GITHUB_PROVIDER_DOMAIN,
+  PersonalGitHubDisconnectRequest,
+  hasReservedPersonalGitHubMetadata,
+  isPersonalGitHubConnection,
+} from "@opengeni/contracts/personal-github";
+import {
   hasPermission,
+  listOwnConnectionAccountsForGrant,
   hasReservedFikenMetadata,
   hasReservedOpenGeniSlackBotMetadata,
-  isFikenConnection,
   isOpenGeniSlackBotConnection,
   openGeniSlackBotMetadata,
   requireAccessGrant,
   requireAccessGrantAuthorization,
   requireEnvironmentEncryption,
-  resolveFikenDefaultCompanySlug,
+  externalContinuationCommitAuthorizer,
 } from "@opengeni/core";
 import {
   consumeIntegrationOAuthStateNonce,
-  createConnection,
+  claimConnectOperation,
+  finishConnectOperation,
+  getConnectAttempt,
+  decryptEnvironmentValue,
+  withWorkspaceSubjectRls,
+  type Database,
   encryptEnvironmentValue,
+  brokeredCredentialBundleProblem,
   getConnectionMetadata,
-  getWorkspaceGrant,
   listConnectionsMetadata,
   listSlackInstallationBindings,
   persistSlackBotInstallationWithSuccessAudit,
@@ -84,8 +128,10 @@ import {
 } from "../integrations/google-drive";
 import {
   completeApiIntegrationProviderOAuth,
+  isApiIntegrationProviderOAuthState,
   startApiIntegrationProviderOAuth,
 } from "../integrations/provider-oauth";
+import { disconnectPersonalGitHub } from "../integrations/personal-github";
 import {
   browseAtlassianSources,
   completeAtlassianOAuthCallback,
@@ -97,9 +143,17 @@ import {
 import {
   completeMcpOAuthCallback,
   integrationBaseUrl,
+  oauthStateFailureReturn,
   startMcpOAuth,
 } from "../integrations/oauth-client";
+import {
+  assertPersonalConnectionOwnerPrincipal,
+  isPersonalConnectionOwnerPrincipal,
+  requireLegacyOAuthActor,
+  requireProviderConsentInBrowser,
+} from "../connection-ownership";
 import { canonicalProviderDomain } from "../integrations/provider-domain";
+import { externalActorContinuationForAuthorization } from "@opengeni/core";
 import {
   exchangeOpenGeniSlackAuthorizationCode,
   SlackBotCredentialVerificationError,
@@ -107,19 +161,21 @@ import {
 } from "../integrations/slack-bot";
 import {
   completeFikenOAuthCallback,
-  fikenCredentialBundle,
   startFikenOAuth,
-  verifyFikenApiToken,
+  prepareFikenTokenInstall,
 } from "../integrations/fiken";
+import { requireConnectOwnerAuthority } from "../integrations/connect-authority";
 import {
   OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
   OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
-  OPENGENI_SLACK_BOT_REQUESTED_SCOPES,
 } from "@opengeni/contracts";
-import { createSignedState, readSignedState } from "@opengeni/github";
+import { readSignedState } from "@opengeni/github";
 import { oauthStateTtlMs, requireIntegrationsStateSecret } from "../integrations/oauth-client";
+import { parseRequestJson } from "../http/request-body";
 
 type OpenGeniSlackInstallState = {
+  connectAttemptId?: string;
+  externalContinuation?: ExternalActorContinuation;
   accountId: string;
   workspaceId: string;
   subjectId: string;
@@ -149,6 +205,26 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  app.get("/v1/workspaces/:workspaceId/connections/accounts", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
+    const includeInactive = c.req.query("includeInactive");
+    if (
+      includeInactive !== undefined &&
+      includeInactive !== "true" &&
+      includeInactive !== "false"
+    ) {
+      throw new HTTPException(400, { message: "includeInactive must be true or false" });
+    }
+    return c.json(
+      ListConnectionsResponse.parse({
+        connections: await listOwnConnectionAccountsForGrant(db, grant, {
+          includeInactive: includeInactive === "true",
+        }),
+      }),
+    );
+  });
+
   app.get("/v1/workspaces/:workspaceId/connections/slack-bot/bindings", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
@@ -162,79 +238,281 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
-  app.post("/v1/workspaces/:workspaceId/connections", async (c) => {
+  app.get("/v1/workspaces/:workspaceId/connections/operations/:operationId", async (c) => {
     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);
-    assertNotReservedFikenMetadata(payload.metadata);
-    assertNotReservedApiIntegrationOAuthMetadata(payload.metadata);
-    const key = requireEnvironmentEncryption(settings);
-    const subjectId = createConnectionSubjectId(payload, grant.subjectId);
-    const providerDomain = canonicalProviderDomain(payload.providerDomain);
-    assertNotDirectPersonalSlackOAuth(providerDomain, payload.kind);
-    assertNotDirectGoogleDriveOAuth(providerDomain, payload.kind, payload.metadata);
-    assertNotDirectAtlassianOAuth(providerDomain, payload.kind, payload.metadata);
-    const connection = await createConnection(db, {
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
+    const operationId = CreateConnectionRequest.shape.operationId
+      .unwrap()
+      .parse(c.req.param("operationId"));
+    const connection = await getConnectionCreationResult(db, {
       accountId: grant.accountId,
       workspaceId,
-      subjectId,
-      providerDomain,
-      kind: payload.kind,
-      credentialEncrypted: encryptCredentialBundle(key, payload.credential),
-      grantedScopes: payload.grantedScopes,
-      expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null,
-      metadata: payload.metadata,
-      createdBySubjectId: grant.subjectId,
+      subjectId: grant.subjectId,
+      operationId,
     });
-    return c.json(ConnectionResponse.parse({ connection }), 201);
+    if (!connection) throw new HTTPException(404, { message: "Connection operation not found" });
+    return c.json(ConnectionResponse.parse({ connection }));
   });
 
-  app.post("/v1/workspaces/:workspaceId/connections/slack-bot/install", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/connections", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
-    const payload = OpenGeniSlackBotInstallRequest.parse(await c.req.json());
-    const slack = requireOpenGeniSlackOAuthSettings(settings);
-    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)) {
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    const grant = access.grant;
+    const beforeCommit = externalContinuationCommitAuthorizer(access);
+    const payload = await parseRequestJson(c, CreateConnectionRequest);
+    if (
+      payload.metadata?.directModelProvider !== undefined ||
+      String(payload.metadata?.credentialRole ?? "").startsWith("direct_")
+    ) {
+      const config = DirectModelProviderMetadata.safeParse(payload.metadata?.directModelProvider);
+      const domain = config.success
+        ? new URL(config.data.endpoint ?? "https://api.openai.com/v1").hostname
+        : null;
+      if (
+        !config.success ||
+        payload.subjectId !== null ||
+        payload.kind !== "api_key" ||
+        canonicalProviderDomain(payload.providerDomain) !== domain ||
+        payload.metadata?.credentialRole !== `direct_${config.data.provider}` ||
+        typeof payload.credential.apiKey !== "string" ||
+        !payload.credential.apiKey.trim() ||
+        !payload.operationId ||
+        payload.expiresAt
+      ) {
+        throw new HTTPException(422, {
+          message:
+            "Invalid OpenAI or Azure OpenAI connection: provide a key, model, and official provider endpoint",
+        });
+      }
+      payload.metadata = { ...payload.metadata, directModelProvider: config.data };
+      if (payload.verifyModelAccess) {
+        await verifyDirectModelAccess(
+          config.data,
+          payload.credential.apiKey as string,
+          deps.directModelFetch,
+        );
+      }
+    } else if (payload.verifyModelAccess) {
       throw new HTTPException(422, {
-        message: "connectionId is not an OpenGeni Slack bot connection",
+        message: "Model checks require an OpenAI or Azure OpenAI connection",
       });
     }
-    const baseUrl = integrationBaseUrl(settings.publicBaseUrl, c.req.url);
-    const redirectUri = `${baseUrl}/v1/integrations/slack/callback`;
-    const returnPath = `/workspaces/${workspaceId}/capabilities`;
-    const state = createSignedState(requireIntegrationsStateSecret(settings), {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId: grant.subjectId,
-      returnPath,
-      ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
+    const directModelKey = payload.metadata?.directModelProvider !== undefined;
+    // All writes in this closure must use the caller-owned scoped transaction.
+    // eslint-disable-next-line no-shadow
+    const persist = async (db: Database) => {
+      assertNotReservedSlackBotMetadata(payload.metadata);
+      assertNotReservedFikenMetadata(payload.metadata);
+      assertNotReservedApiIntegrationOAuthMetadata(payload.metadata);
+      assertNotReservedPersonalGitHubMetadata(payload.metadata);
+      const key = requireEnvironmentEncryption(settings);
+      const subjectId = createConnectionSubjectId(payload, grant.subjectId);
+      if (subjectId !== null) {
+        assertPersonalConnectionOwnerPrincipal(access);
+      }
+      const providerDomain = canonicalProviderDomain(payload.providerDomain);
+      payload.credential = prepareClaudeWorkspaceCredential(
+        settings,
+        workspaceId,
+        payload.metadata,
+        payload.credential,
+      );
+      assertClaudeWorkspaceCredential(settings, {
+        subjectId,
+        providerDomain,
+        kind: payload.kind,
+        metadata: payload.metadata,
+        credential: payload.credential,
+      });
+      assertNotDirectPersonalSlackOAuth(providerDomain, payload.kind);
+      assertNotDirectGoogleDriveOAuth(providerDomain, payload.kind, payload.metadata);
+      assertNotDirectAtlassianOAuth(providerDomain, payload.kind, payload.metadata);
+      assertNotDirectPersonalGitHubOAuth(providerDomain, payload.kind, payload.metadata);
+      const credentialEncrypted = encryptCredentialBundle(key, payload.credential);
+      const workspaceProviderKind = workspaceProviderApiKeyConnectionKind({
+        subjectId,
+        providerDomain,
+        kind: payload.kind,
+        metadata: payload.metadata,
+      });
+      // Validated model keys store `{ apiKey }` for model execution. Generic
+      // integration credentials still require an explicit broker destination.
+      if (!workspaceProviderKind && !directModelKey)
+        assertBrokeredApiKeyCredential(payload.kind, payload.credential);
+      const connection = workspaceProviderKind
+        ? await (async () => {
+            const provider = workspaceProviderApiKeyConnectionSpec(workspaceProviderKind);
+            if (!payload.operationId) {
+              throw new HTTPException(400, {
+                message: `connecting ${provider.label} requires an operationId`,
+              });
+            }
+            const expiresAt = payload.expiresAt ? new Date(payload.expiresAt) : null;
+            const metadata = workspaceProviderCredentialMetadata(
+              workspaceProviderKind,
+              payload.metadata,
+            );
+            const input = {
+              accountId: grant.accountId,
+              workspaceId,
+              operationId: payload.operationId,
+              requestDigest: workspaceProviderCredentialRequestDigest(key, {
+                action: "create",
+                providerDomain,
+                kind: payload.kind,
+                subjectId,
+                credential: payload.credential,
+                grantedScopes: payload.grantedScopes,
+                expiresAt: expiresAt?.toISOString() ?? null,
+                metadata,
+              }),
+              credentialEncrypted,
+              grantedScopes: payload.grantedScopes,
+              expiresAt,
+              metadata,
+              updatedBySubjectId: grant.subjectId,
+            };
+            const created = await upsertWorkspaceProviderApiKeyConnection(
+              db,
+              workspaceProviderKind,
+              input,
+            );
+            if (!created || created.status === "revoked") {
+              throw new HTTPException(409, {
+                message: `${provider.label} is already connected; reload before replacing its key`,
+              });
+            }
+            return created;
+          })()
+        : await createConnectionIdempotently(db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId,
+            providerDomain,
+            kind: payload.kind,
+            credentialEncrypted,
+            grantedScopes: payload.grantedScopes,
+            expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null,
+            metadata: payload.metadata,
+            createdBySubjectId: grant.subjectId,
+            ...(payload.operationId
+              ? {
+                  operation: {
+                    id: payload.operationId,
+                    requestDigest: workspaceProviderCredentialRequestDigest(key, {
+                      action: "create",
+                      providerDomain,
+                      kind: payload.kind,
+                      subjectId,
+                      credential: payload.credential,
+                      grantedScopes: payload.grantedScopes,
+                      expiresAt: payload.expiresAt
+                        ? new Date(payload.expiresAt).toISOString()
+                        : null,
+                      metadata: payload.metadata,
+                    }),
+                  },
+                }
+              : {}),
+          }).catch((error: unknown) => {
+            if (error instanceof ConnectionCreateIdempotencyError) {
+              throw new HTTPException(409, { message: error.message });
+            }
+            throw error;
+          });
+      return c.json(ConnectionResponse.parse({ connection }), 201);
+    };
+    const commit = (database: Database) =>
+      beforeCommit
+        ? withWorkspaceSubjectRls(database, workspaceId, grant.subjectId, async (tx) => {
+            await beforeCommit(tx);
+            return persist(tx);
+          })
+        : persist(database);
+    // Only the canonical workspace model-key lane is outside integration policy.
+    // Generic credentials have no validated protocol/curated target in this contract.
+    const modelKey = workspaceProviderApiKeyConnectionKind({
+      subjectId: createConnectionSubjectId(payload, grant.subjectId),
+      providerDomain: canonicalProviderDomain(payload.providerDomain),
+      kind: payload.kind,
+      metadata: payload.metadata,
     });
-    const authorizationUrl = new URL("https://slack.com/oauth/v2/authorize");
-    authorizationUrl.searchParams.set("client_id", slack.clientId);
-    authorizationUrl.searchParams.set("scope", OPENGENI_SLACK_BOT_REQUESTED_SCOPES.join(","));
-    authorizationUrl.searchParams.set("redirect_uri", redirectUri);
-    authorizationUrl.searchParams.set("state", state);
+    return modelKey || directModelKey
+      ? commit(db)
+      : withOrganizationIntegrationAcquisition(
+          db,
+          { accountId: grant.accountId, workspaceId },
+          [null],
+          commit,
+        );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/connections/slack-bot/install", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    requireLegacyOAuthActor(access);
+    const grant = access.grant;
+    const payload = await parseRequestJson(c, OpenGeniSlackBotInstallRequest);
     return c.json(
-      OpenGeniSlackBotInstallStart.parse({
-        authorizationUrl: authorizationUrl.toString(),
-        expiresAt: new Date(Date.now() + oauthStateTtlMs).toISOString(),
-      }),
+      await withOrganizationIntegrationAcquisition(
+        db,
+        { accountId: grant.accountId, workspaceId },
+        ["slack-bot"],
+        (tx) =>
+          startSlackBotInstall(
+            { ...deps, db: tx },
+            {
+              accountId: grant.accountId,
+              workspaceId,
+              subjectId: grant.subjectId,
+              requestUrl: c.req.url,
+              ...(payload.connectionId ? { connectionId: payload.connectionId } : {}),
+            },
+          ),
+      ),
     );
   });
 
   app.get("/v1/integrations/slack/callback", async (c) => {
     const baseUrl = integrationBaseUrl(settings.publicBaseUrl, c.req.url);
     let state: OpenGeniSlackInstallState | null = null;
+    let exactReturnUrl: string | undefined;
+    let operation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
     let stage: SlackBotInstallCallbackFailureStage = "permission_check";
     try {
       state = readOpenGeniSlackInstallState(c.req.query("state"), settings);
+      if (state.connectAttemptId) {
+        const stored = await getConnectAttempt(db, state, state.connectAttemptId);
+        if (stored.attempt.providerId !== "slack-bot" || stored.attempt.ownership !== "workspace")
+          throw new HTTPException(403, { message: "Slack attempt mismatch" });
+        exactReturnUrl = stored.returnUrl;
+        operation = {
+          attemptId: state.connectAttemptId,
+          operationId: `oauth:${state.nonce}`,
+          inputDigest: createHash("sha256").update(c.req.query("state")!).digest("hex"),
+        };
+        const callbackState = state;
+        const callbackOperation = operation;
+        const claim = await withOrganizationIntegrationPolicyFence(
+          db,
+          callbackState,
+          (policyTx, policy) =>
+            claimConnectOperation(policyTx, callbackState, {
+              ...callbackOperation,
+              expectedRevision: stored.attempt.revision,
+              authorize: (tx, _attempt, origin) =>
+                requireConnectOwnerAuthority(tx, callbackState, "connections:write", origin),
+              authorizeAcquisition: async () => {
+                // Provider denial/cancellation acquires nothing; completed exact
+                // receipts replay before this callback is invoked.
+                if (!c.req.query("error") && c.req.query("code"))
+                  assertOrganizationIntegrationAllowed(policy, "slack-bot");
+              },
+            }),
+        );
+        if (claim.status === "replayed")
+          return new Response(null, { status: 302, headers: { Location: exactReturnUrl } });
+      }
       await requireSlackInstallCallbackGrant(db, state);
       stage = "nonce_consume";
       const consumed = await consumeIntegrationOAuthStateNonce(db, {
@@ -252,6 +530,25 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
           "Slack installation state has already been used",
         );
       }
+      if (operation && (c.req.query("error") || !c.req.query("code"))) {
+        await finishConnectOperation(db, state, {
+          ...operation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+          commit: async (_tx, current) => ({
+            ...current,
+            revision: current.revision + 1,
+            state: c.req.query("error") === "access_denied" ? "cancelled" : "failed",
+            nextAction: { type: "none" },
+            error: {
+              code: c.req.query("error") ? "provider_denied" : "missing_code",
+              message: "Authorization was not completed. Start a new connection attempt.",
+              retryable: false,
+            },
+          }),
+        });
+        return new Response(null, { status: 302, headers: { Location: exactReturnUrl! } });
+      }
       if (c.req.query("error")) {
         stage = "provider_denial";
         throw new SlackInstallCallbackError(
@@ -269,9 +566,10 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
           "Slack installation callback is missing code",
         );
       }
+      await withOrganizationIntegrationAcquisition(db, state, ["slack-bot"], async () => {});
       const slack = requireOpenGeniSlackOAuthSettings(settings);
       const redirectUri = `${baseUrl}/v1/integrations/slack/callback`;
-      const token = await exchangeOpenGeniSlackAuthorizationCode(
+      const authorization = await exchangeOpenGeniSlackAuthorizationCode(
         {
           code,
           clientId: slack.clientId,
@@ -281,21 +579,72 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
         deps.slackFetch ?? fetch,
       );
       stage = "credential_verification";
-      const verified = await verifyOpenGeniSlackBotCredential(token, deps.slackFetch ?? fetch);
+      const verified = await verifyOpenGeniSlackBotCredential(
+        authorization.accessToken,
+        {
+          appId: authorization.appId,
+          displayName: settings.slackBotDisplayName,
+        },
+        deps.slackFetch ?? fetch,
+        new Date(),
+      );
       stage = "permission_recheck";
       await requireSlackInstallCallbackGrant(db, state);
       stage = "persistence";
-      const connection = await persistOpenGeniSlackBotConnection({
-        deps,
-        state,
-        token,
-        verified,
-      });
+      const acceptedState = state;
+      const persist = (tx: Database) =>
+        persistOpenGeniSlackBotConnection({
+          deps: { ...deps, db: tx },
+          state: acceptedState,
+          token: authorization.accessToken,
+          verified,
+        });
+      if (operation) {
+        const acceptedOperation = operation;
+        await withOrganizationIntegrationPolicyFence(db, acceptedState, (policyTx, policy) =>
+          finishConnectOperation(policyTx, acceptedState, {
+            ...acceptedOperation,
+            authorize: (tx, _attempt, origin) =>
+              requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
+            commit: async (tx, current) => {
+              assertOrganizationIntegrationAllowed(policy, "slack-bot");
+              const connection = await persist(tx);
+              return {
+                ...current,
+                revision: current.revision + 1,
+                state: "complete",
+                credentialsCommitted: true,
+                nextAction: { type: "none" },
+                account: {
+                  id: connection.id,
+                  version: connection.version,
+                  providerId: "slack-bot",
+                  label: "Slack workspace bot",
+                  ownership: "workspace",
+                  status: "connected",
+                },
+              };
+            },
+          }),
+        );
+        return new Response(null, { status: 302, headers: { Location: exactReturnUrl! } });
+      }
+      const connection = await withOrganizationIntegrationAcquisition(
+        db,
+        acceptedState,
+        ["slack-bot"],
+        async (tx) => {
+          await requireSlackInstallCallbackGrant(tx, acceptedState);
+          return persist(tx);
+        },
+      );
       return c.redirect(
         slackInstallReturnUrl(baseUrl, state.returnPath, "connected", connection.id),
         302,
       );
     } catch (error) {
+      if (exactReturnUrl)
+        return new Response(null, { status: 302, headers: { Location: exactReturnUrl } });
       if (state) {
         const failure = slackInstallCallbackFailure(stage, error);
         try {
@@ -316,7 +665,12 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       }
       const reason = slackInstallErrorReason(error);
       return c.redirect(
-        slackInstallReturnUrl(baseUrl, state?.returnPath ?? "/integrations", "error", reason),
+        slackInstallReturnUrl(
+          baseUrl,
+          state?.returnPath ?? oauthStateFailureReturn(settings, c.req.query("state")).returnPath,
+          "error",
+          reason,
+        ),
         302,
       );
     }
@@ -328,80 +682,32 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/connections/fiken/install", async (c) => {
     assertIntegrationsEnabled();
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
-    const payload = FikenInstallRequest.parse(await c.req.json());
-    const key = requireEnvironmentEncryption(settings);
-    const existing = payload.connectionId
-      ? await getConnectionMetadata(db, workspaceId, payload.connectionId, null)
-      : null;
-    if (payload.connectionId && !existing) {
-      throw new HTTPException(404, { message: "connection not found" });
-    }
-    if (existing && !isFikenConnection(existing)) {
-      throw new HTTPException(422, { message: "connectionId is not a Fiken connection" });
-    }
-    const verified = await verifyFikenApiToken(payload.apiToken, deps.fikenFetch ?? fetch);
-    const previousDefault = existing
-      ? (fikenConnectionMetadata(existing.metadata)?.defaultCompanySlug ?? null)
-      : null;
-    const defaultCompanySlug = resolveFikenDefaultCompanySlug({
-      requested: payload.defaultCompanySlug ?? null,
-      previous: previousDefault,
-      companies: verified.companies,
-    });
-    if (payload.defaultCompanySlug && defaultCompanySlug !== payload.defaultCompanySlug) {
-      throw new HTTPException(422, {
-        message: `defaultCompanySlug is not among the companies this token can access: ${verified.companies
-          .map((company) => company.slug)
-          .join(", ")}`,
-      });
-    }
-    const metadata = {
-      credentialRole: FIKEN_CREDENTIAL_ROLE,
-      credentialLabel: FIKEN_CREDENTIAL_LABEL,
-      companies: verified.companies,
-      defaultCompanySlug,
-      verifiedAt: new Date().toISOString(),
-    };
-    const credentialEncrypted = encryptCredentialBundle(
-      key,
-      fikenCredentialBundle(payload.apiToken),
-    );
-    if (existing) {
-      // Rewrites the whole credential identity: a token pasted over an OAuth
-      // row must also flip kind and clear the OAuth expiry, or the broker
-      // keeps treating the api_key bundle as a refreshable oauth2 credential.
-      const updated = await updateConnection(db, {
-        workspaceId,
-        connectionId: existing.id,
-        visibleToSubjectId: null,
-        expectedVersion: existing.version,
-        kind: "api_key",
-        status: "active",
-        credentialEncrypted,
-        grantedScopes: [],
-        expiresAt: null,
-        metadata,
-        updatedBySubjectId: grant.subjectId,
-      });
-      if (!updated) {
-        throw new HTTPException(409, { message: "the Fiken connection changed; retry" });
-      }
-      return c.json(ConnectionResponse.parse({ connection: updated }));
-    }
-    const connection = await createConnection(db, {
-      accountId: grant.accountId,
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
       workspaceId,
-      subjectId: null,
-      providerDomain: FIKEN_PROVIDER_DOMAIN,
-      kind: "api_key",
-      credentialEncrypted,
-      grantedScopes: [],
-      expiresAt: null,
-      metadata,
-      createdBySubjectId: grant.subjectId,
-    });
-    return c.json(ConnectionResponse.parse({ connection }), 201);
+      "connections:write",
+    );
+    const grant = authorization.grant;
+    const payload = await parseRequestJson(c, FikenInstallRequest);
+    const persist = await prepareFikenTokenInstall(deps, grant, payload);
+    const continuation = externalActorContinuationForAuthorization(authorization);
+    const connection = await withOrganizationIntegrationAcquisition(
+      db,
+      { accountId: grant.accountId, workspaceId },
+      ["fiken"],
+      async (tx) => {
+        await requireConnectOwnerAuthority(tx, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          personalOwnerVerified: isPersonalConnectionOwnerPrincipal(authorization),
+          ...(continuation ? { externalContinuation: continuation } : {}),
+        });
+        return persist(tx);
+      },
+    );
+    return c.json(ConnectionResponse.parse({ connection }), payload.connectionId ? 200 : 201);
   });
 
   // Fiken OAuth (registered app) start. Both Fiken lanes produce the same
@@ -409,8 +715,10 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/connections/fiken/oauth/start", async (c) => {
     assertIntegrationsEnabled();
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
-    const payload = FikenOAuthStartRequest.parse(await c.req.json());
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    requireLegacyOAuthActor(access);
+    const grant = access.grant;
+    const payload = await parseRequestJson(c, FikenOAuthStartRequest);
     requireEnvironmentEncryption(settings);
     return c.json(
       FikenOAuthStartResponse.parse(
@@ -433,13 +741,20 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       ...(c.req.query("error") ? { error: c.req.query("error") } : {}),
       requestUrl: c.req.url,
     });
+    if (result.exactReturn)
+      return new Response(null, { status: 302, headers: { Location: result.redirectTo } });
     return c.redirect(result.redirectTo, 302);
   });
 
   app.post("/v1/workspaces/:workspaceId/connections/google-drive/install", async (c) => {
     assertIntegrationsEnabled();
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    // The Drive connector writes only a personal Connection, so only a managed
+    // human may start it.
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    assertPersonalConnectionOwnerPrincipal(access, "Google Drive");
+    requireLegacyOAuthActor(access);
+    const grant = access.grant;
     const parsed = GoogleDriveOAuthStartRequest.safeParse(await c.req.json());
     if (!parsed.success) {
       throw new HTTPException(400, { message: "invalid Google Drive install request" });
@@ -460,7 +775,12 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/connections/atlassian/install", async (c) => {
     assertIntegrationsEnabled();
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    // The Atlassian connector writes only a personal Connection, so only a
+    // managed human may start it.
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    assertPersonalConnectionOwnerPrincipal(access, "Atlassian");
+    requireLegacyOAuthActor(access);
+    const grant = access.grant;
     const parsed = AtlassianOAuthStartRequest.safeParse(await c.req.json());
     if (!parsed.success) {
       throw new HTTPException(400, { message: "invalid Atlassian install request" });
@@ -486,6 +806,8 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       ...(c.req.query("error") ? { error: c.req.query("error") } : {}),
       requestUrl: c.req.url,
     });
+    if (result.exactReturn)
+      return new Response(null, { status: 302, headers: { Location: result.redirectTo } });
     return c.redirect(result.redirectTo, 302);
   });
 
@@ -557,9 +879,12 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       ...(c.req.query("code") ? { code: c.req.query("code") } : {}),
       ...(c.req.query("state") ? { state: c.req.query("state") } : {}),
       ...(c.req.query("error") ? { error: c.req.query("error") } : {}),
+      ...(c.req.query("picked_file_ids") ? { pickedFileIds: c.req.query("picked_file_ids") } : {}),
       requestUrl: c.req.url,
     };
     const result = await completeGoogleDriveOAuthCallback(deps, input);
+    if (result.exactReturn)
+      return new Response(null, { status: 302, headers: { Location: result.redirectTo } });
     return c.redirect(result.redirectTo, 302);
   });
 
@@ -658,150 +983,351 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       "connections:write",
     );
     const { grant } = authorization;
-    const payload = UpdateConnectionRequest.parse(await c.req.json());
-    assertNotReservedSlackBotMetadata(payload.metadata);
-    assertNotReservedFikenMetadata(payload.metadata);
-    assertNotReservedApiIntegrationOAuthMetadata(payload.metadata);
-    const existing = await getConnectionMetadata(
+    const payload = await parseRequestJson(c, UpdateConnectionRequest);
+    // Policy first, then the existing tenancy prefix and exact credential row.
+    // The locked live identity makes unchanged/reducing updates safe against a
+    // concurrent replacement; all final writes below use this same transaction.
+    return withOrganizationIntegrationPolicyFence(
       db,
-      workspaceId,
-      c.req.param("connectionId"),
-      grant.subjectId,
-    );
-    if (existing && isOpenGeniSlackBotConnection(existing)) {
-      const destination = ConnectorDocumentDestinationSelection.safeParse(
-        payload.metadata?.documentDestination,
-      );
-      const destinationOnlyUpdate =
-        payload.metadata !== undefined &&
-        Object.keys(payload.metadata).length === 1 &&
-        payload.providerDomain === undefined &&
-        payload.subjectId === undefined &&
-        payload.kind === undefined &&
-        payload.status === undefined &&
-        payload.credential === undefined &&
-        payload.grantedScopes === undefined &&
-        payload.expiresAt === undefined;
-      if (!destination.success || !destinationOnlyUpdate) {
-        throw new HTTPException(422, {
-          message: "use the dedicated OpenGeni Slack bot reinstall flow to update this connection",
-        });
-      }
-      const destinationSelection = destination.data;
-      if (
-        destinationSelection.authorityKind === "organization" &&
-        authorization.accountGrant?.permissions.includes("account:admin") !== true
-      ) {
-        throw new HTTPException(403, { message: "missing permission: account:admin" });
-      }
-      if (
-        destinationSelection.authorityKind === "workspace" &&
-        !hasPermission(grant.permissions, "workspace:admin")
-      ) {
-        throw new HTTPException(403, { message: "missing permission: workspace:admin" });
-      }
-      if (
-        destinationSelection.authorityKind === "personal" &&
-        (!authorization.contextIntegrity ||
-          authorization.authenticatedSubjectId !== grant.subjectId)
-      ) {
-        throw new HTTPException(403, {
-          message: "personal destination requires the exact actor",
-        });
-      }
-      const metadata = {
-        ...existing.metadata,
-        documentDestination: bindConnectorDocumentDestination(destinationSelection, {
-          accountId: grant.accountId,
-          workspaceId,
-          initiatingSubjectId: grant.subjectId,
+      { accountId: grant.accountId, workspaceId },
+      (policyTx, policy) =>
+        // eslint-disable-next-line no-shadow -- every existing final writer must use this exact scoped transaction
+        withWorkspaceSubjectRls(policyTx, workspaceId, grant.subjectId, async (db) => {
+          const initial = await getConnectionMetadata(
+            db,
+            workspaceId,
+            c.req.param("connectionId"),
+            grant.subjectId,
+          );
+          if (
+            initial?.metadata.directModelProvider !== undefined ||
+            payload.metadata?.directModelProvider !== undefined ||
+            String(payload.metadata?.credentialRole ?? "").startsWith("direct_")
+          ) {
+            throw new HTTPException(422, {
+              message:
+                "Disconnect and reconnect OpenAI or Azure OpenAI to replace its key or deployment",
+            });
+          }
+          // Model-key rotation owns an advisory -> credential-row prefix. Do
+          // not take its row first or change that excluded lane's lock order.
+          if (!initial || !workspaceProviderApiKeyConnectionKind(initial)) {
+            await db.execute(
+              sql`select id from connections where workspace_id = ${workspaceId}::uuid and id = ${c.req.param("connectionId")}::uuid and (subject_id is null or subject_id = ${grant.subjectId}) for update`,
+            );
+          }
+          assertNotReservedSlackBotMetadata(payload.metadata);
+          assertNotReservedFikenMetadata(payload.metadata);
+          assertNotReservedApiIntegrationOAuthMetadata(payload.metadata);
+          assertNotReservedPersonalGitHubMetadata(payload.metadata);
+          const existing = await getConnectionMetadata(
+            db,
+            workspaceId,
+            c.req.param("connectionId"),
+            grant.subjectId,
+          );
+          if (existing && isOpenGeniSlackBotConnection(existing)) {
+            const destination = ConnectorDocumentDestinationSelection.safeParse(
+              payload.metadata?.documentDestination,
+            );
+            const destinationOnlyUpdate =
+              payload.metadata !== undefined &&
+              Object.keys(payload.metadata).length === 1 &&
+              payload.providerDomain === undefined &&
+              payload.subjectId === undefined &&
+              payload.kind === undefined &&
+              payload.status === undefined &&
+              payload.credential === undefined &&
+              payload.grantedScopes === undefined &&
+              payload.expiresAt === undefined;
+            if (!destination.success || !destinationOnlyUpdate) {
+              throw new HTTPException(422, {
+                message:
+                  "use the dedicated Opengeni Slack bot reinstall flow to update this connection",
+              });
+            }
+            const destinationSelection = destination.data;
+            if (
+              destinationSelection.authorityKind === "organization" &&
+              authorization.accountGrant?.permissions.includes("account:admin") !== true
+            ) {
+              throw new HTTPException(403, { message: "missing permission: account:admin" });
+            }
+            if (
+              destinationSelection.authorityKind === "workspace" &&
+              !hasPermission(grant.permissions, "workspace:admin")
+            ) {
+              throw new HTTPException(403, { message: "missing permission: workspace:admin" });
+            }
+            if (
+              destinationSelection.authorityKind === "personal" &&
+              (!authorization.contextIntegrity ||
+                authorization.authenticatedSubjectId !== grant.subjectId)
+            ) {
+              throw new HTTPException(403, {
+                message: "personal destination requires the exact actor",
+              });
+            }
+            const metadata = {
+              ...existing.metadata,
+              documentDestination: bindConnectorDocumentDestination(destinationSelection, {
+                accountId: grant.accountId,
+                workspaceId,
+                initiatingSubjectId: grant.subjectId,
+              }),
+            };
+            if (
+              stableJson(metadata.documentDestination) !==
+              stableJson(existing.metadata.documentDestination)
+            ) {
+              assertOrganizationIntegrationAllowed(policy, "slack-bot");
+            }
+            const connection = await updateSlackBotDocumentDestination(db, {
+              accountId: grant.accountId,
+              workspaceId,
+              connectionId: existing.id,
+              visibleToSubjectId: grant.subjectId,
+              expectedVersion: existing.version,
+              metadata,
+              updatedBySubjectId: grant.subjectId,
+            });
+            if (!connection) {
+              throw new HTTPException(409, {
+                message: "Slack bot connection changed; reload before saving its destination",
+              });
+            }
+            return c.json(ConnectionResponse.parse({ connection }));
+          }
+          if (existing && GoogleDriveConnectionMetadata.safeParse(existing.metadata).success) {
+            throw new HTTPException(422, {
+              message: "use the dedicated Google Drive reconnect or source-selection flow",
+            });
+          }
+          if (existing?.metadata.credentialRole === API_INTEGRATION_OAUTH_CREDENTIAL_ROLE) {
+            throw new HTTPException(422, {
+              message:
+                "use the dedicated Integration provider OAuth flow to update this connection",
+            });
+          }
+          if (existing && AtlassianConnectionMetadata.safeParse(existing.metadata).success) {
+            throw new HTTPException(422, {
+              message: "use the dedicated Atlassian reconnect or source-selection flow",
+            });
+          }
+          if (existing && isPersonalGitHubConnection(existing)) {
+            throw new HTTPException(422, {
+              message: "use the dedicated personal GitHub reconnect flow to update this connection",
+            });
+          }
+          if (existing) {
+            const providerDomain = canonicalProviderDomain(
+              payload.providerDomain ?? existing.providerDomain,
+            );
+            const kind = payload.kind ?? existing.kind;
+            const subjectId =
+              payload.subjectId === undefined
+                ? existing.subjectId
+                : writableSubjectId(payload.subjectId, grant.subjectId);
+            const targetWorkspaceProviderKind = workspaceProviderApiKeyConnectionKind({
+              subjectId,
+              providerDomain,
+              kind,
+              metadata: payload.metadata ?? existing.metadata,
+            });
+            if (!workspaceProviderApiKeyConnectionKind(existing) && targetWorkspaceProviderKind) {
+              throw new HTTPException(422, {
+                message:
+                  targetWorkspaceProviderKind === "vercel_gateway"
+                    ? "use the Vercel AI Gateway connect flow to create this connection"
+                    : "use the OpenRouter connect flow to create this connection",
+              });
+            }
+            assertNotDirectPersonalSlackOAuth(providerDomain, kind);
+            assertNotDirectGoogleDriveOAuth(
+              providerDomain,
+              kind,
+              payload.metadata ?? existing.metadata,
+            );
+            assertNotDirectAtlassianOAuth(
+              providerDomain,
+              kind,
+              payload.metadata ?? existing.metadata,
+            );
+            assertNotDirectPersonalGitHubOAuth(
+              providerDomain,
+              kind,
+              payload.metadata ?? existing.metadata,
+            );
+          }
+          // 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
+          // could clear the broker's re-auth signal while stale tokens stay in place.
+          if (payload.status !== undefined) {
+            if (payload.status !== "active") {
+              throw new HTTPException(400, {
+                message: 'status can only be set to "active"; use DELETE to revoke',
+              });
+            }
+            if (payload.credential === undefined) {
+              throw new HTTPException(400, {
+                message: "reactivating a connection requires a new credential",
+              });
+            }
+          }
+          const existingWorkspaceProviderKind = existing
+            ? workspaceProviderApiKeyConnectionKind(existing)
+            : null;
+          if (existing && existingWorkspaceProviderKind) {
+            const provider = workspaceProviderApiKeyConnectionSpec(existingWorkspaceProviderKind);
+            const providerDomain = canonicalProviderDomain(
+              payload.providerDomain ?? existing.providerDomain,
+            );
+            const subjectId =
+              payload.subjectId === undefined
+                ? existing.subjectId
+                : writableSubjectId(payload.subjectId, grant.subjectId);
+            const kind = payload.kind ?? existing.kind;
+            if (
+              subjectId !== null ||
+              providerDomain !== provider.providerDomain ||
+              kind !== "api_key" ||
+              (payload.metadata?.credentialRole !== undefined &&
+                payload.metadata.credentialRole !== provider.credentialRole)
+            ) {
+              throw new HTTPException(422, {
+                message: `${provider.label} connection identity cannot be changed`,
+              });
+            }
+            if (payload.credential === undefined) {
+              throw new HTTPException(400, {
+                message: `updating a ${provider.label} connection requires a new credential`,
+              });
+            }
+            if (payload.expectedVersion === undefined || payload.operationId === undefined) {
+              throw new HTTPException(400, {
+                message: `updating a ${provider.label} connection requires expectedVersion and operationId`,
+              });
+            }
+            payload.credential = prepareClaudeWorkspaceCredential(
+              settings,
+              workspaceId,
+              existing.metadata,
+              payload.credential,
+            );
+            assertClaudeWorkspaceCredential(settings, {
+              subjectId,
+              providerDomain,
+              kind,
+              metadata: existing.metadata,
+              credential: payload.credential,
+            });
+            const key = requireEnvironmentEncryption(settings);
+            const grantedScopes = payload.grantedScopes ?? existing.grantedScopes;
+            const expiresAt =
+              payload.expiresAt !== undefined
+                ? payload.expiresAt
+                  ? new Date(payload.expiresAt)
+                  : null
+                : existing.expiresAt
+                  ? new Date(existing.expiresAt)
+                  : null;
+            const metadata = workspaceProviderCredentialMetadata(existingWorkspaceProviderKind, {
+              ...existing.metadata,
+              ...(payload.metadata ?? {}),
+            });
+            const input = {
+              accountId: grant.accountId,
+              workspaceId,
+              connectionId: existing.id,
+              expectedVersion: payload.expectedVersion,
+              operationId: payload.operationId,
+              requestDigest: workspaceProviderCredentialRequestDigest(key, {
+                action: "rotate",
+                connectionId: existing.id,
+                expectedVersion: payload.expectedVersion,
+                credential: payload.credential,
+                grantedScopes,
+                expiresAt: expiresAt?.toISOString() ?? null,
+                metadata,
+              }),
+              credentialEncrypted: encryptCredentialBundle(key, payload.credential),
+              grantedScopes,
+              expiresAt,
+              metadata,
+              updatedBySubjectId: grant.subjectId,
+            };
+            const connection = await rotateWorkspaceProviderApiKeyConnection(
+              db,
+              existingWorkspaceProviderKind,
+              input,
+            );
+            if (!connection) {
+              throw new HTTPException(409, {
+                message: `${provider.label} connection changed; reload before replacing its key`,
+              });
+            }
+            return c.json(ConnectionResponse.parse({ connection }));
+          }
+          const key =
+            payload.credential === undefined ? null : requireEnvironmentEncryption(settings);
+          const subjectId =
+            payload.subjectId === undefined
+              ? undefined
+              : writableSubjectId(payload.subjectId, grant.subjectId);
+          if (
+            existing &&
+            (payload.credential !== undefined ||
+              (payload.providerDomain !== undefined &&
+                canonicalProviderDomain(payload.providerDomain) !== existing.providerDomain) ||
+              (payload.kind !== undefined && payload.kind !== existing.kind) ||
+              (subjectId !== undefined && subjectId !== existing.subjectId) ||
+              payload.grantedScopes?.some((scope) => !existing.grantedScopes.includes(scope)) ||
+              (payload.metadata !== undefined &&
+                ["mcpUrl", "resource", "credentialRole"].some(
+                  (field) =>
+                    stableJson(payload.metadata?.[field] ?? null) !==
+                    stableJson(existing.metadata[field] ?? null),
+                )) ||
+              (payload.expiresAt !== undefined &&
+                existing.expiresAt !== null &&
+                (payload.expiresAt === null ||
+                  Date.parse(payload.expiresAt) > Date.parse(existing.expiresAt))) ||
+              (payload.status === "active" && existing.status !== "active"))
+          ) {
+            assertOrganizationIntegrationAllowed(policy, null);
+          }
+          if (payload.credential !== undefined) {
+            assertBrokeredApiKeyCredential(payload.kind ?? existing?.kind, payload.credential);
+          }
+          const connection = await updateConnection(db, {
+            workspaceId,
+            connectionId: c.req.param("connectionId"),
+            visibleToSubjectId: grant.subjectId,
+            updatedBySubjectId: grant.subjectId,
+            ...(payload.providerDomain !== undefined
+              ? { providerDomain: canonicalProviderDomain(payload.providerDomain) }
+              : {}),
+            ...(subjectId !== undefined ? { subjectId } : {}),
+            ...(payload.kind !== undefined ? { kind: payload.kind } : {}),
+            ...(payload.status !== undefined ? { status: payload.status } : {}),
+            ...(payload.credential !== undefined && key
+              ? { credentialEncrypted: encryptCredentialBundle(key, payload.credential) }
+              : {}),
+            ...(payload.grantedScopes !== undefined
+              ? { grantedScopes: payload.grantedScopes }
+              : {}),
+            ...(payload.expiresAt !== undefined
+              ? { expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null }
+              : {}),
+            ...(payload.metadata !== undefined ? { metadata: payload.metadata } : {}),
+          });
+          if (!connection) {
+            throw new HTTPException(404, { message: "connection not found" });
+          }
+          return c.json(ConnectionResponse.parse({ connection }));
         }),
-      };
-      const connection = await updateSlackBotDocumentDestination(db, {
-        accountId: grant.accountId,
-        workspaceId,
-        connectionId: existing.id,
-        visibleToSubjectId: grant.subjectId,
-        expectedVersion: existing.version,
-        metadata,
-        updatedBySubjectId: grant.subjectId,
-      });
-      if (!connection) {
-        throw new HTTPException(409, {
-          message: "Slack bot connection changed; reload before saving its destination",
-        });
-      }
-      return c.json(ConnectionResponse.parse({ connection }));
-    }
-    if (existing && GoogleDriveConnectionMetadata.safeParse(existing.metadata).success) {
-      throw new HTTPException(422, {
-        message: "use the dedicated Google Drive reconnect or source-selection flow",
-      });
-    }
-    if (existing?.metadata.credentialRole === API_INTEGRATION_OAUTH_CREDENTIAL_ROLE) {
-      throw new HTTPException(422, {
-        message: "use the dedicated Integration provider OAuth flow to update this connection",
-      });
-    }
-    if (existing && AtlassianConnectionMetadata.safeParse(existing.metadata).success) {
-      throw new HTTPException(422, {
-        message: "use the dedicated Atlassian reconnect or source-selection flow",
-      });
-    }
-    if (existing) {
-      const providerDomain = canonicalProviderDomain(
-        payload.providerDomain ?? existing.providerDomain,
-      );
-      const kind = payload.kind ?? existing.kind;
-      assertNotDirectPersonalSlackOAuth(providerDomain, kind);
-      assertNotDirectGoogleDriveOAuth(providerDomain, kind, payload.metadata ?? existing.metadata);
-      assertNotDirectAtlassianOAuth(providerDomain, kind, payload.metadata ?? existing.metadata);
-    }
-    // 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
-    // could clear the broker's re-auth signal while stale tokens stay in place.
-    if (payload.status !== undefined) {
-      if (payload.status !== "active") {
-        throw new HTTPException(400, {
-          message: 'status can only be set to "active"; use DELETE to revoke',
-        });
-      }
-      if (payload.credential === undefined) {
-        throw new HTTPException(400, {
-          message: "reactivating a connection requires a new credential",
-        });
-      }
-    }
-    const key = payload.credential === undefined ? null : requireEnvironmentEncryption(settings);
-    const subjectId =
-      payload.subjectId === undefined
-        ? undefined
-        : writableSubjectId(payload.subjectId, grant.subjectId);
-    const connection = await updateConnection(db, {
-      workspaceId,
-      connectionId: c.req.param("connectionId"),
-      visibleToSubjectId: grant.subjectId,
-      updatedBySubjectId: grant.subjectId,
-      ...(payload.providerDomain !== undefined
-        ? { providerDomain: canonicalProviderDomain(payload.providerDomain) }
-        : {}),
-      ...(subjectId !== undefined ? { subjectId } : {}),
-      ...(payload.kind !== undefined ? { kind: payload.kind } : {}),
-      ...(payload.status !== undefined ? { status: payload.status } : {}),
-      ...(payload.credential !== undefined && key
-        ? { credentialEncrypted: encryptCredentialBundle(key, payload.credential) }
-        : {}),
-      ...(payload.grantedScopes !== undefined ? { grantedScopes: payload.grantedScopes } : {}),
-      ...(payload.expiresAt !== undefined
-        ? { expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null }
-        : {}),
-      ...(payload.metadata !== undefined ? { metadata: payload.metadata } : {}),
-    });
-    if (!connection) {
-      throw new HTTPException(404, { message: "connection not found" });
-    }
-    return c.json(ConnectionResponse.parse({ connection }));
+    );
   });
 
   app.delete("/v1/workspaces/:workspaceId/connections/:connectionId", async (c) => {
@@ -812,6 +1338,26 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!existing) {
       throw new HTTPException(404, { message: "connection not found" });
     }
+    const expectedVersion = c.req.query("expectedVersion");
+    if (expectedVersion !== undefined) {
+      if (!/^[1-9]\d*$/.test(expectedVersion) || !Number.isSafeInteger(Number(expectedVersion))) {
+        throw new HTTPException(400, { message: "invalid expected connection version" });
+      }
+      if (Number(expectedVersion) !== existing.version) {
+        throw new HTTPException(409, { message: "connection changed; refresh before disconnect" });
+      }
+    }
+    const isPersonalGitHub =
+      existing.subjectId === grant.subjectId && isPersonalGitHubConnection(existing);
+    if (isPersonalGitHub) {
+      const access = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "connections:write",
+      );
+      assertPersonalConnectionOwnerPrincipal(access, "My GitHub account");
+    }
     const isGoogleDrive =
       existing.subjectId === grant.subjectId &&
       existing.providerDomain === GOOGLE_DRIVE_PROVIDER_DOMAIN &&
@@ -822,6 +1368,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       existing.providerDomain === ATLASSIAN_PROVIDER_DOMAIN &&
       existing.kind === "oauth2" &&
       AtlassianConnectionMetadata.safeParse(existing.metadata).success;
+    const workspaceProviderKind = workspaceProviderApiKeyConnectionKind(existing);
     const disconnectPayload = await c.req.json().catch(() => null);
     const googleDriveDisconnect = isGoogleDrive
       ? GoogleDriveDisconnectRequest.safeParse(disconnectPayload)
@@ -842,7 +1389,23 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
           atlassianDisconnect.error.issues[0]?.message ?? "invalid Atlassian disconnect request",
       });
     }
-    if (existing.status === "revoked" && !isGoogleDrive && !isAtlassian) {
+    const personalGitHubDisconnect = isPersonalGitHub
+      ? PersonalGitHubDisconnectRequest.safeParse(disconnectPayload)
+      : null;
+    if (personalGitHubDisconnect && !personalGitHubDisconnect.success) {
+      throw new HTTPException(400, {
+        message:
+          personalGitHubDisconnect.error.issues[0]?.message ??
+          "invalid personal GitHub disconnect request",
+      });
+    }
+    if (
+      existing.status === "revoked" &&
+      !isGoogleDrive &&
+      !isAtlassian &&
+      !isPersonalGitHub &&
+      !workspaceProviderKind
+    ) {
       return c.json(ConnectionResponse.parse({ connection: existing }));
     }
     const connection = isGoogleDrive
@@ -859,24 +1422,39 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
             connection: existing,
             payload: atlassianDisconnect!.data,
           })
-        : isOpenGeniSlackBotConnection(existing)
-          ? await revokeConnectionWithSlackBotSuccessAudit(db, {
-              accountId: grant.accountId,
+        : isPersonalGitHub
+          ? await disconnectPersonalGitHub(deps, {
               workspaceId,
               subjectId: grant.subjectId,
               connectionId,
-              expectedVersion: existing.version,
-              credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
-              credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
-              slackTeamId: openGeniSlackBotMetadata(existing.metadata)!.slackTeamId,
+              payload: personalGitHubDisconnect!.data,
             })
-          : await revokeConnection(
-              db,
-              workspaceId,
-              connectionId,
-              grant.subjectId,
-              existing.version,
-            );
+          : isOpenGeniSlackBotConnection(existing)
+            ? await revokeConnectionWithSlackBotSuccessAudit(db, {
+                accountId: grant.accountId,
+                workspaceId,
+                subjectId: grant.subjectId,
+                connectionId,
+                expectedVersion: existing.version,
+                credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
+                credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
+                slackTeamId: openGeniSlackBotMetadata(existing.metadata)!.slackTeamId,
+              })
+            : workspaceProviderKind
+              ? await revokeWorkspaceProviderApiKeyConnections(db, workspaceProviderKind, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  connectionId,
+                  expectedVersion: existing.version,
+                  updatedBySubjectId: grant.subjectId,
+                })
+              : await revokeConnection(
+                  db,
+                  workspaceId,
+                  connectionId,
+                  grant.subjectId,
+                  existing.version,
+                );
     if (!connection) {
       throw new HTTPException(409, { message: "connection changed during disconnect; try again" });
     }
@@ -886,7 +1464,9 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/connections/oauth/start", async (c) => {
     assertIntegrationsEnabled();
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    requireProviderConsentInBrowser(access);
+    const grant = access.grant;
     const parsed = OAuthStartRequest.safeParse(await c.req.json());
     if (!parsed.success) {
       throw new HTTPException(400, {
@@ -897,9 +1477,13 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const result = await startMcpOAuth(
       { db, settings, observability, oauthStartDeadlineMs: deps.oauthStartDeadlineMs },
       {
+        ...(externalActorContinuationForAuthorization(access)
+          ? { externalContinuation: externalActorContinuationForAuthorization(access)! }
+          : {}),
         accountId: grant.accountId,
         workspaceId,
         subjectId: grant.subjectId,
+        personalOwnershipAllowed: isPersonalConnectionOwnerPrincipal(access),
         requestUrl: c.req.url,
         payload,
       },
@@ -910,7 +1494,9 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/integrations/oauth/start", async (c) => {
     assertIntegrationsEnabled();
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    requireProviderConsentInBrowser(access);
+    const grant = access.grant;
     const parsed = ApiIntegrationOAuthStartRequest.safeParse(await c.req.json());
     if (!parsed.success) {
       throw new HTTPException(400, {
@@ -920,9 +1506,13 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(
       OAuthStartResponse.parse(
         await startApiIntegrationProviderOAuth(deps, {
+          ...(externalActorContinuationForAuthorization(access)
+            ? { externalContinuation: externalActorContinuationForAuthorization(access)! }
+            : {}),
           accountId: grant.accountId,
           workspaceId,
           subjectId: grant.subjectId,
+          personalOwnershipAllowed: isPersonalConnectionOwnerPrincipal(access),
           requestUrl: c.req.url,
           payload: parsed.data,
         }),
@@ -932,15 +1522,24 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/integrations/oauth/callback", async (c) => {
     assertIntegrationsEnabled();
-    const result = await completeMcpOAuthCallback(
-      { db, settings, observability, oauthCallbackDeadlineMs: deps.oauthCallbackDeadlineMs },
-      {
-        code: c.req.query("code"),
-        state: c.req.query("state"),
-        requestUrl: c.req.url,
-      },
-    );
-    return c.redirect(result.redirectTo, 302);
+    const input = {
+      ...(c.req.query("code") ? { code: c.req.query("code") } : {}),
+      ...(c.req.query("state") ? { state: c.req.query("state") } : {}),
+      ...(c.req.query("error") ? { error: c.req.query("error") } : {}),
+      requestUrl: c.req.url,
+    };
+    const result = isApiIntegrationProviderOAuthState(input.state, deps.settings)
+      ? await completeApiIntegrationProviderOAuth(deps, input)
+      : await completeMcpOAuthCallback(
+          { db, settings, observability, oauthCallbackDeadlineMs: deps.oauthCallbackDeadlineMs },
+          input,
+        );
+    if ("exactReturn" in result && result.exactReturn)
+      return new Response(null, { status: 302, headers: { Location: result.redirectTo } });
+    const redirectTo = settings.webBaseUrl
+      ? new URL(result.redirectTo, settings.webBaseUrl).toString()
+      : result.redirectTo;
+    return c.redirect(redirectTo, 302);
   });
 
   app.get("/v1/integrations/provider-oauth/callback", async (c) => {
@@ -951,6 +1550,8 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       ...(c.req.query("error") ? { error: c.req.query("error") } : {}),
       requestUrl: c.req.url,
     });
+    if (result.exactReturn)
+      return new Response(null, { status: 302, headers: { Location: result.redirectTo } });
     return c.redirect(result.redirectTo, 302);
   });
 
@@ -999,7 +1600,7 @@ async function persistOpenGeniSlackBotConnection(input: {
     throw new SlackInstallCallbackError(
       422,
       "connection_conflict",
-      "connectionId is not an OpenGeni Slack bot connection",
+      "connectionId is not an Opengeni Slack bot connection",
       "principal_validation",
     );
   }
@@ -1067,21 +1668,6 @@ async function persistOpenGeniSlackBotConnection(input: {
   }
 }
 
-function requireOpenGeniSlackOAuthSettings(settings: ApiRouteDeps["settings"]): {
-  clientId: string;
-  clientSecret: string;
-} {
-  const clientId = settings.slackClientId?.trim();
-  const clientSecret = settings.slackClientSecret?.trim();
-  if (!clientId || !clientSecret) {
-    throw new HTTPException(503, {
-      message:
-        "OpenGeni Slack installation requires OPENGENI_SLACK_CLIENT_ID and OPENGENI_SLACK_CLIENT_SECRET",
-    });
-  }
-  return { clientId, clientSecret };
-}
-
 function readOpenGeniSlackInstallState(
   rawState: string | undefined,
   settings: ApiRouteDeps["settings"],
@@ -1096,6 +1682,11 @@ function readOpenGeniSlackInstallState(
   if (!payload) {
     throw new HTTPException(400, { message: "invalid or expired Slack installation state" });
   }
+  if (
+    (payload.kind !== undefined && payload.kind !== "slack_bot_install") ||
+    (payload.connectAttemptId && payload.kind !== "slack_bot_install")
+  )
+    throw new HTTPException(400, { message: "invalid Slack installation state kind" });
   const requiredString = (value: unknown, label: string): string => {
     if (typeof value !== "string" || value.length === 0) {
       throw new HTTPException(400, { message: `invalid Slack installation ${label}` });
@@ -1130,6 +1721,21 @@ function readOpenGeniSlackInstallState(
     workspaceId,
     subjectId,
     returnPath,
+    ...(typeof payload.connectAttemptId === "string"
+      ? { connectAttemptId: payload.connectAttemptId }
+      : {}),
+    ...(typeof payload.encryptedExternalContinuation === "string"
+      ? {
+          externalContinuation: ExternalActorContinuation.parse(
+            JSON.parse(
+              decryptEnvironmentValue(
+                requireEnvironmentEncryption(settings),
+                payload.encryptedExternalContinuation,
+              ),
+            ),
+          ),
+        }
+      : {}),
     ...(connectionId ? { connectionId, connectionVersion: connectionVersion! } : {}),
     nonce: requiredString(payload.nonce, "nonce"),
     iat:
@@ -1181,6 +1787,9 @@ function slackInstallCallbackFailure(
   if (error instanceof SlackBotLifecycleSuccessAuditError) {
     return { stage: "persistence", reason: "success_audit_failed" };
   }
+  if (stage === "permission_check" && error instanceof HTTPException && error.status === 403) {
+    return { stage, reason: "permission_lost" };
+  }
   if (stage === "code_exchange") {
     return { stage, reason: "exchange_failed" };
   }
@@ -1204,18 +1813,7 @@ async function requireSlackInstallCallbackGrant(
   db: ApiRouteDeps["db"],
   state: OpenGeniSlackInstallState,
 ): Promise<void> {
-  const grant = await getWorkspaceGrant(db, state.subjectId, state.workspaceId);
-  if (
-    !grant ||
-    grant.accountId !== state.accountId ||
-    !hasPermission(grant.permissions, "connections:write")
-  ) {
-    throw new SlackInstallCallbackError(
-      403,
-      "permission_lost",
-      "Slack installation subject no longer has permission for this workspace",
-    );
-  }
+  await requireConnectOwnerAuthority(db, state, "connections:write");
 }
 
 function assertNotDirectPersonalSlackOAuth(providerDomain: string, kind: string): void {
@@ -1256,10 +1854,78 @@ function assertNotDirectAtlassianOAuth(
   }
 }
 
+function assertNotDirectPersonalGitHubOAuth(
+  providerDomain: string,
+  kind: string,
+  metadata: Record<string, unknown> | undefined,
+): void {
+  if (
+    (providerDomain === PERSONAL_GITHUB_PROVIDER_DOMAIN && kind === "oauth2") ||
+    hasReservedPersonalGitHubMetadata(metadata)
+  ) {
+    throw new HTTPException(422, {
+      message: "personal GitHub credentials must use the dedicated OAuth connection flow",
+    });
+  }
+}
+
+function assertNotReservedPersonalGitHubMetadata(
+  metadata: Record<string, unknown> | undefined,
+): void {
+  if (hasReservedPersonalGitHubMetadata(metadata)) {
+    throw new HTTPException(422, {
+      message: "personal GitHub metadata is reserved for the dedicated OAuth connection flow",
+    });
+  }
+}
+
+function workspaceProviderApiKeyConnectionKind(input: {
+  subjectId?: string | null;
+  providerDomain: string;
+  kind: string;
+  metadata?: Record<string, unknown>;
+}): WorkspaceProviderApiKeyConnectionKind | null {
+  if (input.subjectId != null || input.kind !== "api_key") return null;
+  const providerDomain = input.providerDomain.toLowerCase();
+  if (
+    providerDomain === "api.anthropic.com" &&
+    (input.metadata?.credentialRole === "anthropic" ||
+      input.metadata?.credentialRole === "claude_subscription")
+  )
+    return input.metadata.credentialRole;
+  if (
+    providerDomain === VERCEL_AI_GATEWAY_CONNECTION_DOMAIN &&
+    input.metadata?.credentialRole === VERCEL_AI_GATEWAY_CONNECTION_ROLE
+  ) {
+    return "vercel_gateway";
+  }
+  if (
+    providerDomain === WORKSPACE_OPENROUTER_CONNECTION_DOMAIN &&
+    input.metadata?.credentialRole === WORKSPACE_OPENROUTER_CONNECTION_ROLE
+  ) {
+    return "openrouter";
+  }
+  return null;
+}
+
+/**
+ * A brokered api_key Connection is usable only through `headers` or
+ * `placements`; anything else was previously accepted and then failed every
+ * tool call with a misleading "connect an account" auth-needed notice.
+ */
+function assertBrokeredApiKeyCredential(
+  kind: string | undefined,
+  credential: Record<string, unknown>,
+): void {
+  if (kind !== "api_key") return;
+  const problem = brokeredCredentialBundleProblem(credential);
+  if (problem) throw new HTTPException(422, { message: problem });
+}
+
 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",
+      message: "Opengeni Slack bot metadata is reserved for the dedicated connection flow",
     });
   }
 }
@@ -1315,6 +1981,31 @@ function encryptCredentialBundle(key: Uint8Array, credential: Record<string, unk
   return encryptEnvironmentValue(key, JSON.stringify(credential));
 }
 
+function workspaceProviderCredentialMetadata(
+  providerKind: WorkspaceProviderApiKeyConnectionKind,
+  metadata: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const {
+    [OPENROUTER_CREDENTIAL_OPERATION_ID_METADATA_KEY]: _openRouterOperationId,
+    [OPENROUTER_CREDENTIAL_OPERATION_DIGEST_METADATA_KEY]: _openRouterOperationDigest,
+    [VERCEL_AI_GATEWAY_CREDENTIAL_OPERATION_ID_METADATA_KEY]: _operationId,
+    [VERCEL_AI_GATEWAY_CREDENTIAL_OPERATION_DIGEST_METADATA_KEY]: _operationDigest,
+    ...effectiveMetadata
+  } = metadata ?? {};
+  for (const role of ["anthropic", "claude_subscription"]) {
+    delete effectiveMetadata[`${role}CredentialOperationId`];
+    delete effectiveMetadata[`${role}CredentialOperationDigest`];
+  }
+  return {
+    ...effectiveMetadata,
+    credentialRole: workspaceProviderApiKeyConnectionSpec(providerKind).credentialRole,
+  };
+}
+
+function workspaceProviderCredentialRequestDigest(key: Uint8Array, value: unknown): string {
+  return createHmac("sha256", key).update(stableJson(value), "utf8").digest("hex");
+}
+
 function slackBotCredentialBundle(token: string): Record<string, unknown> {
   const headerName = ["author", "ization"].join("");
   const scheme = ["Bear", "er"].join("");