bhooai-nexus 0.1.2

package/packages/nexus-plugins/src/sandbox/SandboxedPlugin.ts

@@ -0,0 +1,279 @@
+import { Worker } from 'node:worker_threads';
+import type { PluginManifest, SandboxLimits } from '../manifest.js';
+import type { PluginHandle, HostBindings } from '../host.js';
+import { authorize } from './capabilityPolicy.js';
+
+/**
+ * Sandboxed plugin: the entry runs inside a worker_thread with heap + event-loop
+ * isolation. A crash in the worker cannot take the host down. The host owns the
+ * real registrars (HostBindings); the worker calls them over a request/response
+ * RPC, and the host authorizes every call via the capability policy before
+ * forwarding. Route handlers registered by the worker run *inside* the worker —
+ * the host proxies inbound requests to the worker over `invokeRoute` and awaits
+ * the response. If the worker dies mid-request, the host returns a 503 and
+ * (optionally) restarts it.
+ */
+export class SandboxedPlugin implements PluginHandle {
+  readonly manifest: PluginManifest;
+  state: PluginHandle['state'] = 'loaded';
+  private readonly bindings: HostBindings;
+  private readonly pluginDir: string;
+  private readonly limits: SandboxLimits;
+  private readonly caps: Set<string>;
+  private worker: Worker | null = null;
+  private ready = false;
+  private readonly rpcReplies = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  private readonly routeHandlers = new Map<string, (ctx: any) => void | Promise<void>>();
+  private readonly pendingRoutes = new Map<string, { resolve: (r: { status: number; body: unknown; headers: Record<string, string> }) => void }>();
+  private heartbeatTimer: NodeJS.Timeout | null = null;
+  private lastHeartbeat = 0;
+  private lifecycleWaiters = new Map<string, { resolve: () => void; reject: (e: Error) => void }>();
+  private restartCount = 0;
+
+  constructor(manifest: PluginManifest, pluginDir: string, bindings: HostBindings, config: unknown, limits: SandboxLimits = {}) {
+    this.manifest = manifest;
+    this.bindings = bindings;
+    this.pluginDir = pluginDir;
+    this.limits = limits;
+    this.caps = new Set(manifest.capabilities as string[]);
+    this.config = config;
+  }
+
+  private config: unknown;
+
+  private bootstrapUrl(): URL {
+    return new URL('./workerBootstrap.mjs', import.meta.url);
+  }
+
+  private spawnWorker(): void {
+    const entryPath = `${this.pluginDir}/${this.manifest.entry}`;
+    const worker = new Worker(this.bootstrapUrl(), {
+      workerData: {
+        entryPath,
+        manifest: this.manifest,
+        config: this.config,
+        limits: this.limits,
+      },
+      resourceLimits: this.limits.resourceLimits ?? { maxOldGenerationSizeMb: 64, maxYoungGenerationSizeMb: 16 },
+    });
+    this.worker = worker;
+    this.lastHeartbeat = Date.now();
+
+    worker.on('message', (msg) => this.onWorkerMessage(msg));
+    worker.on('error', (err) => {
+      this.bindings.logger.child({ plugin: this.manifest.name }).error('worker error', { error: String(err.message) });
+      this.handleWorkerDeath(err);
+    });
+    worker.on('exit', (code) => {
+      if (code !== 0 && this.state !== 'stopped' && this.state !== 'errored') {
+        this.handleWorkerDeath(new Error(`worker exited with code ${code}`));
+      }
+    });
+  }
+
+  private handleWorkerDeath(err: Error): void {
+    this.ready = false;
+    // Reject any in-flight RPC requests.
+    for (const [, p] of this.rpcReplies) p.reject(err);
+    this.rpcReplies.clear();
+    for (const [, p] of this.pendingRoutes) p.resolve({ status: 503, body: { error: 'plugin worker unavailable' }, headers: {} });
+    this.pendingRoutes.clear();
+    for (const [, p] of this.lifecycleWaiters) p.reject(err);
+    this.lifecycleWaiters.clear();
+    if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = null; }
+    this.state = 'errored';
+  }
+
+  private onWorkerMessage(msg: any): void {
+    switch (msg.kind) {
+      case 'ready':
+        this.ready = true;
+        this.startHeartbeatWatchdog();
+        break;
+      case 'heartbeat':
+        this.lastHeartbeat = Date.now();
+        break;
+      case 'log':
+        {
+          const logger = this.bindings.logger.child({ plugin: this.manifest.name });
+          const level = msg.level as keyof typeof logger;
+          logger[level]?.(msg.msg, msg.meta);
+        }
+        break;
+      case 'rpc': {
+        this.handleRpc(msg.id, msg.method, msg.args);
+        break;
+      }
+      case 'routeResponse': {
+        const p = this.pendingRoutes.get(msg.routeId);
+        if (p) { this.pendingRoutes.delete(msg.routeId); p.resolve({ status: msg.status, body: msg.body, headers: msg.headers }); }
+        break;
+      }
+      case 'lifecycleDone': {
+        const w = this.lifecycleWaiters.get(msg.hook);
+        if (w) {
+          this.lifecycleWaiters.delete(msg.hook);
+          if (msg.ok) w.resolve();
+          else w.reject(new Error(msg.error));
+        }
+        break;
+      }
+      case 'fatal':
+        this.handleWorkerDeath(new Error(msg.error));
+        break;
+    }
+  }
+
+  private async handleRpc(id: number, method: string, args: Record<string, unknown>): Promise<void> {
+    // Authorize first.
+    const decision = authorize(method, args, this.caps as Set<any>, this.limits.fsAllowPaths, this.limits.netAllowHosts);
+    if (!decision.allowed) {
+      this.worker?.postMessage({ kind: 'rpcResult', id, ok: false, error: decision.reason ?? 'denied' });
+      return;
+    }
+    try {
+      const result = await this.dispatch(method, args);
+      this.worker?.postMessage({ kind: 'rpcResult', id, ok: true, result });
+    } catch (err: any) {
+      this.worker?.postMessage({ kind: 'rpcResult', id, ok: false, error: String(err?.message ?? err) });
+    }
+  }
+
+  private async dispatch(method: string, args: Record<string, unknown>): Promise<unknown> {
+    switch (method) {
+      case 'http.addRoute': {
+        const { method: m, path, routeId } = args as { method: string; path: string; routeId: string };
+        const self = this;
+        const handler = (ctx: any): void => self.invokeRoute(routeId, ctx);
+        this.routeHandlers.set(routeId, handler);
+        this.bindings.http.addRoute(m as any, path, handler);
+        return undefined;
+      }
+      case 'http.addMiddleware':
+        // Sandbox cannot serialize middleware functions; documented v1 no-op.
+        this.bindings.logger.child({ plugin: this.manifest.name }).warn('sandboxed middleware not applied (v1 limitation)');
+        return undefined;
+      case 'data.registerModel': return this.bindings.data.registerModel(args.name as string, args.schema);
+      case 'data.getModel': return this.bindings.data.getModel(args.name as string);
+      case 'realtime.join': this.bindings.realtime.join(args.room as string, args.connId as string); return undefined;
+      case 'realtime.broadcast': this.bindings.realtime.broadcast(args.room as string, args.msg); return undefined;
+      case 'scheduler.schedule': {
+        const self = this;
+        this.bindings.scheduler.schedule(args.name as string, args.cron as string, () => self.worker?.postMessage({ kind: 'runSchedule', name: args.name as string }));
+        return undefined;
+      }
+      case 'scheduler.cancel': this.bindings.scheduler.cancel(args.name as string); return undefined;
+      case 'events.publish': this.bindings.events.publish(args.topic as string, args.payload); return undefined;
+      case 'events.subscribe': {
+        const self = this;
+        this.bindings.events.subscribe(args.topic as string, (payload) => self.worker?.postMessage({ kind: 'event', topic: args.topic, payload }));
+        return undefined;
+      }
+      case 'events.unsubscribe':
+        // Best-effort: we don't track the unsubscribe fn here in v1.
+        return undefined;
+      case 'admin.registerAdminPage': this.bindings.admin.registerAdminPage(args.page as any); return undefined;
+      case 'admin.registerSlot': this.bindings.admin.registerSlot(args.slot as any); return undefined;
+      case 'services.register': this.bindings.services.register(args.name as string, args.svc); return undefined;
+      case 'services.get': return this.bindings.services.get(args.name as string);
+      case 'fs.readFile': {
+        const f = await import('node:fs/promises');
+        return f.readFile(args.path as string);
+      }
+      case 'fs.writeFile': {
+        const f = await import('node:fs/promises');
+        await f.writeFile(args.path as string, args.data as any);
+        return undefined;
+      }
+      case 'net.fetch': {
+        const r = await fetch(args.url as string, { method: (args.init as any)?.method, headers: (args.init as any)?.headers, body: (args.init as any)?.body });
+        return { status: r.status, body: await r.text() };
+      }
+      default:
+        throw new Error(`unknown RPC method: ${method}`);
+    }
+  }
+
+  /** Proxy an inbound HTTP request into the worker, await its response. */
+  private invokeRoute(routeId: string, ctx: any): void {
+    const request = {
+      method: ctx.method,
+      path: ctx.path,
+      headers: ctx.headers,
+      body: ctx.body,
+      params: ctx.params,
+      query: ctx.query,
+    };
+    const promise = new Promise<{ status: number; body: unknown; headers: Record<string, string> }>((resolve) => {
+      this.pendingRoutes.set(routeId, { resolve });
+    });
+    this.worker?.postMessage({ kind: 'invokeRoute', routeId, request });
+    promise.then((res) => {
+      ctx.status(res.status);
+      if (res.headers) for (const [k, v] of Object.entries(res.headers)) ctx.setHeader(k, v);
+      if (res.body !== undefined) ctx.json(res.body);
+    });
+  }
+
+  private startHeartbeatWatchdog(): void {
+    const timeout = this.limits.heartbeatTimeoutMs ?? 4000;
+    this.heartbeatTimer = setInterval(() => {
+      if (Date.now() - this.lastHeartbeat > timeout) {
+        this.bindings.logger.child({ plugin: this.manifest.name }).error('heartbeat missed; terminating worker');
+        this.worker?.terminate().catch(() => {});
+        this.handleWorkerDeath(new Error('heartbeat timeout'));
+      }
+    }, timeout);
+  }
+
+  private sendLifecycle(hook: string, config?: unknown): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.lifecycleWaiters.set(hook, { resolve, reject });
+      this.worker?.postMessage({ kind: 'lifecycle', hook, config });
+    });
+  }
+
+  async install(): Promise<void> {
+    if (!this.worker) this.spawnWorker();
+    // Wait for the worker to report ready, then drive install via RPC.
+    await this.waitForReady();
+    await this.sendLifecycle('install');
+    this.state = 'installed';
+  }
+
+  private waitForReady(): Promise<void> {
+    if (this.ready) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const check = () => {
+        if (this.ready) resolve();
+        else if (this.state === 'errored') reject(new Error('worker failed to start'));
+        else setTimeout(check, 20);
+      };
+      check();
+    });
+  }
+
+  async init(): Promise<void> { await this.sendLifecycle('init'); this.state = 'initialized'; }
+  async start(): Promise<void> { await this.sendLifecycle('start'); this.state = 'started'; }
+  async stop(): Promise<void> {
+    try { await this.sendLifecycle('stop'); } catch { /* worker may be dead */ }
+    this.state = 'stopped';
+  }
+
+  async updateConfig(cfg: unknown): Promise<void> {
+    this.config = cfg;
+    await this.sendLifecycle('config:change', cfg);
+  }
+
+  async unload(): Promise<void> {
+    if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = null; }
+    try { await this.sendLifecycle('stop'); } catch { /* ignore */ }
+    await this.worker?.terminate().catch(() => {});
+    this.worker = null;
+    this.ready = false;
+    this.state = 'stopped';
+  }
+
+  /** Test helper: number of times the worker died. */
+  getRestarts(): number { return this.restartCount; }
+}

