slack-term 1.47.0 → 1.48.0

package/worker/src/hub.ts

@@ -0,0 +1,203 @@
+// The relay's WebSocket side, as pure logic: no Cloudflare types, so the CLI's
+// test suite exercises it under bun with fake sockets (tests/relay-hub.test.ts).
+// index.ts adapts a hibernatable WebSocket to `Sock` and SQLite to `Store`.
+//
+// Why WebSocket: an open SSE response keeps the Durable Object in memory — and
+// billed for duration — for as long as any client is connected. A socket
+// accepted with ctx.acceptWebSocket() lets the object hibernate between bells,
+// and the client's keepalive ("ping" → "pong") is answered by the runtime
+// without waking it. Everything this module remembers about a client
+// therefore lives in the socket's attachment, which survives hibernation;
+// nothing lives in memory, and nothing waits on a timer.
+//
+// The guarantees are those of the SSE path:
+//   - hello first: {seq, gap, retention_sec, epoch}, from the same resume rules;
+//   - then the backlog after seq, read from storage in REPLAY_BATCH steps, and
+//     only then live bells — the switch happens right after a read that came
+//     back empty, synchronously, so a bell rung meanwhile is never lost: it is
+//     either in storage for the next read or delivered live;
+//   - a client that stops taking bells is cut off, not buffered for without
+//     bound. SSE learned that from write backpressure; a WebSocket send gives
+//     none, so the client acks ({"type":"ack","seq":n}) what it has received.
+//     A replay step waits for the ack of the previous one (one batch in flight
+//     at most); live bells are cut off past MAX_PENDING unacked; a client that
+//     leaves a send unacked for STALL_MS, or stops pinging for DEAD_MS, is
+//     closed. Closed clients reconnect with ?after and get the rest from storage.
+
+import { type Doorbell as Bell, safeEqual } from "./slack.ts";
+
+export type { Bell };
+export type Row = { seq: number; channel: string; ts: string; thread_ts: string | null; self: string | null };
+export type Hello = { seq: number; gap: boolean; retention_sec: number; epoch: string };
+
+/** Per-socket state, kept with serializeAttachment (2 KiB max; this is ~100 B). */
+export type Attachment = {
+  /** Highest seq sent to this client (its resume point, at the start). */
+  sent: number;
+  /** Highest seq the client has acked. */
+  acked: number;
+  /** Still being fed its backlog from storage; live bells reach it that way. */
+  replaying: boolean;
+  /** Since when (ms) the client owes an ack without having made progress;
+   *  0 while nothing is unacked. */
+  waitSince: number;
+  /** Last message from the client (ms): connect, or an ack. */
+  lastSeen: number;
+};
+
+export interface Sock {
+  send(data: string): void;
+  close(code: number, reason: string): void;
+  attachment(): Attachment | null;
+  setAttachment(a: Attachment): void;
+  /** Last runtime-answered "ping" (ms since epoch), null if none yet. */
+  lastPing(): number | null;
+}
+
+export interface Store {
+  rowsAfter(seq: number, limit: number): Row[];
+}
+
+/** The subprotocol a client must offer; the server echoes it back. */
+export const PROTOCOL = "slack-term-relay.v1";
+/** The other offered subprotocol carries the bearer: `bearer.<base64url(token)>`.
+ *  A header, not the URL: query strings end up in logs. */
+export const BEARER_PREFIX = "bearer.";
+/** Backlog rows sent per replay step. */
+export const REPLAY_BATCH = 100;
+/** Live bells a client may have unacked before it is cut off. */
+export const MAX_PENDING = 64;
+/** An unacked send older than this frees the client's slot. */
+export const STALL_MS = 30_000;
+/** Clients ping every 25 s; one silent for this long is gone. */
+export const DEAD_MS = 90_000;
+/** Close codes (4000–4999: application-defined). */
+export const CLOSE_OVERFLOW = 4008;
+export const CLOSE_STALLED = 4009;
+export const CLOSE_GONE = 4010;
+
+export function base64url(s: string): string {
+  let bin = "";
+  for (const b of new TextEncoder().encode(s)) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Does a Sec-WebSocket-Protocol header offer our protocol and this token?
+ *  Every offered entry is compared, so timing does not reveal which matched. */
+export function protocolAuthorized(header: string | null, token: string): boolean {
+  if (!header || !token) return false;
+  const want = BEARER_PREFIX + base64url(token);
+  let ok = false;
+  let ours = false;
+  for (const p of header.split(",")) {
+    const v = p.trim();
+    if (v === PROTOCOL) ours = true;
+    if (safeEqual(v, want)) ok = true;
+  }
+  return ok && ours;
+}
+
+/** Where a (re)connecting client starts, from ?after (or Last-Event-ID) and
+ *  ?epoch. Absent `after` means "from now". A seq we can no longer serve —
+ *  expired, or from a relay whose storage was reset (a different epoch, or a
+ *  number past our high-water mark) — is a gap: everything kept is replayed
+ *  and the client must also catch up by polling. */
+export function resumePoint(
+  rawAfter: string | null, clientEpoch: string | null, epoch: string, oldest: number | null, latest: number,
+): { from: number; gap: boolean } {
+  const after = rawAfter !== null && /^\d+$/.test(rawAfter) ? Number(rawAfter) : null;
+  if (after === null) return { from: latest, gap: false };
+  const reset = after > latest || (clientEpoch !== null && clientEpoch !== epoch);
+  const gap = reset || (oldest !== null ? after < oldest - 1 : after < latest);
+  return { from: reset ? 0 : after, gap };
+}
+
+export function bellOf(r: Row): Bell {
+  return {
+    channel: r.channel, ts: r.ts,
+    ...(r.thread_ts ? { thread_ts: r.thread_ts } : {}),
+    ...(r.self ? { self: r.self } : {}),
+  };
+}
+
+const bellMsg = (seq: number, b: Bell): string => JSON.stringify({ type: "bell", seq, bell: b });
+
+function trySend(s: Sock, data: string): boolean {
+  try {
+    s.send(data);
+    return true;
+  } catch {
+    s.close(1011, "send failed");
+    return false;
+  }
+}
+
+/** One replay step: the next batch after `a.sent`, or — when that read comes
+ *  back empty — the switch to live. Synchronous from read to switch. */
+function step(s: Sock, a: Attachment, store: Store, now: number, prefix?: string): void {
+  if (prefix !== undefined && !trySend(s, prefix)) return;
+  const rows = store.rowsAfter(a.sent, REPLAY_BATCH);
+  for (const r of rows) {
+    if (!trySend(s, bellMsg(r.seq, bellOf(r)))) return;
+    a.sent = r.seq;
+  }
+  if (!rows.length) a.replaying = false;
+  else if (!a.waitSince) a.waitSince = now;
+  s.setAttachment(a);
+}
+
+/** A newly accepted socket: hello, then the first replay step. */
+export function open(s: Sock, from: number, hello: Hello, store: Store, now: number): void {
+  const a: Attachment = { sent: from, acked: from, replaying: true, waitSince: 0, lastSeen: now };
+  step(s, a, store, now, JSON.stringify({ type: "hello", ...hello }));
+}
+
+/** A message from the client. Only acks mean anything; the rest is ignored. */
+export function message(s: Sock, data: string | ArrayBuffer, store: Store, now: number): void {
+  const a = s.attachment();
+  if (!a) return s.close(1011, "no session");
+  a.lastSeen = now;
+  let seq: unknown;
+  if (typeof data === "string" && data.length <= 200) {
+    try {
+      const m = JSON.parse(data) as { type?: unknown; seq?: unknown };
+      if (m && m.type === "ack") seq = m.seq;
+    } catch { /* not JSON: ignored */ }
+  }
+  if (typeof seq === "number" && Number.isSafeInteger(seq)) {
+    const acked = Math.min(seq, a.sent);
+    // Progress restarts the stall clock: "stalled" means no ack progress for
+    // STALL_MS while something is unacked, not a long busy stretch.
+    if (acked > a.acked) a.waitSince = acked >= a.sent ? 0 : now;
+    a.acked = Math.max(a.acked, acked);
+  }
+  if (a.replaying && a.acked >= a.sent) return step(s, a, store, now);
+  s.setAttachment(a);
+}
+
+/** Close clients that stalled or went silent; return the rest. */
+export function sweep<S extends Sock>(socks: Iterable<S>, now: number): S[] {
+  const live: S[] = [];
+  for (const s of socks) {
+    const a = s.attachment();
+    if (!a) { s.close(1011, "no session"); continue; }
+    if (a.waitSince && now - a.waitSince > STALL_MS) { s.close(CLOSE_STALLED, "stalled"); continue; }
+    if (now - Math.max(a.lastSeen, s.lastPing() ?? 0) > DEAD_MS) { s.close(CLOSE_GONE, "silent"); continue; }
+    live.push(s);
+  }
+  return live;
+}
+
+/** A new bell, already stored as `seq`: push it to every live client. */
+export function deliver(socks: Iterable<Sock>, seq: number, bell: Bell, now: number): void {
+  const msg = bellMsg(seq, bell);
+  for (const s of sweep(socks, now)) {
+    const a = s.attachment()!;
+    if (a.replaying || seq <= a.sent) continue; // storage gets it to a replaying client
+    if (a.sent - a.acked >= MAX_PENDING) { s.close(CLOSE_OVERFLOW, "overflow"); continue; }
+    if (!trySend(s, msg)) continue;
+    if (!a.waitSince) a.waitSince = now;
+    a.sent = seq;
+    s.setAttachment(a);
+  }
+}

package/worker/src/index.ts

@@ -0,0 +1,308 @@
+// slack-term relay — a Cloudflare Worker that turns Slack's Events API into a
+// resumable doorbell stream for `slack stream`.
+//
+//   Slack ──POST /slack/events──▶ Worker ──▶ Relay (Durable Object, SQLite)
+//                                                 │  {seq, channel, ts, thread_ts}
+//   slack stream ◀──GET /ws (WebSocket, hibernating)┤
+//   older clients ◀──GET /stream (SSE, bearer)──────┘
+//
+// Clients connect over a hibernatable WebSocket (hub.ts): between bells the
+// object is evicted from memory and not billed, and keepalive pings are
+// answered by the runtime without waking it. /stream (SSE) stays for clients
+// from before the switch — every connected SSE client keeps the object awake.
+//
+// Privacy: the relay stores and serves ids and timestamps only — never message
+// text, never sender ids (beyond marking the app's own bot posts, `self`). A client that hears a bell reads the message itself
+// through the Web API with its own token, so a forged or replayed bell costs at
+// most one extra scan. Bells are deleted RETENTION_SEC after they arrive; that
+// window only exists so a reconnecting client can resume from its last seq.
+// Nothing here logs a request body.
+
+import { DurableObject } from "cloudflare:workers";
+import { type Doorbell, doorbellOf, MAX_BODY_BYTES, plausiblySigned, readLimited, safeEqual, verifySlack } from "./slack.ts";
+import * as hub from "./hub.ts";
+
+export interface Env {
+  RELAY: DurableObjectNamespace<Relay>;
+  /** Slack app → Basic Information → Signing Secret. */
+  SLACK_SIGNING_SECRET: string;
+  /** Bearer token every stream consumer presents. */
+  RELAY_TOKEN: string;
+  /** Optional: drop events from any other workspace. */
+  SLACK_TEAM_ID?: string;
+}
+
+/** How long a bell is kept for resume. Longer gaps are covered by the client's
+ *  catch-up poll, which runs on every (re)connect anyway. */
+const RETENTION_SEC = 3600;
+const KEEPALIVE_MS = 25_000;
+const MAX_CLIENTS = 16;
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const url = new URL(req.url);
+    const relay = env.RELAY.get(env.RELAY.idFromName("relay"));
+
+    if (url.pathname === "/slack/events" && req.method === "POST") {
+      const timestamp = req.headers.get("x-slack-request-timestamp");
+      const signature = req.headers.get("x-slack-signature");
+      // Reject before reading anything we would have to buffer.
+      if (!plausiblySigned(timestamp, signature, Date.now() / 1000)) return new Response("bad signature", { status: 401 });
+      if (Number(req.headers.get("content-length") ?? 0) > MAX_BODY_BYTES) return new Response("too large", { status: 413 });
+      const body = await readLimited(req.body);
+      if (body === null) return new Response("too large", { status: 413 });
+      if (!await verifySlack(env.SLACK_SIGNING_SECRET, timestamp, signature, body, Date.now() / 1000)) {
+        return new Response("bad signature", { status: 401 });
+      }
+      let payload: { type?: unknown; challenge?: unknown };
+      try {
+        payload = JSON.parse(body) as typeof payload;
+      } catch {
+        return new Response("bad json", { status: 400 });
+      }
+      if (payload.type === "url_verification" && typeof payload.challenge === "string") {
+        return new Response(payload.challenge, { headers: { "content-type": "text/plain" } });
+      }
+      const bell = doorbellOf(payload, env.SLACK_TEAM_ID || undefined);
+      // A single SQLite insert: well inside Slack's 3 s ack budget. Retries of
+      // the same event (x-slack-retry-num) collapse on (channel, ts).
+      if (bell) await relay.ring(bell);
+      return new Response(null, { status: 200 });
+    }
+
+    if (url.pathname === "/ws") {
+      // Checked here, before the object is touched or the socket accepted.
+      // The bearer rides in a subprotocol (Node's WebSocket cannot set
+      // headers); an Authorization header works too.
+      const bearer = !!env.RELAY_TOKEN && safeEqual(req.headers.get("authorization") ?? "", `Bearer ${env.RELAY_TOKEN}`);
+      if (!bearer && !hub.protocolAuthorized(req.headers.get("sec-websocket-protocol"), env.RELAY_TOKEN)) {
+        return new Response("unauthorized", { status: 401 });
+      }
+      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
+      if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") return new Response("upgrade required", { status: 426 });
+      return relay.fetch(req);
+    }
+
+    if (url.pathname === "/stream" || url.pathname === "/health") {
+      if (!env.RELAY_TOKEN || !safeEqual(req.headers.get("authorization") ?? "", `Bearer ${env.RELAY_TOKEN}`)) {
+        return new Response("unauthorized", { status: 401 });
+      }
+      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
+      return relay.fetch(req);
+    }
+
+    return new Response("not found", { status: 404 });
+  },
+} satisfies ExportedHandler<Env>;
+
+/** An SSE client (GET /stream, kept for clients from before /ws).
+ *  `pending`: writes not yet taken by the consumer. A client that stops
+ *  reading is cut off past MAX_PENDING instead of buffering without bound;
+ *  it reconnects with ?after and gets the rest from storage. */
+type Client = {
+  writer: WritableStreamDefaultWriter<Uint8Array>;
+  pending: number;
+  /** Still being fed its backlog from storage; live bells reach it that way. */
+  replaying: boolean;
+};
+const MAX_PENDING = 64;
+/** Backlog rows read and written per step of a replay. */
+const REPLAY_BATCH = hub.REPLAY_BATCH;
+/** A replay write the reader has not taken by then frees its slot. */
+const REPLAY_WRITE_MS = 30_000;
+const enc = new TextEncoder();
+
+export class Relay extends DurableObject<Env> {
+  private clients = new Set<Client>();
+  /** Names this storage. A client that saved a seq under another epoch is
+   *  reading a reset relay, whose numbers mean something else now. */
+  private readonly epoch: string;
+  private keepalive: ReturnType<typeof setInterval> | undefined;
+  /** An alarm is known to be set: ring() skips the getAlarm() storage read.
+   *  Starts false on every (re)start of the object, so it re-checks once. */
+  private alarmArmed = false;
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    // Answered by the runtime, without waking a hibernating object.
+    ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));
+    ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS bells (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      channel TEXT NOT NULL, ts TEXT NOT NULL, thread_ts TEXT,
+      at INTEGER NOT NULL,
+      UNIQUE (channel, ts)
+    )`);
+    // Added later: a relay deployed before it gets the column on its next start.
+    const cols = ctx.storage.sql.exec<{ name: string }>("PRAGMA table_info(bells)").toArray().map((c) => c.name);
+    if (!cols.includes("self")) ctx.storage.sql.exec("ALTER TABLE bells ADD COLUMN self TEXT");
+    ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL)");
+    ctx.storage.sql.exec("INSERT OR IGNORE INTO meta (k, v) VALUES ('epoch', ?)", crypto.randomUUID());
+    this.epoch = ctx.storage.sql.exec<{ v: string }>("SELECT v FROM meta WHERE k = 'epoch'").one().v;
+  }
+
+  /** Store a bell (once per channel+ts) and push it to every live client. */
+  async ring(bell: Doorbell): Promise<void> {
+    const now = Date.now();
+    const rows = this.ctx.storage.sql.exec<{ seq: number }>(
+      "INSERT OR IGNORE INTO bells (channel, ts, thread_ts, self, at) VALUES (?, ?, ?, ?, ?) RETURNING seq",
+      bell.channel, bell.ts, bell.thread_ts ?? null, bell.self ?? null, now,
+    ).toArray();
+    const seq = rows[0]?.seq;
+    if (seq === undefined) return; // a retry of a bell we already have
+    if (!this.alarmArmed) {
+      if ((await this.ctx.storage.getAlarm()) === null) await this.ctx.storage.setAlarm(now + RETENTION_SEC * 1000);
+      this.alarmArmed = true;
+    }
+    this.broadcast(frame(seq, bell));
+    hub.deliver(this.sockets(), seq, bell, now);
+  }
+
+  /** TTL sweep: drop expired bells, re-arm while any remain. */
+  override async alarm(): Promise<void> {
+    const cutoff = Date.now() - RETENTION_SEC * 1000;
+    this.ctx.storage.sql.exec("DELETE FROM bells WHERE at <= ?", cutoff);
+    const next = this.ctx.storage.sql.exec<{ at: number | null }>("SELECT MIN(at) AS at FROM bells").one().at;
+    if (next !== null) await this.ctx.storage.setAlarm(next + RETENTION_SEC * 1000);
+    this.alarmArmed = next !== null;
+    hub.sweep(this.sockets(), Date.now());
+  }
+
+  override webSocketMessage(ws: WebSocket, data: string | ArrayBuffer): void {
+    hub.message(this.sock(ws), data, this.store, Date.now());
+  }
+
+  // Socket state lives on the socket: nothing to clean up but the socket.
+  override webSocketClose(ws: WebSocket, code: number): void {
+    try { ws.close(code === 1005 || code === 1006 ? 1000 : code, "bye"); } catch { /* already closed */ }
+  }
+
+  override webSocketError(ws: WebSocket): void {
+    try { ws.close(1011, "error"); } catch { /* already closed */ }
+  }
+
+  private readonly store: hub.Store = {
+    rowsAfter: (seq, limit) => this.ctx.storage.sql.exec<hub.Row>(
+      "SELECT seq, channel, ts, thread_ts, self FROM bells WHERE seq > ? ORDER BY seq LIMIT ?", seq, limit,
+    ).toArray(),
+  };
+
+  private sock(ws: WebSocket): hub.Sock {
+    return {
+      send: (d) => ws.send(d),
+      close: (code, reason) => { try { ws.close(code, reason); } catch { /* already closed */ } },
+      attachment: () => ws.deserializeAttachment() as hub.Attachment | null,
+      setAttachment: (a) => ws.serializeAttachment(a),
+      lastPing: () => this.ctx.getWebSocketAutoResponseTimestamp(ws)?.getTime() ?? null,
+    };
+  }
+
+  private sockets(): hub.Sock[] {
+    return this.ctx.getWebSockets().filter((ws) => ws.readyState === WebSocket.OPEN).map((ws) => this.sock(ws));
+  }
+
+  override async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    const { oldest, latest } = this.bounds();
+    const now = Date.now();
+    const sockets = hub.sweep(this.sockets(), now);
+    if (url.pathname === "/health") {
+      return Response.json({
+        ok: true, epoch: this.epoch, latest, oldest, clients: this.clients.size + sockets.length,
+        websocket_clients: sockets.length, sse_clients: this.clients.size, retention_sec: RETENTION_SEC,
+      });
+    }
+
+    if (this.clients.size + sockets.length >= MAX_CLIENTS) return new Response("too many clients", { status: 503 });
+    // Resume point: ?after=<seq> or the SSE Last-Event-ID header (hub.resumePoint).
+    const { from, gap } = hub.resumePoint(
+      url.searchParams.get("after") ?? req.headers.get("last-event-id"), url.searchParams.get("epoch"), this.epoch, oldest, latest,
+    );
+    const hello = { seq: from, gap, retention_sec: RETENTION_SEC, epoch: this.epoch };
+
+    if (url.pathname === "/ws") {
+      const [client, server] = Object.values(new WebSocketPair()) as [WebSocket, WebSocket];
+      this.ctx.acceptWebSocket(server);
+      hub.open(this.sock(server), from, hello, this.store, now);
+      const offered = (req.headers.get("sec-websocket-protocol") ?? "").split(",").some((p) => p.trim() === hub.PROTOCOL);
+      return new Response(null, { status: 101, webSocket: client, headers: offered ? { "sec-websocket-protocol": hub.PROTOCOL } : {} });
+    }
+
+    const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
+    const client: Client = { writer: writable.getWriter(), pending: 0, replaying: true };
+    this.clients.add(client);
+    this.keepalive ??= setInterval(() => this.broadcast(": ka\n\n"), KEEPALIVE_MS);
+    void this.replay(client, from, `event: hello\ndata: ${JSON.stringify(hello)}\n\n`);
+
+    return new Response(readable, {
+      headers: { "content-type": "text/event-stream", "cache-control": "no-store", "x-accel-buffering": "no" },
+    });
+  }
+
+  private bounds(): { oldest: number | null; latest: number } {
+    const b = this.ctx.storage.sql.exec<{ oldest: number | null }>("SELECT MIN(seq) AS oldest FROM bells").one();
+    // sqlite_sequence remembers the high-water mark even after every row expired.
+    const hw = this.ctx.storage.sql.exec<{ seq: number }>("SELECT seq FROM sqlite_sequence WHERE name = 'bells'").toArray();
+    return { oldest: b.oldest, latest: hw[0]?.seq ?? 0 };
+  }
+
+  /** Feed a client its backlog in batches, each write awaited — a reader
+   *  that stalls stalls only its own replay, holding one batch at most. A
+   *  bell rung meanwhile is already stored, so the next batch picks it up;
+   *  the switch to live happens right after a read that came back empty,
+   *  with no await in between, so nothing falls between the two. */
+  private async replay(c: Client, from: number, hello: string): Promise<void> {
+    let chunk = hello;
+    let cursor = from;
+    for (;;) {
+      const rows = this.store.rowsAfter(cursor, REPLAY_BATCH);
+      for (const r of rows) {
+        chunk += frame(r.seq, hub.bellOf(r));
+        cursor = r.seq;
+      }
+      if (!rows.length) c.replaying = false;
+      if (chunk) {
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        try {
+          await Promise.race([
+            c.writer.write(enc.encode(chunk)),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("stalled")), REPLAY_WRITE_MS); }),
+          ]);
+        } catch {
+          return this.drop(c);
+        } finally {
+          if (timer !== undefined) clearTimeout(timer);
+        }
+      }
+      if (!c.replaying || !this.clients.has(c)) return;
+      chunk = "";
+    }
+  }
+
+  private broadcast(chunk: string): void {
+    for (const c of this.clients) if (!c.replaying) void this.send(c, chunk);
+  }
+
+  private async send(c: Client, chunk: string): Promise<void> {
+    if (c.pending >= MAX_PENDING) return this.drop(c);
+    c.pending++;
+    try {
+      await c.writer.write(enc.encode(chunk));
+      c.pending--;
+    } catch {
+      this.drop(c);
+    }
+  }
+
+  private drop(c: Client): void {
+    if (!this.clients.delete(c)) return;
+    c.writer.abort().catch(() => {});
+    if (this.clients.size === 0 && this.keepalive !== undefined) {
+      clearInterval(this.keepalive);
+      this.keepalive = undefined;
+    }
+  }
+}
+
+function frame(seq: number, bell: Doorbell): string {
+  return `id: ${seq}\nevent: bell\ndata: ${JSON.stringify(bell)}\n\n`;
+}

package/worker/src/slack.ts

@@ -0,0 +1,127 @@
+// Pure Slack-side logic for the relay Worker: request signing and turning an
+// Events API payload into a doorbell. No Cloudflare types here, so the CLI's
+// test suite can exercise it under bun.
+
+/** What the relay keeps and serves: WHERE something happened, never what was
+ *  said. A client that hears a doorbell reads the message itself, through the
+ *  Slack Web API, with its own token — so the relay holds no message content. */
+export type Doorbell = {
+  channel: string; ts: string; thread_ts?: string;
+  /** Set only on a post by the receiving app's own bot: that bot's user id.
+   *  A consumer streaming as this bot never prints its own posts, so it can
+   *  skip the Web API read the bell would cost. Nothing about any other
+   *  sender is kept. */
+  self?: string;
+};
+
+/** Slack rejects replays older than five minutes; so do we. */
+export const MAX_SKEW_SEC = 300;
+
+/** Slack event payloads are a few KB; anything far larger is not Slack. */
+export const MAX_BODY_BYTES = 1 << 20;
+
+/** Cheap pre-check before the body is read at all: both signing headers
+ *  present, signature well-formed, timestamp fresh. */
+export function plausiblySigned(timestamp: string | null, signature: string | null, nowSec: number): boolean {
+  if (!timestamp || !signature || !/^v0=[0-9a-f]{64}$/.test(signature)) return false;
+  const ts = Number(timestamp);
+  return Number.isFinite(ts) && Math.abs(nowSec - ts) <= MAX_SKEW_SEC;
+}
+
+/** Read a body as text, giving up (null) once it passes `max` bytes —
+ *  so an oversized request is never buffered whole. */
+export async function readLimited(body: ReadableStream<Uint8Array> | null, max = MAX_BODY_BYTES): Promise<string | null> {
+  if (!body) return "";
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > max) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(size);
+  let off = 0;
+  for (const c of chunks) { all.set(c, off); off += c.byteLength; }
+  return new TextDecoder().decode(all);
+}
+
+const enc = new TextEncoder();
+
+function hex(buf: ArrayBuffer): string {
+  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Constant-time string compare (both sides are ours to length-check). */
+export function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let d = 0;
+  for (let i = 0; i < a.length; i++) d |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return d === 0;
+}
+
+/** Verify X-Slack-Signature: v0=HMAC-SHA256(secret, "v0:{timestamp}:{raw body}").
+ *  https://api.slack.com/authentication/verifying-requests-from-slack */
+export async function verifySlack(
+  secret: string, timestamp: string | null, signature: string | null, body: string, nowSec: number,
+): Promise<boolean> {
+  if (!secret || !timestamp || !signature) return false;
+  const ts = Number(timestamp);
+  if (!Number.isFinite(ts) || Math.abs(nowSec - ts) > MAX_SKEW_SEC) return false;
+  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, enc.encode(`v0:${timestamp}:${body}`));
+  return safeEqual(`v0=${hex(mac)}`, signature);
+}
+
+// Housekeeping that is never a person talking. message_changed is dropped too:
+// `slack stream` does not re-emit edits, so ringing for one would only cost a scan.
+const SKIP_SUBTYPES = new Set([
+  "message_changed", "message_deleted", "channel_join", "channel_leave", "group_join", "group_leave",
+  "channel_topic", "channel_purpose", "channel_name", "pinned_item", "unpinned_item",
+  // A hidden update to a thread parent: its outer ts names the update, not a
+  // message — the reply itself arrives as its own event.
+  "message_replied",
+]);
+
+const TS = /^\d{6,}\.\d{1,9}$/;
+const CHANNEL = /^[CDG][A-Z0-9]{2,}$/;
+const USER = /^[UW][A-Z0-9]{2,}$/;
+
+/** The receiving app's bot user id when this event is that bot's own post:
+ *  the sender is the authorized bot user, or the post carries this app's id. */
+function selfPost(p: { api_app_id?: unknown; authorizations?: unknown }, e: Record<string, unknown>): string | undefined {
+  const auth = Array.isArray(p.authorizations) ? p.authorizations[0] as Record<string, unknown> | undefined : undefined;
+  const botUser = auth && auth.is_bot === true && typeof auth.user_id === "string" && USER.test(auth.user_id) ? auth.user_id : undefined;
+  if (!botUser) return undefined;
+  if (e.user === botUser) return botUser;
+  const appId = typeof e.app_id === "string" ? e.app_id
+    : e.bot_profile && typeof e.bot_profile === "object" ? (e.bot_profile as Record<string, unknown>).app_id : undefined;
+  return typeof p.api_app_id === "string" && appId === p.api_app_id && e.user === undefined ? botUser : undefined;
+}
+
+/** The doorbell for one event_callback, or null when there is nothing to ring
+ *  for. Only ids and timestamps survive this function. */
+export function doorbellOf(payload: unknown, teamId?: string): Doorbell | null {
+  if (!payload || typeof payload !== "object") return null;
+  const p = payload as { type?: unknown; team_id?: unknown; api_app_id?: unknown; authorizations?: unknown; event?: Record<string, unknown> };
+  if (p.type !== "event_callback" || !p.event || typeof p.event !== "object") return null;
+  if (teamId && p.team_id !== teamId) return null;
+  const e = p.event;
+  if (e.type !== "message" && e.type !== "app_mention") return null;
+  if (typeof e.subtype === "string" && SKIP_SUBTYPES.has(e.subtype)) return null;
+  if (e.hidden === true) return null;
+  const { channel, ts, thread_ts } = e;
+  if (typeof channel !== "string" || !CHANNEL.test(channel)) return null;
+  if (typeof ts !== "string" || !TS.test(ts)) return null;
+  const self = selfPost(p, e);
+  return {
+    channel, ts,
+    ...(typeof thread_ts === "string" && TS.test(thread_ts) && thread_ts !== ts ? { thread_ts } : {}),
+    ...(self ? { self } : {}),
+  };
+}