switchroom 0.14.9 → 0.14.10

package/telegram-plugin/gateway/gateway.ts

@@ -263,6 +263,8 @@ import { formatUpdateStatusLine } from './update-status-line.js'
 import type { HostdRequest } from '../../src/host-control/protocol.js'
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
+import { startWebhookIngestServer } from './webhook-ingest-server.js'
+import { recordWebhookEvent } from '../../src/web/webhook-gateway-record.js'
 
 import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js'
 import { handleRequestDriveApproval } from './drive-write-approval.js'
@@ -4652,6 +4654,89 @@ const ipcServer: IpcServer = createIpcServer({
   log: (msg) => process.stderr.write(`telegram gateway: ipc — ${msg}\n`),
 })
 
+// ─── Webhook ingest server (RFC webhook-via-gateway-socket) ───────────────
+// Under the Docker runtime the host-side web receiver runs as the operator
+// UID and cannot write this agent's UID-owned dir (EACCES 500) nor connect
+// gateway.sock. When `channels.telegram.webhook_via_gateway` is set, the
+// receiver instead forwards verified+rendered events here over a dedicated
+// peercred-gated UDS; this gateway (agent UID) owns the jsonl append,
+// dedup, and dispatch firing. Wrapped so any failure is best-effort and can
+// NEVER crash gateway boot (which would take the agent down).
+;(() => {
+  try {
+    const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    if (!selfAgent) return
+
+    let viaGateway = false
+    try {
+      const cfg = loadSwitchroomConfig()
+      const raw = cfg.agents?.[selfAgent]
+      viaGateway = raw
+        ? resolveAgentConfig(cfg.defaults, cfg.profiles, raw).channels?.telegram
+            ?.webhook_via_gateway === true
+        : false
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: webhook-ingest config probe failed: ${(err as Error).message}\n`,
+      )
+    }
+    if (!viaGateway) return
+
+    // Allowed peer UIDs: the agent's own UID (self-connections) + the
+    // operator/receiver UID emitted into the env by the compose generator
+    // (SWITCHROOM_WEBHOOK_RECEIVER_UID == operatorUid). Fail-closed: if the
+    // receiver UID is unset, only self can connect → receiver gets 503,
+    // surfacing the misconfiguration instead of silently accepting any UID.
+    const allowedUids: number[] = []
+    const ownUid = typeof process.getuid === 'function' ? process.getuid() : null
+    if (ownUid !== null) allowedUids.push(ownUid)
+    const receiverUidRaw = process.env.SWITCHROOM_WEBHOOK_RECEIVER_UID
+    const receiverUid = receiverUidRaw ? Number(receiverUidRaw) : NaN
+    if (Number.isInteger(receiverUid)) allowedUids.push(receiverUid)
+
+    const socketPath = join(STATE_DIR, 'webhook.sock')
+
+    // In-process delivery of a synthesized webhook turn — the same
+    // sendToAgent + buffer-on-failure primitive onInjectInbound uses, so a
+    // webhook fire landing mid bridge-reconnect is buffered, not dropped.
+    const webhookInject = (agentName: string, inbound: unknown): boolean => {
+      // The wire record is a structural mirror of the bridge's
+      // InboundMessage (same cast the scheduler's ipcDispatcher uses).
+      const msg = inbound as InboundMessage
+      const delivered = ipcServer.sendToAgent(agentName, msg)
+      if (delivered) markClaudeBusyForInbound(msg)
+      else pendingInboundBuffer.push(agentName, msg)
+      return delivered
+    }
+
+    startWebhookIngestServer({
+      socketPath,
+      allowedUids,
+      log: (s) => process.stderr.write(`telegram gateway: ${s}`),
+      onRecord: (req) =>
+        recordWebhookEvent(
+          {
+            agent: selfAgent,
+            source: req.source,
+            event_type: req.event_type,
+            ts: req.ts,
+            rendered_text: req.rendered_text,
+            payload: req.payload,
+            ...(req.delivery_id ? { delivery_id: req.delivery_id } : {}),
+          },
+          {
+            inject: webhookInject,
+            log: (s) => process.stderr.write(`telegram gateway: ${s}`),
+          },
+        ),
+    })
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: webhook-ingest server start failed (non-fatal): ${(err as Error).message}\n`,
+    )
+  }
+})()
+
 // ─── Opportunistic idle-drain of pendingInboundBuffer ─────────────────────
 // pendingInboundBuffer otherwise drains only on (a) bridge re-register
 // (onClientRegistered) or (b) the silence-poke framework fallback

