@open-everywhere/provider-slack 0.1.3 → 0.1.4

package/agent/setup/page.ts

@@ -0,0 +1,579 @@
+// `/setup` — THE AGENT-LED SLACK INSTALL (OPE-2231), as four screens on two routes.
+//
+// WHAT IT REPLACES. Before this, standing a deployment up on Slack meant: fetch the manifest from an
+// ops tool, paste it into api.slack.com, click through five screens, copy two secrets back out, set
+// them as environment variables, redeploy, then hand-edit two config files. Every step moved a
+// SECRET through a human's clipboard and a hosting dashboard. Here the secrets go browser → Slack →
+// this deployment and stop; the operator pastes ONE short-lived token and reads back two config
+// lines that contain no secret at all.
+//
+// THE ROUTES. Two, and the split is the OAuth round trip rather than taste:
+//
+//   GET  /setup           render whichever screen this deployment is up to
+//   POST /setup           screen 1 submits the setup code; screen 2 submits the config token
+//   GET  /setup/callback  Slack's install redirect lands here with `code` + `state`
+//
+// THE SCREENS, and what the deployment has to be true for each:
+//
+//   1. CLAIM        no valid cookie            → ask for the setup code (claim.ts)
+//   2. CREATE       cookie, no pending app     → ask for the app configuration token
+//   3. INSTALL      cookie, a pending app      → the one link to Slack's authorize URL
+//   4. DONE         rendered by the callback   → the two config edits, filled in, and "DM the bot"
+//
+// 🔴 EVERY FAILURE REACHABLE WITHOUT THE CLAIM COOKIE RENDERS ONE OF TWO PAGES, and neither says
+// which. A locked deployment, an absent credential key, a wrong setup code, a missing cookie, a
+// replayed `state` and a Slack refusal are not distinguishable from outside — the posture
+// `credentials/intake-page.ts` takes, for the same reason: an unauthenticated holder must not be able
+// to probe this route for what exists. The two are a 404 (this route is not available to you) and a
+// Slack-refusal page carrying Slack's own error CODE (the operator needs that one to act, and Slack's
+// codes are a closed vocabulary that discloses nothing about this deployment).
+//
+// A CLAIMED run also sees two 500s, and the scoping above is deliberate rather than an oversight: both
+// name a DEPLOYMENT MISCONFIGURATION this operator has to fix (no discoverable public URL; the
+// credential store unwritable) and neither says anything about Slack or about what is stored. They are
+// reachable only with a valid cookie, so no prober reaches them.
+//
+// 🔴 NO SECRET IS EVER RENDERED, RE-RENDERED OR ECHOED. The form fields are write-only: a submitted
+// setup code and a submitted config token are compared or spent and then dropped, and a re-rendered
+// form after a failure comes back EMPTY. Screen 4's copy-paste block is ids only. The page sends
+// `cache-control: no-store` and `referrer-policy: no-referrer` through core's shared chrome. Screen 3
+// carries the one OUTBOUND LINK on any page using that chrome (Slack's authorize URL), and the header
+// is what keeps THIS page's own URL out of the `Referer` that click sends to slack.com — not, as an
+// earlier draft of this comment said, what keeps the authorize URL itself secret; that URL goes to
+// Slack by design.
+
+import {
+  BUTTON_STYLE,
+  CODE_BLOCK_STYLE,
+  appendAudit,
+  credentialKeyArmed,
+  deploymentOrg,
+  encryptedKvVault,
+  escapeHtml,
+  pageBaseUrl,
+  securePageResponse,
+  SLACK_APP_REF_NAMESPACE,
+  type EncryptedKvVault,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { SLACK_DEPLOY_HOST_PLACEHOLDER, slackAppManifestTemplate, slackAppNameProblem } from "../app-manifest.js";
+import {
+  SETUP_COOKIE_NAME,
+  mintSetupCookie,
+  setupCodeMatches,
+  setupCookieFrom,
+  setupCookieHeader,
+  slackSetupOpen,
+  verifySetupCookie,
+  type SlackClaimDeps,
+} from "./claim.js";
+import {
+  SLACK_BOT_TOKEN_REF,
+  SLACK_CLIENT_SECRET_REF,
+  SLACK_COOKIE_KEY_REF,
+  SLACK_PENDING_REF,
+  SLACK_PENDING_SIGNING_SECRET_REF,
+  SLACK_SETUP_CODE_REF,
+  SLACK_SIGNING_SECRET_REF,
+  recordSlackInstall,
+  type SlackInstallState,
+} from "./install-state.js";
+import { createSlackApp, exchangeSlackOauthCode, SlackSetupApiError } from "./slack-api-setup.js";
+
+/** The page's route path. */
+export const SLACK_SETUP_PATH = "/setup";
+/** The OAuth install redirect's path. Declared in the shipped manifest's `oauth_config.redirect_urls`. */
+export const SLACK_SETUP_CALLBACK_PATH = "/setup/callback";
+
+/** Form field names. One letter each, because they ride a POST body and read nowhere else. */
+const FIELD_CODE = "c";
+const FIELD_CONFIG_TOKEN = "t";
+const FIELD_APP_NAME = "n";
+const FIELD_ACTION = "a";
+
+/**
+ * The audit action a completed install writes.
+ *
+ * 🔴 THE EXISTING VOCABULARY, NOT A NEW NAME. `surface.app_installed` is already declared and already
+ * means "this app was installed on a surface" — the Discord bundle emits it off Slack's
+ * `APPLICATION_AUTHORIZED` equivalent. A `/setup` install is that same fact with a different
+ * provenance (this deployment did it, rather than a vendor webhook telling us), and the repo's
+ * one-word-one-meaning rule says a second spelling for one fact is how a wrong claim survives review.
+ */
+const SLACK_SETUP_INSTALLED = "surface.app_installed";
+
+/**
+ * The app `apps.manifest.create` made, between the create and the OAuth callback.
+ *
+ * 🔴 NO CLIENT SECRET HERE. The secret went straight into its own vault ref on screen 2; this record
+ * carries only what the callback needs to FIND it, plus the `state` nonce. A pending record is the
+ * one thing on this page's path that an abandoned run leaves behind, so it is also the thing most
+ * likely to be read by a later run — keeping it secret-free means a stale one discloses nothing.
+ */
+interface PendingSlackApp {
+  readonly v: 1;
+  readonly appId: string;
+  readonly clientId: string;
+  /** The CSRF nonce the authorize URL carries and the callback must match. */
+  readonly state: string;
+  readonly startedAt: string;
+}
+
+/** Injectable seams for the suite. */
+export interface SlackSetupPageDeps extends SlackClaimDeps {
+  readonly vault?: EncryptedKvVault;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly createApp?: typeof createSlackApp;
+  readonly exchangeCode?: typeof exchangeSlackOauthCode;
+  readonly keyArmed?: () => boolean;
+}
+
+function vaultOf(deps: SlackSetupPageDeps): EncryptedKvVault {
+  return deps.vault ?? encryptedKvVault();
+}
+
+// --- the two failure renders ------------------------------------------------------------------------
+
+/** The ONE generic refusal. Identical copy for every reason — see the header. */
+function notAvailable(): Response {
+  return securePageResponse(
+    404,
+    "Not available",
+    `<p>This page is not available on this deployment.</p>` +
+      `<p>If Slack is already installed here, setup is closed. An administrator can reopen it with the ` +
+      `<code>reopen_slack_setup</code> control call.</p>`,
+  );
+}
+
+/** Slack said no. Carries Slack's own error code and nothing of ours. */
+function slackRefused(code: string): Response {
+  return securePageResponse(
+    400,
+    "Slack refused the request",
+    `<p>Slack answered: <code>${escapeHtml(code)}</code></p>` +
+      `<p>The most common cause is an app configuration token that has expired — they last about 12 hours. ` +
+      `Get a fresh one at <code>api.slack.com/apps</code> → "Your App Configuration Tokens", then start again.</p>` +
+      `<p><a href="${escapeHtml(SLACK_SETUP_PATH)}">Back to setup</a></p>`,
+  );
+}
+
+// --- the deployment's own host --------------------------------------------------------------------
+
+/**
+ * This deployment's public base URL, or `undefined` when it cannot be discovered.
+ *
+ * Undiscoverable is a REFUSAL here, not a placeholder: a manifest created with the wrong host gives
+ * Slack a request URL that answers nothing, and the operator finds out when the app silently never
+ * delivers an event. Core owns the precedence (`OE_PUBLIC_BASE_URL` → `VERCEL_PROJECT_PRODUCTION_URL`
+ * → `VERCEL_URL`), so this page cannot answer a different host than the links core mints.
+ */
+function baseUrl(deps: SlackSetupPageDeps): string | undefined {
+  return pageBaseUrl(deps.env ?? process.env);
+}
+
+/** The manifest, with this deployment's host substituted for the shipped placeholder. */
+function manifestForHost(host: string, appName: string | undefined): string {
+  const template = slackAppManifestTemplate(appName ? { appName } : {});
+  // The placeholder appears in four request URLs; a global replace is the substitution.
+  return template.split(SLACK_DEPLOY_HOST_PLACEHOLDER).join(host);
+}
+
+/** The bare host (no scheme) the manifest's `https://…` URLs are built from. */
+function manifestHost(base: string): string {
+  return base.replace(/^https?:\/\//i, "").replace(/\/+$/, "");
+}
+
+// --- the four screens -----------------------------------------------------------------------------
+
+/** Screen 1 — ask for the setup code. `retry` re-renders after a wrong code, with an EMPTY field. */
+function claimScreen(retry: boolean): Response {
+  return securePageResponse(
+    200,
+    "Set up Open Everywhere",
+    (retry ? `<p style="color:#b91c1c">That code did not match. Check the deployment's logs and try again.</p>` : "") +
+      `<p>This deployment logged a one-time setup code when it started. Find it in the deployment's logs ` +
+      `(<code>vercel logs</code>, <code>docker logs</code>) and paste it here.</p>` +
+      `<form method="post" action="${escapeHtml(SLACK_SETUP_PATH)}">` +
+      `<input type="hidden" name="${FIELD_ACTION}" value="claim">` +
+      `<p><input name="${FIELD_CODE}" type="password" autocomplete="off" required style="width:100%;padding:.5rem;font:inherit" ` +
+      `placeholder="setup code"></p>` +
+      `<button type="submit" style="${BUTTON_STYLE}">Continue</button>` +
+      `</form>`,
+  );
+}
+
+/** Screen 2 — ask for the app configuration token. */
+function createScreen(host: string): Response {
+  return securePageResponse(
+    200,
+    "Create the Slack app",
+    `<p>Open <code>api.slack.com/apps</code>, scroll to <strong>Your App Configuration Tokens</strong>, ` +
+      `and generate one for the workspace that will host the agent. Paste it below. It needs the ` +
+      `<code>app_configurations:write</code> scope and lasts about 12 hours.</p>` +
+      `<p>Open Everywhere will create the Slack app for <code>${escapeHtml(host)}</code> and keep its ` +
+      `credentials in this deployment's own encrypted store. The configuration token is used once and never stored.</p>` +
+      `<form method="post" action="${escapeHtml(SLACK_SETUP_PATH)}">` +
+      `<input type="hidden" name="${FIELD_ACTION}" value="create">` +
+      `<p><input name="${FIELD_CONFIG_TOKEN}" type="password" autocomplete="off" required style="width:100%;padding:.5rem;font:inherit" ` +
+      `placeholder="xoxe.xoxp-… (app configuration token)"></p>` +
+      `<p><label>App name (optional)<br><input name="${FIELD_APP_NAME}" type="text" autocomplete="off" ` +
+      `style="width:100%;padding:.5rem;font:inherit" placeholder="Open Everywhere"></label></p>` +
+      `<button type="submit" style="${BUTTON_STYLE}">Create the Slack app</button>` +
+      `</form>`,
+  );
+}
+
+/** Screen 3 — the one link that installs the app. */
+function installScreen(authorizeUrl: string): Response {
+  return securePageResponse(
+    200,
+    "Install to your workspace",
+    `<p>The Slack app exists. Installing it is the step that gives Open Everywhere a bot token for ` +
+      `your workspace, and it has to be done by someone who can approve an app there.</p>` +
+      `<p><a href="${escapeHtml(authorizeUrl)}" style="${BUTTON_STYLE};display:inline-block;text-decoration:none">` +
+      `Install to Slack</a></p>` +
+      `<p>Slack will list the permissions and bring you back here.</p>`,
+  );
+}
+
+/** Screen 4 — the two config edits, filled in, and the last instruction. */
+function doneScreen(state: SlackInstallState): Response {
+  const surfaceLine = `  defineSurface({ key: "slack/${state.teamId}", trust: "internal" }),`;
+  const adminLine = `  admins: ["slack/${state.teamId}/${state.installerUserId}"],`;
+  return securePageResponse(
+    200,
+    "Slack is installed",
+    `<p>Open Everywhere is installed in <strong>${escapeHtml(state.teamName ?? state.teamId)}</strong>. ` +
+      `Its credentials are in this deployment's encrypted store; nothing else needs setting.</p>` +
+      `<p>Two config edits are left. They are not secrets — they say which workspace this deployment ` +
+      `trusts, and who administers it — so they belong in your git repo and deploy with it.</p>` +
+      `<p><strong>1.</strong> In <code>agent/identity/surfaces.ts</code>, inside the surfaces array:</p>` +
+      `<pre style="${CODE_BLOCK_STYLE}">${escapeHtml(surfaceLine)}</pre>` +
+      `<p><strong>2.</strong> In <code>agent/memory/config/domains/org.ts</code>, replace the <code>admins</code> line:</p>` +
+      `<pre style="${CODE_BLOCK_STYLE}">${escapeHtml(adminLine)}</pre>` +
+      `<p><strong>Then DM the bot in Slack.</strong> Ask it to make those two edits and it will open a ` +
+      `pull request against your config repo — the agent configuring itself. Or make them by hand and ` +
+      `push; either way the deploy that lands them is the last step.</p>` +
+      `<p>This page is now closed. An administrator can reopen it with the <code>reopen_slack_setup</code> ` +
+      `control call.</p>`,
+  );
+}
+
+// --- the pending record ---------------------------------------------------------------------------
+
+async function readPending(deps: SlackSetupPageDeps): Promise<PendingSlackApp | undefined> {
+  let raw: string | null;
+  try {
+    raw = await vaultOf(deps).read(SLACK_PENDING_REF);
+  } catch {
+    return undefined;
+  }
+  if (raw === null) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null) return undefined;
+  const r = parsed as Record<string, unknown>;
+  if (r.v !== 1) return undefined;
+  const str = (k: string): string | undefined => (typeof r[k] === "string" && (r[k] as string).length > 0 ? (r[k] as string) : undefined);
+  const appId = str("appId");
+  const clientId = str("clientId");
+  const state = str("state");
+  const startedAt = str("startedAt");
+  if (!appId || !clientId || !state || !startedAt) return undefined;
+  return { v: 1, appId, clientId, state, startedAt };
+}
+
+/** The authorize URL for a pending app, rebuilt from the app's own client id rather than stored.
+ *  Slack's `oauth_authorize_url` is a composition of public facts, so recomposing it keeps the
+ *  pending record free of anything that looks like a capability. */
+function authorizeUrlFor(pending: PendingSlackApp, base: string, scopes: string): string {
+  const u = new URL("https://slack.com/oauth/v2/authorize");
+  u.searchParams.set("client_id", pending.clientId);
+  u.searchParams.set("scope", scopes);
+  u.searchParams.set("redirect_uri", `${base}${SLACK_SETUP_CALLBACK_PATH}`);
+  u.searchParams.set("state", pending.state);
+  return u.toString();
+}
+
+/** The bot scopes the shipped manifest declares, as the comma-joined string an authorize URL wants.
+ *  Read OUT of the manifest rather than listed again here: two lists would drift, and the drift is a
+ *  workspace that installed with fewer scopes than the app needs. */
+function manifestBotScopes(): string {
+  const parsed = JSON.parse(slackAppManifestTemplate()) as {
+    oauth_config?: { scopes?: { bot?: readonly string[] } };
+  };
+  const bot = parsed.oauth_config?.scopes?.bot ?? [];
+  return bot.join(",");
+}
+
+// --- the env-shadowing warning: DELETED, because the page can no longer be reached in that state ---
+//
+// An earlier draft warned on screen 2 that a set `SLACK_BOT_TOKEN` / `SLACK_SIGNING_SECRET` would
+// shadow whatever the run was about to store. That warning is now unreachable, and it was the wrong
+// remedy anyway: `slackSetupOpen` (claim.ts) CLOSES the page entirely when either variable is set,
+// because the resolver is env-first and a run on such a deployment would write credentials nothing
+// would ever read. A warning the operator can click past is worse than a page that refuses — it ends
+// with a Slack app created, credentials stored, the page locked, and no behaviour change at all.
+//
+// The resolver still carries the warning for the case this page cannot cover: a var set AFTER a
+// completed run, which it logs once per name (agent/setup/credentials.ts).
+
+// --- GET /setup -----------------------------------------------------------------------------------
+
+/** Render whichever screen this deployment is up to. Every refusal is {@link notAvailable}. */
+export async function handleSlackSetupGet(req: Request, deps: SlackSetupPageDeps = {}): Promise<Response> {
+  if (!(deps.keyArmed ?? credentialKeyArmed)()) return notAvailable();
+  if (!(await slackSetupOpen(deps))) return notAvailable();
+
+  if (!(await verifySetupCookie(setupCookieFrom(req), deps))) return claimScreen(false);
+
+  const base = baseUrl(deps);
+  if (base === undefined) {
+    return securePageResponse(
+      500,
+      "This deployment does not know its own URL",
+      `<p>Open Everywhere could not work out the public URL to put in the Slack app, so it will not ` +
+        `create one that points at the wrong place.</p>` +
+        `<p>Set <code>OE_PUBLIC_BASE_URL</code> to this deployment's public URL and redeploy.</p>`,
+    );
+  }
+
+  const pending = await readPending(deps);
+  if (pending) return installScreen(authorizeUrlFor(pending, base, manifestBotScopes()));
+  return createScreen(manifestHost(base));
+}
+
+// --- POST /setup ----------------------------------------------------------------------------------
+
+/** Screen 1 and screen 2's submits. */
+export async function handleSlackSetupPost(req: Request, deps: SlackSetupPageDeps = {}): Promise<Response> {
+  if (!(deps.keyArmed ?? credentialKeyArmed)()) return notAvailable();
+  if (!(await slackSetupOpen(deps))) return notAvailable();
+
+  let form: URLSearchParams;
+  try {
+    form = new URLSearchParams(await req.text());
+  } catch {
+    return notAvailable();
+  }
+  const action = form.get(FIELD_ACTION) ?? "";
+
+  if (action === "claim") {
+    const presented = form.get(FIELD_CODE) ?? "";
+    // An EMPTY submit re-renders without a verdict — a genuine mistake, and not an attempt worth
+    // a "did not match" line (the same behaviour the credential-intake form takes on an empty paste).
+    if (presented.trim().length === 0) return claimScreen(false);
+    if (!(await setupCodeMatches(presented, deps))) return claimScreen(true);
+    const cookie = await mintSetupCookie(deps);
+    // 303 so the browser re-GETs the page: the claimed run then renders from the one place that
+    // decides which screen is next, rather than this handler guessing.
+    return new Response(null, {
+      status: 303,
+      headers: { location: SLACK_SETUP_PATH, "set-cookie": setupCookieHeader(cookie), "cache-control": "no-store" },
+    });
+  }
+
+  // Every other action needs the claim.
+  if (!(await verifySetupCookie(setupCookieFrom(req), deps))) return notAvailable();
+
+  if (action !== "create") return notAvailable();
+
+  const base = baseUrl(deps);
+  if (base === undefined) return notAvailable();
+
+  const configToken = (form.get(FIELD_CONFIG_TOKEN) ?? "").trim();
+  if (configToken.length === 0) return createScreen(manifestHost(base));
+
+  const rawName = (form.get(FIELD_APP_NAME) ?? "").trim();
+  if (rawName.length > 0) {
+    const problem = slackAppNameProblem(rawName);
+    // Slack's own limit, checked here so the refusal names the field rather than coming back as an
+    // `invalid_manifest` the operator has to decode.
+    if (problem) return slackRefused(`app_name: ${problem}`);
+  }
+
+  let created;
+  try {
+    created = await (deps.createApp ?? createSlackApp)(
+      { configToken, manifest: manifestForHost(manifestHost(base), rawName.length > 0 ? rawName : undefined) },
+      {},
+    );
+  } catch (err) {
+    return slackRefused(err instanceof SlackSetupApiError ? err.code : "request_failed");
+  }
+
+  // STORE THE SECRETS FIRST, THEN THE POINTER. A pending record naming an app whose client secret
+  // never landed is a run that can only fail at the callback, with the operator holding a Slack app
+  // nothing can install. The vault write throws on a disarmed key, and that throw must reach the
+  // operator rather than be swallowed into a pending record.
+  const vault = vaultOf(deps);
+  try {
+    await vault.write(SLACK_CLIENT_SECRET_REF, created.clientSecret, { connector: "slack", createdBy: "host:slack-setup" });
+    // 🔴 STAGED, NOT LIVE. `SLACK_SIGNING_SECRET_REF` is what verifies every inbound Slack request, so
+    // writing it here would swap a running deployment's signing key at the moment somebody pressed
+    // "Create the Slack app" — before OAuth, before the install record. An abandoned run then left an
+    // installed deployment unable to verify its own workspace. The callback promotes this.
+    await vault.write(SLACK_PENDING_SIGNING_SECRET_REF, created.signingSecret, { connector: "slack", createdBy: "host:slack-setup" });
+    const pending: PendingSlackApp = {
+      v: 1,
+      appId: created.appId,
+      clientId: created.clientId,
+      state: randomBytes(16).toString("base64url"),
+      startedAt: new Date().toISOString(),
+    };
+    await vault.write(SLACK_PENDING_REF, JSON.stringify(pending), { connector: "slack", createdBy: "host:slack-setup" });
+  } catch {
+    return securePageResponse(
+      500,
+      "Could not store the Slack credentials",
+      `<p>The Slack app was created, but this deployment could not write its credentials to the ` +
+        `encrypted store. Check that <code>OE_CREDENTIAL_ENCRYPTION_KEY</code> is set and that the ` +
+        `database is reachable, then start again — you will need a fresh app configuration token.</p>`,
+    );
+  }
+
+  return new Response(null, { status: 303, headers: { location: SLACK_SETUP_PATH, "cache-control": "no-store" } });
+}
+
+// --- GET /setup/callback --------------------------------------------------------------------------
+
+/**
+ * Slack's install redirect. Takes `code` + `state`, exchanges the code, records the install, and
+ * renders screen 4.
+ *
+ * This is the ONE render that happens after the lock closes, and it has to be: recording the install
+ * IS closing the page, and the operator still needs the two config lines. So the handler does its
+ * work and renders, rather than redirecting to a `/setup` that would now 404.
+ */
+export async function handleSlackSetupCallback(req: Request, deps: SlackSetupPageDeps = {}): Promise<Response> {
+  if (!(deps.keyArmed ?? credentialKeyArmed)()) return notAvailable();
+  if (!(await slackSetupOpen(deps))) return notAvailable();
+  if (!(await verifySetupCookie(setupCookieFrom(req), deps))) return notAvailable();
+
+  const url = new URL(req.url);
+  const code = url.searchParams.get("code") ?? "";
+  const presentedState = url.searchParams.get("state") ?? "";
+  if (code.length === 0) {
+    // Slack puts its own refusal here when the installer declined or the app was misconfigured.
+    return slackRefused(url.searchParams.get("error") ?? "no_code");
+  }
+
+  const pending = await readPending(deps);
+  if (!pending) return notAvailable();
+
+  // THE CSRF WALL. Constant-time, length-prechecked: the nonce was minted by this deployment for
+  // this run, so a callback carrying a different one is somebody else's redirect landing in this
+  // operator's claimed session.
+  const a = Buffer.from(presentedState);
+  const b = Buffer.from(pending.state);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return notAvailable();
+
+  const base = baseUrl(deps);
+  if (base === undefined) return notAvailable();
+
+  const vault = vaultOf(deps);
+  let clientSecret: string | null;
+  try {
+    clientSecret = await vault.read(SLACK_CLIENT_SECRET_REF);
+  } catch {
+    return notAvailable();
+  }
+  if (clientSecret === null) return notAvailable();
+
+  let install;
+  try {
+    install = await (deps.exchangeCode ?? exchangeSlackOauthCode)(
+      {
+        clientId: pending.clientId,
+        clientSecret,
+        code,
+        // The SAME `redirect_uri` the authorize step sent — Slack compares them.
+        redirectUri: `${base}${SLACK_SETUP_CALLBACK_PATH}`,
+      },
+      {},
+    );
+  } catch (err) {
+    return slackRefused(err instanceof SlackSetupApiError ? err.code : "request_failed");
+  }
+
+  const state: SlackInstallState = {
+    v: 1,
+    appId: pending.appId,
+    clientId: pending.clientId,
+    teamId: install.teamId,
+    installerUserId: install.installerUserId,
+    installedAt: new Date().toISOString(),
+    ...(install.teamName ? { teamName: install.teamName } : {}),
+  };
+
+  try {
+    // ORDER IS LOAD-BEARING, for the second time on this page, and this is the ONLY point at which a
+    // run changes what the live deployment speaks as:
+    //   1. PROMOTE the staged signing secret to the live ref. Everything before this moment left the
+    //      running deployment's inbound verification exactly as it was.
+    //   2. the bot token;
+    //   3. the install record LAST, because the record is the lock — written first, it would close the
+    //      page on a deployment that cannot talk to Slack, recoverable only by the control call.
+    const staged = await vault.read(SLACK_PENDING_SIGNING_SECRET_REF);
+    if (staged === null) return notAvailable();
+    await vault.write(SLACK_SIGNING_SECRET_REF, staged, { connector: "slack", createdBy: "host:slack-setup" });
+    await vault.write(SLACK_BOT_TOKEN_REF, install.botToken, { connector: "slack", createdBy: "host:slack-setup" });
+    // 🔴 THE CODE AND THE COOKIE KEY DIE HERE, BEFORE THE RECORD. The install is what closes the page,
+    // so this is the last moment at which either is of any use — and both are live credentials sitting
+    // in the deployment's log lines (the code) or in a browser (a cookie minted during this run). Left
+    // in place they are what makes a later reopen, or a lock that failed open, exploitable by whoever
+    // read those logs. Dropping them means the page can only ever be re-entered with a code this
+    // deployment mints AFTER the reopen. Before `recordSlackInstall`, so a crash between the two leaves
+    // the page open with the OLD code already dead rather than still valid.
+    //
+    // THE COST OF THAT ORDER, stated because the 500 below has to carry it: a crash here — or a failed
+    // record write — leaves the page open with NO usable code, because the replacement is minted
+    // silently in the store and logged only by the once-per-process boot notice. The operator's
+    // recovery is a restart, which the 500 says.
+    await vault.delete(SLACK_SETUP_CODE_REF).catch(() => undefined);
+    await vault.delete(SLACK_COOKIE_KEY_REF).catch(() => undefined);
+    await recordSlackInstall(state, deps);
+  } catch {
+    // 🔴 THIS PAGE CANNOT TELL THEM TO "TRY AGAIN", because the two lines above destroyed the only
+    // credentials that re-enter it. The code is minted and logged ONCE PER PROCESS by the boot notice,
+    // so a replacement exists in the store but has been logged nowhere — on a long-lived container the
+    // operator would meet "that code did not match" against a value nothing can show them. A restart is
+    // the recovery, and saying so here is the difference between a bad minute and a support ticket.
+    return securePageResponse(
+      500,
+      "Could not store the Slack install",
+      `<p>Slack authorized the install, but this deployment could not write it to the encrypted store. ` +
+        `Check that <code>OE_CREDENTIAL_ENCRYPTION_KEY</code> is set and the database is reachable.</p>` +
+        `<p><strong>Then restart or redeploy this deployment before trying again.</strong> This run has ` +
+        `already used up its one-time setup code and its claim cookie, and a fresh code is logged only ` +
+        `when the deployment starts. Without a restart, <code>/setup</code> will refuse every code you have.</p>` +
+        `<p>The Slack app itself was created and installed — you do not need a new app configuration ` +
+        `token for the retry, but you will need to install again.</p>`,
+    );
+  }
+
+  // The pending record is spent. A failure to clear it is not worth failing the install over: the page
+  // is locked now, so nothing reads it again until a reopen, and a reopen's next run overwrites it.
+  await vault.delete(SLACK_PENDING_REF).catch(() => undefined);
+  await vault.delete(SLACK_PENDING_SIGNING_SECRET_REF).catch(() => undefined);
+
+  // 🔴 THE ROW CARRIES IDS, NEVER A CREDENTIAL. Audit details are read back by admin views, so this
+  // is the same line the status endpoint could publish: which app, which workspace, which installer.
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "slack",
+    workspace: state.teamId,
+    action: SLACK_SETUP_INSTALLED,
+    detail: { appId: state.appId, teamId: state.teamId, installerUserId: state.installerUserId },
+  }).catch(() => undefined);
+
+  const res = doneScreen(state);
+  // Clear the claim: the run is over, and a cookie that outlived it is a standing claim on a page
+  // that would only reopen by an admin's control call.
+  res.headers.append("set-cookie", `${SETUP_COOKIE_NAME}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`);
+  return res;
+}