@open-everywhere/provider-slack 0.1.0

package/agent/channels/slack-web-api.ts

@@ -0,0 +1,178 @@
+// slack-web-api — THE ONE place a Slack Web API call leaves this host (OPE-1211).
+//
+// WHY THIS MODULE REPLACED eve's `callSlackApi`. Every Slack write used to funnel into
+// `callSlackApi` from `eve/channels/slack`. That primitive is a bare `fetch` POST: it reads no
+// status but the 2xx/non-2xx split, and on a non-2xx it throws a `SlackApiError` carrying
+// `{ method, response, status }` — and NOT the response headers. Slack states a rate-limit delay in
+// the `Retry-After` HEADER and nowhere else, so that delay was unreadable from OE code. Honouring it
+// therefore needs OE to own the request. This module is a faithful port of eve's encoding, token
+// resolution and error posture, with the 429 backoff added around the call.
+//
+// 🔴 WHAT THIS SEAM COVERS, EXACTLY. Every Slack Web API call this repo issues DIRECTLY goes through
+// here: `slackForm`, `callSlackRead`, the `auth.test` identity probes and the wake backscroll. It
+// does NOT cover the calls that ride eve's session BINDING, because those never reach OE code:
+//   • `ctx.slack.request(...)` — slack-context.ts (`auth.test`, `conversations.history`);
+//   • `ctx.thread.postEphemeral(...)` — slack-input-response.ts;
+//   • eve's own machinery — `startTyping`, thread `refresh`, `uploadSlackFiles`.
+// Those resolve through eve's `createSlackRequester`/`postSlackEphemeral` to the same bare
+// `callSlackApi`, so they still fail on the first 429. `slack-web-api-seam-test.ts` holds that list
+// as a KNOWN-UNCOVERED inventory and fails when a NEW bypass appears, which is the honest guarantee:
+// the seam is not universal, but the set of things outside it cannot grow unnoticed.
+//
+// SEMANTICS PORTED VERBATIM from eve's primitive, because callers depend on each one:
+//   • Form encoding. Slack's JSON support is partial (`conversations.replies`/`history` want form),
+//     so form is the only safe default. A null or undefined value is dropped; a string, number or
+//     boolean is stringified; anything else is JSON-encoded.
+//   • Token resolution. An explicit token wins, otherwise `SLACK_BOT_TOKEN`. Neither ⇒ throw
+//     `SLACK_BOT_TOKEN is required.` — the same message and the same fail-loud posture. ONE
+//     DELIBERATE NARROWING: eve's `SlackBotToken` also accepts a function (the secret-manager and
+//     rotation form). No caller in this repo passes one, so this seam takes a string. Widening it
+//     back is a one-line `await` on the resolver if the multi-bot seam ever needs it.
+//   • `ok:false` PASSES THROUGH. Slack answers HTTP 200 with `ok:false` when it read the request and
+//     refused it. That is a successful transport, and the callers classify it themselves
+//     (slack-read.ts marks it not-applied; slack-post-arm.ts reads it as definitive). This module
+//     must never turn it into a throw.
+//   • A non-2xx THROWS {@link SlackWebApiError}. A request that got no usable reply stays ambiguous,
+//     which is what the post spine needs to avoid double-posting.
+//
+// WHAT IS NEW: a 429 is retried after the delay `Retry-After` names, bounded by
+// `channels/rate-limit-retry.js`. When the attempts run out the call throws `RateLimitExhaustedError`
+// — a NAMED failure. Non-429 responses are untouched.
+
+import { withRetryAfter, type RateLimitRetryOptions } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** Slack's Web API base. A trailing slash is required — `new URL(operation, base)` resolves the
+ *  operation against the LAST path segment otherwise. */
+const SLACK_API_BASE = "https://slack.com/api/";
+
+/** The Slack Web API JSON envelope. `ok` signals Slack's own verdict; callers inspect it. */
+export interface SlackWebApiResponse {
+  readonly ok?: boolean;
+  readonly error?: string;
+  readonly [key: string]: unknown;
+}
+
+/** The failure a non-2xx Slack response produces. Mirrors eve's `SlackApiError` field-for-field, so
+ *  a caller that reads `status` or `response` off a caught error keeps reading the same thing. */
+export class SlackWebApiError extends Error {
+  readonly method: string;
+  readonly status: number;
+  readonly response: unknown;
+
+  constructor(init: { method: string; status: number; response: unknown }) {
+    super(`Slack ${init.method} returned HTTP ${init.status}`);
+    this.name = "SlackWebApiError";
+    this.method = init.method;
+    this.status = init.status;
+    this.response = init.response;
+  }
+}
+
+/** The subset of the global `fetch` this module uses — injectable so tests drive it without Slack. */
+export type SlackFetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** Transport and retry seams. A test injects all of them; live code passes none. */
+export interface SlackWebApiDeps {
+  readonly fetch?: SlackFetchLike;
+  readonly sleep?: RateLimitRetryOptions["sleep"];
+  readonly now?: RateLimitRetryOptions["now"];
+  readonly maxAttempts?: number;
+  readonly capMs?: number;
+  readonly totalBudgetMs?: number;
+  readonly apiBase?: string;
+}
+
+/** Form-encode a Slack request body exactly as eve's `encodeSlackApiBody` does. */
+export function encodeSlackForm(body: unknown): string {
+  const params = new URLSearchParams();
+  if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+    for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+      if (value === null || value === undefined) continue;
+      const scalar = typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+      params.set(key, scalar ? String(value) : JSON.stringify(value));
+    }
+  }
+  return params.toString();
+}
+
+/**
+ * Operations that are BEST-EFFORT PROBES on a latency-critical path, and their tightened policy.
+ *
+ * 🔴 WHY THIS EXISTS (OPE-1211 review finding 2). `auth.test` resolves the bot's own identity, and
+ * `slack-front.ts` awaits it BEFORE returning `OK()` on the route Slack posts events to. Slack times
+ * that ack out at 3 seconds and re-delivers; an app that keeps missing the ack gets its event
+ * subscription disabled. Under the shared defaults a workspace-wide 429 — the exact case this whole
+ * change exists for — would block that ack for up to 60 s and turn a rate-limit episode into a
+ * delivery outage. So the probe waits at most about 2 s in total, and its callers already degrade
+ * gracefully when it answers nothing.
+ *
+ * `conversations.info` and `users.info` are here for the same reason (deploy #142 batch review):
+ * the Slack front route awaits both before `OK()` — `channelFactsFor` resolves through
+ * `channelInternalAndMeta` (fails closed to `{internal:false}`) and `authorFactsFor` through
+ * `slackAuthorIsMember` (fails closed to `undefined`) — so the shared 60 s budget would hold the
+ * 3-second ack exactly like `auth.test`.
+ *
+ * `conversations.open` joined them for the SAME two reasons (OPE-1376): a GLOBAL shortcut has no
+ * conversation, so the front route awaits this call to resolve the invoker's DM before it acks, and
+ * `liveOpenDirectMessageChannel` fails closed to `undefined` (the shortcut then wakes nothing and
+ * says so). Slack's interactivity budget is 3 seconds, so the shared policy would hold the ack past
+ * it on a rate-limited workspace. It is NOT here for the governance DM-delivery arm, which makes
+ * the same call off any ack's critical path and is content with the shared budget.
+ *
+ * Only add an operation here if BOTH hold: its caller treats a failure as non-fatal, AND something
+ * time-critical waits on it.
+ *
+ * Every member is pinned by name in `scripts/slack-rate-limit-test.ts` § 4c (OPE-1242): drop one
+ * and it falls back to the shared 4-attempt / 30 s policy, which that suite asserts against.
+ */
+const PROBE_OPERATIONS: ReadonlySet<string> = new Set(["auth.test", "conversations.info", "users.info", "conversations.open"]);
+const PROBE_MAX_ATTEMPTS = 2;
+const PROBE_CAP_MS = 2_000;
+
+/** An explicit token, else `SLACK_BOT_TOKEN`. Throws eve's exact message when neither is set. */
+function resolveBotToken(botToken: string | undefined): string {
+  const token = botToken ?? process.env.SLACK_BOT_TOKEN;
+  if (!token) throw new Error("SLACK_BOT_TOKEN is required.");
+  return token;
+}
+
+/**
+ * POST one Slack Web API method, with the 429 backoff applied.
+ *
+ * Returns Slack's parsed JSON envelope on any 2xx, `ok:false` included. Throws
+ * {@link SlackWebApiError} on a non-2xx that is not a 429, and `RateLimitExhaustedError` when a 429
+ * outlasts the bounded attempts.
+ */
+export async function callSlackWebApi(
+  input: { readonly botToken?: string; readonly operation: string; readonly body: unknown },
+  deps: SlackWebApiDeps = {},
+): Promise<SlackWebApiResponse> {
+  const token = resolveBotToken(input.botToken);
+  const encoded = encodeSlackForm(input.body);
+  const url = new URL(input.operation, deps.apiBase ?? SLACK_API_BASE).toString();
+  const send = (): Promise<Response> =>
+    (deps.fetch ?? (globalThis.fetch as SlackFetchLike))(url, {
+      body: encoded,
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/x-www-form-urlencoded" },
+      method: "POST",
+    });
+
+  const probe = PROBE_OPERATIONS.has(input.operation);
+  const res = await withRetryAfter(send, {
+    surface: "slack",
+    operation: input.operation,
+    // An explicit dep always wins, so a test still drives the policy it wants.
+    maxAttempts: deps.maxAttempts ?? (probe ? PROBE_MAX_ATTEMPTS : undefined),
+    capMs: deps.capMs ?? (probe ? PROBE_CAP_MS : undefined),
+    totalBudgetMs: deps.totalBudgetMs,
+    sleep: deps.sleep,
+    now: deps.now,
+  });
+
+  // eve parses the body before the status check, so a non-2xx carries Slack's error envelope. Keep
+  // that, and keep the parse failure that a non-JSON body produces — callers already treat any throw
+  // from this seam as an ambiguous transport failure.
+  const json = (await res.json()) as SlackWebApiResponse;
+  if (!res.ok) throw new SlackWebApiError({ method: input.operation, status: res.status, response: json });
+  return json;
+}

