@opengeni/api-router 2.11.3 → 2.12.3-canary.0

package/src/integrations/personal-github.ts

@@ -1,4 +1,6 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { requireConnectOwnerAuthority } from "./connect-authority";
 import { personalGitHubOAuthCallbackUrl, type Settings } from "@opengeni/config";
 import {
   PERSONAL_GITHUB_AUTHORIZATION_URL,
@@ -14,22 +16,24 @@ import {
   isPersonalGitHubConnection,
 } from "@opengeni/contracts/personal-github";
 import {
-  hasPermission,
+  externalActorContinuationForAuthorization,
   requireEnvironmentEncryption,
   type AccessGrantAuthorization,
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
   consumeIntegrationOAuthStateNonce,
+  claimConnectOperation,
+  finishConnectOperation,
+  getConnectAttempt,
+  type Database,
   ConnectionDisconnectGenerationError,
   ConnectionDisconnectIdempotencyError,
   decryptEnvironmentValue,
   disconnectConnectionIdempotently,
   encryptEnvironmentValue,
   getConnectionMetadata,
-  getWorkspaceGrant,
   listConnectionsMetadata,
-  namedSubjectHasLiveWorkspaceAuthority,
   persistProviderOAuthConnection,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
@@ -53,6 +57,8 @@ const GITHUB_REQUEST_TIMEOUT_MS = 10_000;
 const GITHUB_API_VERSION = "2022-11-28";
 
 type PersonalGitHubOAuthState = {
+  connectAttemptId?: string;
+  externalContinuation?: ExternalActorContinuation;
   accountId: string;
   workspaceId: string;
   subjectId: string;
@@ -205,6 +211,7 @@ export async function startPersonalGitHubOAuth(
     workspaceId: string;
     connectionId?: string;
     returnPath?: string;
+    connectAttemptId?: string;
   },
 ) {
   const oauth = requirePersonalGitHubOAuthSettings(deps.settings);
@@ -232,6 +239,15 @@ export async function startPersonalGitHubOAuth(
     workspaceId: input.workspaceId,
     subjectId: grant.subjectId,
     kind: PERSONAL_GITHUB_OAUTH_STATE_KIND,
+    ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
+    ...(externalActorContinuationForAuthorization(input.access)
+      ? {
+          encryptedExternalContinuation: encryptEnvironmentValue(
+            key,
+            JSON.stringify(externalActorContinuationForAuthorization(input.access)),
+          ),
+        }
+      : {}),
     [PERSONAL_OWNER_VERIFIED_STATE_CLAIM]: true,
     canonicalManagedHumanSession: input.access.canonicalManagedHumanSession,
     returnPath,
@@ -264,12 +280,35 @@ export async function completePersonalGitHubOAuthCallback(
     error?: string;
     requestUrl: string;
   },
-): Promise<{ redirectTo: string }> {
+): Promise<{ redirectTo: string; exactReturn?: boolean }> {
   const apiBaseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
   const returnBaseUrl = deps.settings.webBaseUrl?.replace(/\/+$/u, "") ?? apiBaseUrl;
   let state: PersonalGitHubOAuthState | null = null;
+  let exactReturnUrl: string | undefined;
+  let operation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
   try {
     state = readPersonalGitHubOAuthState(input.state, deps.settings);
+    if (state.connectAttemptId) {
+      const stored = await getConnectAttempt(deps.db, state, state.connectAttemptId);
+      if (
+        stored.attempt.providerId !== "github-personal" ||
+        stored.attempt.ownership !== "personal"
+      )
+        throw new PersonalGitHubCallbackError("invalid_state");
+      exactReturnUrl = stored.returnUrl;
+      operation = {
+        attemptId: state.connectAttemptId,
+        operationId: `oauth:${state.nonce}`,
+        inputDigest: createHash("sha256").update(input.state!).digest("hex"),
+      };
+      const claim = await claimConnectOperation(deps.db, state, {
+        ...operation,
+        expectedRevision: stored.attempt.revision,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+      });
+      if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
+    }
     await requirePersonalGitHubCallbackGrant(deps, state);
     const consumed = await consumeIntegrationOAuthStateNonce(deps.db, {
       accountId: state.accountId,
@@ -280,6 +319,25 @@ export async function completePersonalGitHubOAuthCallback(
       now: new Date(),
     });
     if (!consumed) throw new PersonalGitHubCallbackError("state_replayed");
+    if (operation && (input.error || !input.code)) {
+      await finishConnectOperation(deps.db, state, {
+        ...operation,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        commit: async (_tx, current) => ({
+          ...current,
+          revision: current.revision + 1,
+          state: input.error === "access_denied" ? "cancelled" : "failed",
+          nextAction: { type: "none" },
+          error: {
+            code: input.error ? "provider_denied" : "missing_code",
+            message: "Authorization was not completed. Start a new connection attempt.",
+            retryable: false,
+          },
+        }),
+      });
+      return { redirectTo: exactReturnUrl!, exactReturn: true };
+    }
     if (input.error) throw new PersonalGitHubCallbackError("provider_denied");
     if (!input.code) throw new PersonalGitHubCallbackError("missing_code");
 
@@ -376,35 +434,73 @@ export async function completePersonalGitHubOAuthCallback(
         scope_parameter_supported: false,
       }),
     );
-    const connection = await persistProviderOAuthConnection(deps.db, {
-      accountId: state.accountId,
-      workspaceId: state.workspaceId,
-      subjectId: state.subjectId,
-      visibleToSubjectId: state.subjectId,
-      providerDomain: PERSONAL_GITHUB_PROVIDER_DOMAIN,
-      kind: "oauth2",
-      status: "active",
-      credentialEncrypted,
-      grantedScopes: token.scopes,
-      expiresAt: token.expiresAt,
-      metadata,
-      createdBySubjectId: state.subjectId,
-      updatedBySubjectId: state.subjectId,
-      credentialRole: PERSONAL_GITHUB_CREDENTIAL_ROLE,
-      providerFamily: PERSONAL_GITHUB_PROVIDER_FAMILY,
-      providerPrincipalId: identity.id,
-      requireLiveUserAuthority: true,
-      requiredLiveUserPermission: "connections:write",
-      allowCanonicalPersonalWorkspaceOwner: state.canonicalManagedHumanSession,
-      exclusiveProviderPrincipalPerOwner: true,
-      preserveExistingMetadataKeys: ["credentialBindingId", "connectedAt"],
-      ...(state.connectionId
-        ? {
-            requestedConnectionId: state.connectionId,
-            requestedConnectionVersion: state.connectionVersion,
-          }
-        : {}),
-    });
+    const acceptedState = state;
+    const persist = (tx: Database) => {
+      // Capture the validated immutable callback state for delayed persistence.
+      // eslint-disable-next-line no-shadow
+      const state = acceptedState;
+      return persistProviderOAuthConnection(tx, {
+        accountId: state.accountId,
+        workspaceId: state.workspaceId,
+        subjectId: state.subjectId,
+        visibleToSubjectId: state.subjectId,
+        providerDomain: PERSONAL_GITHUB_PROVIDER_DOMAIN,
+        kind: "oauth2",
+        status: "active",
+        credentialEncrypted,
+        grantedScopes: token.scopes,
+        expiresAt: token.expiresAt,
+        metadata,
+        createdBySubjectId: state.subjectId,
+        updatedBySubjectId: state.subjectId,
+        credentialRole: PERSONAL_GITHUB_CREDENTIAL_ROLE,
+        providerFamily: PERSONAL_GITHUB_PROVIDER_FAMILY,
+        providerPrincipalId: identity.id,
+        requireLiveUserAuthority: true,
+        requiredLiveUserPermission: "connections:write",
+        // The external lane has passed its own owning-user proof; it does not
+        // impersonate a native login. Both use the same personal workspace anchor.
+        allowCanonicalPersonalWorkspaceOwner:
+          state.canonicalManagedHumanSession || Boolean(state.externalContinuation),
+        authorize: (locked) => requireConnectOwnerAuthority(locked, state, "connections:write"),
+        exclusiveProviderPrincipalPerOwner: true,
+        preserveExistingMetadataKeys: ["credentialBindingId", "connectedAt"],
+        ...(state.connectionId
+          ? {
+              requestedConnectionId: state.connectionId,
+              requestedConnectionVersion: state.connectionVersion,
+            }
+          : {}),
+      });
+    };
+    if (operation) {
+      await finishConnectOperation(deps.db, acceptedState, {
+        ...operation,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
+        commit: async (tx, current) => {
+          const connection = await persist(tx);
+          if (!connection) throw new PersonalGitHubCallbackError("connection_conflict");
+          return {
+            ...current,
+            revision: current.revision + 1,
+            state: "complete",
+            credentialsCommitted: true,
+            nextAction: { type: "none" },
+            account: {
+              id: connection.id,
+              version: connection.version,
+              providerId: "github-personal",
+              label: identity.login,
+              ownership: "personal",
+              status: "connected",
+            },
+          };
+        },
+      });
+      return { redirectTo: exactReturnUrl!, exactReturn: true };
+    }
+    const connection = await persist(deps.db);
     if (!connection) throw new PersonalGitHubCallbackError("connection_conflict");
     return {
       redirectTo: personalGitHubCallbackReturnUrl(returnBaseUrl, state.returnPath, "success", {
@@ -412,6 +508,7 @@ export async function completePersonalGitHubOAuthCallback(
       }),
     };
   } catch (error) {
+    if (exactReturnUrl) return { redirectTo: exactReturnUrl, exactReturn: true };
     return {
       redirectTo: personalGitHubCallbackReturnUrl(
         returnBaseUrl,
@@ -468,6 +565,21 @@ function readPersonalGitHubOAuthState(
     subjectId: requiredString(payload.subjectId),
     personalOwnerVerified: personalOwnerVerifiedInState(payload),
     canonicalManagedHumanSession: payload.canonicalManagedHumanSession === true,
+    ...(typeof payload.connectAttemptId === "string"
+      ? { connectAttemptId: payload.connectAttemptId }
+      : {}),
+    ...(typeof payload.encryptedExternalContinuation === "string"
+      ? {
+          externalContinuation: ExternalActorContinuation.parse(
+            JSON.parse(
+              decryptEnvironmentValue(
+                requireEnvironmentEncryption(settings),
+                payload.encryptedExternalContinuation,
+              ),
+            ),
+          ),
+        }
+      : {}),
     returnPath: personalGitHubReturnPath(workspaceId, requiredString(payload.returnPath)),
     encryptedPkceVerifier: requiredString(payload.encryptedPkceVerifier),
     oauthEnvironment: requiredString(payload.oauthEnvironment),
@@ -491,25 +603,7 @@ async function requirePersonalGitHubCallbackGrant(
   ) {
     throw new PersonalGitHubCallbackError("not_authorized");
   }
-  const grant = await getWorkspaceGrant(deps.db, state.subjectId, state.workspaceId);
-  if (
-    grant &&
-    grant.accountId === state.accountId &&
-    hasPermission(grant.permissions, "connections:write")
-  ) {
-    return;
-  }
-  if (
-    state.canonicalManagedHumanSession &&
-    (await namedSubjectHasLiveWorkspaceAuthority(deps.db, {
-      accountId: state.accountId,
-      workspaceId: state.workspaceId,
-      subjectId: state.subjectId,
-    }))
-  ) {
-    return;
-  }
-  throw new PersonalGitHubCallbackError("not_authorized");
+  await requireConnectOwnerAuthority(deps.db, state, "connections:write");
 }
 
 async function exchangePersonalGitHubAuthorizationCode(

package/src/integrations/provider-oauth.ts

@@ -18,16 +18,18 @@ import {
   type ApiIntegrationOAuthStartRequest,
   type ConnectionOwnership,
 } from "@opengeni/contracts";
-import { hasPermission, requireEnvironmentEncryption, type ApiRouteDeps } from "@opengeni/core";
+import { requireEnvironmentEncryption, type ApiRouteDeps } from "@opengeni/core";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import {
   consumeIntegrationOAuthStateNonce,
   decryptEnvironmentValue,
   encryptEnvironmentValue,
   getConnectionMetadata,
-  getWorkspaceGrant,
   loadConnectionCredentialForBroker,
   persistProviderOAuthConnection,
-  resolveNamedManagedPersonalWorkspaceGrant,
+  getConnectAttempt,
+  claimConnectOperation,
+  finishConnectOperation,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
 import {
@@ -37,6 +39,7 @@ import {
   type FetchLike,
 } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
+import { requireConnectOwnerAuthority } from "./connect-authority";
 
 import {
   assertConnectionOwnershipAllowedForPrincipal,
@@ -69,6 +72,8 @@ type ProviderOAuthClient = {
 };
 
 type ProviderOAuthState = {
+  connectAttemptId?: string;
+  externalContinuation?: ExternalActorContinuation;
   accountId: string;
   workspaceId: string;
   subjectId: string;
@@ -137,6 +142,8 @@ export async function startApiIntegrationProviderOAuth(
      * route from the live authenticated principal, never inferred here.
      */
     personalOwnershipAllowed: boolean;
+    externalContinuation?: ExternalActorContinuation;
+    connectAttemptId?: string;
     requestUrl: string;
     payload: ApiIntegrationOAuthStartRequest;
   },
@@ -230,6 +237,15 @@ export async function startApiIntegrationProviderOAuth(
     clientId: client.clientId,
     tokenEndpointAuthMethod: client.tokenEndpointAuthMethod,
     returnPath,
+    ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
+    ...(input.externalContinuation
+      ? {
+          encryptedExternalContinuation: encryptEnvironmentValue(
+            key,
+            JSON.stringify(ExternalActorContinuation.parse(input.externalContinuation)),
+          ),
+        }
+      : {}),
     ...(existing
       ? {
           connectionId: existing.id,
@@ -270,12 +286,35 @@ export async function completeApiIntegrationProviderOAuth(
     error?: string | undefined;
     requestUrl: string;
   },
-): Promise<{ redirectTo: string }> {
+): Promise<{ redirectTo: string; exactReturn?: boolean }> {
   const apiBaseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
   const returnBaseUrl = deps.settings.webBaseUrl?.replace(/\/+$/, "") ?? apiBaseUrl;
   let state: ProviderOAuthState | null = null;
+  let exactReturnUrl: string | undefined;
+  let connectOperation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
   try {
     state = readProviderOAuthState(input.state, deps.settings);
+    if (state.connectAttemptId) {
+      const stored = await getConnectAttempt(deps.db, state, state.connectAttemptId);
+      if (
+        stored.attempt.providerId !== state.definitionId ||
+        stored.attempt.ownership !== state.ownership
+      )
+        throw new ProviderOAuthCallbackError("state_invalid");
+      exactReturnUrl = stored.returnUrl;
+      connectOperation = {
+        attemptId: state.connectAttemptId,
+        operationId: `oauth:${state.nonce}`,
+        inputDigest: createHash("sha256").update(input.state!).digest("hex"),
+      };
+      const claim = await claimConnectOperation(deps.db, state, {
+        ...connectOperation,
+        expectedRevision: stored.attempt.revision,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+      });
+      if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
+    }
     requireProviderOAuthOwner(state);
     await requireProviderOAuthGrant(deps, state);
     const consumed = await consumeIntegrationOAuthStateNonce(deps.db, {
@@ -287,6 +326,25 @@ export async function completeApiIntegrationProviderOAuth(
       now: new Date(),
     });
     if (!consumed) throw new ProviderOAuthCallbackError("state_replayed");
+    if (connectOperation && (input.error || !input.code)) {
+      await finishConnectOperation(deps.db, state, {
+        ...connectOperation,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        commit: async (_tx, current) => ({
+          ...current,
+          revision: current.revision + 1,
+          state: input.error === "access_denied" ? "cancelled" : "failed",
+          nextAction: { type: "none" },
+          error: {
+            code: input.error ? "provider_denied" : "missing_code",
+            message: "Authorization was not completed. Start a new connection attempt.",
+            retryable: false,
+          },
+        }),
+      });
+      return { redirectTo: exactReturnUrl!, exactReturn: true };
+    }
     if (input.error) throw new ProviderOAuthCallbackError("provider_denied");
     if (!input.code) throw new ProviderOAuthCallbackError("missing_code");
 
@@ -389,7 +447,8 @@ export async function completeApiIntegrationProviderOAuth(
       ]),
       verifiedAt: new Date().toISOString(),
     });
-    const connection = await persistProviderOAuthConnection(deps.db, {
+    const persistenceInput: import("@opengeni/db").PersistProviderOAuthConnectionInput = {
+      authorize: (tx: import("@opengeni/db").Database) => requireConnectOwnerAuthority(tx, state!),
       accountId: state.accountId,
       workspaceId: state.workspaceId,
       subjectId: ownerSubjectId,
@@ -412,7 +471,36 @@ export async function completeApiIntegrationProviderOAuth(
             requestedConnectionVersion: state.connectionVersion,
           }
         : {}),
-    });
+    };
+    const persist = (database: import("@opengeni/db").Database) =>
+      persistProviderOAuthConnection(database, persistenceInput);
+    if (connectOperation) {
+      await finishConnectOperation(deps.db, state, {
+        ...connectOperation,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        commit: async (tx, current) => {
+          const connection = await persist(tx);
+          if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
+          return {
+            ...current,
+            revision: current.revision + 1,
+            state: "connected_but_incomplete",
+            credentialsCommitted: true,
+            nextAction: { type: "none" },
+            account: {
+              id: connection.id,
+              providerId: current.providerId,
+              label: identity.displayName ?? identity.email ?? identity.principalId,
+              ownership: current.ownership,
+              status: "connected",
+            },
+          };
+        },
+      });
+      return { redirectTo: exactReturnUrl!, exactReturn: true };
+    }
+    const connection = await persist(deps.db);
     if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
     return {
       redirectTo: providerOAuthReturnUrl(returnBaseUrl, state.returnPath, "success", {
@@ -423,6 +511,7 @@ export async function completeApiIntegrationProviderOAuth(
       }),
     };
   } catch (error) {
+    if (exactReturnUrl !== undefined) return { redirectTo: exactReturnUrl, exactReturn: true };
     return {
       redirectTo: providerOAuthReturnUrl(
         returnBaseUrl,
@@ -465,6 +554,26 @@ function requiredDefinition(id: string): IntegrationDefinition {
   return definition;
 }
 
+/** Configuration readiness only: consent and installation are still separate. */
+export function curatedOAuthReadiness(
+  settings: Settings,
+  definition: IntegrationDefinition,
+): { configured: boolean; ownership: ConnectionOwnership[] } {
+  const ownership = [
+    ...providerOAuthProfile(definition, integrationDefinitionProviderDomain(definition))
+      .allowedOwnership,
+  ];
+  try {
+    if (!settings.integrationsEnabled) return { configured: false, ownership };
+    requireEnvironmentEncryption(settings);
+    requireIntegrationsStateSecret(settings);
+    providerClientForDefinition(settings, definition);
+    return { configured: true, ownership };
+  } catch {
+    return { configured: false, ownership };
+  }
+}
+
 function providerClientForDefinition(
   settings: Settings,
   definition: IntegrationDefinition,
@@ -594,6 +703,21 @@ function readProviderOAuthState(raw: string | undefined, settings: Settings): Pr
   }
   return {
     accountId: requiredStateString(payload.accountId),
+    ...(optionalString(payload.connectAttemptId)
+      ? { connectAttemptId: optionalString(payload.connectAttemptId)! }
+      : {}),
+    ...(typeof payload.encryptedExternalContinuation === "string"
+      ? {
+          externalContinuation: ExternalActorContinuation.parse(
+            JSON.parse(
+              decryptEnvironmentValue(
+                requireEnvironmentEncryption(settings),
+                payload.encryptedExternalContinuation,
+              ),
+            ),
+          ),
+        }
+      : {}),
     workspaceId: requiredStateString(payload.workspaceId),
     subjectId: requiredStateString(payload.subjectId),
     ownership,
@@ -742,23 +866,10 @@ async function requireProviderOAuthGrant(
   deps: ApiRouteDeps,
   state: Pick<
     ProviderOAuthState,
-    "accountId" | "workspaceId" | "subjectId" | "personalOwnerVerified"
+    "accountId" | "workspaceId" | "subjectId" | "personalOwnerVerified" | "externalContinuation"
   >,
 ): Promise<void> {
-  const membershipGrant = await getWorkspaceGrant(deps.db, state.subjectId, state.workspaceId);
-  const grant =
-    membershipGrant?.accountId === state.accountId
-      ? membershipGrant
-      : state.personalOwnerVerified
-        ? await resolveNamedManagedPersonalWorkspaceGrant(deps.db, state)
-        : null;
-  if (
-    !grant ||
-    grant.accountId !== state.accountId ||
-    !hasPermission(grant.permissions, "connections:write")
-  ) {
-    throw new ProviderOAuthCallbackError("connection_conflict");
-  }
+  await deps.db.transaction((tx) => requireConnectOwnerAuthority(tx, state));
 }
 
 /**

package/src/integrations/slack-install.ts

@@ -0,0 +1,83 @@
+import {
+  OpenGeniSlackBotInstallStart,
+  OPENGENI_SLACK_BOT_REQUESTED_SCOPES,
+} from "@opengeni/contracts";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import {
+  isOpenGeniSlackBotConnection,
+  requireEnvironmentEncryption,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import { encryptEnvironmentValue, getConnectionMetadata } from "@opengeni/db";
+import { createSignedState } from "@opengeni/github";
+import { HTTPException } from "hono/http-exception";
+import {
+  integrationBaseUrl,
+  oauthStateTtlMs,
+  requireIntegrationsStateSecret,
+} from "./oauth-client";
+
+export function requireOpenGeniSlackOAuthSettings(settings: ApiRouteDeps["settings"]) {
+  const clientId = settings.slackClientId?.trim();
+  const clientSecret = settings.slackClientSecret?.trim();
+  if (!clientId || !clientSecret || !settings.slackSigningSecret?.trim())
+    throw new HTTPException(503, {
+      message:
+        "OpenGeni Slack bot installation requires OPENGENI_SLACK_CLIENT_ID, OPENGENI_SLACK_CLIENT_SECRET, and OPENGENI_SLACK_SIGNING_SECRET",
+    });
+  return { clientId, clientSecret };
+}
+
+/** Only authenticated route admission may invoke this workspace-bot starter.
+ * Hosted personal Slack MCP deliberately uses its own OAuth profile. */
+export async function startSlackBotInstall(
+  deps: ApiRouteDeps,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    requestUrl: string;
+    connectionId?: string;
+    connectAttemptId?: string;
+    externalContinuation?: ExternalActorContinuation;
+  },
+) {
+  const slack = requireOpenGeniSlackOAuthSettings(deps.settings);
+  const key = requireEnvironmentEncryption(deps.settings);
+  const existing = input.connectionId
+    ? await getConnectionMetadata(deps.db, input.workspaceId, input.connectionId, input.subjectId)
+    : null;
+  if (input.connectionId && !existing)
+    throw new HTTPException(404, { message: "connection not found" });
+  if (existing && !isOpenGeniSlackBotConnection(existing))
+    throw new HTTPException(422, {
+      message: "connectionId is not an OpenGeni Slack bot connection",
+    });
+  const redirectUri = `${integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl)}/v1/integrations/slack/callback`;
+  const state = createSignedState(requireIntegrationsStateSecret(deps.settings), {
+    kind: "slack_bot_install",
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    returnPath: `/workspaces/${input.workspaceId}/capabilities`,
+    ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
+    ...(input.externalContinuation
+      ? {
+          encryptedExternalContinuation: encryptEnvironmentValue(
+            key,
+            JSON.stringify(ExternalActorContinuation.parse(input.externalContinuation)),
+          ),
+        }
+      : {}),
+    ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
+  });
+  const url = new URL("https://slack.com/oauth/v2/authorize");
+  url.searchParams.set("client_id", slack.clientId);
+  url.searchParams.set("scope", OPENGENI_SLACK_BOT_REQUESTED_SCOPES.join(","));
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("state", state);
+  return OpenGeniSlackBotInstallStart.parse({
+    authorizationUrl: url.toString(),
+    expiresAt: new Date(Date.now() + oauthStateTtlMs).toISOString(),
+  });
+}