@open-everywhere/provider-slack 0.1.3 → 0.1.4

package/dist/agent/setup/credentials.js

@@ -0,0 +1,214 @@
+// 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 } 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";
+/**
+ * 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();
+/**
+ * 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();
+/** Test seam: forget memoised store resolutions, hits and misses alike. */
+export function resetSlackCredentialMemo() {
+    memo.clear();
+    missUntil.clear();
+}
+const noticed = new Set();
+/** 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();
+/** Test seam: forget which names have already logged the shadowing notice, and which have been
+ *  checked at all. */
+export function resetSlackCredentialNotices() {
+    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) {
+    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, fromEnv, ref, deps = {}) {
+    // 🔴 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, injected) {
+    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 = {}) {
+    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 = {}) {
+    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 = {}) {
+    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,
+    };
+}
+//# sourceMappingURL=credentials.js.map

package/dist/agent/setup/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../../agent/setup/credentials.ts"],"names":[],"mappings":"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"}

package/dist/agent/setup/eve-credentials.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare function verifySlackInboundForEve(request: Request, body: string): Promise<void>;
+/**
+ * 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 declare function slackBotTokenForEve(): Promise<string>;
+/** 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 declare const SLACK_EVE_CREDENTIALS: {
+    readonly webhookVerifier: typeof verifySlackInboundForEve;
+    readonly botToken: typeof slackBotTokenForEve;
+};
+//# sourceMappingURL=eve-credentials.d.ts.map

package/dist/agent/setup/eve-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-credentials.d.ts","sourceRoot":"","sources":["../../../agent/setup/eve-credentials.ts"],"names":[],"mappings":"AAiCA;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB5F;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAI3D;AAED;8EAC8E;AAC9E,eAAO,MAAM,qBAAqB;aAChC,eAAe;aACf,QAAQ;CACA,CAAC"}

package/dist/agent/setup/eve-credentials.js

@@ -0,0 +1,73 @@
+// 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, body) {
+    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() {
+    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,
+};
+//# sourceMappingURL=eve-credentials.js.map

package/dist/agent/setup/eve-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-credentials.js","sourceRoot":"","sources":["../../../agent/setup/eve-credentials.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,kGAAkG;AAClG,+FAA+F;AAC/F,gFAAgF;AAChF,EAAE;AACF,6FAA6F;AAC7F,oHAAoH;AACpH,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,sGAAsG;AACtG,sGAAsG;AACtG,mGAAmG;AACnG,+EAA+E;AAC/E,iCAAiC;AACjC,EAAE;AACF,kGAAkG;AAClG,oGAAoG;AACpG,uFAAuF;AACvF,EAAE;AACF,oGAAoG;AACpG,+FAA+F;AAC/F,uGAAuG;AACvG,oFAAoF;AAEpF,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACvH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAErE;6FAC6F;AAC7F,MAAM,gBAAgB,GAAG,EAAE,GAAG,CAAC,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,OAAgB,EAAE,IAAY;IAC3E,MAAM,MAAM,GAAG,MAAM,kBAAkB,EAAE,CAAC;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mHAAmH;YACjH,0CAA0C,CAC7C,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC9D,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAE1G,mGAAmG;IACnG,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,gBAAgB;QAAE,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IAE9I,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;AAClI,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,KAAK,GAAG,MAAM,aAAa,EAAE,CAAC;IACpC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAC5D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;8EAC8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,eAAe,EAAE,wBAAwB;IACzC,QAAQ,EAAE,mBAAmB;CACrB,CAAC"}

package/dist/agent/setup/install-state.d.ts

@@ -0,0 +1,139 @@
+import { 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 declare const SLACK_CLIENT_SECRET_REF = "slack-app:client_secret";
+/** The ref holding the app's request-signing secret. SECRET. */
+export declare const SLACK_SIGNING_SECRET_REF = "slack-app:signing_secret";
+/** The ref holding the workspace bot token (`xoxb-…`). SECRET. */
+export declare const SLACK_BOT_TOKEN_REF = "slack-app: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 declare const SLACK_PENDING_SIGNING_SECRET_REF = "slack-app:pending_signing_secret";
+/** The ref holding the HMAC key for the claim cookie. SECRET, and minted here — see claim.ts. */
+export declare const SLACK_COOKIE_KEY_REF = "slack-app:cookie_key";
+/** The ref holding the one-time setup code a human reads out of the deployment's logs. SECRET. */
+export declare const SLACK_SETUP_CODE_REF = "slack-app:setup_code";
+/** The ref holding {@link SlackInstallState} as JSON. The ONLY ref here with no secret in it. */
+export declare const SLACK_INSTALL_REF = "slack-app: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 declare const SLACK_PENDING_REF = "slack-app: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;
+}
+/**
+ * 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 declare function slackInstallState(deps?: SlackInstallStateDeps): Promise<SlackInstallState | undefined>;
+/**
+ * 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 declare function readInstallRecord(deps?: SlackInstallStateDeps): Promise<InstallRecordRead>;
+/** Parse + validate a stored record. Exported for the suite; `undefined` for anything unreadable. */
+export declare function parseInstallState(raw: string): SlackInstallState | undefined;
+/**
+ * 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 declare function recordSlackInstall(state: SlackInstallState, deps?: SlackInstallStateDeps): Promise<void>;
+/**
+ * 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 declare function reopenSlackSetup(deps?: SlackInstallStateDeps): Promise<boolean>;
+//# sourceMappingURL=install-state.d.ts.map

package/dist/agent/setup/install-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-state.d.ts","sourceRoot":"","sources":["../../../agent/setup/install-state.ts"],"names":[],"mappings":"AA2BA,OAAO,EAA6C,KAAK,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAE9H,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB,4BAA4C,CAAC;AACjF,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,6BAA6C,CAAC;AACnF,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,wBAAwC,CAAC;AACzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,qCAAqD,CAAC;AACnG,iGAAiG;AACjG,eAAO,MAAM,oBAAoB,yBAAyC,CAAC;AAC3E,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,yBAAyC,CAAC;AAC3E,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,sBAAsC,CAAC;AACrE;;2CAE2C;AAC3C,eAAO,MAAM,iBAAiB,sBAAsC,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAEhH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAE/D,oGAAoG;AACpG,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAYpG;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CA2B5E;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAElH;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAiCzF"}