@lumencast/server 0.1.0

package/src/server.ts

@@ -0,0 +1,386 @@
+// HTTP + WebSocket server kit for LSDP/1.
+//
+// Single-scene at a time, single-process. The active scene is mutable so the
+// interop test control plane can swap it via /test/setup without restarting
+// the server.
+//
+// LSDP/1 spec compliance highlights:
+//   - WebSocket subprotocol negotiation: `lsdp.v1`
+//   - subscribe → snapshot(seq=1) → delta(seq=2,...)
+//   - input frames validated against `authenticate()` decision + canWritePath()
+//   - error frames carry codes from the closed taxonomy
+//   - heartbeat: ping → pong
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { WebSocketServer, type WebSocket } from "ws";
+import {
+  delta as deltaFrame,
+  decodeClientFrame,
+  encodeFrame,
+  errorFrame,
+  isProtocolErrorCode,
+  LumencastError,
+  pong,
+  snapshot as snapshotFrame,
+  WS_SUBPROTOCOL,
+  WS_SUBPROTOCOL_V1_1,
+  type Cause,
+  type ErrorCode,
+  type Patch,
+  type SceneVersion,
+} from "@lumencast/protocol";
+import { canWritePath, defaultAuthenticate, type Authenticate, type AuthDecision } from "./auth.js";
+import type { Scene } from "./scene.js";
+
+export interface ServerConfig {
+  /** TCP port to listen on. 0 = random. */
+  port?: number;
+  /** Hostname to bind. Defaults to 127.0.0.1. */
+  host?: string;
+  /** The initial scene this server serves. May be swapped via setActiveScene(). */
+  scene: Scene;
+  /** Resolves a SceneVersion to its LSML bundle JSON. May be swapped. */
+  bundleProvider: (version: SceneVersion) => Promise<unknown> | unknown;
+  /** Authenticate every subscribe; default accepts everything as `viewer`. */
+  authenticate?: Authenticate;
+  /** Optional ws path. Defaults to `/lsdp/v1`. */
+  wsPath?: string;
+  /** Optional bundle path prefix. Defaults to `/lsdp/v1/scenes`. */
+  bundlePathPrefix?: string;
+}
+
+export interface ServerHandle {
+  readonly wsUrl: string;
+  readonly httpUrl: string;
+  /**
+   * Replace the active scene. Detaches every subscriber (they receive a 1012
+   * "service restart" close so well-behaved clients reconnect cleanly).
+   * Test/interop only — production code should never call this.
+   */
+  setActiveScene(scene: Scene): void;
+  /** Replace the bundle provider. Test/interop only. */
+  setBundleProvider(fn: (version: SceneVersion) => Promise<unknown> | unknown): void;
+  /** Read the current active scene. */
+  activeScene(): Scene;
+  /** Drop all subscribers without replacing the scene. Test/interop only. */
+  reset(): void;
+  close(): Promise<void>;
+}
+
+interface Subscriber {
+  ws: WebSocket;
+  // Per-scene seq (LSDP/1.1 §18.1.1) — see activeScene.currentSeq().
+  // Subscribers don't carry their own counter.
+  decision: AuthDecision | null;
+  unsubscribePatches: (() => void) | null;
+}
+
+export async function startServer(config: ServerConfig): Promise<ServerHandle> {
+  const host = config.host ?? "127.0.0.1";
+  const wsPath = config.wsPath ?? "/lsdp/v1";
+  const bundlePathPrefix = config.bundlePathPrefix ?? "/lsdp/v1/scenes";
+  const authenticate = config.authenticate ?? defaultAuthenticate;
+
+  // Mutable refs — swappable via setActiveScene / setBundleProvider.
+  let activeScene: Scene = config.scene;
+  let bundleProvider = config.bundleProvider;
+
+  const httpServer: Server = createServer((req, res) => handleHttp(req, res));
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(config.port ?? 0, host, () => {
+      httpServer.off("error", reject);
+      resolve();
+    });
+  });
+
+  const address = httpServer.address();
+  if (!address || typeof address === "string") {
+    throw new Error("server: failed to bind HTTP");
+  }
+  const port = address.port;
+
+  const wss = new WebSocketServer({
+    server: httpServer,
+    path: wsPath,
+    handleProtocols: (offered: Set<string>) => {
+      // LSDP/1.1 preferred, 1.0 fallback. Anything else → reject upgrade.
+      if (offered.has(WS_SUBPROTOCOL_V1_1)) return WS_SUBPROTOCOL_V1_1;
+      if (offered.has(WS_SUBPROTOCOL)) return WS_SUBPROTOCOL;
+      return false;
+    },
+  });
+
+  const subscribers = new Set<Subscriber>();
+
+  wss.on("connection", (ws) => {
+    const sub: Subscriber = { ws, decision: null, unsubscribePatches: null };
+    subscribers.add(sub);
+
+    ws.on("message", (data) => handleMessage(sub, String(data)).catch(() => undefined));
+    ws.on("close", () => {
+      sub.unsubscribePatches?.();
+      subscribers.delete(sub);
+    });
+  });
+
+  async function handleMessage(sub: Subscriber, raw: string): Promise<void> {
+    let frame;
+    try {
+      frame = decodeClientFrame(raw);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "decode error";
+      // LSDP/1 §13: envelope.v mismatch → close with code 1002 directly,
+      // no error frame (the v != 1 client wouldn't grok our v: 1 envelope).
+      if (message.includes("envelope.v")) {
+        sub.ws.close(1002, "VERSION_MISMATCH");
+        return;
+      }
+      const code = err instanceof LumencastError ? err.code : "INVALID_VALUE";
+      const recoverable = err instanceof LumencastError ? err.recoverable : false;
+      const path = err instanceof LumencastError ? err.path : undefined;
+      sendError(sub, code, message, recoverable, path !== undefined ? { path } : undefined);
+      // Recoverable decode errors (e.g. forbidden object value in a single
+      // patch per §3.2.1) MUST keep the connection open ; only fatal
+      // structural errors close.
+      if (!recoverable) {
+        sub.ws.close(1002, code);
+      }
+      return;
+    }
+    if (frame === null) return; // forward-compat ignore
+
+    switch (frame.type) {
+      case "subscribe": {
+        await handleSubscribe(sub, frame.token, frame.since_sequence);
+        return;
+      }
+      case "input": {
+        await handleInput(sub, frame.patches, frame.client_msg_id);
+        return;
+      }
+      case "ping": {
+        // LSDP/1.1 §3.5 — echo nonce verbatim in pong (omit if absent).
+        sendFrame(sub, pong(frame.nonce));
+        return;
+      }
+      case "unsubscribe": {
+        // LSDP/1.1 §4.4 — clean teardown. Close WS within 1s, no error frame.
+        sub.ws.close(1000, "unsubscribe");
+        return;
+      }
+    }
+  }
+
+  async function handleSubscribe(
+    sub: Subscriber,
+    token: string,
+    sinceSequence?: number,
+  ): Promise<void> {
+    let decision: AuthDecision;
+    try {
+      decision = await authenticate(token);
+    } catch (err) {
+      const code: ErrorCode =
+        err instanceof LumencastError && isProtocolErrorCode(err.code) ? err.code : "AUTH_DENIED";
+      sendError(sub, code, err instanceof Error ? err.message : "auth error", false);
+      sub.ws.close(1008, code);
+      return;
+    }
+    sub.decision = decision;
+
+    // LSDP/1.1 §4.1, §18 — honour since_sequence when the replay buffer
+    // covers the gap. Otherwise fall back to a fresh snapshot at the
+    // current scene seq.
+    const curSeq = activeScene.currentSeq();
+    let useReplay = false;
+    if (sinceSequence !== undefined && sinceSequence > 0 && sinceSequence <= curSeq) {
+      const { records, covered } = activeScene.replaySince(sinceSequence);
+      if (covered) {
+        useReplay = true;
+        for (const r of records) {
+          sendFrame(sub, deltaFrame({ seq: r.seq, patches: r.patches, cause: r.cause }));
+        }
+      }
+    }
+    if (!useReplay) {
+      sendFrame(
+        sub,
+        snapshotFrame({
+          seq: curSeq,
+          scene_id: activeScene.sceneId,
+          scene_version: activeScene.sceneVersion,
+          state: activeScene.store.snapshot(),
+          ts: new Date().toISOString(),
+        }),
+      );
+    }
+
+    // Wire up delta forwarding from the *current* active scene. If the active
+    // scene swaps, this subscriber stays bound to the old one and is detached
+    // by setActiveScene(). Per-scene seq (§18.1.1) — the listener receives
+    // the seq directly from the scene.
+    sub.unsubscribePatches = activeScene.onPatches((seq, patches, cause) => {
+      sendFrame(sub, deltaFrame({ seq, patches, cause }));
+    });
+  }
+
+  async function handleInput(
+    sub: Subscriber,
+    patches: Patch[],
+    clientMsgId?: string,
+  ): Promise<void> {
+    if (!sub.decision) {
+      sendError(sub, "AUTH_DENIED", "input before subscribe", false);
+      return;
+    }
+    // 1. Role-based authorization (LSDP/1 §9).
+    for (const p of patches) {
+      if (!canWritePath(sub.decision, p.path)) {
+        sendError(
+          sub,
+          "WRITE_FORBIDDEN",
+          `role ${sub.decision.role} cannot write ${p.path}`,
+          true,
+          { path: p.path },
+        );
+        return;
+      }
+    }
+    // 2. Schema validation against operator_inputs (LSDP/1 §4.2 + LSML §8).
+    //    Atomic: reject the whole frame on the first violation, no patches applied.
+    const validationError = activeScene.validateInput(patches);
+    if (validationError) {
+      sendError(sub, validationError.code, validationError.message, true, {
+        path: validationError.path,
+      });
+      return;
+    }
+    // LSDP/1.1 §3.2.3 — derive provenance metadata for the resulting delta.
+    // The `source` is conventionally `<role>:<subject>` ; when client_msg_id
+    // is provided, echo it verbatim into `input_id` for optimistic-UI
+    // correlation (§4.2). Cause is omitted entirely if neither yields data,
+    // so 1.0 wire shape is preserved when no client opts into 1.1.
+    const subject = sub.decision.subject ?? sub.decision.role;
+    const cause: Cause | undefined = clientMsgId
+      ? { source: `${sub.decision.role}:${subject}`, input_id: clientMsgId }
+      : undefined;
+    activeScene.update(patches, cause);
+  }
+
+  function handleHttp(req: IncomingMessage, res: ServerResponse): void {
+    const url = req.url ?? "/";
+    res.setHeader("access-control-allow-origin", "*");
+    res.setHeader("access-control-allow-methods", "GET, OPTIONS");
+    res.setHeader("access-control-allow-headers", "*");
+    if (req.method === "OPTIONS") {
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
+
+    if (req.method === "GET" && url === `${wsPath}/health`) {
+      writeJson(res, 200, { status: "ok" });
+      return;
+    }
+
+    // GET /lsdp/v1/scenes/{id}/bundle?v=sha256:...
+    const escaped = bundlePathPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`^${escaped}/([^/?]+)/bundle(?:\\?v=([^&]+))?$`);
+    const match = url.match(re);
+    if (req.method === "GET" && match) {
+      const versionParam = match[2] ? decodeURIComponent(match[2]) : activeScene.sceneVersion;
+      Promise.resolve(bundleProvider(versionParam))
+        .then((bundle) => {
+          if (!bundle) {
+            writeJson(res, 404, { error: "bundle_not_found" });
+            return;
+          }
+          res.statusCode = 200;
+          res.setHeader("content-type", "application/json");
+          res.setHeader("cache-control", "public, max-age=31536000, immutable");
+          res.end(JSON.stringify(bundle));
+        })
+        .catch((err) => writeJson(res, 500, { error: String(err) }));
+      return;
+    }
+
+    writeJson(res, 404, { error: "not_found" });
+  }
+
+  function sendFrame(sub: Subscriber, frame: object): void {
+    if (sub.ws.readyState !== sub.ws.OPEN) return;
+    sub.ws.send(encodeFrame(frame as Parameters<typeof encodeFrame>[0]));
+  }
+
+  function sendError(
+    sub: Subscriber,
+    code: ErrorCode,
+    message: string,
+    recoverable: boolean,
+    extras?: { path?: string; retry_after_ms?: number },
+  ): void {
+    // Errors are connection-scoped, not scene-scoped events
+    // (LSDP/1.1 §18.1.1) — they ride the current scene seq without
+    // advancing it.
+    sendFrame(
+      sub,
+      errorFrame({
+        seq: activeScene.currentSeq(),
+        code,
+        message,
+        recoverable,
+        ...(extras?.path !== undefined ? { path: extras.path } : {}),
+        ...(extras?.retry_after_ms !== undefined ? { retry_after_ms: extras.retry_after_ms } : {}),
+      }),
+    );
+  }
+
+  function detachAllSubscribers(closeCode = 1012, reason = "service restart"): void {
+    for (const sub of subscribers) {
+      sub.unsubscribePatches?.();
+      try {
+        sub.ws.close(closeCode, reason);
+      } catch {
+        // ignore
+      }
+    }
+    subscribers.clear();
+  }
+
+  function setActiveScene(scene: Scene): void {
+    detachAllSubscribers();
+    activeScene = scene;
+  }
+
+  function setBundleProvider(fn: (version: SceneVersion) => Promise<unknown> | unknown): void {
+    bundleProvider = fn;
+  }
+
+  function reset(): void {
+    detachAllSubscribers();
+  }
+
+  async function close(): Promise<void> {
+    detachAllSubscribers(1000, "shutdown");
+    await new Promise<void>((resolve) => wss.close(() => resolve()));
+    await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+  }
+
+  return {
+    wsUrl: `ws://${host}:${port}${wsPath}`,
+    httpUrl: `http://${host}:${port}`,
+    setActiveScene,
+    setBundleProvider,
+    activeScene: () => activeScene,
+    reset,
+    close,
+  };
+}
+
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}

