@moda-labs/bobi-events-core 0.1.0

package/dist/core.js

@@ -0,0 +1,1775 @@
+/**
+ * Resolve the per-bot record for an inbound event's api_app_id, with
+ * read-migration so pre-multi-bot single-bot records still resolve.
+ */
+export function getSlackBotForApp(ws, apiAppId) {
+    if (!ws)
+        return null;
+    if (apiAppId && ws.bots && ws.bots[apiAppId])
+        return ws.bots[apiAppId];
+    // Single registered bot: use it even if api_app_id is absent/unmatched
+    // (defensive — a client may not have sourced api_app_id).
+    if (ws.bots) {
+        const vals = Object.values(ws.bots);
+        if (vals.length === 1)
+            return vals[0];
+    }
+    // Legacy single-bot fields.
+    if (ws.bot_token || ws.bot_id) {
+        return { bot_token: ws.bot_token ?? "", bot_id: ws.bot_id };
+    }
+    return null;
+}
+/**
+ * Every bot id we own in this workspace, across ALL registered apps (+ legacy).
+ * The self-reply filter skips a message authored by ANY of these — not just the
+ * RECEIVING app's bot. When two of our apps share a channel, Slack delivers each
+ * app's events to BOTH apps' webhooks, so one bot's message arrives via the
+ * other bot's webhook (a different api_app_id); keying "self" to the receiving
+ * app alone let that message through and it looped.
+ */
+export function workspaceBotIds(ws) {
+    const ids = new Set();
+    if (!ws)
+        return ids;
+    if (ws.bots)
+        for (const b of Object.values(ws.bots))
+            if (b.bot_id)
+                ids.add(b.bot_id);
+    if (ws.bot_id)
+        ids.add(ws.bot_id);
+    return ids;
+}
+/**
+ * Slack user ids for bot users belonging to the receiving app. Slack emits a
+ * channel mention as both app_mention and message.*, and only the app_mention
+ * should reach chat delivery; otherwise the drain posts two placeholders for
+ * one ts. Self-authorship filtering is workspace-wide; mention dedupe must stay
+ * app-scoped so one bot does not swallow thread replies mentioning another.
+ */
+export function workspaceBotUserIds(ws, apiAppId) {
+    const ids = new Set();
+    if (!ws?.bots)
+        return ids;
+    if (apiAppId && ws.bots[apiAppId]?.bot_user_id) {
+        ids.add(ws.bots[apiAppId].bot_user_id);
+        return ids;
+    }
+    const bots = Object.values(ws.bots);
+    if (bots.length === 1 && bots[0].bot_user_id) {
+        ids.add(bots[0].bot_user_id);
+    }
+    return ids;
+}
+/**
+ * The signing secret to verify an inbound Slack webhook with: the authoring
+ * app's per-app secret if registered, else the global fallback (legacy
+ * single-app deployments). Keeps single-app working without a redeploy.
+ */
+export function resolveSlackSigningSecret(ws, payload, fallback) {
+    const apiAppId = payload.api_app_id || "";
+    const rec = getSlackBotForApp(ws, apiAppId);
+    return rec?.signing_secret || fallback || "";
+}
+/** Storage-aware convenience: load the workspace then resolve the signing secret. */
+export async function slackSigningSecretFor(storage, payload, fallback) {
+    const teamId = payload.team_id || "";
+    const ws = teamId ? await storage.getSlackWorkspace(teamId) : null;
+    return resolveSlackSigningSecret(ws, payload, fallback);
+}
+// The bare topic plus its source-qualified spelling (e.g. "monitor/support.email")
+// so subscriptions written either way match (#235). The single helper both
+// createTopicEvent and createIngestEvent route through, so the two spellings
+// can never drift between the signed-publish and token-ingest paths.
+export function sourceQualifiedTopics(topic, source) {
+    const topics = [topic];
+    if (source && !topic.startsWith(`${source}/`)) {
+        topics.push(`${source}/${topic}`);
+    }
+    return topics;
+}
+export function createTopicEvent(topic, body, bubbleId) {
+    const payload = body.payload || body;
+    // Build topics from any routing fields in the body
+    const topics = [];
+    if (body.repo)
+        topics.push(`github:${body.repo}`);
+    if (body.team_key)
+        topics.push(`linear:${body.team_key}`);
+    if (body.workspace)
+        topics.push(`slack:${body.workspace}`);
+    // Fallback: the topic path itself acts as the subscription key, plus the
+    // source-qualified form (e.g. "monitor/support.email") so subscriptions
+    // written as the full event string match too. Publishers strip the source
+    // to the body when POSTing (see the Python event publisher) — without
+    // this, "source/type" subscriptions silently never match (#235).
+    if (topics.length === 0) {
+        topics.push(...sourceQualifiedTopics(topic, body.source));
+    }
+    const text = body.text || "";
+    return {
+        v: 2,
+        id: body.id || crypto.randomUUID(),
+        source: body.source || "custom",
+        type: topic,
+        timestamp: new Date().toISOString(),
+        topics,
+        delivery: body.delivery || "bulk",
+        text,
+        // Reply address survives publish/forward: an agent re-publishing a chat
+        // event must not strip the field the receiver needs for `bobi reply`.
+        ...(typeof body.conversation === "string" && body.conversation
+            ? { conversation: body.conversation }
+            : {}),
+        fields: body.fields,
+        run_key: body.run_key,
+        payload,
+        bubble_id: bubbleId,
+    };
+}
+// ---------------------------------------------------------------------------
+// Adapters — canonical implementations live in adapters/*.ts.
+// Re-exported here so existing imports from core continue to work.
+// ---------------------------------------------------------------------------
+import { normalizeGitHubWebhook } from "./adapters/github.js";
+import { normalizeLinearWebhook } from "./adapters/linear.js";
+import { bridgeSlackWebhook } from "./adapters/chat-sdk-slack.js";
+import { normalizeWhatsAppWebhook } from "./adapters/whatsapp.js";
+import { chunkForChannel, getChannelAdapter, slackApiUrl, truncateForChannel, whatsappApi } from "./channels.js";
+import { parseConversation } from "./conversation.js";
+export { normalizeGitHubWebhook as normalizeGitHubPayload } from "./adapters/github.js";
+export { normalizeLinearWebhook as normalizeLinearPayload } from "./adapters/linear.js";
+// ---------------------------------------------------------------------------
+// Routing — topics-based (v2)
+// ---------------------------------------------------------------------------
+// Webhook resource topics that stay GLOBAL (cross-bubble) in v1. Inbound
+// webhooks fan out to every subscribing bubble regardless of bubble — an
+// accepted cross-tenant read hole, to be closed by #239 (inbound subscription
+// auth). Slack inbound rides this path, so it keeps working. Everything else
+// (inbox/*, reply/*, monitor/*, agent/*, custom topics) is bubble-scoped.
+const GLOBAL_TOPIC_PREFIXES = ["github:", "linear:", "slack:", "whatsapp:"];
+export function isGlobalTopic(key) {
+    return GLOBAL_TOPIC_PREFIXES.some((p) => key.startsWith(p));
+}
+// Normalize a resource string so the grant key and the topic never diverge on
+// case/alias (#488 §3.3). github `owner/repo` is lowercased and a trailing
+// `.git` stripped (matching the git-remote slug the adapter produces); linear
+// team keys and slack team ids are left verbatim (case-significant upstream).
+// Applied IDENTICALLY at authorize time and at topic parsing.
+export function normalizeResource(service, resource) {
+    let r = resource.trim();
+    if (service === "github") {
+        r = r.toLowerCase();
+        if (r.endsWith(".git"))
+            r = r.slice(0, -4);
+    }
+    return r;
+}
+// Parse a GLOBAL topic key into its {service, resource} for a grant lookup —
+// the inverse of how topics are built, and the single helper both enforcement
+// layers (registration + delivery) use so they can never disagree. Split on the
+// FIRST `:` (github `owner/repo` and linear keys never contain a `:`). Slack
+// topics may be `slack:{team}` OR `slack:{team}:{channel}`; the grant is keyed
+// on the TEAM id, so the channel segment is dropped here. Returns null for a
+// non-global or malformed key.
+export function parseGlobalTopic(key) {
+    if (!isGlobalTopic(key))
+        return null;
+    const idx = key.indexOf(":");
+    if (idx <= 0)
+        return null;
+    const service = key.slice(0, idx);
+    let resource = key.slice(idx + 1);
+    if (!resource)
+        return null;
+    // Slack channel-scoped topic — the grant gates the whole team, so reduce
+    // `team:channel` to `team` before normalizing.
+    if (service === "slack") {
+        const c = resource.indexOf(":");
+        if (c >= 0)
+            resource = resource.slice(0, c);
+    }
+    resource = normalizeResource(service, resource);
+    if (!resource)
+        return null;
+    return { service, resource };
+}
+// The single source of truth for bubble namespacing — used identically when
+// REGISTERING a subscription and when computing an event's delivery keys, so a
+// publish and a subscription can only ever match within the same bubble.
+// Global webhook topics are never namespaced. A non-global key with no bubble
+// context (e.g. an unauthenticated publish) is returned bare — it then matches
+// no bubble-namespaced subscription, so it silently reaches nobody.
+export function namespaceSubKey(bubbleId, key) {
+    if (isGlobalTopic(key))
+        return key;
+    if (!bubbleId)
+        return key;
+    return `${bubbleId}:${key}`;
+}
+export function subscriptionKeysForEvent(event) {
+    const topics = event.topics?.length ? event.topics : [event.type];
+    return topics.map((t) => namespaceSubKey(event.bubble_id, t));
+}
+// ---------------------------------------------------------------------------
+// Signature verification
+// ---------------------------------------------------------------------------
+function bytesToHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+async function hmacSha256Hex(secret, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    // Cast: BufferSource wants an ArrayBuffer-backed view; the buffer is
+    // never a SharedArrayBuffer here, but Uint8Array's default type argument
+    // (ArrayBufferLike) can't prove that across lib variants.
+    return bytesToHex(await crypto.subtle.sign("HMAC", key, bytes));
+}
+// SHA-256 hex digest — the one-way transform between a plaintext ingest token
+// (on the wire) and the stored token_hash. Lookup by digest also gives a
+// constant-time-safe comparison for free: the attacker-controlled token is
+// hashed before any store access, so no stored byte is ever compared
+// positionally against attacker input.
+export async function sha256Hex(data) {
+    return bytesToHex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(data)));
+}
+// Constant-time string compare. Portable across Node and the Cloudflare
+// Worker runtime — `crypto.subtle.timingSafeEqual` does NOT exist (Node's
+// is `node:crypto.timingSafeEqual`, Workers expose neither uniformly), so we
+// do a length-check then XOR-accumulate over char codes. A length mismatch
+// returns fast, which is fine: the compared values here are fixed-length hex
+// digests, so length never leaks the secret — only that the attacker sent the
+// wrong size. Never feed attacker-variable-length input expecting secrecy of
+// length; always compare equal-length digests.
+export function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+// Allowed signature algorithms (the `x-moda-algo` header). The field is
+// reserved so Ed25519 can slot in later (epic auth-v1); for now the server
+// rejects anything else rather than trusting the client's choice.
+const ALLOWED_BUBBLE_ALGOS = new Set(["hmac-sha256"]);
+// Canonical string signed by every authenticated bubble request. The nonce
+// field is included NOW so the wire format is forward-compatible with
+// server-side replay dedup (deferred to a hardening follow-up — #240 does not
+// yet maintain the seen-set). `path` is the exact bytes on the wire
+// (pathname + search); `body` is the exact transmitted bytes (the client
+// signs what it sends, never a re-serialization). timestamp is epoch SECONDS.
+export function bubbleCanonicalString(timestamp, nonce, method, path, body) {
+    return `${timestamp}\n${nonce}\n${method.toUpperCase()}\n${path}\n${body}`;
+}
+export async function buildBubbleSignature(secret, timestamp, nonce, method, path, body) {
+    return hmacSha256Hex(secret, bubbleCanonicalString(timestamp, nonce, method, path, body));
+}
+// Verify a bubble-signed request. Mirrors the CONSTRUCTION of
+// verifySlackSignature (timestamp window + HMAC-SHA256) but uses a
+// constant-time comparison. Rejects unknown algorithms and stale timestamps
+// (±300s replay window). Returns false on any failure — callers respond with
+// an opaque 403 and should perform a dummy HMAC on bubble-miss so that
+// miss and signature-mismatch are timing-indistinguishable (no bubble_id
+// enumeration).
+export async function verifyBubbleSignature(input) {
+    const { secret, algo, timestamp, nonce, method, path, body, signature } = input;
+    if (!timestamp || !nonce || !signature)
+        return false;
+    if (!ALLOWED_BUBBLE_ALGOS.has(algo))
+        return false;
+    const ts = parseInt(timestamp, 10);
+    if (!Number.isFinite(ts))
+        return false;
+    const age = Math.abs(Date.now() / 1000 - ts);
+    if (age > 300)
+        return false;
+    const expected = await buildBubbleSignature(secret, timestamp, nonce, method, path, body);
+    return constantTimeEqual(expected, signature);
+}
+export async function verifySlackSignature(secret, timestamp, body, signature) {
+    if (!timestamp || !signature)
+        return false;
+    const age = Math.abs(Date.now() / 1000 - parseInt(timestamp, 10));
+    if (age > 300)
+        return false;
+    const hexSig = "v0=" + (await hmacSha256Hex(secret, `v0:${timestamp}:${body}`));
+    return constantTimeEqual(hexSig, signature);
+}
+export async function verifyGitHubSignature(secret, body, signatureHeader) {
+    if (!signatureHeader)
+        return false;
+    const expected = "sha256=" + (await hmacSha256Hex(secret, body));
+    return constantTimeEqual(expected, signatureHeader);
+}
+// Linear replay window for the signed webhookTimestamp (ms since epoch),
+// matching the ±300s the slack and bubble verifiers use.
+const LINEAR_REPLAY_WINDOW_MS = 300_000;
+// Linear signs the raw body with HMAC-SHA256 (hex) in the `linear-signature`
+// header. `webhookTimestamp` is the payload's signed timestamp field; like
+// verifySlackSignature, the freshness window lives INSIDE the verifier so a
+// direct caller cannot get signature validation without replay protection.
+// FAIL CLOSED on a missing or non-numeric timestamp: the signature covers the
+// body, so its absence in a signed payload still leaves the request replayable
+// forever if admitted.
+export async function verifyLinearSignature(secret, body, signatureHeader, webhookTimestamp) {
+    if (!signatureHeader)
+        return false;
+    if (typeof webhookTimestamp !== "number" ||
+        Math.abs(Date.now() - webhookTimestamp) > LINEAR_REPLAY_WINDOW_MS) {
+        return false;
+    }
+    const expected = await hmacSha256Hex(secret, body);
+    return constantTimeEqual(expected, signatureHeader);
+}
+export function readBubbleAuthHeaders(get, method, path, rawBody) {
+    return {
+        bubbleId: get("x-moda-bubble") || "",
+        algo: get("x-moda-algo") || "",
+        timestamp: get("x-moda-timestamp") || "",
+        nonce: get("x-moda-nonce") || "",
+        signature: get("x-moda-signature") || "",
+        method,
+        path,
+        rawBody,
+    };
+}
+export function hasBubbleSignature(ctx) {
+    return !!(ctx.bubbleId && ctx.signature && ctx.timestamp && ctx.nonce);
+}
+// True when SOME but not all signing headers are present — a malformed request
+// (e.g. a proxy stripped a header). Registration must reject these rather than
+// silently falling back to MINT, which would fork the session into a new
+// bubble. A genuine mint carries NO signing headers.
+export function hasPartialBubbleSignature(ctx) {
+    const any = !!(ctx.bubbleId || ctx.signature || ctx.timestamp || ctx.nonce || ctx.algo);
+    return any && !hasBubbleSignature(ctx);
+}
+// A fixed dummy key used to run a constant-cost HMAC when the claimed bubble
+// does not exist, so a bubble-miss and a signature-mismatch take the same time
+// — an attacker cannot enumerate valid bubble_ids by timing.
+const DUMMY_BUBBLE_KEY = "bkey_0000000000000000000000000000000000000000000000000000000000000000";
+const _rejectionCounters = {
+    bad_signature: 0,
+    stale_timestamp: 0,
+    unknown_bubble: 0,
+    webhook_unverified: 0,
+    webhook_bad_signature: 0,
+};
+export function getAuthRejectionCounters() {
+    return { ..._rejectionCounters };
+}
+export function resetAuthRejectionCounters() {
+    _rejectionCounters.bad_signature = 0;
+    _rejectionCounters.stale_timestamp = 0;
+    _rejectionCounters.unknown_bubble = 0;
+    _rejectionCounters.webhook_unverified = 0;
+    _rejectionCounters.webhook_bad_signature = 0;
+}
+// Resolve and verify the bubble that signed a request. Returns the bubble on a
+// valid signature, else null (callers respond with an opaque 403). Always
+// performs an HMAC even on bubble-miss to keep timing uniform. Increments
+// rejection counters on failure so /health can surface misconfigured clients.
+export async function authenticateBubble(storage, ctx) {
+    const bubble = ctx.bubbleId ? await storage.getBubble(ctx.bubbleId) : null;
+    const secret = bubble?.key ?? DUMMY_BUBBLE_KEY;
+    // Check for stale timestamp before HMAC — the verifier rejects it anyway,
+    // but we want to classify the rejection reason for observability.
+    const ts = parseInt(ctx.timestamp, 10);
+    const isStale = Number.isFinite(ts) && Math.abs(Date.now() / 1000 - ts) > 300;
+    const ok = await verifyBubbleSignature({
+        secret,
+        algo: ctx.algo,
+        timestamp: ctx.timestamp,
+        nonce: ctx.nonce,
+        method: ctx.method,
+        path: ctx.path,
+        body: ctx.rawBody,
+        signature: ctx.signature,
+    });
+    if (!ok || !bubble) {
+        // Classify the rejection for the counter.
+        if (isStale) {
+            _rejectionCounters.stale_timestamp++;
+        }
+        else if (!bubble && ctx.bubbleId) {
+            _rejectionCounters.unknown_bubble++;
+        }
+        else {
+            _rejectionCounters.bad_signature++;
+        }
+        return null;
+    }
+    return bubble;
+}
+function randomToken(prefix) {
+    return `${prefix}_${crypto.randomUUID().replace(/-/g, "")}${crypto.randomUUID().replace(/-/g, "")}`;
+}
+// ---------------------------------------------------------------------------
+// Transport-agnostic handlers
+// ---------------------------------------------------------------------------
+export async function authenticateDeployment(storage, apiKey, deploymentId) {
+    const deployment = await storage.getDeploymentByApiKey(apiKey);
+    if (!deployment || deployment.id !== deploymentId)
+        return null;
+    return deployment;
+}
+export async function handleGitHubWebhook(storage, eventHeader, deliveryId, payload) {
+    const event = normalizeGitHubWebhook(eventHeader, deliveryId, payload);
+    if (!event)
+        return { status: 400, body: { error: "no repository in payload" } };
+    const delivered = await storage.deliver(event);
+    return { status: 200, body: { delivered_to: delivered } };
+}
+export async function handleLinearWebhook(storage, payload, deliveryId = "", waitUntil) {
+    const deliveryKey = deliveryId ? await sha256Hex(deliveryId) : "";
+    if (deliveryId) {
+        const existing = await storage.getWebhookDelivery("linear", deliveryKey);
+        if (existing)
+            return { status: 200, body: { ok: true } };
+    }
+    const event = normalizeLinearWebhook(payload, deliveryId);
+    const delivery = storage.deliver(event).then(async (delivered) => {
+        if (deliveryId) {
+            await storage.putWebhookDelivery({
+                source: "linear",
+                delivery_id: deliveryId,
+                delivery_key: deliveryKey,
+                received_at: new Date().toISOString(),
+            });
+        }
+        return delivered;
+    });
+    if (waitUntil) {
+        waitUntil(delivery.then(() => undefined).catch((err) => {
+            console.error("linear webhook delivery failed", err);
+        }));
+        return { status: 200, body: { queued: true } };
+    }
+    const delivered = await delivery;
+    return { status: 200, body: { delivered_to: delivered } };
+}
+// `body` is the raw webhook JSON string; `payload` its parsed form (the
+// pipeline parses once before verification and passes both). Normalization
+// runs through the Chat SDK bridge (#628) — the hand-rolled
+// normalizeSlackWebhook remains only as the golden parity reference until
+// the bridge has soaked (#629).
+export async function handleSlackWebhook(storage, body, payload) {
+    const teamId = payload.team_id || "";
+    const apiAppId = payload.api_app_id || "";
+    let selfBotIds;
+    let selfBotUserIds;
+    if (teamId) {
+        const ws = await storage.getSlackWorkspace(teamId);
+        // Skip messages authored by ANY of our bots in this workspace — not just
+        // the bot of the app that received this webhook. Two of our apps in one
+        // channel each receive the other's messages (with their own api_app_id),
+        // so a per-receiving-app "self" id let one bot's message loop in via the
+        // other's webhook.
+        selfBotIds = workspaceBotIds(ws);
+        selfBotUserIds = workspaceBotUserIds(ws, apiAppId);
+    }
+    const result = bridgeSlackWebhook(body, selfBotIds, selfBotUserIds, payload);
+    if (result.challenge !== undefined) {
+        return { status: 200, body: { challenge: result.challenge } };
+    }
+    if (result.skip || !result.event) {
+        return { status: 200, body: { ok: true } };
+    }
+    const delivered = await storage.deliver(result.event);
+    return { status: 200, body: { delivered_to: delivered } };
+}
+const INVALID_SIGNATURE = { status: 401, body: { error: "invalid signature" } };
+const INVALID_JSON = { status: 400, body: { error: "invalid JSON" } };
+// Ingest rejections are an opaque 403 (per #640 acceptance): missing, unknown,
+// revoked, and wrong-topic tokens are indistinguishable to the caller.
+const INGEST_FORBIDDEN = { status: 403, body: { error: "forbidden" } };
+// Ingest request-size cap. Generic publishes have no explicit byte cap today
+// (they are bubble-signed, so the publisher is trusted); ingest is the first
+// surface where the sender holds only a topic-scoped credential, so it gets
+// an explicit one. Sized for alerting/CI/SaaS webhook payloads with headroom.
+export const INGEST_MAX_BODY_BYTES = 256 * 1024;
+// Per-token fixed-window rate limit. In-memory: authoritative on the local
+// server (single process); per-isolate on the Worker, where it still bounds
+// abuse per point of presence — a shared Durable Object limiter is deliberate
+// non-scope for #640.
+export const INGEST_RATE_LIMIT = 60;
+export const INGEST_RATE_WINDOW_MS = 60_000;
+const _ingestRateWindows = new Map();
+// Entries for tokens that stop sending (revoked, retired CI tokens) would
+// otherwise accrete forever in this long-lived process; sweep expired windows
+// once the map is large. O(n) only when the sweep fires.
+const INGEST_RATE_SWEEP_THRESHOLD = 1024;
+function ingestRateAllow(tokenId) {
+    const now = Date.now();
+    if (_ingestRateWindows.size > INGEST_RATE_SWEEP_THRESHOLD) {
+        for (const [id, w] of _ingestRateWindows) {
+            if (now - w.start >= INGEST_RATE_WINDOW_MS)
+                _ingestRateWindows.delete(id);
+        }
+    }
+    const win = _ingestRateWindows.get(tokenId);
+    if (!win || now - win.start >= INGEST_RATE_WINDOW_MS) {
+        _ingestRateWindows.set(tokenId, { start: now, count: 1 });
+        return true;
+    }
+    win.count++;
+    return win.count <= INGEST_RATE_LIMIT;
+}
+export function resetIngestRateLimiter() {
+    _ingestRateWindows.clear();
+}
+// Build the event an ingest request delivers: the raw JSON body rides as the
+// payload with its top-level primitives mirrored into `fields`, on exactly the
+// token's bound topic (bubble-scoped). Deliberately NOT createTopicEvent: that
+// helper trusts routing fields in the body (repo/team_key/workspace → global
+// topics), and an ingest body is attacker-adjacent external input that must
+// never influence routing beyond the token's binding.
+export function createIngestEvent(topic, body, bubbleId) {
+    const fields = {};
+    for (const [k, v] of Object.entries(body)) {
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            fields[k] = v;
+        }
+    }
+    return {
+        v: 2,
+        id: crypto.randomUUID(),
+        source: "ingest",
+        type: topic,
+        timestamp: new Date().toISOString(),
+        // Bare topic plus the source-qualified form, mirroring createTopicEvent's
+        // fallback (#235), so both subscription spellings match.
+        topics: [topic, `ingest/${topic}`],
+        delivery: "bulk",
+        text: typeof body.text === "string" ? body.text : "",
+        fields,
+        payload: body,
+        bubble_id: bubbleId,
+    };
+}
+// Serve a provider's GET verification handshake, if it defines one. Returns
+// null when the source has no handshake (or is unregistered) - the transport
+// falls through to its native 404.
+export function handleWebhookHandshake(source, query, secrets) {
+    const def = WEBHOOK_SOURCES[source];
+    if (!def?.handshake)
+        return null;
+    return def.handshake(query, secrets);
+}
+const WEBHOOK_SOURCES = {
+    github: {
+        async verify(_storage, req, _payload, secret) {
+            if (!secret)
+                return unverifiedAdmission();
+            const valid = await verifyGitHubSignature(secret, new TextEncoder().encode(req.rawBody), req.header("x-hub-signature-256"));
+            return valid ? null : INVALID_SIGNATURE;
+        },
+        handle(storage, req, payload) {
+            return handleGitHubWebhook(storage, req.header("x-github-event") || "unknown", req.header("x-github-delivery") || crypto.randomUUID(), payload);
+        },
+    },
+    linear: {
+        async verify(_storage, req, payload, secret) {
+            if (!secret)
+                return unverifiedAdmission();
+            const valid = await verifyLinearSignature(secret, req.rawBody, req.header("linear-signature"), payload.webhookTimestamp);
+            return valid ? null : INVALID_SIGNATURE;
+        },
+        handle(storage, req, payload, ctx) {
+            return handleLinearWebhook(storage, payload, req.header("linear-delivery"), ctx.waitUntil);
+        },
+    },
+    slack: {
+        preVerify(req, payload) {
+            // url_verification must run before BOTH the retry short-circuit and the
+            // signature check: it carries no signing headers, and Slack retries a
+            // failed handshake with x-slack-retry-num set — swallowing retries here
+            // would leave the request URL permanently unverified.
+            if (payload.type === "url_verification") {
+                return { status: 200, body: { challenge: payload.challenge } };
+            }
+            // Dedup retried EVENT deliveries so the agent doesn't double-process.
+            if (req.header("x-slack-retry-num")) {
+                return { status: 200, body: { ok: true } };
+            }
+            return null;
+        },
+        async verify(storage, req, payload, secret) {
+            // Verify against the AUTHORING app's signing secret (resolved by
+            // api_app_id), falling back to the global secret for legacy single-app
+            // deployments. A second app in the workspace signs with its OWN secret;
+            // validating only the global one 401'd it (and dropped its login DM).
+            const signingSecret = await slackSigningSecretFor(storage, payload, secret);
+            if (!signingSecret)
+                return unverifiedAdmission();
+            const valid = await verifySlackSignature(signingSecret, req.header("x-slack-request-timestamp"), req.rawBody, req.header("x-slack-signature"));
+            return valid ? null : INVALID_SIGNATURE;
+        },
+        handle(storage, req, payload) {
+            return handleSlackWebhook(storage, req.rawBody, payload);
+        },
+    },
+    whatsapp: {
+        // Meta verifies the webhook URL with a GET subscribe handshake; the
+        // challenge must echo back as raw text. An unset verify token rejects:
+        // echoing for anyone would let a third party bind our URL to their app.
+        handshake(query, secrets) {
+            const token = secrets.whatsappVerifyToken || "";
+            if (token
+                && query("hub.mode") === "subscribe"
+                && constantTimeEqual(token, query("hub.verify_token"))) {
+                return { status: 200, text: query("hub.challenge") };
+            }
+            return { status: 403, text: "forbidden" };
+        },
+        async verify(_storage, req, _payload, secret) {
+            // FAIL CLOSED, unlike github/slack: an unverified WhatsApp event is
+            // not a read-only notification - it injects a chat message that
+            // drives an outbound reply through the operator's real number and
+            // opens the conversation's 24h send window. Meta always signs, and
+            // there is no legacy-unverified deployment base to stay compatible
+            // with, so a missing secret rejects instead of admitting.
+            if (!secret) {
+                return {
+                    status: 401,
+                    body: { error: "whatsapp webhook verification not configured (set the app secret)" },
+                };
+            }
+            // Meta signs exactly like GitHub: HMAC-SHA256 over the raw body in
+            // x-hub-signature-256 - one verifier serves both.
+            const valid = await verifyGitHubSignature(secret, new TextEncoder().encode(req.rawBody), req.header("x-hub-signature-256"));
+            return valid ? null : INVALID_SIGNATURE;
+        },
+        handle(storage, _req, payload) {
+            return handleWhatsAppWebhook(storage, payload);
+        },
+    },
+    // Generic ingress (#640): POST /webhooks/ingest/<topic> with
+    // `Authorization: Bearer <ingest token>`. The verify slot is the token
+    // check itself — existence, topic binding, rate limit — so the structural
+    // guarantee (#639) holds: this route cannot exist unverified. The body
+    // size cap is declared here but enforced by the pipeline BEFORE the body
+    // is parsed.
+    ingest: {
+        topicRoute: true,
+        maxBodyBytes: INGEST_MAX_BODY_BYTES,
+        async verify(storage, req, _payload, _secret, ctx) {
+            // RFC 7235: the auth scheme is case-insensitive; several webhook
+            // senders emit "bearer".
+            const m = req.header("authorization").match(/^Bearer\s+(\S+)\s*$/i);
+            if (!m)
+                return INGEST_FORBIDDEN;
+            const record = await storage.getIngestTokenByHash(await sha256Hex(m[1]));
+            // One opaque 403 for unknown/revoked AND wrong-topic: a topic-A token
+            // probing topic B learns nothing beyond "not authorized here".
+            if (!record || record.topic !== req.subpath)
+                return INGEST_FORBIDDEN;
+            if (!ingestRateAllow(record.id)) {
+                return { status: 429, body: { error: "rate limited" } };
+            }
+            ctx.ingestToken = record;
+            return null;
+        },
+        async handle(storage, _req, payload, ctx) {
+            // The verified token is the ONLY routing input — topic and bubble come
+            // from its binding, never from the path or body. The verify slot set
+            // it; a missing record here is a pipeline invariant violation, not a
+            // client error.
+            const record = ctx.ingestToken;
+            if (!record)
+                return { status: 500, body: { error: "internal error" } };
+            const event = createIngestEvent(record.topic, payload, record.bubble_id);
+            const delivered = await storage.deliver(event);
+            return { status: 200, body: { delivered_to: delivered } };
+        },
+    },
+};
+// Storage key for a conversation's message-window bookkeeping (#656). Written
+// on every inbound message; read by handleChannelsSend when the channel
+// declares a messageWindow. Channel-generic so future windowed channels reuse
+// it.
+export function channelWindowKey(source, scope, chatId) {
+    return `window:${source}:${scope}:${chatId}`;
+}
+export async function handleWhatsAppWebhook(storage, payload) {
+    const { events } = normalizeWhatsAppWebhook(payload);
+    // Record the customer-service window: each inbound message re-opens 24h of
+    // free-form replies for its conversation (checked at send time). Stamp the
+    // message's OWN timestamp (newest per conversation) and never regress an
+    // existing record - Meta redelivers failed webhooks for days, and a stale
+    // redelivery must not falsely reopen a closed window.
+    const latest = new Map();
+    for (const event of events) {
+        const ref = event.conversation;
+        if (!ref)
+            continue;
+        const ts = Date.parse(String(event.fields?.message_timestamp ?? ""));
+        const stamp = Number.isNaN(ts) ? Date.now() : ts;
+        if (stamp > (latest.get(ref) ?? 0))
+            latest.set(ref, stamp);
+    }
+    for (const [ref, stamp] of latest) {
+        const conv = parseConversation(ref);
+        if (!conv)
+            continue;
+        const key = channelWindowKey(conv.source, conv.scope, conv.chatId);
+        const existing = await storage.getChannelState(key);
+        const prev = Date.parse(existing?.last_inbound || "");
+        if (!Number.isNaN(prev) && prev >= stamp)
+            continue;
+        await storage.putChannelState(key, { last_inbound: new Date(stamp).toISOString() });
+    }
+    let delivered = 0;
+    for (const event of events) {
+        delivered += await storage.deliver(event);
+    }
+    return { status: 200, body: { ok: true, delivered_to: delivered } };
+}
+// An admit-without-verification, counted so /health surfaces a provider
+// running unverified (the misconfiguration class this pipeline exists to
+// close). Returns null — the pipeline admits the request.
+function unverifiedAdmission() {
+    _rejectionCounters.webhook_unverified++;
+    return null;
+}
+// Match a request path against the registered webhook routes — the single
+// route grammar both transports use; they gate the body read on this, so an
+// unregistered path 404s without ever consuming the request body. Exact
+// sources match `/webhooks/<source>` only (AT MOST one trailing slash, the
+// pre-#640 grammar — `/webhooks/github//` stays a 404); topic sources REQUIRE
+// a non-empty remainder, which may itself contain slashes, again with at most
+// one trailing slash tolerated.
+export function matchWebhookSource(path) {
+    const m = path.match(/^\/webhooks\/([^/]+)(?:\/(.*))?$/);
+    if (!m)
+        return null;
+    const source = m[1];
+    const def = WEBHOOK_SOURCES[source];
+    if (!def)
+        return null;
+    if (def.topicRoute) {
+        // A remainder that still ends in "/" after stripping one had multiple
+        // trailing slashes — malformed, and no mintable topic could match it.
+        const rest = (m[2] ?? "").replace(/\/$/, "");
+        return rest && !rest.endsWith("/") ? { source, subpath: rest } : null;
+    }
+    // Exact route: the remainder must be absent (`/webhooks/github`) or empty
+    // (`/webhooks/github/`) on the wire — anything else, including `//`, 404s.
+    return m[2] === undefined || m[2] === "" ? { source, subpath: "" } : null;
+}
+// Run an inbound webhook through the pipeline. Returns null for an
+// unregistered source (the transport falls through to its native 404;
+// transports that gate on matchWebhookSource never hit this).
+export async function handleWebhookRequest(storage, source, req, secrets, options = {}) {
+    const def = WEBHOOK_SOURCES[source];
+    if (!def)
+        return null;
+    // Size gate BEFORE parse: for a capped source, an oversize body must never
+    // reach JSON.parse — the cap exists to bound work done for an untrusted
+    // sender, and parsing is the work.
+    if (def.maxBodyBytes && req.rawBody.length > def.maxBodyBytes) {
+        return { status: 413, body: { error: "payload too large" } };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(req.rawBody);
+    }
+    catch {
+        return INVALID_JSON;
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return INVALID_JSON;
+    }
+    const body = payload;
+    const early = def.preVerify?.(req, body);
+    if (early)
+        return early;
+    const ctx = { waitUntil: options.waitUntil };
+    const secret = secrets[source] || "";
+    const rejected = await def.verify(storage, req, body, secret, ctx);
+    if (rejected) {
+        // Only auth failures feed the /health signature counter — policy
+        // rejections from a VALID credential (429 rate limit) must not read as
+        // a provider secret misconfiguration.
+        if (rejected.status === 401 || rejected.status === 403) {
+            _rejectionCounters.webhook_bad_signature++;
+        }
+        return rejected;
+    }
+    return def.handle(storage, req, body, ctx);
+}
+// Register a deployment into a bubble — MINT or JOIN.
+//   MINT (no bubble-signing headers): server generates a fresh bubble + key,
+//     returns the key ONCE (over TLS). Used only by named agent start's
+//     one-time bootstrap.
+//   JOIN (signed with an existing bubble's key): server verifies the signature
+//     against THAT bubble's stored key and attaches the deployment to it. Every
+//     session of a running instance joins the bubble minted at start.
+// Subscriptions are stored under bubble-namespaced keys so a deployment only
+// ever receives its own bubble's events (plus global webhook topics).
+export async function handleRegisterDeployment(storage, body, ctx) {
+    const name = body.name;
+    const subscriptions = body.subscriptions;
+    if (!name || !subscriptions?.length) {
+        return { status: 400, body: { error: "name and subscriptions[] required" } };
+    }
+    // A request with incomplete signing headers is malformed — reject it
+    // rather than treating it as an (unsigned) MINT, which would silently fork
+    // the caller into a brand-new bubble.
+    if (hasPartialBubbleSignature(ctx)) {
+        return { status: 403, body: { error: "forbidden" } };
+    }
+    let bubble;
+    const minting = !hasBubbleSignature(ctx);
+    if (minting) {
+        bubble = {
+            id: randomToken("bub"),
+            key: randomToken("bkey"),
+            created_at: new Date().toISOString(),
+        };
+        await storage.putBubble(bubble);
+    }
+    else {
+        const authed = await authenticateBubble(storage, ctx);
+        if (!authed)
+            return { status: 403, body: { error: "forbidden" } };
+        bubble = authed;
+    }
+    // Enforcement layer 1 (#488): every GLOBAL resource topic in the request must
+    // have a matching grant for this bubble. Hard-reject the WHOLE request (no
+    // partial write) so the client surfaces a configuration error rather than
+    // silently running degraded (reviewer decision Q2). Delivery (§3.5) remains
+    // the fail-closed boundary regardless. Non-global topics are never gated, so
+    // the bootstrap MINT (`_bootstrap`) is unaffected.
+    const unauthorized = await unauthorizedGlobalTopics(storage, bubble.id, subscriptions);
+    if (unauthorized.length) {
+        return { status: 400, body: { error: "unauthorized_topics", topics: unauthorized } };
+    }
+    // Supersede any prior deployment with the same name in this bubble — a
+    // re-register (e.g. after losing deployment_state.json or a --fresh start)
+    // must not leave a stale deployment in the subscription index, otherwise
+    // directed events (inbox/<name>) get delivered twice (#278 bug 1).
+    const prior = await storage.getDeploymentByName(name, bubble.id);
+    if (prior) {
+        for (const sub of prior.subscriptions) {
+            await storage.removeSubscription(namespaceSubKey(bubble.id, sub), prior.id);
+        }
+        await storage.removeDeployment(prior);
+    }
+    const deploymentId = crypto.randomUUID();
+    const apiKey = `moda_${crypto.randomUUID().replace(/-/g, "")}`;
+    const deployment = {
+        id: deploymentId,
+        name,
+        api_key: apiKey,
+        bubble_id: bubble.id,
+        subscriptions,
+        created_at: new Date().toISOString(),
+    };
+    await storage.putDeployment(deployment);
+    for (const sub of subscriptions) {
+        await storage.addSubscription(namespaceSubKey(bubble.id, sub), deploymentId);
+    }
+    await storage.initDeploymentSession(deploymentId, subscriptions);
+    const resp = {
+        deployment_id: deploymentId,
+        api_key: apiKey,
+        bubble_id: bubble.id,
+    };
+    // The bubble key transits exactly once, at mint, over TLS. Never on join.
+    if (minting)
+        resp.bubble_key = bubble.key;
+    return { status: 201, body: resp };
+}
+export async function handleUpdateSubscriptions(storage, deploymentId, apiKey, body) {
+    const deployment = await authenticateDeployment(storage, apiKey, deploymentId);
+    if (!deployment)
+        return { status: 403, body: { error: "unauthorized" } };
+    const replaceSubs = body.replace;
+    const addSubs = body.add;
+    if (replaceSubs !== undefined && !replaceSubs.length) {
+        return { status: 400, body: { error: "replace[] must not be empty" } };
+    }
+    if (replaceSubs === undefined && !addSubs?.length) {
+        return { status: 400, body: { error: "add[] or replace[] required" } };
+    }
+    const newSubs = replaceSubs !== undefined ? replaceSubs : addSubs;
+    // Enforcement layer 1 (#488): same grant gate as registration — a global
+    // resource topic added here needs a matching grant for the deployment's
+    // bubble. Reject the whole update (no partial write) on any ungranted topic.
+    const unauthorized = await unauthorizedGlobalTopics(storage, deployment.bubble_id, newSubs);
+    if (unauthorized.length) {
+        return { status: 400, body: { error: "unauthorized_topics", topics: unauthorized } };
+    }
+    // Namespace from the AUTHENTICATED deployment record's bubble — never from a
+    // client-supplied bubble_id — so update-subscriptions can't escape the
+    // deployment's bubble. Same keying as registration (namespaceSubKey).
+    if (replaceSubs !== undefined) {
+        const desired = [...new Set(replaceSubs)];
+        const desiredSet = new Set(desired);
+        let removed = 0;
+        let added = 0;
+        for (const sub of deployment.subscriptions) {
+            if (!desiredSet.has(sub)) {
+                await storage.removeSubscription(namespaceSubKey(deployment.bubble_id, sub), deploymentId);
+                removed++;
+            }
+        }
+        for (const sub of desired) {
+            if (!deployment.subscriptions.includes(sub))
+                added++;
+            await storage.addSubscription(namespaceSubKey(deployment.bubble_id, sub), deploymentId);
+        }
+        deployment.subscriptions = desired;
+        await storage.putDeployment(deployment);
+        return { status: 200, body: { subscriptions: deployment.subscriptions, added, removed } };
+    }
+    let added = 0;
+    for (const sub of addSubs) {
+        if (!deployment.subscriptions.includes(sub)) {
+            deployment.subscriptions.push(sub);
+            added++;
+        }
+        await storage.addSubscription(namespaceSubKey(deployment.bubble_id, sub), deploymentId);
+    }
+    await storage.putDeployment(deployment);
+    return { status: 200, body: { subscriptions: deployment.subscriptions, added } };
+}
+export async function handleDeregisterDeployment(storage, deploymentId, apiKey) {
+    const deployment = await authenticateDeployment(storage, apiKey, deploymentId);
+    if (!deployment) {
+        return { status: 403, body: { error: "unauthorized" } };
+    }
+    for (const sub of deployment.subscriptions) {
+        await storage.removeSubscription(namespaceSubKey(deployment.bubble_id, sub), deploymentId);
+    }
+    await storage.removeDeployment(deployment);
+    return { status: 200, body: { ok: true } };
+}
+// Publish to a generic topic. The publisher MUST sign with its bubble key —
+// the authenticated bubble stamps the event so it routes only within that
+// bubble (global webhook topics excepted). An unsigned/invalid publish is
+// rejected; without this an attacker could inject into any bubble by naming a
+// topic, since namespacing alone is not authentication.
+export async function handleTopicEvent(storage, topic, body, ctx) {
+    const bubble = await authenticateBubble(storage, ctx);
+    if (!bubble)
+        return { status: 403, body: { error: "forbidden" } };
+    if (body.repo || body.team_key || body.workspace) {
+        return { status: 400, body: { error: "global routing fields are webhook-only" } };
+    }
+    const event = createTopicEvent(topic, body, bubble.id);
+    if (event.topics.some((key) => isGlobalTopic(key))) {
+        return { status: 400, body: { error: "global topics are webhook-only" } };
+    }
+    const delivered = await storage.deliver(event);
+    return { status: 200, body: { delivered_to: delivered } };
+}
+// ---------------------------------------------------------------------------
+// Scoped ingest tokens (#640) — mint / list / revoke. Every handler takes the
+// AUTHENTICATED bubble id (entry files reject unsigned or bad-signature
+// requests with an opaque 403 before calling these, mirroring
+// /resources/authorize), so a token is only ever visible to — and only ever
+// binds — the bubble that minted it.
+// ---------------------------------------------------------------------------
+// An ingest topic in the token store: `source/type` form like a CLI publish
+// topic (e.g. "alert/firing"), from a charset that never URL-encodes so the
+// wire path and the stored binding compare byte-for-byte. The first segment
+// must not impersonate a webhook provider, and the `:` exclusion structurally
+// rules out every global (github:/linear:/slack:) routing key.
+const INGEST_TOPIC_SEGMENT_RE = /^[A-Za-z0-9_.-]+$/;
+const INGEST_TOPIC_MAX_LENGTH = 200;
+const INGEST_RESERVED_SOURCES = new Set(["github", "linear", "slack"]);
+export function validateIngestTopic(topic) {
+    if (!topic || topic.length > INGEST_TOPIC_MAX_LENGTH) {
+        return "topic must be 1-200 characters";
+    }
+    const segments = topic.split("/");
+    if (segments.length < 2) {
+        return "topic must use source/type form, e.g. alert/firing";
+    }
+    if (!segments.every((s) => INGEST_TOPIC_SEGMENT_RE.test(s))) {
+        return "topic segments must be non-empty [A-Za-z0-9_.-]";
+    }
+    if (INGEST_RESERVED_SOURCES.has(segments[0])) {
+        return "github, linear, and slack sources are reserved for webhooks";
+    }
+    return null;
+}
+export async function envIngestTokenRecords(envValue, bubbleId, now = new Date().toISOString()) {
+    const records = [];
+    for (const rawBinding of envValue.split(",")) {
+        const binding = rawBinding.trim();
+        if (!binding)
+            continue;
+        const eq = binding.indexOf("=");
+        if (eq <= 0 || eq === binding.length - 1) {
+            throw new Error("BOBI_ES_INGEST_TOKENS entries must use topic=token");
+        }
+        const topic = binding.slice(0, eq).trim();
+        const token = binding.slice(eq + 1).trim();
+        const invalid = validateIngestTopic(topic);
+        if (invalid) {
+            throw new Error(`BOBI_ES_INGEST_TOKENS invalid topic ${JSON.stringify(topic)}: ${invalid}`);
+        }
+        if (!token) {
+            throw new Error(`BOBI_ES_INGEST_TOKENS token for ${JSON.stringify(topic)} must not be empty`);
+        }
+        const tokenHash = await sha256Hex(token);
+        records.push({
+            id: crypto.randomUUID(),
+            bubble_id: bubbleId,
+            topic,
+            token_hash: tokenHash,
+            name: "BOBI_ES_INGEST_TOKENS",
+            env_managed: true,
+            created_at: now,
+        });
+    }
+    return records;
+}
+export async function handleIngestTokenCreate(storage, body, bubbleId) {
+    const topic = typeof body.topic === "string" ? body.topic.trim() : "";
+    const name = typeof body.name === "string" && body.name ? body.name : undefined;
+    const invalid = validateIngestTopic(topic);
+    if (invalid)
+        return { status: 400, body: { error: invalid } };
+    const token = randomToken("ingt");
+    const record = {
+        id: crypto.randomUUID(),
+        bubble_id: bubbleId,
+        topic,
+        token_hash: await sha256Hex(token),
+        ...(name ? { name } : {}),
+        created_at: new Date().toISOString(),
+    };
+    await storage.putIngestToken(record);
+    // The plaintext token appears here and nowhere else — it is never stored
+    // and never recoverable from list.
+    return {
+        status: 201,
+        body: {
+            id: record.id,
+            topic: record.topic,
+            ...(name ? { name } : {}),
+            token,
+            created_at: record.created_at,
+        },
+    };
+}
+export async function handleIngestTokenList(storage, bubbleId) {
+    const records = await storage.listIngestTokens(bubbleId);
+    return {
+        status: 200,
+        body: {
+            tokens: records.map((r) => ({
+                id: r.id,
+                topic: r.topic,
+                ...(r.name ? { name: r.name } : {}),
+                ...(r.env_managed ? { env_managed: true } : {}),
+                created_at: r.created_at,
+            })),
+        },
+    };
+}
+export async function handleIngestTokenRevoke(storage, tokenId, bubbleId) {
+    // Resolve the id inside the caller's OWN token list — another bubble's
+    // token id yields the same 404 as a nonexistent one.
+    const records = await storage.listIngestTokens(bubbleId);
+    const record = records.find((r) => r.id === tokenId);
+    if (!record)
+        return { status: 404, body: { error: "not found" } };
+    if (record.env_managed) {
+        return {
+            status: 400,
+            body: {
+                error: "env-managed ingest tokens are rotated by changing BOBI_ES_INGEST_TOKENS and restarting",
+            },
+        };
+    }
+    await storage.deleteIngestToken(record);
+    return { status: 200, body: { ok: true } };
+}
+// ---------------------------------------------------------------------------
+// Resource grants (#488) — verify an upstream credential ONCE, store a grant.
+// ---------------------------------------------------------------------------
+// Upstream hosts are fixed constants, NEVER client-supplied (SSRF guard).
+const GITHUB_API = "https://api.github.com";
+const LINEAR_API = "https://api.linear.app/graphql";
+// GitHub bar (resolved, Q4): the MINIMUM read probe — `GET /repos/{owner}/{repo}`
+// returns 2xx means the token can read the repo, which is all webhook delivery
+// needs. We deliberately do NOT parse `private`/`permissions` (the Rev-2
+// tightening was dropped); only the 2xx/non-2xx distinction gates the grant.
+async function verifyGitHubAccess(resource, credential) {
+    const resp = await fetch(`${GITHUB_API}/repos/${resource}`, {
+        headers: {
+            Authorization: `Bearer ${credential}`,
+            "User-Agent": "bobi-event-server",
+            Accept: "application/vnd.github+json",
+        },
+    });
+    return { ok: resp.ok };
+}
+// Linear (Q3): keep TEAM-KEY granularity — confirm the credential can see the
+// SPECIFIC team it claims, not merely that the token is valid org-wide. Records
+// the team's organization id for the future disambiguation (§4).
+async function verifyLinearAccess(resource, credential) {
+    // `resource` is validated against a strict charset by the caller before this
+    // runs, so it cannot break out of the GraphQL string literal.
+    const query = `{ teams(filter:{key:{eq:"${resource}"}}){ nodes { id key organization { id } } } }`;
+    const resp = await fetch(LINEAR_API, {
+        method: "POST",
+        headers: { Authorization: credential, "Content-Type": "application/json" },
+        body: JSON.stringify({ query }),
+    });
+    if (!resp.ok)
+        return { ok: false };
+    const data = (await resp.json());
+    const nodes = data?.data?.teams?.nodes ?? [];
+    const match = Array.isArray(nodes) ? nodes.find((n) => n?.key === resource) : undefined;
+    if (!match)
+        return { ok: false };
+    return { ok: true, organizationId: match.organization?.id ?? null };
+}
+// A linear team key as it appears in a topic — uppercase alnum plus `-`/`_`.
+// Anchored so a malicious `resource` can never inject into the GraphQL string.
+const LINEAR_KEY_RE = /^[A-Za-z0-9_-]+$/;
+// owner/repo shape (each segment non-empty, no extra slashes).
+const GITHUB_SLUG_RE = /^[^/\s]+\/[^/\s]+$/;
+// POST /resources/authorize handler. `bubbleId` is the AUTHENTICATED bubble -
+// the entry file rejects an unsigned / partial / bad-signature request with an
+// opaque 403 BEFORE calling this. Verifies the upstream credential once, then
+// stores ONLY a grant.
+//
+// The credential is NEVER logged and NEVER stored: the route is excluded from
+// body logging, and a verification failure logs `{service, reason}` only.
+export async function handleAuthorizeResource(storage, body, bubbleId) {
+    const service = typeof body.service === "string" ? body.service : "";
+    const rawResource = typeof body.resource === "string" ? body.resource.trim() : "";
+    const credential = typeof body.credential === "string" ? body.credential : "";
+    // Slack authorizes via the bubble-signed /slack/workspaces registration
+    // (§6) — there is no separate verify call — so only github/linear reach here.
+    if ((service !== "github" && service !== "linear") || !rawResource || !credential) {
+        return { status: 400, body: { error: "invalid_request" } };
+    }
+    const resource = normalizeResource(service, rawResource);
+    if (service === "github" && !GITHUB_SLUG_RE.test(resource)) {
+        return { status: 400, body: { error: "invalid_request" } };
+    }
+    if (service === "linear" && !LINEAR_KEY_RE.test(resource)) {
+        return { status: 400, body: { error: "invalid_request" } };
+    }
+    let result;
+    try {
+        result = service === "github"
+            ? await verifyGitHubAccess(resource, credential)
+            : await verifyLinearAccess(resource, credential);
+    }
+    catch (err) {
+        // Reason only — NEVER the credential or the raw body.
+        console.warn(`resource authorize error: service=${service} reason=${String(err)}`);
+        return { status: 403, body: { error: "forbidden" } };
+    }
+    if (!result.ok) {
+        console.warn(`resource authorize denied: service=${service}`);
+        return { status: 403, body: { error: "forbidden" } };
+    }
+    const grant = {
+        id: `${service}:${resource}:${bubbleId}`,
+        account_id: null,
+        bubble_id: bubbleId,
+        service,
+        resource,
+        granted_by: "upstream_token_verification",
+        organization_id: result.organizationId ?? null,
+        created_at: new Date().toISOString(),
+        expires_at: null,
+    };
+    await storage.putResourceGrant(grant);
+    return { status: 200, body: { ok: true } };
+}
+export async function handleTestSeedResourceGrants(storage, body, bubbleId) {
+    const grants = Array.isArray(body.grants) ? body.grants : [];
+    if (!bubbleId || grants.length === 0) {
+        return { status: 400, body: { error: "invalid_request" } };
+    }
+    for (const raw of grants) {
+        if (!raw || typeof raw !== "object") {
+            return { status: 400, body: { error: "invalid_request" } };
+        }
+        const grant = raw;
+        const service = typeof grant.service === "string" ? grant.service : "";
+        const rawResource = typeof grant.resource === "string" ? grant.resource.trim() : "";
+        if ((service !== "github" && service !== "linear" && service !== "slack"
+            && service !== "whatsapp") || !rawResource) {
+            return { status: 400, body: { error: "invalid_request" } };
+        }
+        const resource = normalizeResource(service, rawResource);
+        await storage.putResourceGrant({
+            id: `${service}:${resource}:${bubbleId}`,
+            account_id: null,
+            bubble_id: bubbleId,
+            service,
+            resource,
+            granted_by: "test_seed",
+            organization_id: null,
+            created_at: new Date().toISOString(),
+            expires_at: null,
+        });
+    }
+    return { status: 200, body: { ok: true, grants: grants.length } };
+}
+// The global resource topics in `subs` that the bubble does NOT currently hold a
+// grant for (#488 enforcement layer 1). A malformed global key (no parseable
+// service/resource) counts as unauthorized. Non-global topics are ignored.
+export async function unauthorizedGlobalTopics(storage, bubbleId, subs) {
+    const bad = [];
+    for (const sub of subs) {
+        if (!isGlobalTopic(sub))
+            continue;
+        const parsed = parseGlobalTopic(sub);
+        if (!parsed) {
+            bad.push(sub);
+            continue;
+        }
+        if (!(await storage.hasResourceGrant(parsed.service, parsed.resource, bubbleId))) {
+            bad.push(sub);
+        }
+    }
+    return bad;
+}
+// Resolve the deployment IDs an event should fan out to, applying the #488
+// resource-grant filter to GLOBAL topics. `subscribersForKey` returns the
+// subscriber ids the runtime has indexed for a subscription key. A non-global
+// key admits every subscriber (the common bubble-scoped path pays nothing); a
+// global key admits a subscriber ONLY if its bubble currently holds a matching
+// grant — so a stale index entry for a revoked / never-granted bubble is dropped
+// (fail-closed; delivery is the authoritative boundary, §3.5).
+export async function admittedDeploymentIds(storage, event, subscribersForKey) {
+    const admitted = new Set();
+    for (const key of subscriptionKeysForEvent(event)) {
+        const ids = await subscribersForKey(key);
+        if (isGlobalTopic(key)) {
+            const parsed = parseGlobalTopic(key);
+            if (!parsed)
+                continue;
+            for (const id of ids) {
+                if (admitted.has(id))
+                    continue;
+                const dep = await storage.getDeploymentById(id);
+                if (dep && (await storage.hasResourceGrant(parsed.service, parsed.resource, dep.bubble_id))) {
+                    admitted.add(id);
+                }
+            }
+        }
+        else {
+            for (const id of ids)
+                admitted.add(id);
+        }
+    }
+    return admitted;
+}
+// Storage key for a bubble-scoped Slack workspace registration. Outbound
+// channel sends read ONLY this key - never the bare global `slack_workspace:<id>`
+// that drives inbound self-reply - so one bubble can never send through a
+// workspace another bubble registered. With the KV adapter's `slack_workspace:`
+// prefix this yields `slack_workspace:${bubbleId}:${workspaceId}`.
+export function bubbleScopedWorkspaceKey(bubbleId, workspaceId) {
+    return `${bubbleId}:${workspaceId}`;
+}
+// Resolve the sending bot's token for an outbound Slack send. Bubble-scoped
+// lookup ONLY - no fallback to the global workspace store. A workspace
+// registered by another bubble (or only inbound-registered) is absent here and
+// yields the same empty result as a truly unknown workspace, so an attacker
+// can't probe which workspaces another bubble registered.
+//
+// Pick the sending bot's token: by app_id, then bot_id, then the single
+// registered bot, then the legacy workspace token. With several bots in a
+// workspace, "the workspace's bot_token" is ambiguous.
+async function resolveSlackSendToken(storage, bubbleId, workspaceId, appId, botId) {
+    if (!workspaceId)
+        return "";
+    const ws = await storage.getSlackWorkspace(bubbleScopedWorkspaceKey(bubbleId, workspaceId));
+    if (!ws)
+        return "";
+    let botToken = ws.bot_token || "";
+    if (appId && ws.bots?.[appId]) {
+        botToken = ws.bots[appId].bot_token;
+    }
+    else if (botId && ws.bots) {
+        const match = Object.values(ws.bots).find((b) => b.bot_id === botId);
+        if (match)
+            botToken = match.bot_token;
+    }
+    else if (!botToken && ws.bots) {
+        const vals = Object.values(ws.bots);
+        if (vals.length >= 1)
+            botToken = vals[0].bot_token;
+    }
+    return botToken;
+}
+// Resolve the sending credential for a conversation's channel, scoped to the
+// AUTHENTICATED bubble. The switch is the single place Phase 3 extends when a
+// new channel brings its own credential store.
+async function resolveChannelSendToken(storage, bubbleId, conv, body) {
+    if (conv.source === "slack") {
+        return resolveSlackSendToken(storage, bubbleId, conv.scope, body.app_id || "", body.bot_id || "");
+    }
+    if (conv.source === "whatsapp") {
+        // Bubble-scoped lookup only, same tenancy boundary as Slack: a number
+        // registered by another bubble is indistinguishable from an unknown one.
+        const rec = await storage.getChannelState(whatsappNumberKey(bubbleId, conv.scope));
+        return rec?.access_token || "";
+    }
+    return "";
+}
+// Storage key for a bubble-scoped WhatsApp number registration (#656). There
+// is no global record: unlike Slack, our own sends never come back as inbound
+// message webhooks, so no self-reply loop prevention is needed.
+export function whatsappNumberKey(bubbleId, phoneNumberId) {
+    return `whatsapp_number:${bubbleId}:${phoneNumberId}`;
+}
+// POST /whatsapp/numbers - registration mirror of handleSlackWorkspaceRegister,
+// but signed-only: there is no unsigned (global) use case, so an
+// unauthenticated registration is rejected outright. Verifies the access token
+// against the Graph API (the phone-number node must be readable with it), then
+// stores the bubble-scoped send credential and writes the whatsapp resource
+// grant that lets this bubble subscribe to `whatsapp:<pnid>` (#488).
+export async function handleWhatsAppNumberRegister(storage, body, bubbleId) {
+    const phoneNumberId = body.phone_number_id;
+    const accessToken = body.access_token;
+    if (!phoneNumberId || !accessToken) {
+        return { status: 400, body: { error: "phone_number_id and access_token required" } };
+    }
+    if (!bubbleId) {
+        return { status: 403, body: { error: "forbidden" } };
+    }
+    try {
+        const data = await whatsappApi(accessToken, `${encodeURIComponent(phoneNumberId)}?fields=id`, { method: "GET" });
+        if (String(data.id ?? "") !== phoneNumberId) {
+            return { status: 403, body: { error: "forbidden" } };
+        }
+    }
+    catch {
+        return { status: 403, body: { error: "forbidden" } };
+    }
+    await storage.putChannelState(whatsappNumberKey(bubbleId, phoneNumberId), {
+        access_token: accessToken,
+    });
+    // Upstream token verification IS the proof of access, same convergence as
+    // Slack (#488 §6): the grant gates inbound `whatsapp:<pnid>` delivery.
+    await storage.putResourceGrant({
+        id: `whatsapp:${phoneNumberId}:${bubbleId}`,
+        account_id: null,
+        bubble_id: bubbleId,
+        service: "whatsapp",
+        resource: phoneNumberId,
+        granted_by: "upstream_token_verification",
+        organization_id: null,
+        created_at: new Date().toISOString(),
+        expires_at: null,
+    });
+    return { status: 200, body: { ok: true, phone_number_id: phoneNumberId } };
+}
+// One outbound file on /channels/send: { name, content_b64, title? }.
+function decodeOutboundFiles(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return null;
+    const files = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            return null;
+        const f = item;
+        if (typeof f.name !== "string" || !f.name || typeof f.content_b64 !== "string" || !f.content_b64) {
+            return null;
+        }
+        let data;
+        try {
+            data = Uint8Array.from(atob(f.content_b64), (c) => c.charCodeAt(0));
+        }
+        catch {
+            return null;
+        }
+        files.push({
+            name: f.name,
+            data,
+            ...(typeof f.title === "string" && f.title ? { title: f.title } : {}),
+        });
+    }
+    return files;
+}
+// Channel-agnostic outbound send (#618, #629):
+//   { conversation, text?, mode?, edit_ref?, files? }
+// Parses the conversation reference and delegates to the channel's adapter.
+// `bubbleId` is the authenticated bubble; credentials resolve only under its
+// scope.
+//
+// Text arrives as raw markdown — formatting is the gateway's job (the Slack
+// adapter delivers it natively via markdown_text). Modes:
+//   post    post a new message
+//   update  edit the message named by edit_ref (e.g. a placeholder)
+//   final   resolve the response context: edit edit_ref when given, else
+//           post; then clear the typing indicator either way
+// Capability degradation happens here: update on a channel without edit
+// support becomes a follow-up post; typing on a channel without indicators
+// is a silent no-op.
+// Spacing between follow-up chunk posts (#651): chunked sends fire several
+// posts into one channel back-to-back, and chat platforms rate-limit sustained
+// per-channel posting (Slack: ~1/sec with burst allowance).
+const CHUNK_SPACING_MS = 300;
+export async function handleChannelsSend(storage, body, bubbleId) {
+    const ref = body.conversation;
+    const text = body.text;
+    // Explicit string checks: a non-string conversation (array, number) must
+    // be a 400, not a TypeError escaping the handler as a 500.
+    if (typeof ref !== "string" || !ref) {
+        return { status: 400, body: { error: "conversation required" } };
+    }
+    const files = decodeOutboundFiles(body.files);
+    if (files === null) {
+        return { status: 400, body: { error: "invalid files: expected [{name, content_b64, title?}]" } };
+    }
+    // Text is required unless files carry the payload (it then becomes the
+    // upload comment). A present-but-non-string text is always a 400.
+    if (text !== undefined && typeof text !== "string") {
+        return { status: 400, body: { error: "text must be a string" } };
+    }
+    if (!text && files.length === 0) {
+        return { status: 400, body: { error: "text or files required" } };
+    }
+    const conv = parseConversation(ref);
+    if (!conv) {
+        return { status: 400, body: { error: "invalid conversation reference" } };
+    }
+    const adapter = getChannelAdapter(conv.source);
+    if (!adapter) {
+        return { status: 400, body: { error: `unsupported channel: ${conv.source}` } };
+    }
+    const mode = body.mode || "post";
+    if (mode !== "post" && mode !== "update" && mode !== "final") {
+        return { status: 400, body: { error: `invalid mode: ${mode}` } };
+    }
+    const editRef = body.edit_ref || "";
+    if (mode === "update" && !editRef) {
+        return { status: 400, body: { error: "edit_ref required for mode: update" } };
+    }
+    const caps = adapter.descriptor.capabilities;
+    // The credential and window-state reads are independent; start both
+    // together and keep the credential error's precedence.
+    const [botToken, windowState] = await Promise.all([
+        resolveChannelSendToken(storage, bubbleId, conv, body),
+        caps.messageWindow
+            ? storage.getChannelState(channelWindowKey(conv.source, conv.scope, conv.chatId))
+            : Promise.resolve(null),
+    ]);
+    if (!botToken) {
+        return { status: 400, body: { error: `no send credential registered for ${conv.source}:${conv.scope}` } };
+    }
+    // Message-window enforcement (#656): a windowed channel (WhatsApp's 24h
+    // customer-service window) only accepts free-form replies for N hours
+    // after the user's last inbound message. A KNOWN-stale window fails with
+    // a TYPED error so the agent can report the situation instead of a
+    // mystery platform rejection. A MISSING record passes through: it can
+    // mean KV replication lag right after a fresh inbound (Workers), so
+    // rejecting would break the most common flow - the platform itself is
+    // the authoritative enforcer and its rejection surfaces as a send error.
+    // Template messaging (the outside-window escape hatch) is a follow-up.
+    if (caps.messageWindow) {
+        const state = windowState;
+        const last = Date.parse(state?.last_inbound || "");
+        if (!Number.isNaN(last)
+            && Date.now() - last > caps.messageWindow.hours * 3600_000) {
+            return {
+                status: 400,
+                body: {
+                    error: "outside_message_window",
+                    detail: `no inbound message from this user in the last `
+                        + `${caps.messageWindow.hours}h; free-form replies are closed`
+                        + (caps.messageWindow.outsideWindow === "template"
+                            ? " (template messages are not supported yet)"
+                            : ""),
+                },
+            };
+        }
+    }
+    const rawText = text || "";
+    let result;
+    try {
+        if (files.length > 0) {
+            // File sends stay single-message: the text is a comment or a
+            // placeholder replacement, so over-budget text truncates.
+            const outText = truncateForChannel(rawText, caps);
+            if (!adapter.uploadFiles || !caps.files) {
+                return { status: 400, body: { error: `channel ${conv.source} does not support files` } };
+            }
+            // A file reply that resolves a placeholder: a message cannot be
+            // edited INTO a file share, so replace the placeholder text first,
+            // then attach the file without a duplicate comment.
+            if (editRef && (mode === "update" || mode === "final")) {
+                if (!outText) {
+                    return { status: 400, body: { error: "text required when edit_ref is combined with files" } };
+                }
+                if (adapter.update && caps.edit) {
+                    const edited = await adapter.update(botToken, conv, editRef, outText);
+                    if (!edited.ok) {
+                        return { status: 502, body: { ok: false, error: edited.error } };
+                    }
+                }
+                result = await adapter.uploadFiles(botToken, conv, files);
+            }
+            else {
+                result = await adapter.uploadFiles(botToken, conv, files, outText || undefined);
+            }
+        }
+        else {
+            // Editing a placeholder degrades to a follow-up post on a channel
+            // without edit support - one degradation rule for update and final.
+            // mode "post" always posts, even if a stray edit_ref is present.
+            const wantsEdit = Boolean(editRef) && (mode === "update" || mode === "final");
+            const editOrSend = (txt) => wantsEdit && adapter.update && caps.edit
+                ? adapter.update(botToken, conv, editRef, txt)
+                : adapter.send(botToken, conv, txt);
+            if (editRef && mode === "update") {
+                // Streaming rewrite of one message: chunking would post a new
+                // message on every tick, so the budget stays truncation-enforced
+                // until the final send.
+                result = await editOrSend(truncateForChannel(rawText, caps));
+            }
+            else {
+                // Terminal send (post, or final resolving a placeholder):
+                // over-budget text goes out whole as natural-boundary chunks.
+                // The first chunk carries the message identity (placeholder
+                // edit, returned ts); later chunks are follow-up posts in the
+                // same conversation, lightly paced for channel rate limits.
+                const chunks = chunkForChannel(rawText, caps);
+                result = await editOrSend(chunks[0]);
+                for (let i = 1; result.ok && i < chunks.length; i++) {
+                    await new Promise((r) => setTimeout(r, CHUNK_SPACING_MS));
+                    const follow = await adapter.send(botToken, conv, chunks[i]);
+                    if (!follow.ok) {
+                        // Chunks 1..i are already visible: clear the typing
+                        // indicator (the reply IS partially delivered) and
+                        // surface an error a caller will not blindly retry.
+                        if ((mode === "update" || mode === "final") && adapter.typing && caps.typing) {
+                            await adapter.typing(botToken, conv, false);
+                        }
+                        return {
+                            status: 502,
+                            body: {
+                                ok: false,
+                                ts: result.ts,
+                                error: `chunk ${i + 1}/${chunks.length} failed after partial delivery `
+                                    + `(do not resend; the reply is partially visible): ${follow.error}`,
+                            },
+                        };
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        return { status: 502, body: { ok: false, error: String(err) } };
+    }
+    if (!result.ok) {
+        return { status: 502, body: { ok: false, error: result.error } };
+    }
+    // Resolving a response context (placeholder edit or final reply) also
+    // clears the "is thinking..." indicator the placeholder flow set.
+    if ((mode === "update" || mode === "final") && adapter.typing && caps.typing) {
+        await adapter.typing(botToken, conv, false);
+    }
+    return { status: 200, body: { ok: true, ts: result.ts } };
+}
+// POST /channels/typing (#629): { conversation, on }. Sets or clears the
+// channel's thinking/typing indicator. A channel without typing support is a
+// silent no-op (200, supported: false) — capability degradation is the
+// gateway's job, not the caller's.
+export async function handleChannelsTyping(storage, body, bubbleId) {
+    const ref = body.conversation;
+    if (typeof ref !== "string" || !ref || typeof body.on !== "boolean") {
+        return { status: 400, body: { error: "conversation and on required" } };
+    }
+    const conv = parseConversation(ref);
+    if (!conv) {
+        return { status: 400, body: { error: "invalid conversation reference" } };
+    }
+    const adapter = getChannelAdapter(conv.source);
+    if (!adapter) {
+        return { status: 400, body: { error: `unsupported channel: ${conv.source}` } };
+    }
+    if (!adapter.typing || !adapter.descriptor.capabilities.typing) {
+        return { status: 200, body: { ok: true, supported: false } };
+    }
+    const botToken = await resolveChannelSendToken(storage, bubbleId, conv, body);
+    if (!botToken) {
+        return { status: 400, body: { error: `no send credential registered for ${conv.source}:${conv.scope}` } };
+    }
+    await adapter.typing(botToken, conv, body.on);
+    return { status: 200, body: { ok: true, supported: true } };
+}
+// GET /channels/history (#629): ?conversation=...&limit=... — read the
+// messages of a conversation (Slack: the thread the ref anchors). Returns
+// { ok, messages: [{user, text, ts, files?}] } oldest-first.
+export async function handleChannelsHistory(storage, conversationRef, limit, bubbleId) {
+    if (!conversationRef) {
+        return { status: 400, body: { error: "conversation required" } };
+    }
+    const conv = parseConversation(conversationRef);
+    if (!conv) {
+        return { status: 400, body: { error: "invalid conversation reference" } };
+    }
+    const adapter = getChannelAdapter(conv.source);
+    if (!adapter) {
+        return { status: 400, body: { error: `unsupported channel: ${conv.source}` } };
+    }
+    if (!adapter.fetchConversation) {
+        return { status: 400, body: { error: `channel ${conv.source} does not support history` } };
+    }
+    const botToken = await resolveChannelSendToken(storage, bubbleId, conv, {});
+    if (!botToken) {
+        return { status: 400, body: { error: `no send credential registered for ${conv.source}:${conv.scope}` } };
+    }
+    const capped = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 1000) : 100;
+    let messages;
+    try {
+        messages = await adapter.fetchConversation(botToken, conv, capped);
+    }
+    catch (err) {
+        return { status: 502, body: { ok: false, error: String(err) } };
+    }
+    return { status: 200, body: { ok: true, messages } };
+}
+// `bubbleId`, when present, is the AUTHENTICATED bubble that signed the
+// registration. The global record (bare workspaceId) is ALWAYS written so
+// inbound webhook self-reply loop prevention keeps working for any client -
+// signed or not. The bubble-scoped record is written ONLY for an authenticated
+// bubble, and is the only store outbound channel sends read.
+export async function handleSlackWorkspaceRegister(storage, body, bubbleId) {
+    const workspaceId = body.workspace_id;
+    const botToken = body.bot_token;
+    if (!workspaceId || !botToken) {
+        return { status: 400, body: { error: "workspace_id and bot_token required" } };
+    }
+    // Accept explicit bot_id/app_id when the caller already resolved them (e.g.
+    // tests, or a Python client). Fall back to auth.test (bot_id) and
+    // bots.info (app_id) — auth.test does NOT return app_id.
+    let botId = body.bot_id || undefined;
+    let botUserId = body.bot_user_id || undefined;
+    let appId = body.app_id || undefined;
+    const signingSecret = body.signing_secret || undefined;
+    if (bubbleId) {
+        try {
+            const resp = await fetch(`${slackApiUrl()}auth.test`, {
+                headers: { Authorization: `Bearer ${botToken}` },
+            });
+            const data = (await resp.json());
+            if (!data.ok || data.team_id !== workspaceId) {
+                return { status: 403, body: { error: "forbidden" } };
+            }
+            if (data.bot_id)
+                botId = data.bot_id;
+        }
+        catch {
+            return { status: 403, body: { error: "forbidden" } };
+        }
+    }
+    else if (!botId) {
+        try {
+            const resp = await fetch(`${slackApiUrl()}auth.test`, {
+                headers: { Authorization: `Bearer ${botToken}` },
+            });
+            const data = (await resp.json());
+            if (data.ok) {
+                botId = data.bot_id;
+                botUserId = data.user_id || botUserId;
+            }
+        }
+        catch {
+            // best-effort — self-loop filtering degrades gracefully without bot_id
+        }
+    }
+    if (!appId && botId) {
+        try {
+            const resp = await fetch(`${slackApiUrl()}bots.info?bot=${encodeURIComponent(botId)}`, { headers: { Authorization: `Bearer ${botToken}` } });
+            const data = (await resp.json());
+            if (data.ok)
+                appId = data.bot?.app_id;
+        }
+        catch {
+            // best-effort — falls back to bot_id-keyed storage below
+        }
+    }
+    // UPSERT one entry into the per-app map — never overwrite the whole record,
+    // so a second bot registering the same workspace doesn't clobber the first.
+    // Pure: applied INDEPENDENTLY to the global and the bubble-scoped record so
+    // the two stores accrete in parallel and never alias.
+    const mergeBot = (existing) => {
+        const bots = { ...(existing?.bots ?? {}) };
+        // Migrate a pre-existing legacy single-bot record into the map.
+        if (existing?.bot_id && existing.bot_token && !bots[existing.bot_id]) {
+            bots[existing.bot_id] = { bot_token: existing.bot_token, bot_id: existing.bot_id };
+        }
+        // Key by api_app_id; fall back to bot_id when app_id couldn't be resolved
+        // (still unique per bot within a workspace, just not loop-safe across two
+        // bots that share a bot_id — which never happens).
+        const key = appId || botId || "default";
+        // MERGE, don't replace: a registration that omits a field (e.g. an older
+        // client that doesn't send signing_secret) must NOT wipe a value a previous
+        // registration set — otherwise every restart of such a client drops the
+        // per-app signing secret and the app's events fall back to the global secret
+        // and 401. Always refresh the bot_token (it may rotate); preserve the rest.
+        const prev = bots[key] ?? {};
+        bots[key] = {
+            bot_token: botToken,
+            bot_id: botId ?? prev.bot_id,
+            bot_user_id: botUserId ?? prev.bot_user_id,
+            signing_secret: signingSecret ?? prev.signing_secret,
+            app_id: appId ?? prev.app_id,
+        };
+        return {
+            // Keep legacy fields reflecting the just-registered bot for back-compat
+            // readers; `bots` is authoritative.
+            bot_token: botToken,
+            bot_id: botId,
+            bots,
+        };
+    };
+    // Global record - drives inbound webhook self-reply loop prevention. ALWAYS
+    // written so a client that doesn't (yet) sign keeps loop prevention.
+    const globalExisting = await storage.getSlackWorkspace(workspaceId);
+    await storage.putSlackWorkspace(workspaceId, mergeBot(globalExisting));
+    // Bubble-scoped record - the ONLY store outbound channel sends read. Written
+    // only for an authenticated bubble, so that bubble (and no other) can send
+    // through this workspace.
+    if (bubbleId) {
+        const scopedKey = bubbleScopedWorkspaceKey(bubbleId, workspaceId);
+        const scopedExisting = await storage.getSlackWorkspace(scopedKey);
+        await storage.putSlackWorkspace(scopedKey, mergeBot(scopedExisting));
+        // Slack convergence (#488 §6): the signed registration — proving
+        // possession of the bot token + signing secret — IS the proof of access,
+        // so it doubles as the slack resource grant. `slack:{teamId}` inbound
+        // delivery is then grant-filtered exactly like github/linear. Idempotent.
+        await storage.putResourceGrant({
+            id: `slack:${workspaceId}:${bubbleId}`,
+            account_id: null,
+            bubble_id: bubbleId,
+            service: "slack",
+            resource: workspaceId,
+            granted_by: "upstream_token_verification",
+            organization_id: null,
+            created_at: new Date().toISOString(),
+            expires_at: null,
+        });
+    }
+    return {
+        status: 200,
+        body: { ok: true, workspace_id: workspaceId, bot_id: botId, bot_user_id: botUserId, app_id: appId },
+    };
+}
+//# sourceMappingURL=core.js.map