package/agent/channels/slack-webhook-verifier.ts

@@ -0,0 +1,116 @@
+// Slack's webhook signature scheme, as a registry entry (OPE-197) — what lets a GENERIC hook
+// (`POST /webhooks/<id>`) declare `source: "slack"` and be verified exactly the way Slack signs,
+// instead of the deployment being able to check that signature in the surface front door and
+// nowhere else.
+//
+// WHY THIS EXISTS AT ALL, in the two terms that survive. (1) `registeredWebhookVerifierSources()` is
+// printed VERBATIM in the gate's 401 (webhooks/gate.ts), so it is a live statement to a caller about
+// what this deployment can authenticate — and it was under-reporting a scheme the tree has
+// implemented and tested for as long as the Slack surface has existed. (2) Registration is the only
+// place `keyOrigin` and `signedTimestamp` get DECLARED, and those two fields are what drive
+// `acceptsMintedSecret` (webhooks/source-vocabulary.ts) and the durable single-use replay dedupe
+// (webhooks/replay-dedupe.ts). Inline in a front door, both facts are true of the code and invisible
+// to every registry that reasons about them.
+//
+// ZERO NEW CRYPTO. The basestring and digest are `channels/slack-signature.ts`'s — the SAME
+// primitive the surface front door (`verifySlackSignature`) uses, extracted for this entry rather
+// than copied, so there is one implementation of Slack's scheme in the tree and not two that can
+// drift. What this file adds is the part a registry entry needs and a boolean-returning front door
+// has no use for: the closed FAILURE vocabulary, and iteration over a rotation's key list.
+//
+// THE SCHEME (https://api.slack.com/authentication/verifying-requests-from-slack):
+//   X-Slack-Request-Timestamp: <unix seconds>
+//   X-Slack-Signature:         v0=<hex>   HMAC-SHA256 of `v0:<timestamp>:<raw body>`.
+//
+// 🔴 `keyOrigin: "vendor-issued"` (OPE-186) — the key is the app's **Signing Secret**, which SLACK
+// generates and shows on the app's Basic Information page (docs/deploy/surfaces/slack.md step 1.5:
+// *"copy the Signing Secret"*). It is read, never chosen, so a secret WE minted can never verify a
+// Slack delivery. That is what keeps `slack` OUT of the chat-mintable source vocabulary
+// (`acceptsMintedSecret` is false for it) — only an OPERATOR-DECLARED hook, whose `secretRef` the
+// operator points at the stored signing secret, can use this verifier. Registering it does NOT make
+// it chat-creatable, and that is the intended outcome, not a limitation to be fixed later.
+//
+// ⭐ `signedTimestamp: true` — and this is the substantive gain over leaving it inline. Slack's
+// basestring COVERS the timestamp, so the freshness claim is the sender's own signed one, and this
+// verifier enforces a window against it. Under `webhooks/gate.ts` that promotes the source from
+// "replay bounded by nothing" to the durable single-use 409 (webhooks/replay-dedupe.ts) — the layer
+// `github` and `notion` structurally cannot have, because they sign the body alone.
+//
+// ⚠️ THE SKEW WINDOW HERE IS THE DEPLOYMENT'S, NOT SLACK'S. The front door hard-codes Slack's own
+// documented 5 minutes because it answers a Slack Request URL; this entry reads
+// `webhookMaxSkewSeconds()` (`OE_WEBHOOK_MAX_SKEW_SECONDS`, default 300) because it answers the
+// GENERIC ingress, where an operator's one freshness bound governs every scheme. The two coincide at
+// the default on purpose and are allowed to diverge on purpose.
+//
+// NOTE this entry changes NO existing route. `/eve/v1/slack` and `/eve/v1/slack/commands` keep their
+// own inline gate, unchanged; registering here only makes the scheme available to the generic
+// ingress.
+
+import { createHash } from "node:crypto";
+import {
+  SLACK_SIGNATURE_HEADER,
+  SLACK_SIGNATURE_VERSION,
+  SLACK_TIMESTAMP_HEADER,
+  slackSignatureMatches,
+} from "./slack-signature.js";
+import { webhookMaxSkewSeconds, type WebhookVerifier } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The registry key — what a generic hook declares as its `source` to be verified as Slack. */
+export const SLACK_WEBHOOK_SOURCE = "slack";
+
+/** Unix seconds, as Slack sends them. Checked as TEXT before `Number()` so `"1e9"`, `" 12"` and
+ *  `"12.0"` are `malformed-timestamp` rather than silently coerced into a passing window. */
+const TIMESTAMP_RE = /^[0-9]{1,15}$/;
+
+/**
+ * The opaque single-use nonce for an accepted Slack delivery.
+ *
+ * 🔴 IT IS THE SIGNED CONTENT, HASHED — not a delivery id, because Slack's scheme has none: the
+ * basestring is `v0:<timestamp>:<rawBody>` and nothing else, so `(timestamp, rawBody)` IS the
+ * complete identity the sender signed. Two presentations agreeing on both are, to this scheme,
+ * indistinguishable — which is exactly what "the same delivery, twice" means here.
+ *
+ * WHAT THAT COSTS, stated rather than assumed: a byte-identical re-send from Slack inside the window
+ * is graded a replay. That is deliberate and it is nearly free, because a byte-identical re-send
+ * OUTSIDE the window already fails the skew check at 401 — so this dedupe only ever changes the
+ * verdict in the interval where the scheme itself cannot tell a legitimate re-send from a captured
+ * one. Deriving it from the SIGNATURE instead would have been wrong for a different reason: the
+ * signature is key-dependent, so it would change identity across a rotation overlap for a delivery
+ * that never changed.
+ */
+function slackReplayKey(timestamp: string, rawBody: string): string {
+  return createHash("sha256").update(`${SLACK_WEBHOOK_SOURCE}:${timestamp}:${rawBody}`).digest("hex");
+}
+
+export const slackWebhookVerifier: WebhookVerifier = {
+  source: SLACK_WEBHOOK_SOURCE,
+  // Provider-owned ⇒ routed through admitProviderRegistration: de-select the slack bundle and this
+  // row never lands, so a `source: "slack"` hook 401s instead of silently using another scheme.
+  provider: "slack",
+  keyKind: "shared-secret",
+  keyOrigin: "vendor-issued",
+  signedTimestamp: true,
+  verify({ rawBody, headers, keys, nowMs }) {
+    const signature = headers.get(SLACK_SIGNATURE_HEADER);
+    if (!signature) return { ok: false, failure: "missing-signature" };
+    const timestamp = headers.get(SLACK_TIMESTAMP_HEADER);
+    // A missing timestamp is its own failure, not `missing-signature`: it is COVERED BY the
+    // signature, so without it there is no basestring to compute at all.
+    if (timestamp === null) return { ok: false, failure: "missing-timestamp" };
+    if (!TIMESTAMP_RE.test(timestamp)) return { ok: false, failure: "malformed-timestamp" };
+    // SKEW BEFORE ANY HMAC — a stale replay must not cost a digest per configured key.
+    if (Math.abs(nowMs / 1000 - Number(timestamp)) > webhookMaxSkewSeconds()) return { ok: false, failure: "stale-timestamp" };
+    // A signature tagged with a version we do not implement is `unsupported-scheme`, never an
+    // attempted match: if Slack ever ships a `v1`, guessing at it is the shape of a downgrade.
+    if (!signature.startsWith(`${SLACK_SIGNATURE_VERSION}=`)) return { ok: false, failure: "unsupported-scheme" };
+    for (const [i, key] of keys.entries()) {
+      // Ordered, current-first: a match at i>0 is a rotation overlap and the gate audits it. Slack
+      // documents no overlap window of its own (rotating the signing secret is immediate), so
+      // `keys[]` is how an operator gets one on our side.
+      if (slackSignatureMatches(key, timestamp, rawBody, signature)) {
+        return { ok: true, keyIndex: i, replayKey: slackReplayKey(timestamp, rawBody) };
+      }
+    }
+    return { ok: false, failure: "signature-mismatch" };
+  },
+};