package/src/store.ts

@@ -0,0 +1,40 @@
+// LeafStore — a leaf-grain key/value map with an `onPatches` event.
+// Adapters write into the store; the Scene listens and rebroadcasts as deltas.
+
+import type { Cause, LeafPath, LeafValue, Patch } from "@lumencast/protocol";
+
+export type LeafStoreListener = (patches: Patch[], cause?: Cause) => void;
+
+export class LeafStore {
+  private state: Record<LeafPath, LeafValue> = {};
+  private listeners = new Set<LeafStoreListener>();
+
+  constructor(initial: Record<LeafPath, LeafValue> = {}) {
+    this.state = { ...initial };
+  }
+
+  /** Snapshot of the full state (shallow copy). */
+  snapshot(): Record<LeafPath, LeafValue> {
+    return { ...this.state };
+  }
+
+  /** Read a single leaf. */
+  get(path: LeafPath): LeafValue | undefined {
+    return this.state[path];
+  }
+
+  /** Apply patches and notify listeners. Returns the patches actually applied.
+   * Optional `cause` is forwarded to listeners so a downstream delta can carry
+   * provenance (LSDP/1.1 §3.2.3). */
+  apply(patches: Patch[], cause?: Cause): Patch[] {
+    if (patches.length === 0) return [];
+    for (const p of patches) this.state[p.path] = p.value;
+    for (const l of this.listeners) l(patches, cause);
+    return patches;
+  }
+
+  onPatches(listener: LeafStoreListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}

package/src/test-control.ts

@@ -0,0 +1,279 @@
+// LSDP/1 interop test control plane.
+//
+// HTTP API spec: lumencast-protocol/interop/CONTROL.md
+// Reference impl: lumencast-go/interop/control/control.go (mirrored here)
+//
+// This module is for test infrastructure only. NEVER mount on a public-facing
+// port. The serve-scenario CLI is the only sanctioned consumer.
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { canWritePath, type AuthDecision, type Role, type StaticTokens } from "./auth.js";
+import { createScene } from "./scene.js";
+import type { ServerHandle } from "./server.js";
+
+export interface TestControlOptions {
+  /** TCP port. 0 = random. */
+  port?: number;
+  host?: string;
+  /** The lumencast server the plane drives. */
+  server: ServerHandle;
+  /** The static-token authenticator the plane mutates on /test/setup. */
+  auth: StaticTokens;
+}
+
+export interface TestControlHandle {
+  readonly url: string;
+  close(): Promise<void>;
+}
+
+interface SetupRequest {
+  scenario?: string;
+  tokens?: Record<string, string>;
+  bundles: SetupBundle[];
+  initial_state?: Record<string, unknown>;
+}
+
+interface SetupBundle {
+  id: string;
+  hash?: string;
+  inline?: unknown;
+}
+
+interface EmitRequest {
+  patches: { path: string; value: unknown }[];
+}
+
+const SERVER_NAME = "lumencast-js";
+const CONTROL_PLANE_VERSION = 1;
+
+const ROUTES: Record<string, { method: string }> = {
+  "/test/setup": { method: "POST" },
+  "/test/reset": { method: "POST" },
+  "/test/state": { method: "GET" },
+  "/test/emit": { method: "POST" },
+  "/test/health": { method: "GET" },
+};
+
+export async function startTestControl(options: TestControlOptions): Promise<TestControlHandle> {
+  const host = options.host ?? "127.0.0.1";
+  const httpServer: Server = createServer((req, res) => handle(req, res));
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(options.port ?? 0, host, () => {
+      httpServer.off("error", reject);
+      resolve();
+    });
+  });
+
+  const address = httpServer.address();
+  if (!address || typeof address === "string") {
+    throw new Error("test-control: failed to bind HTTP");
+  }
+  const port = address.port;
+
+  function handle(req: IncomingMessage, res: ServerResponse): void {
+    const url = req.url ?? "/";
+    const method = req.method ?? "";
+    const route = ROUTES[url];
+    if (!route) {
+      writeProblem(res, 404, "not-found", `unknown path ${url}`);
+      return;
+    }
+    if (method !== route.method) {
+      writeProblem(res, 405, "method-not-allowed", `${method} not allowed on ${url}`);
+      return;
+    }
+    switch (url) {
+      case "/test/setup":
+        return void onSetup(req, res);
+      case "/test/reset":
+        return void onReset(req, res);
+      case "/test/state":
+        return void onState(req, res);
+      case "/test/emit":
+        return void onEmit(req, res);
+      case "/test/health":
+        return void onHealth(req, res);
+    }
+  }
+
+  async function onSetup(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    let body: SetupRequest;
+    try {
+      body = (await readJson(req)) as SetupRequest;
+    } catch (err) {
+      writeProblem(res, 400, "bad-body", `invalid JSON: ${(err as Error).message}`);
+      return;
+    }
+    if (!body || !Array.isArray(body.bundles) || body.bundles.length === 0) {
+      writeProblem(res, 400, "missing-bundle", "at least one bundle required");
+      return;
+    }
+
+    options.server.reset();
+    installTokens(options.auth, body.tokens ?? {});
+
+    const primary = body.bundles[0];
+    if (!primary || !primary.id) {
+      writeProblem(res, 400, "missing-bundle-id", "bundles[0].id required");
+      return;
+    }
+
+    const initialState = (body.initial_state ?? {}) as Record<string, never>;
+    // Prefer the inline LSML's `scene_id` over the bundle id (which is just
+    // the $BUNDLE.<id>.hash placeholder identifier). Fall back to the bundle id.
+    const inline =
+      primary.inline && typeof primary.inline === "object" && primary.inline !== null
+        ? (primary.inline as { scene_id?: unknown; operator_inputs?: unknown })
+        : undefined;
+    const inlineSceneId = inline?.scene_id;
+    const sceneId = typeof inlineSceneId === "string" ? inlineSceneId : primary.id;
+    const sceneVersion = primary.hash ?? "";
+    const operatorInputs = Array.isArray(inline?.operator_inputs)
+      ? (inline.operator_inputs as Parameters<typeof createScene>[0]["operatorInputs"])
+      : undefined;
+    const scene = createScene({
+      sceneId,
+      sceneVersion,
+      initialState,
+      ...(operatorInputs ? { operatorInputs } : {}),
+    });
+    options.server.setActiveScene(scene);
+
+    // The bundle provider serves the inline body of any registered bundle.
+    const bundleMap = new Map<string, unknown>();
+    for (const b of body.bundles) {
+      if (b.hash && b.inline !== undefined) bundleMap.set(b.hash, b.inline);
+    }
+    options.server.setBundleProvider((version) => bundleMap.get(version));
+
+    writeJson(res, 200, {
+      ws_url: options.server.wsUrl,
+      scene_id: sceneId,
+      scene_version: sceneVersion,
+    });
+  }
+
+  function onReset(_req: IncomingMessage, res: ServerResponse): void {
+    options.server.reset();
+    options.auth.reset();
+    res.statusCode = 204;
+    res.end();
+  }
+
+  function onState(_req: IncomingMessage, res: ServerResponse): void {
+    const scene = options.server.activeScene();
+    // The contract returns 409 if /test/setup wasn't called; we approximate
+    // that condition by checking whether the scene has been swapped from a
+    // synthetic initial scene. Since the kit always has an active scene, we
+    // expose whatever is current. Callers that need the 409 semantics call
+    // /test/reset first to drop everything.
+    writeJson(res, 200, {
+      scene_id: scene.sceneId,
+      scene_version: scene.sceneVersion,
+      state: scene.store.snapshot(),
+    });
+  }
+
+  async function onEmit(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    let body: EmitRequest;
+    try {
+      body = (await readJson(req)) as EmitRequest;
+    } catch (err) {
+      writeProblem(res, 400, "bad-body", `invalid JSON: ${(err as Error).message}`);
+      return;
+    }
+    if (!body || !Array.isArray(body.patches) || body.patches.length === 0) {
+      writeProblem(res, 400, "empty-patches", "at least one patch required");
+      return;
+    }
+    const scene = options.server.activeScene();
+    try {
+      scene.update(body.patches as Parameters<typeof scene.update>[0]);
+    } catch (err) {
+      writeProblem(res, 400, "invalid", (err as Error).message);
+      return;
+    }
+    res.statusCode = 204;
+    res.end();
+  }
+
+  function onHealth(_req: IncomingMessage, res: ServerResponse): void {
+    writeJson(res, 200, {
+      status: "ok",
+      control_plane_version: CONTROL_PLANE_VERSION,
+      server: SERVER_NAME,
+    });
+  }
+
+  async function close(): Promise<void> {
+    await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+  }
+
+  return {
+    url: `http://${host}:${port}`,
+    close,
+  };
+}
+
+/** Replace the StaticTokens contents with one entry per recognised
+ *  placeholder. $TOKEN_INVALID is intentionally NOT installed — the LSDP/1
+ *  conformance suite expects auth to reject it. */
+export function installTokens(auth: StaticTokens, tokens: Record<string, string>): void {
+  auth.reset();
+  for (const [placeholder, value] of Object.entries(tokens)) {
+    if (placeholder === "$TOKEN_INVALID" || !value) continue;
+    const role = placeholderRole(placeholder);
+    if (!role) continue;
+    auth.set(value, { role, subject: placeholder });
+  }
+  // canWritePath is referenced indirectly via the role we install — keep the
+  // import alive so the bundler doesn't drop it.
+  void canWritePath;
+}
+
+function placeholderRole(placeholder: string): Role | null {
+  switch (placeholder) {
+    case "$TOKEN_OPERATOR":
+      return "operator";
+    case "$TOKEN_VIEWER":
+      return "viewer";
+    case "$TOKEN_SERVICE":
+      return "service";
+    case "$TOKEN_TEST":
+      return "test";
+    default:
+      return null;
+  }
+}
+
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+
+function writeProblem(res: ServerResponse, status: number, code: string, detail: string): void {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/problem+json");
+  res.end(
+    JSON.stringify({
+      type: "about:blank",
+      title: `control: ${code}`,
+      status,
+      detail,
+    }),
+  );
+}
+
+async function readJson(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  const body = Buffer.concat(chunks).toString("utf8");
+  if (body.length === 0) return {};
+  return JSON.parse(body);
+}
+
+// AuthDecision is referenced for type clarity; keep it exported via the helper.
+export type { AuthDecision };