package/telegram-plugin/gateway/webhook-ingest-server.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Tests for the peercred-gated webhook ingest UDS server
+ * (RFC docs/rfcs/webhook-via-gateway-socket.md).
+ *
+ * MUST run under `bun test`: the peer-credential gate calls
+ * `getPeerCred` (bun:ffi getsockopt SO_PEERCRED), which returns null
+ * under node/vitest — so the allow path is only exercisable under bun.
+ * This file is excluded from the vitest run (see vitest.config.ts) and
+ * listed in the `test:bun` / `test` scripts in package.json.
+ *
+ * Sockets live in an isolated tmpdir — never `~/.switchroom`.
+ */
+
+import { describe, it, expect, afterEach } from 'bun:test'
+import net from 'node:net'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  startWebhookIngestServer,
+  type WebhookIngestServer,
+  type WebhookIngestRequest,
+} from './webhook-ingest-server.js'
+import { forwardToGateway } from '../../src/web/webhook-ingest-client.js'
+
+const servers: WebhookIngestServer[] = []
+afterEach(() => {
+  for (const s of servers.splice(0)) s.close()
+})
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'webhook-ingest-srv-'))
+  return join(dir, 'webhook.sock')
+}
+
+function sampleReq(): WebhookIngestRequest {
+  return {
+    agent: 'reggie',
+    source: 'github',
+    event_type: 'pull_request',
+    ts: 1_700_000_000_000,
+    rendered_text: 'PR opened',
+    payload: { action: 'opened', number: 7 },
+    delivery_id: 'd-7',
+  }
+}
+
+describe('startWebhookIngestServer (peercred-gated)', () => {
+  it('accepts a connection from an allowed uid and round-trips onRecord', async () => {
+    const socketPath = tmpSocket()
+    let received: WebhookIngestRequest | null = null
+    const server = startWebhookIngestServer({
+      socketPath,
+      allowedUids: [process.getuid!()], // our own uid → allowed
+      onRecord: (req) => {
+        received = req
+        return { status: 'ok', ts: req.ts, dispatched: 1 }
+      },
+      log: () => {},
+    })
+    servers.push(server)
+
+    const resp = await forwardToGateway(socketPath, sampleReq())
+
+    expect(resp).not.toBeNull()
+    expect(resp!.status).toBe('ok')
+    expect(resp!.ts).toBe(1_700_000_000_000)
+    expect(resp!.dispatched).toBe(1)
+    expect(received).not.toBeNull()
+    expect(received!.agent).toBe('reggie')
+    expect(received!.event_type).toBe('pull_request')
+    expect(received!.delivery_id).toBe('d-7')
+  })
+
+  it('denies a connection whose uid is not in allowedUids (onRecord never runs)', async () => {
+    const socketPath = tmpSocket()
+    let called = false
+    const server = startWebhookIngestServer({
+      socketPath,
+      allowedUids: [999_999], // definitely not our uid
+      onRecord: () => {
+        called = true
+        return { status: 'ok' }
+      },
+      log: () => {},
+    })
+    servers.push(server)
+
+    // The server destroys the connection in its accept callback BEFORE
+    // reading any bytes, so onRecord must never run. We assert the
+    // security property (no service for an unlisted uid) directly rather
+    // than via the client resolving: bun's net client does not observe a
+    // server-side destroy of a just-accepted UDS connection promptly, so
+    // awaiting forwardToGateway here would hang. Send raw bytes and give
+    // the server ample time to (not) process them.
+    const raw = net.createConnection(socketPath)
+    raw.on('connect', () => raw.write(JSON.stringify(sampleReq()) + '\n'))
+    raw.on('error', () => {})
+    await new Promise((r) => setTimeout(r, 300))
+    raw.destroy()
+
+    expect(called).toBe(false)
+  })
+
+  it('returns null when the socket does not exist (gateway down)', async () => {
+    const socketPath = tmpSocket() // never bound
+    const resp = await forwardToGateway(socketPath, sampleReq(), { timeoutMs: 2000 })
+    expect(resp).toBeNull()
+  })
+
+  it('surfaces a gateway-side error status from onRecord', async () => {
+    const socketPath = tmpSocket()
+    const server = startWebhookIngestServer({
+      socketPath,
+      allowedUids: [process.getuid!()],
+      onRecord: () => ({ status: 'error', error: 'write failed' }),
+      log: () => {},
+    })
+    servers.push(server)
+
+    const resp = await forwardToGateway(socketPath, sampleReq())
+    expect(resp).not.toBeNull()
+    expect(resp!.status).toBe('error')
+  })
+})

