slack-term 1.47.0 → 1.49.0

package/worker/README.md

@@ -0,0 +1,216 @@
+# slack-term relay
+
+A Cloudflare Worker that turns Slack's **Events API** into a resumable stream of
+*doorbells* for `slack stream`. Slack posts each event to the Worker; the Worker
+keeps only `{channel, ts, thread_ts}` and pushes it over a WebSocket (or, for
+older clients, Server-Sent Events) to authenticated clients. Each client then
+reads the message itself, with its own token.
+
+```
+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)──────┘
+```
+
+## Cost: why WebSocket
+
+A Durable Object is billed for **duration** while it is in memory, and an open
+SSE response keeps it there for as long as a client is connected — all day,
+for a stream that is idle most of the time. `/ws` instead uses the Durable
+Object [WebSocket Hibernation API](https://developers.cloudflare.com/durable-objects/best-practices/websockets/):
+
+- sockets are accepted with `ctx.acceptWebSocket()`, so between bells the object
+  is evicted and not billed, while the connections stay open;
+- the client's keepalive (`"ping"` every 25 s) is answered `"pong"` by the
+  runtime (`setWebSocketAutoResponse`) **without waking the object**;
+- all per-client state (resume position, acked position, replay/live, stall
+  clock) lives in the socket's attachment (`serializeAttachment`), so it
+  survives hibernation, and nothing waits on a timer.
+
+The object wakes only for a Slack event, a client connecting, a client's ack
+(sent within ~100 ms of the bells it acknowledges, while the object is still
+awake from the event), or the hourly TTL alarm.
+
+**SSE is kept for one release** so `slack stream` clients from before `/ws`
+keep working against a redeployed relay. Each connected SSE client keeps the
+object awake as before; `/health` shows `sse_clients` so you can see when none
+are left, after which `/stream` can be removed. New clients try `/ws` first and
+fall back to `/stream` for a connection only if the socket cannot be opened at
+all (an older relay, a proxy that strips upgrades, a runtime without
+`WebSocket`); `SLACK_RELAY_TRANSPORT=websocket|sse` pins one.
+
+## Endpoints
+
+| Path | Auth | What |
+|---|---|---|
+| `POST /slack/events` | Slack signing secret (`X-Slack-Signature`, ±5 min) | Answers `url_verification`; stores one bell per `message` / `app_mention` event. Acks with a single SQLite insert, well inside Slack's 3 s. Retries collapse on `(channel, ts)`. |
+| `GET /ws?after=<seq>&epoch=<e>` | Subprotocols `slack-term-relay.v1` **and** `bearer.<base64url($RELAY_TOKEN)>` (or `Authorization: Bearer`) | WebSocket (below). Rejected with 401 before the upgrade is accepted. |
+| `GET /stream?after=<seq>` | `Authorization: Bearer $RELAY_TOKEN` | SSE (kept for older clients). First an `event: hello` frame `{seq, gap, retention_sec}`, then the backlog after `seq`, then live `event: bell` frames (`id:` = seq). A keepalive comment goes out every 25 s. `Last-Event-ID` works as well as `?after`. Pass `&epoch=` from the last hello: the epoch names the relay's storage, so a client resuming against a reset relay is told `gap: true` and gets everything kept, even once the new numbers have passed its old seq. If `after` is omitted, the stream starts from now. `gap: true` means some bells after `after` are gone (expired, or the relay was reset): everything still kept is replayed, and the client should also catch up by polling. |
+| `GET /health` | Bearer | `{epoch, latest, oldest, clients, websocket_clients, sse_clients, retention_sec}` |
+
+At most 16 clients (both kinds) at once; more get 503.
+
+### The WebSocket protocol (`/ws`)
+
+**Auth.** The token is never put in the URL (query strings end up in logs).
+Node's built-in `WebSocket` cannot send an `Authorization` header, so the client
+offers two subprotocols — `Sec-WebSocket-Protocol: slack-term-relay.v1,
+bearer.<base64url(token)>` (base64url because subprotocols must be HTTP tokens;
+the same scheme Kubernetes uses) — and the Worker compares the bearer one in
+constant time before the request reaches the Durable Object. The server
+selects only `slack-term-relay.v1`, never echoing the token.
+
+**Messages** are JSON text, one per frame:
+
+- server → client: `{"type":"hello","seq","gap","retention_sec","epoch"}` first
+  (same resume rules as SSE: `after`, `epoch`, `gap`); then
+  `{"type":"bell","seq":n,"bell":{channel,ts,thread_ts?,self?}}` — the backlog
+  after `seq`, then live bells; and `"pong"` (from the runtime).
+- client → server: `"ping"` every 25 s; `{"type":"ack","seq":n}` for the highest
+  bell received — at once after 32 unacked bells, else within 100 ms.
+
+**Flow control** replaces SSE's write backpressure, which a WebSocket send
+does not give: the backlog is replayed 100 bells at a time, each batch only
+after the previous one is acked, and the switch to live happens right after a
+storage read comes back empty (synchronously, so no bell falls in between). A
+client is closed — and resumes from storage with `?after` — when it has 64 live
+bells unacked (`4008 overflow`), makes no ack progress for 30 s while owing one
+(`4009 stalled`), or neither pings nor acks for 90 s (`4010 silent`). These
+checks run whenever the object is awake (an event, a connect, the alarm), since
+a hibernating object runs no timers.
+
+## Privacy
+
+- **No message content is stored or served:** no text, no sender, no attachments.
+  A bell holds a channel id and two timestamps — plus, on posts by **this app's own
+  bot** only, `self`: that bot's user id. A client streaming as the bot never prints
+  its own posts, so it skips the Web API read such a bell would cost (and, for
+  `--replies-to`, learns from it that the bot is in the thread). No other sender
+  is ever recorded.
+- **Bells are deleted 1 hour after arrival** (`RETENTION_SEC`, enforced by a
+  Durable Object alarm). That window exists only so a client can resume.
+  Anything older is covered by the client's catch-up poll, except replies
+  under a thread parent older than the client's `--thread-window`: the poll
+  cannot find those, so a bell that expired before the client read it is lost.
+- **Nothing logs a request body**, and Workers Logs are off (`observability`).
+- **Token holders see activity metadata.** Anyone with `RELAY_TOKEN` can watch
+  *when* and *where* messages are posted — channel ids, timestamps and thread
+  structure, for every conversation the bot is in, **including DMs** with it —
+  even though they never see text or senders. Treat the token like read access
+  to that timing data: give it only to consumers you trust, and rotate it
+  (`wrangler secret put RELAY_TOKEN`) when one should lose access.
+- **A forged bell costs a few Web API reads at most:** one
+  `conversations.replies` call, a few pages if needed, and up to 8 retries
+  if the message is not found. The client applies its own filter to what
+  Slack returns, so a forged bell never prints anything.
+
+## Deploy
+
+### Without cloning (recommended)
+
+The relay ships in the npm package as `slack-term/worker`. Scaffold a Worker
+folder with the CLI:
+
+```sh
+slack relay init my-relay        # or: npx slack-term relay init my-relay
+cd my-relay && npm install
+npx wrangler login               # or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID (below)
+npx wrangler deploy
+```
+
+`init` writes `package.json` (slack-term as `^` the CLI's version, wrangler
+pinned), `wrangler.jsonc` (the same config as this folder's, with `--name` or
+the folder's name), `src/index.ts`, `.gitignore` and a `README.md`. It makes no
+network calls and refuses to overwrite existing files unless `--force`. It
+prints a freshly generated `RELAY_TOKEN` — not saved anywhere — and the
+remaining steps: the secrets, the Slack app settings and the client env, all
+as described below (run them from the new folder, with `npx wrangler`).
+
+Already have a Worker project? `src/index.ts` is just
+
+```ts
+export { default, Relay } from "slack-term/worker";
+```
+
+with a `RELAY` Durable Object binding to class `Relay` and a
+`new_sqlite_classes: ["Relay"]` migration — copy them from
+[`wrangler.jsonc`](wrangler.jsonc). `Env` is exported too, for typing.
+`@cloudflare/workers-types` is an optional peer dependency of slack-term.
+
+To update, bump `slack-term` in the folder's package.json and redeploy.
+
+### From a clone of this repo (contributors)
+
+Wrangler 4 needs **Node ≥ 22**.
+
+Cloudflare credentials, in the environment:
+
+- `CLOUDFLARE_API_TOKEN` — a token with the **Workers Scripts: Edit** permission
+  (the "Edit Cloudflare Workers" template).
+- `CLOUDFLARE_ACCOUNT_ID` — from the dashboard sidebar.
+
+```sh
+cd worker
+npx --yes wrangler@4.105.0 deploy
+npx --yes wrangler@4.105.0 secret put SLACK_SIGNING_SECRET   # Slack app → Basic Information → Signing Secret
+npx --yes wrangler@4.105.0 secret put RELAY_TOKEN            # long random string, shared with consumers (e.g. openssl rand -hex 32)
+npx --yes wrangler@4.105.0 secret put SLACK_TEAM_ID          # optional: accept one workspace only (T…)
+```
+
+Redeploying an existing relay keeps its storage (and epoch): no migration is
+needed, the Durable Object class is unchanged. A deploy restarts the object,
+which drops every connection; clients reconnect and resume from their last seq.
+
+### Then, either way
+
+Check it (expects `{"ok":true,…}`):
+
+```sh
+curl -H "Authorization: Bearer $RELAY_TOKEN" https://<worker>/health
+# or, with SLACK_RELAY_URL / SLACK_RELAY_TOKEN set:
+slack relay health
+```
+
+Then, in the Slack app:
+
+1. Go to **Event Subscriptions** and turn on **Enable Events**.
+2. Set the **Request URL** to `https://<worker>/slack/events`. It should verify at once.
+3. Under **Subscribe to bot events**, add:
+   - `message.channels`
+   - `message.groups`
+   - `message.im`
+   - `app_mention`
+   - `message.mpim`, only if the bot has `mpim:history`.
+   Each needs its bot scope (`channels:history`, `groups:history`, `im:history`,
+   `app_mentions:read`); Slack offers to add them.
+4. Click **Save**, then reinstall the app if Slack asks.
+
+The secrets must be in place first: Slack's URL verification is signed.
+
+Consumers set `SLACK_RELAY_URL=https://<worker>` and `SLACK_RELAY_TOKEN=…`
+(the same value as the `RELAY_TOKEN` secret). `slack stream` then uses the relay
+automatically and says so on stderr: `relay connected (websocket)` — or
+`(sse)` if it fell back. Optional: `SLACK_RELAY_TRANSPORT=websocket` or `sse`.
+
+## Develop
+
+```sh
+cd worker && bun install && bun run typecheck
+# or, from the repo root (what CI runs):
+bun run typecheck:worker
+```
+
+The signature and event parsing live in `src/slack.ts`, and the WebSocket
+session logic (replay, acks, flow control, auth) in `src/hub.ts`; neither has
+Cloudflare types, and the CLI suite tests both (`tests/relay.test.ts`,
+`tests/relay-hub.test.ts`, `tests/relay-ws.test.ts`).
+
+To run the Worker locally (Node ≥ 22; on an older Node,
+`npx -y -p node@22 -- …` works):
+
+```sh
+cd worker
+printf 'SLACK_SIGNING_SECRET=dev\nRELAY_TOKEN=dev\n' > .dev.vars   # git-ignored
+npx --yes wrangler@4.105.0 dev --local
+```

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);
+  }
+}