package/packages/nexus-plugins/src/sandbox/capabilityPolicy.ts

@@ -0,0 +1,68 @@
+import type { Capability } from '../manifest.js';
+
+/** Maps an RPC method name to the capability it requires. */
+const METHOD_CAPABILITY: Record<string, Capability> = {
+  'http.addRoute': 'http',
+  'http.addMiddleware': 'http',
+  'data.registerModel': 'data',
+  'data.getModel': 'data',
+  'realtime.join': 'realtime',
+  'realtime.broadcast': 'realtime',
+  'scheduler.schedule': 'scheduler',
+  'scheduler.cancel': 'scheduler',
+  'events.publish': 'events',
+  'events.subscribe': 'events',
+  'events.unsubscribe': 'events',
+  'admin.registerAdminPage': 'admin',
+  'admin.registerSlot': 'admin',
+  'services.register': 'events',
+  'services.get': 'events',
+  'fs.readFile': 'fs',
+  'fs.writeFile': 'fs',
+  'net.fetch': 'net',
+};
+
+/** Result of an authorization check. */
+export interface PolicyDecision {
+  allowed: boolean;
+  reason?: string;
+}
+
+/**
+ * Decide whether a sandboxed plugin may invoke an RPC method with the given args,
+ * given its declared capabilities and allowlists. The capability set is checked
+ * first; for fs/net the path/host is additionally checked against the allowlist.
+ * The `http` route handler is *not* gated here — it is a push from the host to the
+ * worker (invokeRoute), not a worker RPC.
+ */
+export function authorize(
+  method: string,
+  args: Record<string, unknown>,
+  capabilities: Set<Capability>,
+  fsAllowPaths?: string[],
+  netAllowHosts?: string[],
+): PolicyDecision {
+  const cap = METHOD_CAPABILITY[method];
+  if (!cap) {
+    // Unknown methods (incl. logger, which is always allowed) — allow by default.
+    return { allowed: true };
+  }
+  if (!capabilities.has(cap)) {
+    return { allowed: false, reason: `missing capability: ${cap}` };
+  }
+  if (method === 'fs.readFile' || method === 'fs.writeFile') {
+    const path = String(args.path ?? '');
+    if (fsAllowPaths && fsAllowPaths.length > 0 && !fsAllowPaths.some((p) => path === p || path.startsWith(p))) {
+      return { allowed: false, reason: `path outside allowlist: ${path}` };
+    }
+  }
+  if (method === 'net.fetch') {
+    const url = String(args.url ?? '');
+    let host = '';
+    try { host = new URL(url).hostname; } catch { host = url; }
+    if (netAllowHosts && netAllowHosts.length > 0 && !netAllowHosts.includes(host)) {
+      return { allowed: false, reason: `host outside allowlist: ${host}` };
+    }
+  }
+  return { allowed: true };
+}

