@jskit-ai/realtime 0.1.176 → 0.1.178

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/realtime",
-  "version": "0.1.176",
+  "version": "0.1.178",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -20,8 +20,8 @@
     "socket.io-client": "^4.8.3"
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.179",
-    "@jskit-ai/shell-web": "0.1.183",
+    "@jskit-ai/kernel": "0.1.181",
+    "@jskit-ai/shell-web": "0.1.185",
     "vue": "^3.5.13"
   },
   "description": "Thin, generic realtime runtime wrappers for socket.io server and client.",

package/patterns/realtime-application/PATTERN.md

@@ -53,9 +53,26 @@ Omit the placement when the product does not need a visible connection state.
 Change event listeners, Redis provisioning, and client invalidation behavior to
 match the product. Keep transport retry policy in the realtime runtime.
 
+When every realtime event belongs behind the application's authentication
+boundary, let the selected `auth.service` opt in with
+`realtime.requireAuthentication: true`. Socket.IO then rejects an
+unauthenticated handshake before the client can join any broadcast room. A
+browser whose login identity changes must disconnect and reconnect its socket
+so the next handshake resolves the new actor.
+
+Use `auth.service.realtime.authorizeEvent({ actor, event: { name, payload } })`
+for resource-specific read authorization. Return `true` only when the current
+actor can read that event's resource. Authentication is revalidated before
+delivery and every 30 seconds while idle. Redis peers perform the same checks
+locally. Realtime failures are logged without failing an already-successful
+mutation; one mutation owner publishes each completion, while progress events
+describe distinct lifecycle states.
+
 ## Verification
 
 - Test in-process delivery without Redis.
+- When authenticated-client mode is selected, reject an anonymous handshake
+  and reconnect after login, logout, and identity changes.
 - When Redis is selected, test delivery across two server processes.
 - Disconnect and reconnect a browser and verify recovery behavior.
 - Confirm the status contribution renders in compact and expanded shells.

package/patterns/realtime-application/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.1.176",
-    "@jskit-ai/shell-web": "0.1.183"
+    "@jskit-ai/realtime": "0.1.178",
+    "@jskit-ai/shell-web": "0.1.185"
   }
 }

package/src/server/RealtimeProvider.js

