feat(server): live booth WebSocket feed (/api/ws)

Add @fastify/websocket. EventLog fires an onAppended callback after each durable append; device-events gains a ledger channel (emitLedger). /api/ws fans out ledger + occupancy + printer-status to authenticated booth clients. Origin allowlist (WS_ALLOWED_ORIGINS) replaces CSRF for the handshake (anti-CSWSH). Note: server.ts also reflects later booth route wiring; the final HEAD builds.
2026-06-18 11:00:22 +02:00
parent 58d8f06ba0
commit c2f06a5d2a
6 changed files with 162 additions and 4 deletions
@@ -0,0 +1,104 @@
+import type { FastifyInstance } from "fastify";
+import type { Db } from "@parking/db";
+import type { Role } from "@parking/shared";
+import { deviceEvents } from "../device-events.js";
+import { getOccupancy } from "../occupancy.js";
+
+// Live booth feed over a WebSocket. The booth UI opens ONE socket and receives
+// server-pushed updates instead of polling: each signed ledger append (entry,
+// exit, payment, void) is fanned out, and the recomputed occupancy rides along
+// so the screen's count stays exact (occupancy is a fold over the same ledger,
+// never a counter). Printer-status changes are forwarded too.
+//
+// Auth: the handshake is a normal GET through Fastify's lifecycle, so the same
+// HttpOnly JWT cookie that guards the REST API guards this. We verify the JWT and
+// role here. A browser's WebSocket constructor cannot set custom headers, so the
+// CSRF double-submit header the REST mutations use is unavailable — which would
+// leave the socket open to Cross-Site WebSocket Hijacking: a malicious page in the
+// operator's browser could open ws://<booth>/api/ws, the browser would auto-attach
+// the HttpOnly cookie, and the attacker would receive the live entry/exit/payment
+// stream. The cookie alone is NOT a control here. So we replace the CSRF check with
+// an Origin allowlist: the handshake's Origin must be same-origin (or an explicitly
+// allowed booth UI origin). Non-browser clients (no Origin) are rejected too.
+// See auth.ts, event-log.ts (emitLedger), capacity-occupancy.md.
+
+/** Roles allowed to watch the live feed (everyone signed in; readonly included —
+ *  it's a read-only stream). */
+const WATCH_ROLES: Role[] = ["admin", "operator", "cashier", "readonly"];
+
+/**
+ * Is the handshake's Origin trusted? Same-origin (Origin host === Host header) is
+ * always allowed; additional origins can be allowlisted via WS_ALLOWED_ORIGINS
+ * (comma-separated) for a booth UI served from a different origin. A missing or
+ * mismatched Origin is rejected — that is the anti-CSWSH control.
+ */
+function isAllowedOrigin(origin: string | undefined, host: string | undefined): boolean {
+  if (!origin) return false; // no Origin → not a same-origin browser request
+  let originHost: string;
+  try {
+    originHost = new URL(origin).host;
+  } catch {
+    return false; // malformed Origin
+  }
+  if (host && originHost === host) return true; // same-origin (any scheme/port match via host)
+  const allow = (process.env.WS_ALLOWED_ORIGINS ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return allow.includes(origin);
+}
+
+type OutMsg =
+  | { kind: "hello"; occupancy: ReturnType<typeof getOccupancy> }
+  | { kind: "ledger"; event: unknown; occupancy: ReturnType<typeof getOccupancy> }
+  | { kind: "printer-status"; event: unknown };
+
+export async function wsRoutes(app: FastifyInstance, db: Db): Promise<void> {
+  app.get(
+    "/api/ws",
+    {
+      websocket: true,
+      // Origin allowlist (anti-CSWSH, replaces CSRF — see file header) THEN JWT +
+      // role. Reject a cross/absent origin before touching the token, so a hijack
+      // attempt never reaches an authenticated socket. jwtVerify reads the cookie.
+      preHandler: async (req) => {
+        if (!isAllowedOrigin(req.headers.origin, req.headers.host)) {
+          throw Object.assign(new Error("forbidden origin"), { statusCode: 403 });
+        }
+        await req.jwtVerify();
+        if (!req.user || !WATCH_ROLES.includes(req.user.role)) {
+          throw Object.assign(new Error("forbidden"), { statusCode: 403 });
+        }
+      },
+    },
+    (socket) => {
+      const send = (msg: OutMsg) => {
+        // readyState 1 = OPEN; never throw out of an event-bus callback.
+        if (socket.readyState === 1) {
+          try {
+            socket.send(JSON.stringify(msg));
+          } catch {
+            /* drop on a broken socket */
+          }
+        }
+      };
+
+      // Initial snapshot so the client renders immediately, before any event.
+      send({ kind: "hello", occupancy: getOccupancy(db) });
+
+      // Subscribe to the live buses. Each handler recomputes occupancy from the
+      // ledger (cheap fold) so the pushed count is always authoritative.
+      const offLedger = deviceEvents.onLedger((event) => {
+        send({ kind: "ledger", event, occupancy: getOccupancy(db) });
+      });
+      const offPrinter = deviceEvents.onPrinterStatus((event) => {
+        send({ kind: "printer-status", event });
+      });
+
+      socket.on("close", () => {
+        offLedger();
+        offPrinter();
+      });
+    },
+  );
+}