package/packages/nexus-plugins/src/sandbox/workerBootstrap.mjs

@@ -0,0 +1,211 @@
+// Plugin worker bootstrap (plain ESM — Node runs this directly in a worker_thread,
+// no TS loader needed). Loads the plugin entry and exposes a PluginContext whose
+// registrars RPC back to the host (capability-gated there). Runs lifecycle hooks
+// and route/schedule/event handlers in response to host messages. A crash here
+// is isolated from the host process.
+import { workerData, parentPort } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+
+const { entryPath, manifest, config } = workerData;
+const caps = new Set(manifest.capabilities);
+
+// Pending RPC requests awaiting host replies.
+const rpcPending = new Map();
+let rpcSeq = 0;
+
+function callHost(method, args) {
+  const id = ++rpcSeq;
+  return new Promise((resolve, reject) => {
+    rpcPending.set(id, { resolve, reject });
+    parentPort.postMessage({ kind: 'rpc', id, method, args });
+  });
+}
+
+function requireCap(cap) {
+  if (!caps.has(cap)) throw new Error(`plugin ${manifest.name} lacks capability: ${cap}`);
+}
+
+// Stored handlers the host invokes via messages.
+const routes = new Map(); // routeId -> handler
+const schedules = new Map(); // name -> fn
+const eventHandlers = new Map(); // topic -> handler
+
+function buildContext() {
+  const logger = {
+    info: (m, meta) => parentPort.postMessage({ kind: 'log', level: 'info', msg: m, meta }),
+    warn: (m, meta) => parentPort.postMessage({ kind: 'log', level: 'warn', msg: m, meta }),
+    error: (m, meta) => parentPort.postMessage({ kind: 'log', level: 'error', msg: m, meta }),
+  };
+  const ctx = {
+    pluginName: manifest.name,
+    capabilities: manifest.capabilities,
+    config,
+    logger,
+    http: {
+      addRoute(method, path, handler) {
+        requireCap('http');
+        const routeId = `${method}:${path}:${Math.random().toString(36).slice(2, 8)}`;
+        routes.set(routeId, handler);
+        callHost('http.addRoute', { method, path, routeId });
+      },
+      addMiddleware(mw, phase) {
+        requireCap('http');
+        // Middleware can't be serialized; sandboxed middleware is a v1 no-op stub
+        // (documented). The host logs that middleware was requested but not applied.
+        callHost('http.addMiddleware', { phase });
+      },
+    },
+    graphql: {
+      addSubgraph() {
+        throw new Error('sandboxed plugins cannot add GraphQL subgraphs in v1 (resolvers are not serializable; use trusted mode)');
+      },
+    },
+    data: {
+      registerModel(name, schema) { requireCap('data'); return callHost('data.registerModel', { name, schema }); },
+      getModel(name) { requireCap('data'); return callHost('data.getModel', { name }); },
+    },
+    realtime: {
+      join(room, connId) { requireCap('realtime'); callHost('realtime.join', { room, connId }); },
+      broadcast(room, msg) { requireCap('realtime'); callHost('realtime.broadcast', { room, msg }); },
+    },
+    scheduler: {
+      schedule(name, cron, fn) { requireCap('scheduler'); schedules.set(name, fn); callHost('scheduler.schedule', { name, cron }); },
+      cancel(name) { requireCap('scheduler'); schedules.delete(name); callHost('scheduler.cancel', { name }); },
+    },
+    events: {
+      publish(topic, payload) { requireCap('events'); callHost('events.publish', { topic, payload }); },
+      subscribe(topic, handler) {
+        requireCap('events');
+        eventHandlers.set(topic, handler);
+        callHost('events.subscribe', { topic });
+        return () => { eventHandlers.delete(topic); callHost('events.unsubscribe', { topic }); };
+      },
+    },
+    admin: {
+      registerAdminPage(page) { requireCap('admin'); callHost('admin.registerAdminPage', { page }); },
+      registerSlot(slot) { requireCap('admin'); callHost('admin.registerSlot', { slot }); },
+    },
+    services: {
+      register(name, svc) { requireCap('events'); callHost('services.register', { name, svc }); },
+      get(name) { requireCap('events'); return callHost('services.get', { name }); },
+    },
+  };
+  if (caps.has('fs')) {
+    ctx.fs = {
+      readFile(path) { return callHost('fs.readFile', { path }); },
+      writeFile(path, data) { return callHost('fs.writeFile', { path, data }); },
+    };
+  }
+  if (caps.has('net')) {
+    ctx.net = {
+      fetch(url, init) { return callHost('net.fetch', { url, init }); },
+    };
+  }
+  return ctx;
+}
+
+// Build a serializable request context for an invoked route handler.
+function buildRequestContext(request) {
+  let sent = false;
+  const response = { status: 200, body: undefined, headers: {} };
+  const api = {
+    method: request.method,
+    path: request.path,
+    headers: request.headers,
+    body: request.body,
+    params: request.params,
+    query: request.query,
+    json(data, status) { response.body = data; response.status = status ?? 200; sent = true; },
+    text(data, status) { response.body = data; response.status = status ?? 200; sent = true; },
+    html(data, status) { response.body = data; response.status = status ?? 200; sent = true; },
+    status(status) { response.status = status; sent = true; },
+    setHeader(name, value) { response.headers[name] = value; },
+  };
+  return { api, response, isSent: () => sent };
+}
+
+let ctx;
+let pluginModule;
+
+async function loadPlugin() {
+  const mod = await import(pathToFileURL(entryPath).href);
+  pluginModule = mod.default ?? mod;
+}
+
+async function runHook(hook, hookConfig) {
+  const fn = pluginModule?.[hook];
+  if (hook === 'onConfigChange') {
+    if (pluginModule?.onConfigChange) await pluginModule.onConfigChange(ctx, hookConfig);
+    return;
+  }
+  if (fn) await fn(ctx);
+}
+
+parentPort.on('message', async (msg) => {
+  try {
+    if (msg.kind === 'rpcResult') {
+      const p = rpcPending.get(msg.id);
+      if (!p) return;
+      rpcPending.delete(msg.id);
+      if (msg.ok) p.resolve(msg.result);
+      else p.reject(new Error(msg.error));
+      return;
+    }
+    if (msg.kind === 'lifecycle') {
+      if (msg.config !== undefined) ctx.config = msg.config;
+      try {
+        // Map hook names to module methods.
+        const hookMap = { install: 'install', init: 'init', start: 'start', stop: 'stop', 'config:change': 'onConfigChange' };
+        const fnName = hookMap[msg.hook];
+        const fn = pluginModule?.[fnName];
+        if (fn) await fn(ctx, msg.config);
+        parentPort.postMessage({ kind: 'lifecycleDone', hook: msg.hook, ok: true });
+      } catch (err) {
+        parentPort.postMessage({ kind: 'lifecycleDone', hook: msg.hook, ok: false, error: String(err?.message ?? err) });
+      }
+      return;
+    }
+    if (msg.kind === 'invokeRoute') {
+      const handler = routes.get(msg.routeId);
+      const { api, response, isSent } = buildRequestContext(msg.request);
+      try {
+        if (handler) await handler(api);
+        if (!isSent()) { response.body = response.body ?? ''; response.status = response.status ?? 200; }
+        parentPort.postMessage({ kind: 'routeResponse', routeId: msg.routeId, status: response.status, body: response.body, headers: response.headers });
+      } catch (err) {
+        parentPort.postMessage({ kind: 'routeResponse', routeId: msg.routeId, status: 500, body: { error: String(err?.message ?? err) }, headers: {} });
+      }
+      return;
+    }
+    if (msg.kind === 'runSchedule') {
+      const fn = schedules.get(msg.name);
+      if (fn) await fn();
+      return;
+    }
+    if (msg.kind === 'event') {
+      const h = eventHandlers.get(msg.topic);
+      if (h) h(msg.payload);
+      return;
+    }
+  } catch (err) {
+    // Never let a message-handler throw crash the worker silently.
+    parentPort.postMessage({ kind: 'log', level: 'error', msg: 'handler error', meta: { error: String(err?.message ?? err) } });
+  }
+});
+
+// Heartbeat — tell the host we're alive on an interval.
+const heartbeatMs = (workerData.limits && workerData.limits.heartbeatMs) || 1000;
+const heartbeat = setInterval(() => parentPort.postMessage({ kind: 'heartbeat' }), heartbeatMs);
+
+async function start() {
+  ctx = buildContext();
+  await loadPlugin();
+  parentPort.postMessage({ kind: 'ready' });
+  // The host drives all lifecycle hooks (install → init → start) via messages.
+}
+start().catch((err) => {
+  parentPort.postMessage({ kind: 'log', level: 'error', msg: 'plugin failed to start', meta: { error: String(err?.message ?? err) } });
+  parentPort.postMessage({ kind: 'fatal', error: String(err?.message ?? err) });
+});
+
+export {}; // keep this an ES module

