@checkstack/signal-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# @checkstack/signal-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- b55fae6: Added realtime Signal Service for backend-to-frontend push notifications via WebSockets.
+
+  ## New Packages
+
+  - **@checkstack/signal-common**: Shared types including `Signal`, `SignalService`, `createSignal()`, and WebSocket protocol messages
+  - **@checkstack/signal-backend**: `SignalServiceImpl` with EventBus integration and Bun WebSocket handler using native pub/sub
+  - **@checkstack/signal-frontend**: React `SignalProvider` and `useSignal()` hook for consuming typed signals
+
+  ## Changes
+
+  - **@checkstack/backend-api**: Added `coreServices.signalService` reference for plugins to emit signals
+  - **@checkstack/backend**: Integrated WebSocket server at `/api/signals/ws` with session-based authentication
+
+  ## Usage
+
+  Backend plugins can emit signals:
+
+  ```typescript
+  import { coreServices } from "@checkstack/backend-api";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  const signalService = context.signalService;
+  await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { ... });
+  ```
+
+  Frontend components subscribe to signals:
+
+  ```tsx
+  import { useSignal } from "@checkstack/signal-frontend";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  useSignal(NOTIFICATION_RECEIVED, (payload) => {
+    // Handle realtime notification
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/signal-common@0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@checkstack/signal-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "@checkstack/backend-api": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.2",
+    "zod": "^4.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,19 @@
+import { createHook } from "@checkstack/backend-api";
+import type { SignalMessage } from "@checkstack/signal-common";
+
+/**
+ * Internal hook for broadcasting signals across backend instances.
+ * All instances subscribe in broadcast mode to push to their local WebSocket clients.
+ */
+export const SIGNAL_BROADCAST_HOOK = createHook<SignalMessage>(
+  "signal.internal.broadcast"
+);
+
+/**
+ * Internal hook for user-specific signals across backend instances.
+ * All instances subscribe in broadcast mode to push to the user's WebSocket connections.
+ */
+export const SIGNAL_USER_HOOK = createHook<{
+  userId: string;
+  message: SignalMessage;
+}>("signal.internal.user");

package/src/index.ts

@@ -0,0 +1,13 @@
+// Implementation
+export { SignalServiceImpl } from "./signal-service-impl";
+
+// WebSocket handler for Bun.serve()
+export {
+  createWebSocketHandler,
+  type WebSocketHandler,
+  type WebSocketHandlerConfig,
+  type WebSocketData,
+} from "./websocket-handler";
+
+// Internal hooks (for registering SignalService in the backend)
+export { SIGNAL_BROADCAST_HOOK, SIGNAL_USER_HOOK } from "./hooks";

package/src/signal-service-impl.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, mock } from "bun:test";
+import { SignalServiceImpl } from "../src/signal-service-impl";
+import { SIGNAL_BROADCAST_HOOK, SIGNAL_USER_HOOK } from "../src/hooks";
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+import type { EventBus, Logger } from "@checkstack/backend-api";
+
+// Test signals
+const TEST_BROADCAST_SIGNAL = createSignal(
+  "test.broadcast",
+  z.object({ message: z.string() })
+);
+
+const TEST_USER_SIGNAL = createSignal(
+  "test.user",
+  z.object({ notification: z.string(), count: z.number() })
+);
+
+describe("SignalServiceImpl", () => {
+  let signalService: SignalServiceImpl;
+  let mockEventBus: EventBus;
+  let mockLogger: Logger;
+  let emittedEvents: Array<{ hook: unknown; payload: unknown }>;
+
+  beforeEach(() => {
+    emittedEvents = [];
+
+    mockEventBus = {
+      emit: mock(async (hook, payload) => {
+        emittedEvents.push({ hook, payload });
+      }),
+      subscribe: mock(async () => {}),
+      shutdown: mock(async () => {}),
+    } as unknown as EventBus;
+
+    mockLogger = {
+      debug: mock(() => {}),
+      info: mock(() => {}),
+      warn: mock(() => {}),
+      error: mock(() => {}),
+      child: mock(() => mockLogger),
+    } as unknown as Logger;
+
+    signalService = new SignalServiceImpl(mockEventBus, mockLogger);
+  });
+
+  describe("broadcast", () => {
+    it("should emit broadcast signal to EventBus", async () => {
+      const payload = { message: "Hello, World!" };
+
+      await signalService.broadcast(TEST_BROADCAST_SIGNAL, payload);
+
+      expect(emittedEvents).toHaveLength(1);
+      expect(emittedEvents[0].hook).toBe(SIGNAL_BROADCAST_HOOK);
+
+      const message = emittedEvents[0].payload as {
+        signalId: string;
+        payload: typeof payload;
+        timestamp: string;
+      };
+      expect(message.signalId).toBe("test.broadcast");
+      expect(message.payload).toEqual(payload);
+      expect(typeof message.timestamp).toBe("string");
+    });
+
+    it("should log debug message when broadcasting", async () => {
+      await signalService.broadcast(TEST_BROADCAST_SIGNAL, {
+        message: "Test",
+      });
+
+      expect(mockLogger.debug).toHaveBeenCalled();
+    });
+
+    it("should include ISO timestamp in signal message", async () => {
+      const beforeTime = new Date().toISOString();
+      await signalService.broadcast(TEST_BROADCAST_SIGNAL, {
+        message: "Test",
+      });
+      const afterTime = new Date().toISOString();
+
+      const message = emittedEvents[0].payload as { timestamp: string };
+      expect(message.timestamp >= beforeTime).toBe(true);
+      expect(message.timestamp <= afterTime).toBe(true);
+    });
+  });
+
+  describe("sendToUser", () => {
+    it("should emit user signal to EventBus with userId", async () => {
+      const userId = "user-123";
+      const payload = { notification: "New message", count: 5 };
+
+      await signalService.sendToUser(TEST_USER_SIGNAL, userId, payload);
+
+      expect(emittedEvents).toHaveLength(1);
+      expect(emittedEvents[0].hook).toBe(SIGNAL_USER_HOOK);
+
+      const emitted = emittedEvents[0].payload as {
+        userId: string;
+        message: { signalId: string; payload: typeof payload };
+      };
+      expect(emitted.userId).toBe(userId);
+      expect(emitted.message.signalId).toBe("test.user");
+      expect(emitted.message.payload).toEqual(payload);
+    });
+
+    it("should log debug message with user and signal info", async () => {
+      await signalService.sendToUser(TEST_USER_SIGNAL, "user-456", {
+        notification: "Alert",
+        count: 1,
+      });
+
+      expect(mockLogger.debug).toHaveBeenCalled();
+    });
+  });
+
+  describe("sendToUsers", () => {
+    it("should emit signal to multiple users", async () => {
+      const userIds = ["user-1", "user-2", "user-3"];
+      const payload = { notification: "Broadcast to users", count: 10 };
+
+      await signalService.sendToUsers(TEST_USER_SIGNAL, userIds, payload);
+
+      // Should emit one event per user
+      expect(emittedEvents).toHaveLength(3);
+
+      for (const [index, event] of emittedEvents.entries()) {
+        expect(event.hook).toBe(SIGNAL_USER_HOOK);
+        const emitted = event.payload as { userId: string };
+        expect(emitted.userId).toBe(userIds[index]);
+      }
+    });
+
+    it("should handle empty user array", async () => {
+      await signalService.sendToUsers(TEST_USER_SIGNAL, [], {
+        notification: "Empty",
+        count: 0,
+      });
+
+      expect(emittedEvents).toHaveLength(0);
+    });
+
+    it("should handle single user in array", async () => {
+      await signalService.sendToUsers(TEST_USER_SIGNAL, ["single-user"], {
+        notification: "Single",
+        count: 1,
+      });
+
+      expect(emittedEvents).toHaveLength(1);
+    });
+  });
+});
+
+describe("Signal Hooks", () => {
+  it("should have correct hook IDs", () => {
+    expect(SIGNAL_BROADCAST_HOOK.id).toBe("signal.internal.broadcast");
+    expect(SIGNAL_USER_HOOK.id).toBe("signal.internal.user");
+  });
+
+  it("should have consistent hook structure", () => {
+    expect(SIGNAL_BROADCAST_HOOK).toHaveProperty("id");
+    expect(SIGNAL_USER_HOOK).toHaveProperty("id");
+  });
+});

package/src/signal-service-impl.ts

@@ -0,0 +1,117 @@
+import type { EventBus, Logger } from "@checkstack/backend-api";
+import { qualifyPermissionId } from "@checkstack/common";
+import type {
+  Signal,
+  SignalMessage,
+  SignalService,
+} from "@checkstack/signal-common";
+import { SIGNAL_BROADCAST_HOOK, SIGNAL_USER_HOOK } from "./hooks";
+
+/**
+ * Interface for the auth client methods needed by SignalService.
+ * This is a subset of the AuthApi client to avoid circular dependencies.
+ */
+interface AuthClientForSignals {
+  filterUsersByPermission: (input: {
+    userIds: string[];
+    permission: string;
+  }) => Promise<string[]>;
+}
+
+/**
+ * SignalService implementation that uses EventBus for multi-instance coordination.
+ *
+ * When a signal is emitted, it goes through the EventBus (backed by the queue system),
+ * ensuring all backend instances receive it and can push to their local WebSocket clients.
+ */
+export class SignalServiceImpl implements SignalService {
+  private authClient?: AuthClientForSignals;
+
+  constructor(private eventBus: EventBus, private logger: Logger) {}
+
+  /**
+   * Set the auth client for permission-based signal filtering.
+   * This should be called after plugins have loaded.
+   */
+  setAuthClient(client: AuthClientForSignals): void {
+    this.authClient = client;
+  }
+
+  async broadcast<T>(signal: Signal<T>, payload: T): Promise<void> {
+    const message: SignalMessage<T> = {
+      signalId: signal.id,
+      payload,
+      timestamp: new Date().toISOString(),
+    };
+
+    this.logger.debug(`Broadcasting signal: ${signal.id}`);
+
+    // Emit to EventBus - all backend instances receive and push to their WebSocket clients
+    await this.eventBus.emit(SIGNAL_BROADCAST_HOOK, message);
+  }
+
+  async sendToUser<T>(
+    signal: Signal<T>,
+    userId: string,
+    payload: T
+  ): Promise<void> {
+    const message: SignalMessage<T> = {
+      signalId: signal.id,
+      payload,
+      timestamp: new Date().toISOString(),
+    };
+
+    this.logger.debug(`Sending signal ${signal.id} to user ${userId}`);
+
+    await this.eventBus.emit(SIGNAL_USER_HOOK, { userId, message });
+  }
+
+  async sendToUsers<T>(
+    signal: Signal<T>,
+    userIds: string[],
+    payload: T
+  ): Promise<void> {
+    await Promise.all(
+      userIds.map((userId) => this.sendToUser(signal, userId, payload))
+    );
+  }
+
+  async sendToAuthorizedUsers<T>(
+    signal: Signal<T>,
+    userIds: string[],
+    payload: T,
+    pluginMetadata: { pluginId: string },
+    permission: { id: string }
+  ): Promise<void> {
+    if (userIds.length === 0) return;
+
+    if (!this.authClient) {
+      this.logger.warn(
+        `sendToAuthorizedUsers called but auth client not set. Skipping signal ${signal.id}`
+      );
+      return;
+    }
+
+    // Construct fully-qualified permission ID: ${pluginMetadata.pluginId}.${permission.id}
+    const qualifiedPermission = qualifyPermissionId(pluginMetadata, permission);
+
+    // Filter users via auth RPC
+    const authorizedIds = await this.authClient.filterUsersByPermission({
+      userIds,
+      permission: qualifiedPermission,
+    });
+
+    if (authorizedIds.length === 0) {
+      this.logger.debug(
+        `No users authorized for signal ${signal.id} with permission ${qualifiedPermission}`
+      );
+      return;
+    }
+
+    this.logger.debug(
+      `Sending signal ${signal.id} to ${authorizedIds.length}/${userIds.length} authorized users`
+    );
+
+    await this.sendToUsers(signal, authorizedIds, payload);
+  }
+}

package/src/websocket-handler.test.ts

@@ -0,0 +1,352 @@
+import { describe, it, expect, beforeEach, mock } from "bun:test";
+import {
+  createWebSocketHandler,
+  type WebSocketData,
+} from "../src/websocket-handler";
+import { SIGNAL_BROADCAST_HOOK, SIGNAL_USER_HOOK } from "../src/hooks";
+import type { EventBus, Logger } from "@checkstack/backend-api";
+import type { Server, ServerWebSocket } from "bun";
+
+describe("createWebSocketHandler", () => {
+  let mockEventBus: EventBus;
+  let mockLogger: Logger;
+  let subscriptions: Array<{
+    group: string;
+    hook: unknown;
+    handler: (payload: unknown) => Promise<void>;
+    mode: string;
+  }>;
+
+  beforeEach(() => {
+    subscriptions = [];
+
+    mockEventBus = {
+      emit: mock(async () => {}),
+      subscribe: mock(async (group, hook, handler, options) => {
+        subscriptions.push({ group, hook, handler, mode: options?.mode || "" });
+      }),
+      shutdown: mock(async () => {}),
+    } as unknown as EventBus;
+
+    mockLogger = {
+      debug: mock(() => {}),
+      info: mock(() => {}),
+      warn: mock(() => {}),
+      error: mock(() => {}),
+      child: mock(() => mockLogger),
+    } as unknown as Logger;
+  });
+
+  describe("initialization", () => {
+    it("should create handler with websocket configuration", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      expect(handler).toHaveProperty("setServer");
+      expect(handler).toHaveProperty("websocket");
+      expect(handler.websocket).toHaveProperty("open");
+      expect(handler.websocket).toHaveProperty("message");
+      expect(handler.websocket).toHaveProperty("close");
+    });
+
+    it("should subscribe to EventBus hooks when server is set", async () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      const mockServer = {
+        publish: mock(() => {}),
+      } as unknown as Server<WebSocketData>;
+
+      handler.setServer(mockServer);
+
+      // Wait for async subscription setup
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(subscriptions).toHaveLength(2);
+      expect(subscriptions[0].hook).toBe(SIGNAL_BROADCAST_HOOK);
+      expect(subscriptions[1].hook).toBe(SIGNAL_USER_HOOK);
+    });
+
+    it("should subscribe with broadcast mode", async () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      const mockServer = {
+        publish: mock(() => {}),
+      } as unknown as Server<WebSocketData>;
+
+      handler.setServer(mockServer);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(subscriptions[0].mode).toBe("broadcast");
+      expect(subscriptions[1].mode).toBe("broadcast");
+    });
+  });
+
+  describe("websocket.open", () => {
+    it("should subscribe authenticated user to broadcast and user channels", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      const subscribedChannels: string[] = [];
+      const mockWs = {
+        data: { userId: "user-123", createdAt: Date.now() },
+        subscribe: mock((channel: string) => subscribedChannels.push(channel)),
+        send: mock(() => {}),
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      handler.websocket.open(mockWs);
+
+      expect(subscribedChannels).toContain("signals:broadcast");
+      expect(subscribedChannels).toContain("signals:user:user-123");
+    });
+
+    it("should subscribe anonymous user to broadcast channel only", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      const subscribedChannels: string[] = [];
+      const mockWs = {
+        data: { userId: undefined, createdAt: Date.now() },
+        subscribe: mock((channel: string) => subscribedChannels.push(channel)),
+        send: mock(() => {}),
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      handler.websocket.open(mockWs);
+
+      expect(subscribedChannels).toContain("signals:broadcast");
+      expect(subscribedChannels).not.toContain("signals:user:undefined");
+      expect(subscribedChannels).toHaveLength(1);
+    });
+
+    it("should send connected message with userId", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      let sentMessage: string | undefined;
+      const mockWs = {
+        data: { userId: "user-456", createdAt: Date.now() },
+        subscribe: mock(() => {}),
+        send: mock((msg: string) => {
+          sentMessage = msg;
+        }),
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      handler.websocket.open(mockWs);
+
+      expect(sentMessage).toBeDefined();
+      const parsed = JSON.parse(sentMessage!);
+      expect(parsed.type).toBe("connected");
+      expect(parsed.userId).toBe("user-456");
+    });
+
+    it("should send 'anonymous' userId for unauthenticated connections", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      let sentMessage: string | undefined;
+      const mockWs = {
+        data: { userId: undefined, createdAt: Date.now() },
+        subscribe: mock(() => {}),
+        send: mock((msg: string) => {
+          sentMessage = msg;
+        }),
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      handler.websocket.open(mockWs);
+
+      const parsed = JSON.parse(sentMessage!);
+      expect(parsed.type).toBe("connected");
+      expect(parsed.userId).toBe("anonymous");
+    });
+  });
+
+  describe("websocket.message", () => {
+    it("should respond to ping with pong", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      let sentMessage: string | undefined;
+      const mockWs = {
+        data: { userId: "user-123", createdAt: Date.now() },
+        send: mock((msg: string) => {
+          sentMessage = msg;
+        }),
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      handler.websocket.message(mockWs, JSON.stringify({ type: "ping" }));
+
+      expect(sentMessage).toBeDefined();
+      const parsed = JSON.parse(sentMessage!);
+      expect(parsed.type).toBe("pong");
+    });
+
+    it("should handle invalid JSON gracefully", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      const mockWs = {
+        data: { userId: "user-123", createdAt: Date.now() },
+        send: mock(() => {}),
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      // Should not throw
+      expect(() => {
+        handler.websocket.message(mockWs, "invalid json {{{");
+      }).not.toThrow();
+
+      expect(mockLogger.warn).toHaveBeenCalled();
+    });
+
+    it("should ignore unknown message types", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      let sentMessage: string | undefined;
+      const mockWs = {
+        data: { userId: "user-123", createdAt: Date.now() },
+        send: mock((msg: string) => {
+          sentMessage = msg;
+        }),
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      handler.websocket.message(mockWs, JSON.stringify({ type: "unknown" }));
+
+      // Should not send any response for unknown types
+      expect(sentMessage).toBeUndefined();
+    });
+  });
+
+  describe("websocket.close", () => {
+    it("should log close event with user info", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      const mockWs = {
+        data: { userId: "user-789", createdAt: Date.now() },
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      handler.websocket.close(mockWs, 1000, "Normal closure");
+
+      expect(mockLogger.debug).toHaveBeenCalled();
+    });
+
+    it("should handle anonymous user close", () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      const mockWs = {
+        data: { userId: undefined, createdAt: Date.now() },
+      } as unknown as ServerWebSocket<WebSocketData>;
+
+      expect(() => {
+        handler.websocket.close(mockWs, 1001, "Going away");
+      }).not.toThrow();
+    });
+  });
+
+  describe("signal relay", () => {
+    it("should publish broadcast signals to broadcast channel", async () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      let publishedChannel: string | undefined;
+      let publishedMessage: string | undefined;
+      const mockServer = {
+        publish: mock((channel: string, message: string) => {
+          publishedChannel = channel;
+          publishedMessage = message;
+        }),
+      } as unknown as Server<WebSocketData>;
+
+      handler.setServer(mockServer);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Find the broadcast handler and call it
+      const broadcastSubscription = subscriptions.find(
+        (s) => s.hook === SIGNAL_BROADCAST_HOOK
+      );
+      expect(broadcastSubscription).toBeDefined();
+
+      await broadcastSubscription!.handler({
+        signalId: "test.signal",
+        payload: { data: "test" },
+        timestamp: new Date().toISOString(),
+      });
+
+      expect(publishedChannel).toBe("signals:broadcast");
+      expect(publishedMessage).toBeDefined();
+
+      const parsed = JSON.parse(publishedMessage!);
+      expect(parsed.type).toBe("signal");
+      expect(parsed.signalId).toBe("test.signal");
+    });
+
+    it("should publish user signals to user-specific channel", async () => {
+      const handler = createWebSocketHandler({
+        eventBus: mockEventBus,
+        logger: mockLogger,
+      });
+
+      let publishedChannel: string | undefined;
+      let publishedMessage: string | undefined;
+      const mockServer = {
+        publish: mock((channel: string, message: string) => {
+          publishedChannel = channel;
+          publishedMessage = message;
+        }),
+      } as unknown as Server<WebSocketData>;
+
+      handler.setServer(mockServer);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Find the user handler and call it
+      const userSubscription = subscriptions.find(
+        (s) => s.hook === SIGNAL_USER_HOOK
+      );
+      expect(userSubscription).toBeDefined();
+
+      await userSubscription!.handler({
+        userId: "target-user",
+        message: {
+          signalId: "notification.received",
+          payload: { id: "n-1" },
+          timestamp: new Date().toISOString(),
+        },
+      });
+
+      expect(publishedChannel).toBe("signals:user:target-user");
+      expect(publishedMessage).toBeDefined();
+
+      const parsed = JSON.parse(publishedMessage!);
+      expect(parsed.type).toBe("signal");
+      expect(parsed.signalId).toBe("notification.received");
+    });
+  });
+});

package/src/websocket-handler.ts

@@ -0,0 +1,172 @@
+import type { Server, ServerWebSocket } from "bun";
+import type { EventBus, Logger } from "@checkstack/backend-api";
+import type { ServerToClientMessage } from "@checkstack/signal-common";
+import { SIGNAL_BROADCAST_HOOK, SIGNAL_USER_HOOK } from "./hooks";
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * WebSocket connection data attached on upgrade.
+ * userId is optional - anonymous users can connect for broadcast signals.
+ */
+export interface WebSocketData {
+  userId?: string;
+  createdAt: number;
+}
+
+/**
+ * Channel names for Bun's native pub/sub.
+ */
+const CHANNELS = {
+  BROADCAST: "signals:broadcast",
+  user: (userId: string) => `signals:user:${userId}`,
+};
+
+// =============================================================================
+// WEBSOCKET HANDLER
+// =============================================================================
+
+export interface WebSocketHandlerConfig {
+  eventBus: EventBus;
+  logger: Logger;
+}
+
+export interface WebSocketHandler {
+  /**
+   * Set the Bun server reference after `Bun.serve()` returns.
+   * This enables publishing to channels from EventBus subscribers.
+   */
+  setServer(server: Server<WebSocketData>): void;
+
+  /**
+   * WebSocket configuration object to pass to Bun.serve().
+   */
+  websocket: {
+    data: WebSocketData;
+    open(ws: ServerWebSocket<WebSocketData>): void | Promise<void>;
+    message(
+      ws: ServerWebSocket<WebSocketData>,
+      message: string | Buffer
+    ): void | Promise<void>;
+    close(
+      ws: ServerWebSocket<WebSocketData>,
+      code: number,
+      reason: string
+    ): void | Promise<void>;
+  };
+}
+
+/**
+ * Create a WebSocket handler for Bun's native WebSocket server.
+ *
+ * Uses Bun's built-in pub/sub for efficient channel-based routing:
+ * - `signals:broadcast` - all clients subscribe (including anonymous)
+ * - `signals:user:{userId}` - user-specific messages (authenticated only)
+ */
+export function createWebSocketHandler(
+  config: WebSocketHandlerConfig
+): WebSocketHandler {
+  const { eventBus, logger } = config;
+  let server: Server<WebSocketData> | undefined;
+  let eventBusInitialized = false;
+
+  const setupEventBusListeners = async () => {
+    if (eventBusInitialized || !server) return;
+    eventBusInitialized = true;
+
+    logger.debug("Setting up EventBus listeners for signal relay");
+
+    // Subscribe to broadcast signals from EventBus
+    await eventBus.subscribe(
+      "signal-backend",
+      SIGNAL_BROADCAST_HOOK,
+      async (message) => {
+        const payload: ServerToClientMessage = {
+          type: "signal",
+          signalId: message.signalId,
+          payload: message.payload,
+          timestamp: message.timestamp,
+        };
+        server!.publish(CHANNELS.BROADCAST, JSON.stringify(payload));
+        logger.debug(`Relayed broadcast signal: ${message.signalId}`);
+      },
+      { mode: "broadcast" }
+    );
+
+    // Subscribe to user-specific signals from EventBus
+    await eventBus.subscribe(
+      "signal-backend",
+      SIGNAL_USER_HOOK,
+      async ({ userId, message }) => {
+        const payload: ServerToClientMessage = {
+          type: "signal",
+          signalId: message.signalId,
+          payload: message.payload,
+          timestamp: message.timestamp,
+        };
+        server!.publish(CHANNELS.user(userId), JSON.stringify(payload));
+        logger.debug(`Relayed signal ${message.signalId} to user ${userId}`);
+      },
+      { mode: "broadcast" }
+    );
+
+    logger.info("✅ Signal WebSocket relay initialized");
+  };
+
+  return {
+    setServer: (s: Server<WebSocketData>) => {
+      server = s;
+      void setupEventBusListeners();
+    },
+
+    websocket: {
+      // Type template for ws.data (used by TypeScript)
+      data: {} as WebSocketData,
+
+      open(ws: ServerWebSocket<WebSocketData>) {
+        const { userId } = ws.data;
+        logger.debug(
+          `WebSocket opened${userId ? ` for user ${userId}` : " (anonymous)"}`
+        );
+
+        // All clients subscribe to broadcast channel
+        ws.subscribe(CHANNELS.BROADCAST);
+
+        // Only authenticated users subscribe to their private channel
+        if (userId) {
+          ws.subscribe(CHANNELS.user(userId));
+        }
+
+        // Send connected confirmation
+        const msg: ServerToClientMessage = {
+          type: "connected",
+          userId: userId ?? "anonymous",
+        };
+        ws.send(JSON.stringify(msg));
+      },
+
+      message(ws: ServerWebSocket<WebSocketData>, message: string | Buffer) {
+        try {
+          const data = JSON.parse(message.toString());
+          if (data.type === "ping") {
+            const pong: ServerToClientMessage = { type: "pong" };
+            ws.send(JSON.stringify(pong));
+          }
+        } catch (error) {
+          logger.warn("Invalid WebSocket message received", { error });
+        }
+      },
+
+      close(ws: ServerWebSocket<WebSocketData>, code: number, reason: string) {
+        const { userId } = ws.data;
+        logger.debug(
+          `WebSocket closed${userId ? ` for user ${userId}` : " (anonymous)"}`,
+          { code, reason }
+        );
+        // Bun automatically unsubscribes from all channels on close
+      },
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}