@@ -2,7 +2,10 @@ import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import { createProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { createRealtimeDelivery } from "./realtimeDelivery.js";
-import { registerSocketAudienceBootstrap } from "./realtimeAudience.js";
+import {
+  realtimeAuthenticationRequired,
+  registerSocketAudienceBootstrap
+} from "./realtimeAudience.js";
 import {
   closeSocketIoRedisConnections,
   closeSocketIoServer,
@@ -32,6 +35,7 @@ function createRealtimeCapability({ io }) {
     diagnostics() {
       const state = stateByCapability.get(capability);
       return Object.freeze({
+        authenticationRequired: state?.authenticationRequired === true,
         connectedClients: Number.isInteger(Number(io?.engine?.clientsCount))
           ? Number(io.engine.clientsCount)
           : null,
@@ -59,22 +63,26 @@ const RealtimeProvider = defineProvider({
   provides: {
     realtime: "runtime.realtime"
   },
-  setup({ config, database, env, events, fastify, logger }) {
+  setup({ config, env, fastify, logger }) {
     const io = createSocketIoServer({ fastify });
     const providerLogger = createProviderLogger(logger, { debugEnabled: debugEnabled(config, env) });
-    const delivery = createRealtimeDelivery({ io, database, logger: providerLogger });
     const realtime = createRealtimeCapability({ io });
-    stateByCapability.set(realtime, { io, providerLogger, redisConnection: null });
-    events.register({
-      id: "runtime.realtime.delivery",
-      matches: (event) => Boolean(normalizeText(event?.realtime?.event)),
-      handle: delivery.handle
+    stateByCapability.set(realtime, {
+      authenticationRequired: false,
+      delivery: null,
+      io,
+      providerLogger,
+      redisConnection: null
     });
     return { realtime };
   },
-  async boot({ authService, env, workspaces }, { outputs }) {
+  async boot({ authService, database, env, events, workspaces }, { outputs }) {
     const state = stateByCapability.get(outputs.realtime);
     if (!state) throw new Error("Realtime runtime state is unavailable.");
+    state.delivery = createRealtimeDelivery({
+      io: state.io, database, logger: state.providerLogger, authService, workspaces
+    });
+    state.authenticationRequired = realtimeAuthenticationRequired(authService);
     registerSocketAudienceBootstrap({
       io: state.io,
       logger: state.providerLogger,
@@ -82,13 +90,21 @@ const RealtimeProvider = defineProvider({
       workspaces
     });
     state.redisConnection = await configureSocketIoRedisAdapter(state.io, {
+      logger: state.providerLogger,
       redisUrl: resolveRealtimeRedisUrl(env),
       redisNamespace: resolveRealtimeRedisNamespace(env)
     });
+    state.delivery.start({ redisConfigured: state.redisConnection.enabled });
+    events.register({
+      id: "runtime.realtime.delivery",
+      matches: (event) => Boolean(normalizeText(event?.realtime?.event)),
+      handle: state.delivery.handle
+    });
   },
   async shutdown(_dependencies, { outputs }) {
     const state = stateByCapability.get(outputs.realtime);
     if (!state) return;
+    state.delivery?.stop();
     await closeSocketIoServer(state.io);
     await closeSocketIoRedisConnections(state.redisConnection || {});
     stateByCapability.delete(outputs.realtime);

package/src/server/realtimeAudience.js

@@ -26,6 +26,17 @@ function roomForWorkspaceUser(workspaceId, userId) {
   return `workspace:${String(workspaceId || "").trim()}:user:${String(userId || "").trim()}`;
 }
 
+function workspaceAudienceRooms(workspaceIds, actorId) {
+  const rooms = [];
+  for (const rawId of normalizeArray(workspaceIds)) {
+    const workspaceId = normalizeRecordId(rawId, { fallback: null });
+    if (workspaceId) {
+      rooms.push(roomForWorkspace(workspaceId), roomForWorkspaceUser(workspaceId, actorId));
+    }
+  }
+  return rooms;
+}
+
 function resolveScopeWorkspaceId(scope = {}) {
   const kind = normalizeText(scope?.kind).toLowerCase();
   if (kind === "workspace") return normalizeRecordId(scope.id, { fallback: null });
@@ -171,7 +182,7 @@ function parseCookieHeader(value = "") {
   return cookies;
 }
 
-async function resolveSocketActorId(authService, socket) {
+async function resolveSocketActor(authService, socket) {
   if (typeof authService?.authenticateRequest !== "function") return null;
   const handshakeHeaders = socket?.handshake?.headers || {};
   const requestHeaders = socket?.request?.headers || {};
@@ -185,31 +196,65 @@ async function resolveSocketActorId(authService, socket) {
   if (host) request.headers = { host };
   if (remoteAddress) request.socket = { remoteAddress };
   const result = await authService.authenticateRequest(request);
-  return result?.authenticated === true
-    ? normalizeRecordId(result?.actor?.id, { fallback: null })
-    : null;
+  const id = result?.authenticated === true
+    ? normalizeRecordId(result?.actor?.id, { fallback: null }) : null;
+  return id ? { ...result.actor, id } : null;
+}
+
+function realtimeAuthenticationRequired(authService = null) {
+  return authService?.realtime?.requireAuthentication === true;
+}
+
+function authenticationRequiredError() {
+  const error = new Error("Authentication required.");
+  error.data = Object.freeze({ code: "AUTHENTICATION_REQUIRED" });
+  return error;
+}
+
+function rememberSocketActorId(socket, actorId) {
+  socket.data = socket.data && typeof socket.data === "object" ? socket.data : {};
+  socket.data.actorId = actorId;
+}
+
+function registerRequiredSocketAuthentication({ io, logger, authService }) {
+  if (!realtimeAuthenticationRequired(authService)) return;
+  if (typeof io?.use !== "function") {
+    throw new TypeError("Realtime authenticated-client mode requires Socket.IO middleware support.");
+  }
+  io.use(async (socket, next) => {
+    try {
+      const actorId = (await resolveSocketActor(authService, socket))?.id;
+      if (!actorId) {
+        next(authenticationRequiredError());
+        return;
+      }
+      rememberSocketActorId(socket, actorId);
+      next();
+    } catch (error) {
+      logger.warn({ error: String(error?.message || error) }, "Realtime socket authentication failed.");
+      next(authenticationRequiredError());
+    }
+  });
 }
 
 function registerSocketAudienceBootstrap({ io, logger, authService = null, workspaces = null }) {
   if (typeof io?.on !== "function") return;
+  registerRequiredSocketAuthentication({ io, logger, authService });
   io.on("connection", async (socket) => {
     try {
       socket.join(ALL_CLIENTS_ROOM);
-      const actorId = await resolveSocketActorId(authService, socket);
+      const actorId = normalizeRecordId(socket?.data?.actorId, { fallback: null })
+        || (await resolveSocketActor(authService, socket))?.id;
       if (!actorId) return;
-      socket.data = socket.data && typeof socket.data === "object" ? socket.data : {};
-      socket.data.actorId = actorId;
+      rememberSocketActorId(socket, actorId);
       socket.join(ALL_USERS_ROOM);
       socket.join(roomForUser(actorId));
       const repository = workspaces?.repositories?.workspaceMemberships;
       const workspaceIds = typeof repository?.listActiveWorkspaceIdsByUserId === "function"
         ? await repository.listActiveWorkspaceIdsByUserId(actorId)
         : [];
-      for (const rawId of normalizeArray(workspaceIds)) {
-        const workspaceId = normalizeRecordId(rawId, { fallback: null });
-        if (!workspaceId) continue;
-        socket.join(roomForWorkspace(workspaceId));
-        socket.join(roomForWorkspaceUser(workspaceId, actorId));
+      for (const room of workspaceAudienceRooms(workspaceIds, actorId)) {
+        socket.join(room);
       }
     } catch (error) {
       logger.warn({ error: String(error?.message || error) }, "Realtime socket audience bootstrap failed.");
@@ -217,4 +262,32 @@ function registerSocketAudienceBootstrap({ io, logger, authService = null, works
   });
 }
 
-export { registerSocketAudienceBootstrap, resolveAudienceTargets };
+async function revalidateSocket({ socket, authService, workspaces = null }) {
+  const actor = await resolveSocketActor(authService, socket);
+  const previousActorId = socket.data?.actorId;
+  if ((!actor && realtimeAuthenticationRequired(authService)) ||
+      (previousActorId && previousActorId !== actor?.id)) {
+    socket.disconnect(true);
+    return null;
+  }
+  if (!actor) return null;
+
+  rememberSocketActorId(socket, actor.id);
+  const repository = workspaces?.repositories?.workspaceMemberships;
+  if (typeof repository?.listActiveWorkspaceIdsByUserId !== "function") return actor;
+
+  const workspaceIds = await repository.listActiveWorkspaceIdsByUserId(actor.id);
+  const rooms = new Set(workspaceAudienceRooms(workspaceIds, actor.id));
+  for (const room of socket.rooms) {
+    if (room.startsWith("workspace:") && !rooms.has(room)) await socket.leave(room);
+  }
+  for (const room of rooms) await socket.join(room);
+  return actor;
+}
+
+export {
+  realtimeAuthenticationRequired,
+  revalidateSocket,
+  registerSocketAudienceBootstrap,
+  resolveAudienceTargets
+};

package/src/server/realtimeDelivery.js

@@ -1,16 +1,25 @@
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { resolveAudienceTargets } from "./realtimeAudience.js";
+import { resolveAudienceTargets, revalidateSocket } from "./realtimeAudience.js";
+
+const DELIVERY_EVENT = "jskit:realtime:delivery";
 
 function publicRealtimePayload(event) {
-  const { realtime, ...canonical } = event && typeof event === "object" ? event : {};
+  const { realtime } = event && typeof event === "object" ? event : {};
+  const canonical = {};
+  for (const key of [
+    "type", "source", "entity", "operation", "entityId", "scope", "actorId",
+    "commandId", "sourceClientId", "occurredAt"
+  ]) {
+    if (Object.hasOwn(event, key)) canonical[key] = event[key];
+  }
   const payload = realtime?.payload;
-  if (payload != null && (!payload || typeof payload !== "object" || Array.isArray(payload))) {
+  if (payload != null && (typeof payload !== "object" || Array.isArray(payload))) {
     throw new TypeError("Realtime event payload must be an object when provided.");
   }
   return Object.freeze({ ...(payload || {}), ...canonical });
 }
 
-function createRealtimeDelivery({ io, database = null, logger }) {
+function createRealtimeDelivery({ io, database = null, logger, authService = null, workspaces = null }) {
   if (!io || typeof io.emit !== "function" || typeof io.to !== "function") {
     throw new TypeError("Realtime delivery requires a Socket.IO server.");
   }
@@ -18,22 +27,109 @@ function createRealtimeDelivery({ io, database = null, logger }) {
     throw new TypeError("Realtime delivery requires a logger.");
   }
 
+  const guarded = typeof authService?.authenticateRequest === "function";
+  if (authService?.realtime?.authorizeEvent != null && typeof authService.realtime.authorizeEvent !== "function") {
+    throw new TypeError("Realtime authorizeEvent must be a function.");
+  }
+  if ((authService?.realtime?.requireAuthentication === true || authService?.realtime?.authorizeEvent) && !guarded) {
+    throw new TypeError("Realtime authorization requires auth.service.authenticateRequest().");
+  }
+  let redisEnabled = false;
+  let revalidationTimer = null;
+  let stopped = false;
+
+  async function revalidate(socket) {
+    try {
+      return await revalidateSocket({ socket, authService, workspaces });
+    } catch (error) {
+      socket.disconnect(true);
+      logger.warn({ error: String(error?.message || error) }, "Realtime socket revalidation failed.");
+      return null;
+    }
+  }
+
+  async function deliverLocal({ eventName, payload, targets }) {
+    await Promise.all([...io.sockets.sockets.values()].map(async (socket) => {
+      try {
+        const actor = await revalidate(socket);
+        if (!socket.connected) return;
+        if (!targets.broadcastAllClients && !targets.rooms.some((room) => socket.rooms.has(room))) return;
+        if (typeof authService.realtime?.authorizeEvent === "function") {
+          const authorized = await authService.realtime.authorizeEvent({
+            actor,
+            event: { name: eventName, payload }
+          });
+          if (authorized !== true) return;
+        }
+        if (socket.connected) socket.emit(eventName, payload);
+      } catch (error) {
+        logger.warn({ socketEvent: eventName, error: String(error?.message || error) }, "Realtime delivery denied after authorization failure.");
+      }
+    }));
+  }
+
+  async function receive(envelope) {
+    try {
+      await deliverLocal(envelope);
+    } catch (error) {
+      logger.warn({ error: String(error?.message || error) }, "Realtime peer delivery failed.");
+    }
+  }
+
+  function scheduleRevalidation() {
+    if (stopped) return;
+    revalidationTimer = setTimeout(async () => {
+      await Promise.all([...io.sockets.sockets.values()].map(revalidate));
+      scheduleRevalidation();
+    }, 30_000);
+    revalidationTimer.unref();
+  }
+
   return Object.freeze({
+    start({ redisConfigured = false } = {}) {
+      redisEnabled = redisConfigured;
+      if (guarded) {
+        io.on(DELIVERY_EVENT, receive);
+        scheduleRevalidation();
+      }
+    },
+    stop() {
+      stopped = true;
+      clearTimeout(revalidationTimer);
+      if (guarded) io.off(DELIVERY_EVENT, receive);
+    },
     async handle(event = {}) {
-      const eventName = normalizeText(event?.realtime?.event);
-      if (!eventName) return;
-      const targets = await resolveAudienceTargets(event.realtime.audience, event, { database, logger });
-      const payload = publicRealtimePayload(event);
-      if (targets.broadcastAllClients) io.emit(eventName, payload);
-      for (const room of targets.rooms) io.to(room).emit(eventName, payload);
-      logger.debug({
-        socketEvent: eventName,
-        rooms: targets.rooms,
-        broadcastAllClients: targets.broadcastAllClients,
-        connectedClients: Number.isInteger(Number(io?.engine?.clientsCount))
-          ? Number(io.engine.clientsCount)
-          : null
-      }, "Realtime delivered an action event.");
+      try {
+        const eventName = normalizeText(event?.realtime?.event);
+        if (!eventName) return;
+        const targets = await resolveAudienceTargets(event.realtime.audience, event, { database, logger });
+        const payload = publicRealtimePayload(event);
+        if (guarded) {
+          const envelope = { eventName, payload, targets };
+          if (redisEnabled) {
+            try {
+              io.serverSideEmit(DELIVERY_EVENT, envelope);
+            } catch (error) {
+              logger.warn({ socketEvent: eventName, error: String(error?.message || error) }, "Realtime peer publication failed.");
+            }
+          }
+          await deliverLocal(envelope);
+        } else if (targets.broadcastAllClients) {
+          io.emit(eventName, payload);
+        } else if (targets.rooms.length) {
+          io.to(targets.rooms).emit(eventName, payload);
+        }
+        logger.debug({
+          socketEvent: eventName,
+          rooms: targets.rooms,
+          broadcastAllClients: targets.broadcastAllClients,
+          connectedClients: Number.isInteger(Number(io?.engine?.clientsCount))
+            ? Number(io.engine.clientsCount)
+            : null
+        }, "Realtime delivered an action event.");
+      } catch (error) {
+        logger.warn({ socketEvent: event?.realtime?.event, error: String(error?.message || error) }, "Realtime delivery failed; the domain mutation remains successful.");
+      }
     }
   });
 }

package/src/server/runtime.js

@@ -81,6 +81,7 @@ async function configureSocketIoRedisAdapter(
   {
     redisUrl = "",
     redisNamespace = "",
+    logger = console,
     createRedisAdapter = createSocketIoRedisAdapter,
     createRedisConnection = createRedisClient
   } = {}
@@ -105,6 +106,19 @@ async function configureSocketIoRedisAdapter(
     url: normalizedRedisUrl
   });
   const subClient = pubClient.duplicate();
+  const reportError = (error) => logger.warn({ error: String(error?.message || error) }, "Realtime Redis connection failed.");
+  pubClient.on("error", reportError);
+  subClient.on("error", reportError);
+  const publish = pubClient.publish.bind(pubClient);
+  // The Socket.IO adapter does not await Redis publish promises.
+  pubClient.publish = async (...args) => {
+    try {
+      return await publish(...args);
+    } catch (error) {
+      reportError(error);
+      return 0;
+    }
+  };
 
   try {
     await pubClient.connect();

package/test/authorization.test.js

@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { once } from "node:events";
+import test from "node:test";
+import { io as connect } from "socket.io-client";
+import { createSocketIoServer, closeSocketIoServer } from "../src/server/runtime.js";
+import { createRealtimeDelivery } from "../src/server/realtimeDelivery.js";
+import { registerSocketAudienceBootstrap } from "../src/server/realtimeAudience.js";
+
+const logger = { debug() {}, warn() {} };
+const event = {
+  type: "entity.changed", entity: "session", entityId: "s1",
+  meta: { secret: "server-only" },
+  realtime: {
+    audience: ["all_clients", { userId: 1 }], event: "conversation.changed",
+    payload: { projectSlug: "private", conversationLogPatch: { text: "private answer" } }
+  }
+};
+
+test("invalid authorization configuration fails closed at startup", () => {
+  const io = { emit() {}, to() {} };
+  assert.throws(() => createRealtimeDelivery({ io, logger, authService: {
+    authenticateRequest() {}, realtime: { authorizeEvent: true }
+  } }), /authorizeEvent must be a function/u);
+  assert.throws(() => createRealtimeDelivery({ io, logger, authService: {
+    realtime: { requireAuthentication: true }
+  } }), /authenticateRequest/u);
+});
+
+test("real sockets authorize each conversation delivery and disconnect a revoked session", async (t) => {
+  const httpServer = createServer();
+  const io = createSocketIoServer({ httpServer });
+  const users = new Map([["allowed", { id: "1" }], ["denied", { id: "2" }]]);
+  let permitted = "1";
+  const authService = {
+    realtime: {
+      requireAuthentication: true,
+      authorizeEvent: ({ actor }) => actor.id === permitted
+    },
+    async authenticateRequest(request) {
+      const actor = users.get(request.cookies.session);
+      return { authenticated: Boolean(actor), actor };
+    }
+  };
+  registerSocketAudienceBootstrap({ io, authService, logger });
+  const delivery = createRealtimeDelivery({ io, authService, logger });
+  delivery.start();
+  t.after(async () => { delivery.stop(); await closeSocketIoServer(io); });
+  httpServer.listen(0, "127.0.0.1");
+  await once(httpServer, "listening");
+  const url = `http://127.0.0.1:${httpServer.address().port}`;
+  const received = { allowed: [], denied: [] };
+  const clients = {};
+  for (const session of ["allowed", "denied"]) {
+    const socket = connect(url, { transports: ["websocket"], extraHeaders: { Cookie: `session=${session}` }, reconnection: false });
+    clients[session] = socket;
+    t.after(() => socket.disconnect());
+    socket.on("conversation.changed", (payload) => received[session].push(payload));
+    await once(socket, "connect");
+  }
+  const answer = once(clients.allowed, "conversation.changed");
+  await delivery.handle(event);
+  await answer;
+  assert.equal(received.allowed.length, 1);
+  assert.equal(received.allowed[0].conversationLogPatch.text, "private answer");
+  assert.equal(Object.hasOwn(received.allowed[0], "meta"), false);
+  assert.equal(received.denied.length, 0);
+  permitted = "2";
+  const nextAnswer = once(clients.denied, "conversation.changed");
+  await delivery.handle(event);
+  await nextAnswer;
+  assert.equal(received.allowed.length, 1);
+  users.delete("denied");
+  const disconnected = once(clients.denied, "disconnect");
+  await delivery.handle(event);
+  await disconnected;
+  assert.equal(received.denied.length, 1);
+});
+
+test("idle socket sessions are revalidated without an application event", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout"] });
+  const socket = { data: { actorId: "1" }, handshake: {}, disconnect() { this.connected = false; }, connected: true };
+  const io = { emit() {}, to() {}, on() {}, off() {}, sockets: { sockets: new Map([["s1", socket]]) } };
+  const delivery = createRealtimeDelivery({ io, logger, authService: {
+    realtime: { requireAuthentication: true },
+    async authenticateRequest() { return { authenticated: false }; }
+  } });
+  t.after(() => delivery.stop());
+  delivery.start();
+  t.mock.timers.tick(30_000);
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(socket.connected, false);
+});
+
+test("delivery failures never reject a committed mutation and room unions emit once", async () => {
+  const warnings = [];
+  const io = { emit() { throw new Error("transport down"); }, to() { throw new Error("transport down"); } };
+  const delivery = createRealtimeDelivery({ io, logger: { debug() {}, warn(value) { warnings.push(value); } } });
+  await assert.doesNotReject(delivery.handle(event));
+  await assert.doesNotReject(delivery.handle({ ...event, realtime: { ...event.realtime, payload: "invalid" } }));
+  assert.equal(warnings.length, 2);
+});
+
+test("Redis peer deliveries authorize the receiving server's sockets without rebroadcasting", async () => {
+  const delivered = [];
+  const peerHandlers = new Map();
+  const socket = {
+    connected: true, data: { actorId: "2" }, handshake: {}, rooms: new Set(["users", "user:2"]),
+    disconnect() { this.connected = false; },
+    emit(name, payload) { delivered.push({ name, payload }); }
+  };
+  let allowed = false;
+  const authService = {
+    realtime: { requireAuthentication: true, authorizeEvent: () => allowed },
+    async authenticateRequest() { return { authenticated: true, actor: { id: "2" } }; }
+  };
+  const peer = createRealtimeDelivery({ logger, authService, io: {
+    emit() { assert.fail("must authorize individual sockets"); }, to() {},
+    sockets: { sockets: new Map([["peer-socket", socket]]) },
+    on(name, handler) { peerHandlers.set(name, handler); },
+    off(name) { peerHandlers.delete(name); },
+    serverSideEmit() { assert.fail("must not rebroadcast a received event"); }
+  } });
+  const pending = [];
+  const origin = createRealtimeDelivery({ logger, authService, io: {
+    emit() {}, to() {}, sockets: { sockets: new Map() }, on() {}, off() {},
+    serverSideEmit(name, envelope) { pending.push(peerHandlers.get(name)(structuredClone(envelope))); }
+  } });
+  peer.start({ redisConfigured: true });
+  origin.start({ redisConfigured: true });
+  try {
+    await origin.handle(event);
+    await Promise.all(pending);
+    assert.equal(delivered.length, 0);
+    allowed = true;
+    await origin.handle(event);
+    await Promise.all(pending);
+    assert.equal(delivered.length, 1);
+    assert.equal(delivered[0].payload.conversationLogPatch.text, "private answer");
+  } finally {
+    origin.stop();
+    peer.stop();
+  }
+});

package/test/providerRuntime.test.js

@@ -8,9 +8,37 @@ import { RealtimeClientProvider } from "../src/client/RealtimeClientProvider.js"
 import { RealtimeProvider } from "../src/server/RealtimeProvider.js";
 import { registerSocketAudienceBootstrap } from "../src/server/realtimeAudience.js";
 import { createRealtimeDelivery } from "../src/server/realtimeDelivery.js";
+import { attachDeferredAuthService, createDeferredAuthService } from "../../auth-core/src/server/deferredAuthService.js";
 
 const logger = Object.freeze({ debug() {}, info() {}, warn() {}, error() {} });
 
+test("RealtimeProvider waits for authentication boot before accessing the auth service", async () => {
+  const authService = createDeferredAuthService();
+  const authProvider = defineProvider({
+    id: "test.deferred.auth",
+    provides: { authService: "auth.service" },
+    setup() { return { authService }; },
+    boot() {
+      attachDeferredAuthService(authService, {
+        realtime: { requireAuthentication: true },
+        async authenticateRequest() { return { authenticated: false, actor: null }; }
+      });
+    }
+  });
+  const runtime = createCapabilityRuntime({
+    inputs: {
+      "runtime.config": {}, "runtime.env": {},
+      "runtime.fastify": { server: createServer() }, "runtime.logger": logger
+    },
+    providers: [EventProvider, RealtimeProvider, authProvider]
+  });
+  try {
+    await runtime.start();
+  } finally {
+    await runtime.shutdown();
+  }
+});
+
 function createIoDouble() {
   const emitted = [];
   return {
@@ -72,7 +100,7 @@ test("realtime delivery sends explicit action events to their selected rooms", a
   });
 
   assert.deepEqual(io.emitted, [{
-    room: "workspace:11",
+    room: ["workspace:11"],
     eventName: "workspace.settings.changed",
     payload: {
       workspaceSlug: "acme",
@@ -115,7 +143,7 @@ test("realtime delivery resolves an explicit database-backed audience without ex
     }
   });
   assert.equal(io.emitted.length, 1);
-  assert.equal(io.emitted[0].room, "user:55");
+  assert.deepEqual(io.emitted[0].room, ["user:55"]);
   assert.equal(Object.hasOwn(io.emitted[0].payload, "realtime"), false);
 });
 
@@ -168,6 +196,58 @@ test("socket audience bootstrap authenticates explicitly and joins actor workspa
   ]);
 });
 
+test("socket audience bootstrap rejects unauthenticated handshakes when the auth service requires them", async () => {
+  let connectionHandler = null;
+  let authenticationMiddleware = null;
+  const io = {
+    on(eventName, handler) {
+      if (eventName === "connection") connectionHandler = handler;
+    },
+    use(handler) {
+      authenticationMiddleware = handler;
+    }
+  };
+  registerSocketAudienceBootstrap({
+    io,
+    logger,
+    authService: {
+      realtime: { requireAuthentication: true },
+      async authenticateRequest(request) {
+        return request.cookies.session === "valid"
+          ? { authenticated: true, actor: { id: 17 } }
+          : { authenticated: false, actor: null };
+      }
+    }
+  });
+
+  const rejected = [];
+  await authenticationMiddleware({
+    data: {},
+    handshake: { headers: { cookie: "session=invalid" } },
+    request: { headers: {} }
+  }, (error) => rejected.push(error));
+  assert.equal(rejected.length, 1);
+  assert.equal(rejected[0].data.code, "AUTHENTICATION_REQUIRED");
+
+  const socket = {
+    data: {},
+    handshake: { headers: { cookie: "session=valid" } },
+    request: { headers: {} },
+    join(room) {
+      this.joinedRooms ||= [];
+      this.joinedRooms.push(room);
+    }
+  };
+  let acceptedError = "not-called";
+  await authenticationMiddleware(socket, (error) => {
+    acceptedError = error;
+  });
+  assert.equal(acceptedError, undefined);
+  await connectionHandler(socket);
+  assert.equal(socket.data.actorId, "17");
+  assert.deepEqual(socket.joinedRooms, ["clients", "users", "user:17"]);
+});
+
 async function startRealtimeClient({ mobile = null } = {}) {
   const registrations = new Map();
   const provided = new Map();

package/test/serverRuntime.test.js

@@ -169,12 +169,15 @@ test("configureSocketIoRedisAdapter applies namespaced adapter key when redis na
   const createRedisConnection = ({ url }) => {
     const client = {
       url,
+      on() {},
+      async publish() { throw new Error("Redis publication unavailable"); },
       async connect() {
         connectionCalls.push(`${url}:connect`);
       },
       async quit() {},
       duplicate() {
         return {
+          on() {},
           async connect() {
             connectionCalls.push(`${url}:duplicate.connect`);
           },
@@ -191,6 +194,7 @@ test("configureSocketIoRedisAdapter applies namespaced adapter key when redis na
   });
 
   const result = await configureSocketIoRedisAdapter(io, {
+    logger: { warn() {} },
     redisUrl: "redis://localhost:6379",
     redisNamespace: "my-app:production",
     createRedisConnection,
@@ -202,4 +206,5 @@ test("configureSocketIoRedisAdapter applies namespaced adapter key when redis na
   assert.equal(adapterCalls[0].options?.key, "my-app:production:socket.io");
   assert.equal(result.adapterKey, "my-app:production:socket.io");
   assert.equal(result.redisNamespace, "my-app:production");
+  assert.equal(await result.pubClient.publish("channel", "payload"), 0);
 });