package/packages/nexus-realtime/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@bhooai/nexus-realtime",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "@bhooai/nexus-auth": "^0.1.0",
+    "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "mediasoup": "^3.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-realtime/src/adapter/PubSubAdapter.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Pub/sub adapter for cross-instance room broadcast fanout. The default
+ * `MemoryPubSubAdapter` is a single-process EventEmitter-backed implementation
+ * (fine for tests and single-node deployments). A Redis-backed adapter is used
+ * for horizontal scaling — see `RedisPubSubAdapter`.
+ *
+ * Broadcast model: `RealtimeServer` publishes a room event; every instance's
+ * subscriber (including the originator) delivers it to its local members. This
+ * gives exactly-once delivery per instance without the originator also sending
+ * locally.
+ */
+export interface PubSubAdapter {
+  /** Publish a message to a channel (room). Returns void (fire-and-forget). */
+  publish(channel: string, message: Buffer | string): void;
+  /** Subscribe to a channel; the handler is called for each published message. */
+  subscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> | void;
+  /** Unsubscribe a handler from a channel. */
+  unsubscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> | void;
+}
+
+export class MemoryPubSubAdapter implements PubSubAdapter {
+  private bus = new EventEmitter();
+
+  constructor() {
+    // Many subscribers per channel; allow headroom for fanout.
+    this.bus.setMaxListeners(0);
+  }
+
+  publish(channel: string, message: Buffer | string): void {
+    this.bus.emit(channel, message);
+  }
+
+  subscribe(channel: string, handler: (message: Buffer | string) => void): void {
+    this.bus.on(channel, handler);
+  }
+
+  unsubscribe(channel: string, handler: (message: Buffer | string) => void): void {
+    this.bus.off(channel, handler);
+  }
+}

