@open-everywhere/provider-slack 0.1.3 → 0.1.4

package/agent/setup/eve-credentials.ts

@@ -0,0 +1,77 @@
+// WHAT EVE IS TOLD ABOUT THIS DEPLOYMENT'S SLACK CREDENTIALS (OPE-2231).
+//
+// 🔴 WHY THIS FILE HAD TO EXIST, AND THE DEFECT IT CLOSES. OE's front route is not the only thing
+// that verifies a Slack signature. It verifies, then FORWARDS to eve's own `slackChannel` POST
+// handler, and eve verifies AGAIN — `verifyInbound` in eve's `slackChannel.js`:
+//
+//     signingSecret: credentials?.signingSecret ?? (credentials?.webhookVerifier ? undefined
+//                                                                               : process.env.SLACK_SIGNING_SECRET)
+//
+// `channels/slack.ts` passed NO `credentials`, so eve resolved the secret from `process.env` and
+// nowhere else. Moving OE's own read to the credential store therefore produced a deployment where
+// OE's half of the verification passed and EVE's half 401'd: a `/setup`-configured deployment with no
+// env vars — the exact case the page exists to produce — would have acked nothing, woken nothing, and
+// said only `unauthorized`. Eve's outbound path had the same shape: `buildSlackBinding({ botToken:
+// credentials?.botToken })` falls back to `resolveSlackBotToken`, which throws
+// `SLACK_BOT_TOKEN is required.`
+//
+// So the migration is only complete when EVE resolves through the same seam OE does. That is what
+// these two arms are. Both are FUNCTIONS, not values, because the resolution is async and because a
+// value read at module load would pin whatever was true at boot — before `/setup` ran.
+//
+// `webhookVerifier` rather than `signingSecret`: eve takes `signingSecret` as a plain string, which
+// means reading it once at module load. Supplying the verifier instead also makes eve SKIP its
+// `process.env.SLACK_SIGNING_SECRET` fallback entirely (see the expression above), so there is no path
+// left on which eve and OE can disagree about which secret this request is held to.
+
+import { slackSignatureMatches, SLACK_SIGNATURE_HEADER, SLACK_TIMESTAMP_HEADER } from "../channels/slack-signature.js";
+import { slackBotToken, slackSigningSecret } from "./credentials.js";
+
+/** How far a request's signed timestamp may be from now. Slack's own recommendation, and the same
+ *  bound OE's front route applies — the two verifications must not differ on skew either. */
+const MAX_SKEW_SECONDS = 60 * 5;
+
+/**
+ * Eve's inbound verifier. THROWS to reject — eve catches, logs, and answers 401, so a thrown error
+ * here is the refusal. It must never return a verdict as a value.
+ *
+ * The message names no secret and no header value: a verification failure is one of three things to
+ * an attacker (no secret configured, bad signature, stale timestamp) and telling them which is free
+ * information. The three are distinguished in the thrown text only to the extent an OPERATOR reading
+ * their own logs needs, which is why it names the CONDITION and never the input.
+ */
+export async function verifySlackInboundForEve(request: Request, body: string): Promise<void> {
+  const secret = await slackSigningSecret();
+  if (!secret) {
+    throw new Error(
+      "SLACK_SIGNING_SECRET is not set and no signing secret is stored — this deployment cannot verify a Slack request. " +
+        "Run /setup, or set SLACK_SIGNING_SECRET.",
+    );
+  }
+  const timestamp = request.headers.get(SLACK_TIMESTAMP_HEADER);
+  const signature = request.headers.get(SLACK_SIGNATURE_HEADER);
+  if (!timestamp || !signature) throw new Error("slack inbound: the request carries no signature headers.");
+
+  // The timestamp is INSIDE the signed basestring, which is what makes a skew check meaningful here.
+  const skew = Math.abs(Date.now() / 1000 - Number(timestamp));
+  if (!Number.isFinite(skew) || skew > MAX_SKEW_SECONDS) throw new Error("slack inbound: the signed timestamp is outside the accepted window.");
+
+  if (!slackSignatureMatches(secret, timestamp, body, signature)) throw new Error("slack inbound: the signature does not match.");
+}
+
+/**
+ * Eve's outbound bot-token provider. Throws eve's OWN message when none resolves, byte for byte, so a
+ * misconfigured deployment produces the error every runbook and every existing test already names.
+ */
+export async function slackBotTokenForEve(): Promise<string> {
+  const token = await slackBotToken();
+  if (!token) throw new Error("SLACK_BOT_TOKEN is required.");
+  return token;
+}
+
+/** The `credentials` block for `slackChannel(...)`. One object, so the two halves cannot be wired
+ *  independently and leave eve resolving one of them from the environment. */
+export const SLACK_EVE_CREDENTIALS = {
+  webhookVerifier: verifySlackInboundForEve,
+  botToken: slackBotTokenForEve,
+} as const;