package/telegram-plugin/gateway/webhook-ingest-server.ts

@@ -0,0 +1,218 @@
+/**
+ * Webhook ingest UDS server (RFC docs/rfcs/webhook-via-gateway-socket.md).
+ *
+ * A dedicated, peercred-gated Unix socket the host-side web receiver
+ * forwards verified webhook events to. It is deliberately SEPARATE from
+ * the bridge IPC socket (`gateway.sock`):
+ *
+ *   - `gateway.sock` is bound via `Bun.listen`, whose accepted socket does
+ *     NOT expose a file descriptor — so SO_PEERCRED can't be read on it.
+ *     This server uses `node:net` (whose `Socket._handle.fd` IS readable
+ *     under Bun, verified empirically) precisely so the peer-credential
+ *     gate works.
+ *   - Keeping the chat-critical bridge socket untouched avoids any risk to
+ *     the bridge-flap-sensitive reconnect path.
+ *
+ * Auth model — two independent layers:
+ *   1. **Filesystem**: the socket is chmod 0o666 so the host operator UID
+ *      can connect at all (the agent dir itself is 0775/agent-UID, which
+ *      blocks the operator from writing files but not from connecting a
+ *      world-connectable socket).
+ *   2. **Peer credentials**: every connection's SO_PEERCRED UID must be in
+ *      `allowedUids` (the agent's own UID + the operator/receiver UID).
+ *      This is the load-bearing gate: it ensures only the trusted receiver
+ *      (which enforces per-event HMAC) — or the agent itself — can inject a
+ *      webhook turn. Fail-closed: unreadable creds or an unlisted UID is
+ *      denied.
+ *
+ * Wire protocol: one JSON line in (`WebhookIngestRequest`), one JSON line
+ * out (`WebhookIngestResponse`), then the connection closes. No framing
+ * beyond the trailing newline; requests are small (a rendered event +
+ * payload).
+ */
+
+import net from 'node:net'
+import { chmodSync, existsSync, unlinkSync } from 'node:fs'
+import { getPeerCred } from '../../src/vault/broker/peercred-ffi.js'
+
+/** Forwarded by the receiver; structural mirror of WebhookGatewayRecord. */
+export interface WebhookIngestRequest {
+  agent: string
+  source: string
+  event_type: string
+  ts: number
+  rendered_text: string
+  payload: Record<string, unknown>
+  delivery_id?: string
+}
+
+export interface WebhookIngestResponse {
+  status: 'ok' | 'deduped' | 'error'
+  ts?: number
+  error?: string
+  dispatched?: number
+}
+
+export interface WebhookIngestServerOptions {
+  socketPath: string
+  /** SO_PEERCRED UIDs permitted to inject. Connections from any other UID
+   *  (or with unreadable creds) are denied and the socket destroyed. */
+  allowedUids: number[]
+  /** Handle one verified, forwarded event. Synchronous return (the record
+   *  path is file I/O + an in-process inject) wrapped in Promise for the
+   *  server's await. */
+  onRecord: (req: WebhookIngestRequest) => WebhookIngestResponse | Promise<WebhookIngestResponse>
+  log?: (line: string) => void
+}
+
+export interface WebhookIngestServer {
+  close: () => void
+}
+
+const MAX_REQUEST_BYTES = 1024 * 1024 // 1 MiB — github payloads fit easily
+
+/** Read the accepted connection's fd via the undocumented `_handle.fd`.
+ *  Under Bun's node:net polyfill this is present (verified); returns null
+ *  if absent so the caller fails closed. */
+function fdOf(conn: net.Socket): number | null {
+  const handle = (conn as unknown as { _handle?: { fd?: number } })._handle
+  if (!handle || typeof handle.fd !== 'number' || handle.fd < 0) return null
+  return handle.fd
+}
+
+/**
+ * Start the webhook ingest server. Never throws — bind failures are logged
+ * and surfaced via the returned server still being usable as a no-op close.
+ * The CALLER (gateway boot) additionally wraps this so a failure here can
+ * never take the agent down; this function's own try/catch is belt-and-
+ * suspenders.
+ */
+export function startWebhookIngestServer(
+  opts: WebhookIngestServerOptions,
+): WebhookIngestServer {
+  const log = opts.log ?? ((s) => process.stderr.write(s))
+  const allowed = new Set(opts.allowedUids)
+
+  // Clear a stale socket from a previous (crashed) gateway. Safe: only this
+  // agent's gateway binds this path, and we're about to rebind it.
+  try {
+    if (existsSync(opts.socketPath)) unlinkSync(opts.socketPath)
+  } catch (err) {
+    log(`webhook-ingest-server: could not unlink stale socket: ${(err as Error).message}\n`)
+  }
+
+  const server = net.createServer((conn) => {
+    // ── Peer-credential gate (fail-closed) ──────────────────────────────────
+    const fd = fdOf(conn)
+    const cred = fd !== null ? getPeerCred(fd) : null
+    if (cred === null || !allowed.has(cred.uid)) {
+      log(
+        `webhook-ingest-server: DENY connection uid=${cred?.uid ?? 'unknown'} ` +
+          `(allowed=${[...allowed].join(',')})\n`,
+      )
+      conn.destroy()
+      return
+    }
+
+    let buf = ''
+    let handled = false
+    conn.setEncoding('utf8')
+
+    const reply = (resp: WebhookIngestResponse) => {
+      if (handled) return
+      handled = true
+      try {
+        conn.write(JSON.stringify(resp) + '\n')
+      } catch {
+        /* peer may have hung up */
+      }
+      conn.end()
+    }
+
+    conn.on('data', (chunk: string) => {
+      if (handled) return
+      buf += chunk
+      if (buf.length > MAX_REQUEST_BYTES) {
+        reply({ status: 'error', error: 'request too large' })
+        return
+      }
+      const nl = buf.indexOf('\n')
+      if (nl === -1) return // wait for the full line
+      const line = buf.slice(0, nl)
+
+      let req: WebhookIngestRequest
+      try {
+        req = JSON.parse(line) as WebhookIngestRequest
+      } catch {
+        reply({ status: 'error', error: 'malformed request' })
+        return
+      }
+      if (
+        !req ||
+        typeof req.agent !== 'string' ||
+        typeof req.source !== 'string' ||
+        typeof req.event_type !== 'string' ||
+        typeof req.rendered_text !== 'string' ||
+        typeof req.payload !== 'object' ||
+        req.payload === null
+      ) {
+        reply({ status: 'error', error: 'invalid request shape' })
+        return
+      }
+
+      Promise.resolve()
+        .then(() => opts.onRecord(req))
+        .then((resp) => reply(resp))
+        .catch((err: unknown) => {
+          log(`webhook-ingest-server: onRecord threw: ${String(err)}\n`)
+          reply({ status: 'error', error: 'internal error' })
+        })
+    })
+
+    conn.on('error', (err) => {
+      log(`webhook-ingest-server: conn error: ${err.message}\n`)
+    })
+
+    // Drop slow/idle clients so a stuck connection can't pin the socket.
+    conn.setTimeout(10_000, () => {
+      if (!handled) reply({ status: 'error', error: 'timeout' })
+      conn.destroy()
+    })
+  })
+
+  server.on('error', (err) => {
+    log(`webhook-ingest-server: server error: ${err.message}\n`)
+  })
+
+  try {
+    server.listen(opts.socketPath, () => {
+      try {
+        // World-connectable at the FS layer; peercred is the real gate.
+        chmodSync(opts.socketPath, 0o666)
+      } catch (err) {
+        log(`webhook-ingest-server: chmod failed: ${(err as Error).message}\n`)
+      }
+      log(
+        `webhook-ingest-server: listening at ${opts.socketPath} ` +
+          `(allowed uids: ${[...allowed].join(',')})\n`,
+      )
+    })
+  } catch (err) {
+    log(`webhook-ingest-server: listen failed: ${(err as Error).message}\n`)
+  }
+
+  return {
+    close: () => {
+      try {
+        server.close()
+      } catch {
+        /* ignore */
+      }
+      try {
+        if (existsSync(opts.socketPath)) unlinkSync(opts.socketPath)
+      } catch {
+        /* ignore */
+      }
+    },
+  }
+}