@open-everywhere/provider-slack 0.1.3 → 0.1.5

package/agent/setup/claim.ts

@@ -0,0 +1,343 @@
+// WHO MAY RUN `/setup` (OPE-2231) — the claim, the cookie, and the lock.
+//
+// THE PROBLEM. `/setup` hands whoever completes it a Slack app wired to THIS deployment and a bot
+// token for the workspace that installs it. An unclaimed setup page is first-come: the first
+// stranger to find a fresh deployment owns the agent. So the page needs an identity assertion before
+// it will talk, and the deployment has nothing to assert one with — no users, no admins, no surface
+// (Slack is what setup is for), and no operator-set secret on the hosted path, where the one env
+// value the deploy button asks for is the credential encryption key.
+//
+// THE ANSWER, AND IT IS THE RATIFIED ONE (OPE-2231; "No other auth design"). The deployment proves
+// it owns its own LOGS, which is a thing only its operator can read:
+//
+//   1. On boot, while no install is recorded, the deployment mints a one-time SETUP CODE and logs it
+//      once (`vercel logs` / `docker logs`; a coding agent reads it). The code lives in the vault, so
+//      every instance logs the same one and a restart does not invalidate a code in use.
+//   2. `/setup` asks for the code once. A match sets a short-lived signed COOKIE; every later step
+//      in the run presents the cookie, so the code is typed once and never rides a URL.
+//   3. The page LOCKS once an install is recorded (install-state.ts) and answers 404 from then on.
+//      An admin reopens it with the control call (`reopen_slack_setup`), never by presenting a code.
+//
+// 🔴 WHAT THIS IS AND IS NOT WORTH. The trust root is READ ACCESS TO THE DEPLOYMENT'S LOGS — a
+// PLATFORM permission (`vercel logs`, `docker logs`), not any role this product defines. It is the
+// right root for the hosted path, because whoever holds it can already read every secret the platform
+// holds. It is honestly weaker than an account login in one way worth stating: a platform where log
+// access is granted more widely than deploy access grants setup to everyone with log access, for as
+// long as the page is open. Note which permission that is — it is NOT the OE `admin` role that the
+// reopen verb requires, and the two sets need not overlap.
+//
+// TWO THINGS BOUND THAT WINDOW, and both are load-bearing:
+//   • the page closes at the first successful install, and {@link announceSlackSetupCode} stops
+//     EMITTING a code from then on. The logs are append-only history, so a post-install deployment's
+//     OLD log lines still contain the code it emitted before the install — which is why the INSTALL
+//     ITSELF destroys that code and the claim cookie key (`setup/page.ts`, before it records the
+//     install), and why a reopen rotates both BEFORE it deletes the record (`reopenSlackSetup`, which
+//     throws rather than opening the page if it cannot). The strings in those old log lines are dead
+//     the moment the install completes, and a reopen can only ever be entered with a code minted
+//     after it.
+//   • the lock FAILS CLOSED. Only an absent install record opens the page; a store fault, an
+//     unparseable row or a record from a future build all keep it shut. See {@link slackSetupOpen}.
+//   • the page is also closed on a deployment configured the OLD way, by environment variable. That
+//     one is not a nicety: without it every existing deployment in the world would upgrade into an
+//     open setup page it never asked for. See {@link slackSetupOpen}.
+//
+// 🔴 THE CODE IS A SECRET AND THE LOG LINE IS ITS ONLY RENDERING. It is never put in an error, never
+// echoed back by the form, never written to the audit detail, and never returned by any function
+// here but the two that exist to mint or compare it. A failed code attempt renders the same generic
+// page a right-but-locked attempt does.
+//
+// WHY A SECOND COOKIE CODEC AND NOT core's PAGE-TOKEN CODEC. `credentials/page-token.ts` signs a
+// capability bound to ONE ROW in `credential_intake` — its claim set is `{v, aud, org, id, rb, exp}`
+// and `id`/`rb` are the row and the principal the act is attributed to. A setup cookie binds no row
+// and no principal (there is no principal yet — that is what setup produces), rides a `Set-Cookie`
+// rather than a URL, and is presented many times rather than consumed once. Bending the row codec
+// around that would mean two meanings for `id` and a THIRD audience in a closed union whose N×N
+// replay matrix is a suite (`webhook-reveal-test.ts`), for a token that has no row to replay onto.
+// So: its own codec, its own key, and the two cannot verify each other's tokens in either direction
+// because neither key is the other's and neither payload satisfies the other's shape check.
+
+import {
+  encryptedKvVault,
+  type EncryptedKvVault,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { SLACK_COOKIE_KEY_REF, SLACK_SETUP_CODE_REF, readInstallRecord, type SlackInstallStateDeps } from "./install-state.js";
+import { slackSecretEnvPresent } from "./credentials.js";
+
+/** The cookie the page sets once the code matches. `__Host-` pins it to this exact host with no
+ *  domain and a `/` path, which a subdomain cannot overwrite. */
+export const SETUP_COOKIE_NAME = "__Host-oe-setup";
+
+/** How long a claimed run stays claimed. Long enough to walk the page and Slack's OAuth consent,
+ *  short enough that an unattended browser on a shared machine is not a standing claim. */
+export const SETUP_COOKIE_TTL_MS = 30 * 60 * 1000;
+
+/** The setup code's length in bytes before encoding — 16 bytes is 128 bits, which is not guessable
+ *  and still short enough for a human to copy out of a log line in one go. */
+const SETUP_CODE_BYTES = 16;
+
+/** The cookie HMAC key's length in bytes. Nobody types this one, so it is a full 256-bit key. */
+const COOKIE_KEY_BYTES = 32;
+
+/** Injectable seams for tests. `now` is the clock the cookie's expiry is read against. */
+export interface SlackClaimDeps extends SlackInstallStateDeps {
+  readonly vault?: EncryptedKvVault;
+  readonly now?: () => number;
+  /** Override `process.env` — the lock reads it to close on an env-configured deployment. */
+  readonly env?: NodeJS.ProcessEnv;
+  /**
+   * Use the lock-verdict cache even though a vault is injected. TEST SEAM ONLY.
+   *
+   * 🔴 SAME REASON AS `SlackCredentialDeps.memo`. An injected vault normally bypasses the cache, which
+   * the suite leans on — a test writes an install record and the next call sees it. That also made
+   * {@link LOCK_TTL_MS} undrivable by any test, and a TTL nobody can drive is a claim nobody has
+   * checked. This one gates a PUBLIC route, so it is the last place to take that on faith. Nothing in
+   * `agent/**` passes it.
+   */
+  readonly lockCache?: boolean;
+}
+
+function vaultOf(deps: SlackClaimDeps): EncryptedKvVault {
+  return deps.vault ?? encryptedKvVault();
+}
+
+// --- mint-on-first-use, into the Slack app's own namespace ------------------------------------------
+//
+// WHY NOT core's `getOrMintSelfSecret`. That function's contract is "an env var of the same NAME is
+// the announced on-ramp", which is right for a secret an operator might already hold — and wrong for
+// these two. Nobody sets a setup code or a cookie key by hand: there is nothing to migrate from, and
+// an env name for an auto-minted value is a knob whose only use is to weaken it. So these mint into
+// `slack-app:` beside the rest of the bundle's material, with no env name at all, and this helper
+// carries the SAME race discipline that function documents: a per-key lock, a read-back rather than
+// trust in the local candidate, and no memo of a fresh mint (the vault is last-write-wins with no
+// put-if-absent, so two cold processes can briefly diverge and the next read converges).
+async function mintedSecret(ref: string, bytes: number, vault: EncryptedKvVault, now: () => number, cache: boolean): Promise<string> {
+  // 🔴 AN EXISTING ROW IS MEMOISED BRIEFLY, A FRESH MINT NEVER IS, and both halves matter.
+  //
+  // WHY CACHE AT ALL. Both callers sit on the UNAUTHENTICATED `/setup` route: `verifySetupCookie`
+  // resolves the cookie key for any request carrying a non-empty cookie, and `setupCodeMatches` resolves
+  // the code for every claim POST. Uncached, that is one `stored_credential` SELECT plus one decrypt per
+  // request for as long as the page is open — the same exposure `LOCK_TTL_MS` and the credential
+  // resolver's `MISS_TTL_MS` exist to remove, left open on the one route most exposed to it.
+  //
+  // WHY NOT A FRESH MINT. A mint reflects only what THIS process wrote, not what a concurrent racer's
+  // later write did (the vault is last-write-wins with no put-if-absent). Caching it would pin a value
+  // that lost the race; leaving it uncached means the next resolution re-reads and converges.
+  const cached = cache ? secretCache.get(ref) : undefined;
+  if (cached !== undefined && cached.until > now()) return cached.value;
+
+  return vault.withLock(ref, async () => {
+    const stored = await vault.read(ref);
+    if (stored !== null) {
+      if (cache) secretCache.set(ref, { value: stored, until: now() + SECRET_TTL_MS });
+      return stored;
+    }
+    const minted = randomBytes(bytes).toString("base64url");
+    await vault.write(ref, minted, { connector: "slack", createdBy: "host:slack-setup" });
+    const confirmed = await vault.read(ref);
+    return confirmed ?? minted;
+  });
+}
+
+/** How long a read-back claim secret is reused. Matched to {@link LOCK_TTL_MS}: a reopen's rotation has
+ *  to take effect without a restart, and five seconds is the staleness this page already accepts. */
+const SECRET_TTL_MS = 5_000;
+
+/** Read-back claim secrets and when each stops being trusted. Bypassed for an injected vault. */
+const secretCache = new Map<string, { readonly value: string; readonly until: number }>();
+
+/** Test seam: forget cached claim secrets. */
+export function resetSlackClaimSecretCache(): void {
+  secretCache.clear();
+}
+
+/** The HMAC key for the claim cookie, minting it on first use. Never logged, never rendered. A full
+ *  32 bytes: it keys an HMAC rather than being typed by a human, so there is no reason to be short. */
+async function cookieKey(deps: SlackClaimDeps): Promise<string> {
+  return mintedSecret(SLACK_COOKIE_KEY_REF, COOKIE_KEY_BYTES, vaultOf(deps), deps.now ?? Date.now, deps.vault === undefined);
+}
+
+/**
+ * The deployment's setup code, minting it on first use. SECRET — the ONLY place it may be rendered
+ * is the boot log line in {@link announceSlackSetupCode}.
+ */
+export async function slackSetupCode(deps: SlackClaimDeps = {}): Promise<string> {
+  return mintedSecret(SLACK_SETUP_CODE_REF, SETUP_CODE_BYTES, vaultOf(deps), deps.now ?? Date.now, deps.vault === undefined);
+}
+
+// --- the lock ---------------------------------------------------------------------------------------
+
+/**
+ * Is `/setup` OPEN right now? True only while NO install is recorded.
+ *
+ * Every route on the page calls this FIRST and 404s on false, so a locked deployment's `/setup` is
+ * indistinguishable from a deployment that never had the page — the same posture
+ * `credentials/intake-page.ts` takes on a disarmed vault.
+ */
+export async function slackSetupOpen(deps: SlackClaimDeps = {}): Promise<boolean> {
+  // The cached verdict, while it is still inside its TTL. Skipped for an injected vault (a test
+  // driving a specific store state), and the env check below is a property read either way.
+  const cacheApplies = deps.vault === undefined || deps.lockCache === true;
+  if (cacheApplies && lockCache !== null && lockCache.until > (deps.now ?? Date.now)()) return lockCache.open;
+
+  // 🔴 AN ENV-CONFIGURED DEPLOYMENT IS CLOSED, and this arm is not a convenience — without it the
+  // whole upgrade population gets an OPEN setup page and a live claim code in its logs, forever.
+  //
+  // The lock is "an install record exists". A deployment that was configured the old way — the two
+  // env vars, set by hand — has never run `/setup`, so it has no record. Before this check, landing
+  // this feature would have opened `/setup` on every such deployment and logged a one-time code on
+  // every cold start indefinitely, with no install ever arriving to close it. Anyone who could read
+  // the deployment's logs could then install the app into a workspace THEY control, overwrite the
+  // stored credentials, lock the page behind themselves, and have `slackInstallFacts()` publish their
+  // workspace as this deployment's install.
+  //
+  // Closing on env presence costs nothing a real `/setup` operator wants: the resolver is env-first,
+  // so a deployment with either var set would IGNORE everything a run stored anyway — the page would
+  // have been a no-op with a credential write. An operator who wants to migrate onto the store unsets
+  // the vars and redeploys, which is what the runbook says and what makes the run meaningful.
+  // Screen 2's shadow notice still covers the case where one var is set after an install.
+  const env = slackSecretEnvPresent({ ...(deps.env ? { env: deps.env } : {}) });
+  if (env.botToken || env.signingSecret) return false;
+
+  // 🔴 ONLY AN ABSENT ROW OPENS THE PAGE, and the earlier draft got this backwards. It read through
+  // `slackInstallState`, which collapses a store fault, a malformed row and an unknown record version
+  // into `undefined` — so any of those REOPENED `/setup`. That is not a safe default here: the setup
+  // code sits in the deployment's log lines from before the install, so a reopen is a window for
+  // whoever read them. The cost of failing closed is a page briefly unavailable during a store
+  // outage, recoverable by a retry or the control call; the other direction is not recoverable.
+  // `readInstallRecord` tells the three cases apart — see its doc comment.
+  const read = await readInstallRecord(deps);
+  const open = read.kind === "absent";
+
+  // Cached briefly, for the same reason the credential resolver caches a miss: this predicate runs on
+  // EVERY request to a PUBLIC route, so an uncached read let anyone who knew the host drive one
+  // `stored_credential` SELECT per request. A few seconds is enough to collapse that while keeping the
+  // page responsive to a `/setup` run or a reopen that just changed the answer.
+  if (cacheApplies) lockCache = { open, until: (deps.now ?? Date.now)() + LOCK_TTL_MS };
+  return open;
+}
+
+/** How long the lock verdict is reused. Short, because a reopen must take effect without a restart. */
+const LOCK_TTL_MS = 5_000;
+
+/** The last lock verdict and when it stops being trusted. Bypassed entirely for an injected vault. */
+let lockCache: { readonly open: boolean; readonly until: number } | null = null;
+
+/** Test seam: forget the cached lock verdict. */
+export function resetSlackSetupLockCache(): void {
+  lockCache = null;
+}
+
+/**
+ * The boot notice (core `boot/notices.ts`): log the setup code ONCE per process, while the page is
+ * open. Silent whenever {@link slackSetupOpen} is false — an install is recorded, OR this deployment
+ * is configured by environment variable and would ignore anything a run stored. Both cases would be
+ * emitting a live claim credential for a page that will refuse every request.
+ *
+ * 🔴 THIS IS THE ONE PLACE THE CODE IS RENDERED. It goes to the log and nowhere else: not to the
+ * audit detail (`appendAudit` details are read back by admin views), not into an error message, not
+ * into the page. Minting it is also what this call does first, so the code exists from the first
+ * boot rather than from the first visit.
+ */
+export async function announceSlackSetupCode(deps: SlackClaimDeps = {}): Promise<void> {
+  if (!(await slackSetupOpen(deps))) return;
+  const code = await slackSetupCode(deps);
+  console.log(
+    `[open-everywhere:slack-setup] Slack is not installed on this deployment. Open /setup and enter this one-time setup code: ${code}\n` +
+      `[open-everywhere:slack-setup] The code stops being logged once the Slack install completes, and /setup locks at that point.`,
+  );
+}
+
+// --- the cookie codec -------------------------------------------------------------------------------
+
+/** The signed cookie's claim set. No row, no principal — see the header on why it is not a page
+ *  token. `exp` is a hard epoch-ms wall; `v` guards a grammar change. */
+interface SetupCookieClaims {
+  readonly v: 1;
+  readonly exp: number;
+}
+
+function b64urlEncode(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64urlDecode(s: string): Buffer {
+  // Reject anything outside the base64url alphabet BEFORE decoding (Buffer is lax), so a malformed
+  // cookie fails cleanly rather than decoding to attacker-shaped bytes.
+  if (!/^[A-Za-z0-9_-]*$/.test(s)) return Buffer.alloc(0);
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+
+function sign(secret: string, payloadB64: string): string {
+  return b64urlEncode(createHmac("sha256", secret).update(payloadB64, "utf8").digest());
+}
+
+/** Mint the signed cookie VALUE for a run that just presented the right code. CAPABILITY-BEARING. */
+export async function mintSetupCookie(deps: SlackClaimDeps = {}): Promise<string> {
+  const now = (deps.now ?? Date.now)();
+  const claims: SetupCookieClaims = { v: 1, exp: now + SETUP_COOKIE_TTL_MS };
+  const payloadB64 = b64urlEncode(Buffer.from(JSON.stringify(claims), "utf8"));
+  return `${payloadB64}.${sign(await cookieKey(deps), payloadB64)}`;
+}
+
+/** Verify a presented cookie value. True only for a well-formed, correctly-signed, unexpired one. */
+export async function verifySetupCookie(value: string | undefined, deps: SlackClaimDeps = {}): Promise<boolean> {
+  if (typeof value !== "string") return false;
+  const dot = value.indexOf(".");
+  if (dot <= 0 || dot === value.length - 1) return false;
+  const payloadB64 = value.slice(0, dot);
+  const sigB64 = value.slice(dot + 1);
+
+  const expected = sign(await cookieKey(deps), payloadB64);
+  const a = Buffer.from(sigB64);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
+
+  let parsed: unknown;
+  try {
+    const raw = b64urlDecode(payloadB64);
+    if (raw.length === 0) return false;
+    parsed = JSON.parse(raw.toString("utf8"));
+  } catch {
+    return false;
+  }
+  if (typeof parsed !== "object" || parsed === null) return false;
+  const c = parsed as Record<string, unknown>;
+  if (c.v !== 1) return false;
+  if (typeof c.exp !== "number" || !Number.isFinite(c.exp)) return false;
+  return c.exp > (deps.now ?? Date.now)();
+}
+
+/**
+ * Does `presented` equal the deployment's setup code? CONSTANT-TIME, length-prechecked.
+ *
+ * Never reports WHY it said no, and the caller never tells the holder either: a wrong code and a
+ * right code on a locked deployment render the same page.
+ */
+export async function setupCodeMatches(presented: string, deps: SlackClaimDeps = {}): Promise<boolean> {
+  const a = Buffer.from(presented.trim());
+  const b = Buffer.from(await slackSetupCode(deps));
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/** The `Set-Cookie` header value for a claimed run. `HttpOnly` (no script reads it), `Secure` (the
+ *  page is HTTPS-only), `SameSite=Lax` — Lax rather than Strict because the run RETURNS from Slack's
+ *  OAuth consent as a top-level cross-site GET, which Strict would strip the cookie from, breaking
+ *  the callback for the very person who claimed the run. */
+export function setupCookieHeader(value: string): string {
+  return `${SETUP_COOKIE_NAME}=${value}; Path=/; Max-Age=${Math.floor(SETUP_COOKIE_TTL_MS / 1000)}; HttpOnly; Secure; SameSite=Lax`;
+}
+
+/** Read the setup cookie out of a request's `Cookie` header, or `undefined`. */
+export function setupCookieFrom(req: Request): string | undefined {
+  const header = req.headers.get("cookie");
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    if (part.slice(0, eq).trim() !== SETUP_COOKIE_NAME) continue;
+    const value = part.slice(eq + 1).trim();
+    return value.length > 0 ? value : undefined;
+  }
+  return undefined;
+}

package/agent/setup/credentials.ts

@@ -0,0 +1,265 @@
+// WHERE THE SLACK BUNDLE'S TWO SECRETS COME FROM (OPE-2231) — the signing secret that verifies
+// Slack's requests, and the bot token that signs ours.
+//
+// Before this module there was one answer: `process.env.SLACK_SIGNING_SECRET` and
+// `process.env.SLACK_BOT_TOKEN`, read inline at each call site. A `/setup` run now captures both
+// into the credential store, so there are two homes and an order is needed.
+//
+// 🔴 THE ORDER IS ENV-FIRST, AND IT IS THE OPPOSITE OF `getOperatorSecret`'s. Core's operator-secret
+// resolver puts the db store first and treats env as a fallback on its way out (OPE-408: "db-over-env
+// is the DEFAULT home for secrets"). This module inverts that, deliberately, on the OPE-2231 ruling
+// ("env as fallback (env wins if set, for existing installs)"). The reason is the migration, not a
+// disagreement about where secrets belong:
+//
+//   • EVERY deployment that exists today holds these two in env and works. This change must not be
+//     able to alter which Slack app a working deployment speaks as. Store-first could: a `/setup` run
+//     somebody started and abandoned, or a second workspace's install, would silently take over a
+//     live deployment's Slack identity at the next cold start, with a 401 loop as the symptom and
+//     nothing in the logs saying a different secret had been picked.
+//   • Env-first cannot do that. A deployment with the env vars set resolves to exactly the value it
+//     resolved to before this commit, every time. It reads the store AT MOST ONCE PER NAME PER
+//     PROCESS — only to decide whether to warn that the env var is shadowing something — and never
+//     again, so the per-request hot path for an existing install costs the same property read it
+//     always did.
+//   • A fresh hosted install sets neither env var (the deploy button asks for one value, the
+//     credential encryption key), so it reads the store, which is where `/setup` put them.
+//
+// The cost, stated plainly: an operator who runs `/setup` on a deployment that still has the env vars
+// set will find the stored credentials ignored. {@link slackCredentialSourceNotice} is what makes that
+// visible instead of mysterious — the page says it before the run, and the resolver logs it once.
+//
+// MEMOISED PER PROCESS WITH A SHORT TTL, store reads only. The signature check runs on every inbound
+// Slack request and the bot token on every outbound call, so a vault round trip per request is not
+// acceptable.
+//
+// 🔴 THE TTL IS NOT A TIDINESS CHOICE — A LIFETIME MEMO WAS A CORRECTNESS BUG. An earlier draft cached
+// a store hit for the process's lifetime, on the same reasoning core's `self-secrets.ts` gives for its
+// own memo. That reasoning does not transfer, because `self-secrets` holds values this deployment
+// minted for ITSELF and only rotation changes: nothing re-mints them behind a warm process. These two
+// DO change behind one — `reopen_slack_setup` followed by a second `/setup` run replaces both, by
+// design. With a lifetime memo every warm instance kept serving the OLD signing secret and the OLD
+// bot token after that second install, so the deployment verified the previous app's signature and
+// posted with the previous app's token until every instance happened to recycle: a 401 loop that
+// healed at different times on different instances, with nothing in the logs naming the cause.
+//
+// A TTL bounds that to {@link HIT_TTL_MS} without giving up the per-request cost, which is what the
+// memo was for. It is deliberately not a cache invalidated by the reopen path: a reopen runs in ONE
+// process and these memos live in all of them, so nothing a reopen does can reach them. Only time can. An env hit is not memoised because it is already a
+// property read. A MISS is remembered only BRIEFLY ({@link MISS_TTL_MS}) — long enough that an
+// unauthenticated POST to the public Slack route cannot drive one database query per request, short
+// enough that a process which booted before `/setup` finished still picks the credentials up without a
+// restart.
+
+import { encryptedKvVault, type EncryptedKvVault } from "@open-everywhere/core/agent/adapter-api.js";
+import { SLACK_BOT_TOKEN_REF, SLACK_SIGNING_SECRET_REF } from "./install-state.js";
+
+/** The env var holding the app's request-signing secret — the pre-OPE-2231 home, still first. */
+const SLACK_SIGNING_SECRET_ENV = "SLACK_SIGNING_SECRET";
+/** The env var holding the workspace bot token — the pre-OPE-2231 home, still first. */
+const SLACK_BOT_TOKEN_ENV = "SLACK_BOT_TOKEN";
+
+/** Which home answered. Reported by {@link resolveSlackSecret} for the suite and the notice. */
+export type SlackSecretSource = "env" | "store";
+
+/** Injectable seams for tests — the live defaults are the real vault and `process.env`. */
+export interface SlackCredentialDeps {
+  readonly vault?: EncryptedKvVault;
+  readonly env?: NodeJS.ProcessEnv;
+  /** The clock the hit and miss TTLs are read against. Tests advance it to prove a cached value stops
+   *  being reused; the live default is `Date.now`. */
+  readonly now?: () => number;
+  /**
+   * Use the per-process memo even though a vault is injected. TEST SEAM ONLY.
+   *
+   * 🔴 WHY IT HAS TO EXIST. An injected vault normally bypasses the memo, which is a contract the suite
+   * leans on — a test rewrites a row and the next call sees it. But that also made {@link HIT_TTL_MS}
+   * UNTESTABLE: the only path that memoises was the one no test can hand a store to. A TTL nobody can
+   * drive is a claim nobody has checked, and this one is the fix for a real defect (see the header), so
+   * the seam is the smaller cost. Nothing in `agent/**` passes it.
+   */
+  readonly memo?: boolean;
+}
+
+/** A resolved secret and the home it came from. */
+export interface ResolvedSlackSecret {
+  readonly value: string;
+  readonly source: SlackSecretSource;
+}
+
+/**
+ * How long a resolved STORE value is reused. Bounds how long a warm instance can keep serving the
+ * credentials a `reopen_slack_setup` + second `/setup` run replaced — see the header. Thirty seconds
+ * keeps the per-request cost at zero in the steady state while making a reinstall take effect on its
+ * own, which a lifetime memo never did.
+ */
+const HIT_TTL_MS = 30_000;
+
+/** A resolved store value and when it stops being trusted. */
+const memo = new Map<string, { readonly value: string; readonly until: number }>();
+
+/**
+ * How long a store MISS is remembered. A miss cannot be cached for the process's life — a process
+ * that boots while `/setup` is still running has to pick the credentials up without a restart — but it
+ * must not be re-asked on every request either.
+ *
+ * 🔴 WHY A MISS NEEDS CACHING AT ALL. The signature check runs through this resolver on every inbound
+ * request to the PUBLIC Slack webhook route. On a deployment with neither an env var nor a stored value
+ * — which is every deployment for the whole window `/setup` is open — an uncached miss meant one
+ * `stored_credential` SELECT per request, before the 401. Anyone who knew the host could drive one
+ * database query per request by POSTing garbage. Thirty seconds bounds that at two queries a minute
+ * while keeping "a mid-`/setup` process picks them up without a restart" true, one TTL later.
+ */
+const MISS_TTL_MS = 30_000;
+
+/** When each ref's miss stops being trusted, epoch ms. Absent ⇒ no remembered miss. */
+const missUntil = new Map<string, number>();
+
+/** Test seam: forget memoised store resolutions, hits and misses alike. */
+export function resetSlackCredentialMemo(): void {
+  memo.clear();
+  missUntil.clear();
+}
+
+const noticed = new Set<string>();
+
+/** The names whose env-shadows-store CHECK has run in this process, whether or not it warned. See the
+ *  resolver: keying the one-shot off `noticed` alone made the no-stored-value case re-read the vault
+ *  on every single request. */
+const shadowChecked = new Set<string>();
+
+/** Test seam: forget which names have already logged the shadowing notice, and which have been
+ *  checked at all. */
+export function resetSlackCredentialNotices(): void {
+  noticed.clear();
+  shadowChecked.clear();
+}
+
+/**
+ * The sentence an operator needs when the env var is set AND the store holds a value for the same
+ * secret: the env var is winning and the stored value is inert. `undefined` when there is nothing to
+ * say. The `/setup` page renders this before a run so the operator learns it BEFORE capturing
+ * credentials the deployment will ignore, and {@link resolveSlackSecret} logs it once per name.
+ */
+function slackCredentialSourceNotice(envName: string): string {
+  return (
+    `[open-everywhere:slack-setup] ${envName} is set in the environment, so this deployment uses the environment value and ` +
+    `IGNORES the one in the credential store. That is the documented order (OPE-2231): env wins, so landing this change cannot ` +
+    `alter which Slack app an existing deployment speaks as. To use the stored value instead, unset ${envName} and redeploy.`
+  );
+}
+
+/**
+ * Resolve one Slack secret: env if set, else the credential store, else `undefined`.
+ *
+ * `undefined` is a real answer, not an error — it means this deployment has not been through `/setup`
+ * and holds no env var either. Each caller fails in its own way (the front route 401s; an outbound
+ * call throws the message eve's primitive always threw), which is what keeps this function free of
+ * any opinion about what a missing credential should do.
+ */
+export async function resolveSlackSecret(
+  envName: string,
+  fromEnv: string,
+  ref: string,
+  deps: SlackCredentialDeps = {},
+): Promise<ResolvedSlackSecret | undefined> {
+  // 🔴 THE ENV VALUE IS PASSED IN, NOT READ HERE, and that is a gate's requirement rather than a
+  // style choice. `lint:env-docs` resolves `env[SOME_CONST]` through the const so every variable the
+  // runtime reads can be named in `scripts/env-read-allowlist.ts`; a read through a PARAMETER
+  // (`env[envName]`) resolves to nothing, so the gate cannot tell which variable it reaches and
+  // refuses the site. The two public helpers below each do their own read with a module-level const
+  // as the key, which keeps both names visible to the allowlist — and leaves this function with no
+  // environment access at all.
+
+  // An injected vault means a test driving a specific store state — bypass the memo entirely, so a
+  // test can rewrite a row and see the effect without reaching for a reset.
+  const vault = deps.vault;
+  const now = (deps.now ?? Date.now)();
+  // The memo applies on the live path, and on an injected vault only when a test opts in — see
+  // `deps.memo`.
+  const memoApplies = vault === undefined || deps.memo === true;
+  const cached = memoApplies ? memo.get(ref) : undefined;
+  const memoised = cached !== undefined && cached.until > now ? cached.value : undefined;
+
+  if (fromEnv.length > 0) {
+    // Only say the env is shadowing a stored value when one is ACTUALLY stored — the notice is for
+    // the operator who ran `/setup` and is about to wonder why nothing changed, not for every
+    // deployment that has always used env.
+    //
+    // 🔴 THE CHECK IS MARKED DONE WHETHER OR NOT IT WARNED, and that is the whole reason this is a
+    // separate set from `noticed`. Keying the guard off "have I warned?" meant a deployment with the
+    // env var set and NOTHING stored — the common case, every pre-OPE-2231 install — never recorded
+    // that it had looked, so it re-read the vault on EVERY resolution: one store round trip per
+    // inbound Slack request, for an answer that was always going to be the env value. One read per
+    // name per process, then never again.
+    if (!shadowChecked.has(envName)) {
+      shadowChecked.add(envName);
+      const stored = memoised ?? (await readStored(ref, vault)); // best-effort; a store failure says nothing
+      if (stored !== undefined) {
+        noticed.add(envName);
+        console.warn(slackCredentialSourceNotice(envName));
+      }
+    }
+    return { value: fromEnv, source: "env" };
+  }
+
+  if (memoised !== undefined) return { value: memoised, source: "store" };
+
+  // A remembered MISS, still inside its TTL — answer without touching the store. Skipped entirely for
+  // an injected vault (a test driving a specific store state).
+  if (memoApplies) {
+    const until = missUntil.get(ref);
+    if (until !== undefined && until > now) return undefined;
+  }
+
+  const stored = await readStored(ref, vault);
+  if (stored === undefined) {
+    if (memoApplies) missUntil.set(ref, now + MISS_TTL_MS);
+    return undefined;
+  }
+  if (memoApplies) {
+    memo.set(ref, { value: stored, until: now + HIT_TTL_MS });
+    missUntil.delete(ref);
+  }
+  return { value: stored, source: "store" };
+}
+
+/** Read one ref out of the vault, fail-soft to `undefined`. A disarmed credential key, an
+ *  unreachable store and an absent row are one answer here on purpose: all three mean "the store has
+ *  nothing for me", and the caller's next step is the same for each. */
+async function readStored(ref: string, injected: EncryptedKvVault | undefined): Promise<string | undefined> {
+  try {
+    const value = await (injected ?? encryptedKvVault()).read(ref);
+    return value === null || value.length === 0 ? undefined : value;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The app's request-signing secret, or `undefined` when this deployment holds none. */
+export async function slackSigningSecret(deps: SlackCredentialDeps = {}): Promise<string | undefined> {
+  const env = deps.env ?? process.env;
+  const fromEnv = (env[SLACK_SIGNING_SECRET_ENV] ?? "").trim();
+  return (await resolveSlackSecret(SLACK_SIGNING_SECRET_ENV, fromEnv, SLACK_SIGNING_SECRET_REF, deps))?.value;
+}
+
+/** The workspace bot token, or `undefined` when this deployment holds none. */
+export async function slackBotToken(deps: SlackCredentialDeps = {}): Promise<string | undefined> {
+  const env = deps.env ?? process.env;
+  const fromEnv = (env[SLACK_BOT_TOKEN_ENV] ?? "").trim();
+  return (await resolveSlackSecret(SLACK_BOT_TOKEN_ENV, fromEnv, SLACK_BOT_TOKEN_REF, deps))?.value;
+}
+
+/**
+ * Is `name`'s env var set, for the ONE caller that needs to ask without resolving — the `/setup`
+ * page's "this env var will shadow what you are about to store" notice.
+ *
+ * Unrolled rather than looped over the two names for the same reason {@link resolveSlackSecret} takes
+ * its env value as a parameter: the gate resolves a const key and nothing else.
+ */
+export function slackSecretEnvPresent(deps: SlackCredentialDeps = {}): { readonly signingSecret: boolean; readonly botToken: boolean } {
+  const env = deps.env ?? process.env;
+  return {
+    signingSecret: (env[SLACK_SIGNING_SECRET_ENV] ?? "").trim().length > 0,
+    botToken: (env[SLACK_BOT_TOKEN_ENV] ?? "").trim().length > 0,
+  };
+}