package/agent/setup/install-state.ts

@@ -0,0 +1,248 @@
+// THE SLACK INSTALL RECORD (OPE-2231) — what a `/setup` run captured, and the ONE predicate the
+// rest of the deployment asks about it.
+//
+// WHERE IT LIVES. Every field sits in the encrypted KV vault (core `credentials/kv-vault.ts`) under
+// the reserved `slack-app:` namespace, so the outbound credential resolver refuses all of it — see
+// `SLACK_APP_REF_NAMESPACE`'s own doc comment for why the bot token is reserved too. Four refs hold
+// SECRET material and one holds the non-secret record:
+//
+//   slack-app:client_secret   the app's OAuth client secret        (apps.manifest.create returned it)
+//   slack-app:signing_secret  the app's request-signing secret     (apps.manifest.create returned it)
+//   slack-app:bot_token       the workspace bot token              (oauth.v2.access returned it)
+//   slack-app:cookie_key      the HMAC key for the claim cookie    (this deployment minted it)
+//   slack-app:install         the record below, as JSON            (ids and timestamps only)
+//
+// 🔴 THE RECORD CARRIES NO SECRET, AND THAT IS WHAT MAKES IT READABLE. {@link slackInstallState} is
+// the seam a STATUS ENDPOINT reads (OPE-2230 builds that endpoint; this function is its whole
+// contract with Slack). A status endpoint is a place where a value gets rendered to whoever can
+// reach it, so the thing it reads must be unable to carry one. Hence the split: ids and timestamps
+// in `slack-app:install`, every secret under its own ref, and no function here that returns both.
+// Adding a field to {@link SlackInstallState} means asking "would I publish this?" — if the answer
+// is no, it belongs in its own ref instead.
+//
+// 🔴 THE RECORD IS THE LOCK. `/setup` is open while no record exists and closed once one does
+// (`agent/setup/claim.ts` reads exactly this). So writing the record is the LAST act of a
+// successful install, after both secrets are stored — a record written first would lock the page
+// against a run that had not finished, with no way back in but the reopen call.
+
+import { encryptedKvVault, SLACK_APP_REF_NAMESPACE, type EncryptedKvVault } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The ref holding the app's OAuth client secret. SECRET — never rendered, never logged. */
+export const SLACK_CLIENT_SECRET_REF = `${SLACK_APP_REF_NAMESPACE}client_secret`;
+/** The ref holding the app's request-signing secret. SECRET. */
+export const SLACK_SIGNING_SECRET_REF = `${SLACK_APP_REF_NAMESPACE}signing_secret`;
+/** The ref holding the workspace bot token (`xoxb-…`). SECRET. */
+export const SLACK_BOT_TOKEN_REF = `${SLACK_APP_REF_NAMESPACE}bot_token`;
+/**
+ * The ref holding a PENDING app's signing secret, between the create and the OAuth callback.
+ *
+ * 🔴 WHY A SECOND REF AND NOT JUST {@link SLACK_SIGNING_SECRET_REF}. That ref is LIVE — it is what
+ * verifies every inbound Slack request. Writing the new app's secret straight into it at the create
+ * step would swap the running deployment's signing key before the install existed, so an ABANDONED
+ * run (wrong workspace, expired token, closed tab) left an installed deployment unable to verify its
+ * own workspace's requests: every cold start from then on 401s, staggered by the per-process memo, with
+ * nothing in the logs saying a different secret had been picked. The callback promotes this to the live
+ * ref immediately before it records the install, so the live secret changes only when a run COMPLETES.
+ */
+export const SLACK_PENDING_SIGNING_SECRET_REF = `${SLACK_APP_REF_NAMESPACE}pending_signing_secret`;
+/** The ref holding the HMAC key for the claim cookie. SECRET, and minted here — see claim.ts. */
+export const SLACK_COOKIE_KEY_REF = `${SLACK_APP_REF_NAMESPACE}cookie_key`;
+/** The ref holding the one-time setup code a human reads out of the deployment's logs. SECRET. */
+export const SLACK_SETUP_CODE_REF = `${SLACK_APP_REF_NAMESPACE}setup_code`;
+/** The ref holding {@link SlackInstallState} as JSON. The ONLY ref here with no secret in it. */
+export const SLACK_INSTALL_REF = `${SLACK_APP_REF_NAMESPACE}install`;
+/** The ref holding the PENDING app record (`agent/setup/page.ts` writes and spends it). Declared here
+ *  so one module owns the ref vocabulary — `reopenSlackSetup` has to clear it, and a ref it could not
+ *  name is a ref it would leave behind. */
+export const SLACK_PENDING_REF = `${SLACK_APP_REF_NAMESPACE}pending`;
+
+/**
+ * What a completed `/setup` run recorded. IDS AND TIMESTAMPS ONLY — see the header on why.
+ *
+ * `v` guards a future shape change: an unreadable or wrong-version record reads as NO install, which
+ * fails in the safe direction (the page reopens; it does not grant anything).
+ */
+export interface SlackInstallState {
+  readonly v: 1;
+  /** The Slack app id (`A…`) `apps.manifest.create` returned. */
+  readonly appId: string;
+  /** The app's OAuth client id. Public by Slack's own design (it rides the authorize URL). */
+  readonly clientId: string;
+  /** The workspace (team) id (`T…`) the OAuth install landed in. */
+  readonly teamId: string;
+  /** The workspace's display name, when `oauth.v2.access` reported one. */
+  readonly teamName?: string;
+  /** The installing member's id (`U…`) — `authed_user.id` on the OAuth response. */
+  readonly installerUserId: string;
+  /** ISO-8601 instant the install completed. */
+  readonly installedAt: string;
+}
+
+/** Injectable seams for tests — the live default is the real encrypted KV vault. */
+export interface SlackInstallStateDeps {
+  readonly vault?: EncryptedKvVault;
+}
+
+function vaultOf(deps: SlackInstallStateDeps): EncryptedKvVault {
+  return deps.vault ?? encryptedKvVault();
+}
+
+/**
+ * The recorded Slack install, or `undefined` when this deployment has none.
+ *
+ * 🔴 THIS IS THE SEAM OPE-2230's STATUS ENDPOINT READS, and the only one it should: it returns the
+ * whole non-secret truth about whether Slack is installed and where, and it can return nothing
+ * else. Call it; do not read `slack-app:install` directly, or the status endpoint and the claim lock
+ * end up with two readings of one record.
+ *
+ * FAIL-SOFT TO "NOT INSTALLED". An unreachable vault, a disarmed credential key, a malformed row or
+ * a record of an unknown version all answer `undefined`. For a STATUS READER that is the safe
+ * direction and the honest one: it reports Slack as not installed, which is true as far as this
+ * process can tell, and it cannot report an install that is not there.
+ *
+ * 🔴 THE CLAIM LOCK MUST NOT USE THIS FUNCTION. For the lock, the same collapse is a hole — a store
+ * fault would reopen `/setup`. The lock reads {@link readInstallRecord} instead, which tells the
+ * three cases apart. See its doc comment.
+ */
+export async function slackInstallState(deps: SlackInstallStateDeps = {}): Promise<SlackInstallState | undefined> {
+  return (await readInstallRecord(deps)).state;
+}
+
+/**
+ * What a read of the install record actually found — THREE outcomes, not two.
+ *
+ * 🔴 WHY THE LOCK NEEDS THIS AND THE STATUS SEAM DOES NOT. {@link slackInstallState} collapses every
+ * unreadable case into `undefined`, which is right for a status endpoint: "no install I can see" is
+ * the honest answer whether the store is unreachable or the row is absent, and it cannot report an
+ * install that is not there. For the LOCK that collapse is a hole. The lock asks the opposite
+ * question — "may this page serve?" — and `undefined` meaning both "nothing stored" and "I could not
+ * tell" makes a store fault, a malformed row or a row from a future version REOPEN `/setup`. The
+ * setup code is in the deployment's old log lines from before the install, so a reopen is a window
+ * for whoever read them.
+ *
+ * So the lock distinguishes: `absent` is the ONLY outcome that opens the page. `unreadable` covers a
+ * throw, a non-JSON row, and a row whose `v` this build does not know — all of which mean "something
+ * IS stored and I cannot read it", which is never a reason to grant. The cost of that is a setup page
+ * that is briefly unavailable during a store outage, recoverable by a retry or the control call; the
+ * cost of the other direction is not recoverable at all.
+ */
+export type InstallRecordRead =
+  | { readonly kind: "present"; readonly state: SlackInstallState }
+  | { readonly kind: "absent"; readonly state: undefined }
+  | { readonly kind: "unreadable"; readonly state: undefined };
+
+/** Read the install record, reporting WHICH of the three outcomes happened. The lock reads this. */
+export async function readInstallRecord(deps: SlackInstallStateDeps = {}): Promise<InstallRecordRead> {
+  let raw: string | null;
+  try {
+    raw = await vaultOf(deps).read(SLACK_INSTALL_REF);
+  } catch {
+    return { kind: "unreadable", state: undefined };
+  }
+  if (raw === null) return { kind: "absent", state: undefined };
+  const state = parseInstallState(raw);
+  // A row that exists but will not parse is the `unreadable` case, NOT `absent`: something is stored.
+  if (state === undefined) return { kind: "unreadable", state: undefined };
+  return { kind: "present", state };
+}
+
+/** Parse + validate a stored record. Exported for the suite; `undefined` for anything unreadable. */
+export function parseInstallState(raw: string): SlackInstallState | 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 teamId = str("teamId");
+  const installerUserId = str("installerUserId");
+  const installedAt = str("installedAt");
+  if (!appId || !clientId || !teamId || !installerUserId || !installedAt) return undefined;
+  const teamName = str("teamName");
+  return {
+    v: 1,
+    appId,
+    clientId,
+    teamId,
+    installerUserId,
+    installedAt,
+    ...(teamName ? { teamName } : {}),
+  };
+}
+
+/**
+ * Record a completed install. THE LAST WRITE OF A SUCCESSFUL `/setup` RUN — it is what closes the
+ * page, so every secret the install captured must already be stored when this is called.
+ *
+ * Throws whatever the vault throws (a disarmed credential key, an unreachable store). The caller
+ * must NOT swallow it: a run that stored the credentials but failed to record the install has to
+ * say so, because the page is still open and a second run would mint a second Slack app.
+ */
+export async function recordSlackInstall(state: SlackInstallState, deps: SlackInstallStateDeps = {}): Promise<void> {
+  await vaultOf(deps).write(SLACK_INSTALL_REF, JSON.stringify(state), { connector: "slack", createdBy: "host:slack-setup" });
+}
+
+/**
+ * REOPEN the setup page: destroy the install record, keeping every stored credential.
+ *
+ * WHY THE LIVE CREDENTIALS STAY. A reopen is "let me run setup again", not "forget this workspace".
+ * The running deployment is still serving Slack with the stored bot token and signing secret while the
+ * admin walks the page, and a reopen that deleted them would take the agent off Slack the moment it
+ * was called. A COMPLETED second run replaces them, at its callback; an abandoned one leaves the
+ * working install untouched, which is true because the create step stages the new signing secret under
+ * {@link SLACK_PENDING_SIGNING_SECRET_REF} rather than writing the live ref.
+ *
+ * What DOES go, besides the record: the setup code (so the reopened page needs a fresh one — see
+ * below) and any stale pending-app material.
+ *
+ * THROWS on a failure to rotate the setup code or the claim cookie key, and leaves the install record
+ * in place when it does — see the body. A reopen that could not rotate must not open the page.
+ *
+ * NO REOPEN HISTORY SURVIVES THIS, deliberately. The record IS the lock, so reopening means
+ * destroying it, and a field recording "reopened at" would have to live on a record that no longer
+ * exists. The audit row is where the history lives (`slack.setup_reopened`, audit/action-registry.ts)
+ * — a hash-chained row naming the admin who called it, which is a better home for that fact than a
+ * field on a row the next install overwrites.
+ *
+ * Returns true iff a record went (false when the page was already open) — idempotent either way.
+ */
+export async function reopenSlackSetup(deps: SlackInstallStateDeps = {}): Promise<boolean> {
+  const vault = vaultOf(deps);
+  return vault.withLock(SLACK_INSTALL_REF, async () => {
+    // 🔴 THE CLAIM CREDENTIALS DIE BEFORE THE LOCK DOES, and the order is the whole safety property.
+    //
+    // The record IS the lock, so deleting it is what opens the page. An earlier draft deleted it FIRST
+    // and then rotated these two with `.catch(() => undefined)`, returning `true` either way — the
+    // exact inverse of the rule `setup/page.ts` states for the install path. That left a real hole: if
+    // the setup-code delete failed, or the lambda was cut between the two, the page was OPEN with the
+    // PRE-INSTALL code still matching, and that code is in the deployment's log lines from before the
+    // install. Whoever read them could then claim the run.
+    //
+    // So: rotate first, open second, and let a rotation failure THROW. `vault.delete` answers `false`
+    // for an absent row rather than throwing, so the only thing that propagates here is a real store
+    // failure — and on one the record survives, the page stays shut, and the control verb reports the
+    // error instead of a reopen that left the door open.
+    //
+    // `slackSetupCode` returns the STORED value when one exists, so dropping the ref is what makes the
+    // next boot mint and log a fresh code. The cookie key goes with it: a claim cookie minted before
+    // the reopen is signed with that key, so leaving it would let a browser still holding one walk
+    // straight past the code prompt and undo the rotation.
+    await vault.delete(SLACK_SETUP_CODE_REF);
+    await vault.delete(SLACK_COOKIE_KEY_REF);
+
+    const reopened = await vault.delete(SLACK_INSTALL_REF);
+
+    // Stale pending-app material, AFTER the record. These two are not credentials and not the lock:
+    // the worst a leftover does is offer the install screen for an app the previous run abandoned, and
+    // a new run overwrites both. So a failure here is swallowed rather than failing the reopen.
+    await vault.delete(SLACK_PENDING_SIGNING_SECRET_REF).catch(() => undefined);
+    await vault.delete(SLACK_PENDING_REF).catch(() => undefined);
+    return reopened;
+  });
+}