package/packages/nexus-realtime/src/adapter/RedisPubSubAdapter.ts

@@ -0,0 +1,59 @@
+import type { PubSubAdapter } from './PubSubAdapter.js';
+
+/**
+ * Minimal Redis client interface this adapter depends on (compatible with
+ * `node-redis` i.e. `createClient()`). Kept structural so the realtime package
+ * does not hard-depend on a redis client at import time — `nexus-cache`
+ * (Phase 7) supplies a configured client.
+ */
+export interface RedisLike {
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(...channels: string[]): Promise<number>;
+  unsubscribe(...channels: string[]): Promise<number>;
+  on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+  off(event: 'message', listener: (channel: string, message: string) => void): unknown;
+}
+
+/**
+ * Redis-backed pub/sub adapter for multi-instance room broadcast. Uses one
+ * configured Redis client in subscribe mode; messages are JSON strings.
+ */
+export class RedisPubSubAdapter implements PubSubAdapter {
+  private handlers = new Map<string, Set<(message: Buffer | string) => void>>();
+
+  constructor(private client: RedisLike) {
+    // Route incoming Redis messages to registered handlers.
+    const route = (channel: string, message: string) => {
+      const set = this.handlers.get(channel);
+      if (set) for (const h of set) h(message);
+    };
+    this.route = route;
+    client.on('message', route);
+  }
+
+  private route: (channel: string, message: string) => void;
+
+  publish(channel: string, message: Buffer | string): void {
+    void this.client.publish(channel, typeof message === 'string' ? message : message.toString('utf8'));
+  }
+
+  async subscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> {
+    let set = this.handlers.get(channel);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(channel, set);
+      await this.client.subscribe(channel);
+    }
+    set.add(handler);
+  }
+
+  async unsubscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> {
+    const set = this.handlers.get(channel);
+    if (!set) return;
+    set.delete(handler);
+    if (set.size === 0) {
+      this.handlers.delete(channel);
+      await this.client.unsubscribe(channel);
+    }
+  }
+}