room-kit 1.0.0 → 1.0.1

package/example/server.ts

@@ -2,7 +2,7 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { randomUUID } from "node:crypto";
+import { randomUUID, timingSafeEqual as cryptoTimingSafeEqual } from "node:crypto";
 
 import { Server } from "socket.io";
 
@@ -10,191 +10,218 @@ import { ClientSafeError, serveRoomType } from "../src/index";
 import { chatRoomType, type ChatMessage } from "./common";
 
 type ChatAuth = {
-  userId: string;
+	userId: string;
 };
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const port = Number(process.env.PORT || 3000);
-const publicDir = path.join(__dirname, "public");
+const publicDir = path.resolve(path.join(__dirname, "public"));
 
 function normalizeRoomId(value: unknown): string {
-  if (typeof value !== "string" || !value.trim()) {
-    throw new ClientSafeError("Room id is required.");
-  }
+	if (typeof value !== "string" || !value.trim()) {
+		throw new ClientSafeError("Room id is required.");
+	}
 
-  return value.trim().toLowerCase();
+	return value.trim().toLowerCase();
 }
 
 function normalizeRoomKey(value: unknown): string {
-  if (typeof value !== "string" || !value.trim()) {
-    throw new ClientSafeError("Room key is required.");
-  }
+	if (typeof value !== "string" || !value.trim()) {
+		throw new ClientSafeError("Room key is required.");
+	}
 
-  return value.trim();
+	const key = value.trim();
+	if (key.length > 64) {
+		throw new ClientSafeError("Room key must be 64 characters or fewer.");
+	}
+
+	return key;
 }
 
 function normalizeUserId(value: unknown): string {
-  if (typeof value !== "string" || !value.trim()) {
-    throw new ClientSafeError("User id is required.");
-  }
+	if (typeof value !== "string" || !value.trim()) {
+		throw new ClientSafeError("User id is required.");
+	}
 
-  return value.trim();
+	return value.trim();
 }
 
 function normalizeDisplayName(value: unknown): string {
-  if (typeof value !== "string" || !value.trim()) {
-    throw new ClientSafeError("Display name is required.");
-  }
+	if (typeof value !== "string" || !value.trim()) {
+		throw new ClientSafeError("Display name is required.");
+	}
 
-  const name = value.trim();
-  if (name.length > 32) {
-    throw new ClientSafeError("Display name must be 32 characters or fewer.");
-  }
+	const name = value.trim();
+	if (name.length > 32) {
+		throw new ClientSafeError("Display name must be 32 characters or fewer.");
+	}
 
-  return name;
+	return name;
 }
 
 function normalizeMessageText(value: unknown): string {
-  if (typeof value !== "string" || !value.trim()) {
-    throw new ClientSafeError("Message text is required.");
-  }
+	if (typeof value !== "string" || !value.trim()) {
+		throw new ClientSafeError("Message text is required.");
+	}
 
-  const text = value.trim();
-  if (text.length > 500) {
-    throw new ClientSafeError("Message text must be 500 characters or fewer.");
-  }
+	const text = value.trim();
+	if (text.length > 500) {
+		throw new ClientSafeError("Message text must be 500 characters or fewer.");
+	}
 
-  return text;
+	return text;
 }
 
 function serveFile(filePath: string, res: http.ServerResponse): void {
-  fs.readFile(filePath, (error, contents) => {
-    if (error) {
-      res.statusCode = 404;
-      res.end("Not found");
-      return;
-    }
-
-    const ext = path.extname(filePath);
-    const contentType =
-      ext === ".html"
-        ? "text/html; charset=utf-8"
-        : ext === ".css"
-          ? "text/css; charset=utf-8"
-          : ext === ".js"
-            ? "text/javascript; charset=utf-8"
-            : "application/octet-stream";
-
-    res.writeHead(200, {
-      "content-type": contentType,
-      "cache-control": "no-store",
-    });
-    res.end(contents);
-  });
+	const resolved = path.resolve(filePath);
+	if (!resolved.startsWith(publicDir + path.sep) && resolved !== publicDir) {
+		res.statusCode = 403;
+		res.end("Forbidden");
+		return;
+	}
+
+	fs.readFile(resolved, (error, contents) => {
+		if (error) {
+			res.statusCode = 404;
+			res.end("Not found");
+			return;
+		}
+
+		const ext = path.extname(resolved);
+		const contentType =
+			ext === ".html"
+				? "text/html; charset=utf-8"
+				: ext === ".css"
+					? "text/css; charset=utf-8"
+					: ext === ".js"
+						? "text/javascript; charset=utf-8"
+						: "application/octet-stream";
+
+		res.writeHead(200, {
+			"content-type": contentType,
+			"cache-control": "no-store",
+		});
+		res.end(contents);
+	});
 }
 
-const server = http.createServer((req, res) => {
-  const requestUrl = new URL(req.url || "/", "http://127.0.0.1");
-
-  if (requestUrl.pathname === "/" || requestUrl.pathname === "/index.html") {
-    serveFile(path.join(publicDir, "index.html"), res);
-    return;
-  }
+const STATIC_ROUTES: Record<string, string> = {
+	"/": "index.html",
+	"/index.html": "index.html",
+	"/styles.css": "styles.css",
+	"/app.js": "app.js",
+};
 
-  if (requestUrl.pathname === "/styles.css") {
-    serveFile(path.join(publicDir, "styles.css"), res);
-    return;
-  }
+const server = http.createServer((req, res) => {
+	const requestUrl = new URL(req.url || "/", "http://127.0.0.1");
+	const staticFile = STATIC_ROUTES[requestUrl.pathname];
 
-  if (requestUrl.pathname === "/app.js") {
-    serveFile(path.join(publicDir, "app.js"), res);
-    return;
-  }
+	if (staticFile) {
+		serveFile(path.join(publicDir, staticFile), res);
+		return;
+	}
 
-  res.statusCode = 404;
-  res.end("Not found");
+	res.statusCode = 404;
+	res.end("Not found");
 });
 
 const io = new Server(server);
 
 io.on("connection", (socket) => {
-  serveRoomType<typeof chatRoomType, ChatAuth>(socket, chatRoomType, {
-    onAuth: () => ({
-      userId: socket.id,
-    }),
-
-    initState: async (join) => {
-      return {
-        roomKey: normalizeRoomKey(join.roomKey),
-        created: new Date().toISOString(),
-        history: [],
-      };
-    },
-
-    admit: async (join, ctx) => {
-      const roomId = normalizeRoomId(join.roomId);
-      const roomKey = normalizeRoomKey(join.roomKey);
-      const userId = normalizeUserId(ctx.auth.userId);
-      const userName = normalizeDisplayName(join.userName);
-
-      if (ctx.serverState.roomKey !== roomKey) {
-        throw new ClientSafeError("That room key is incorrect.");
-      }
-
-      return {
-        roomId,
-        memberId: userId,
-        memberProfile: {
-          userId,
-          userName,
-          joinedAt: Date.now(),
-        },
-        roomProfile: {
-          roomId,
-          created: ctx.serverState.created,
-          history: ctx.serverState.history.slice(-50),
-        },
-      };
-    },
-
-    onJoin: async (member, ctx) => {
-      await ctx.emit.systemNotice({
-        text: `${member.userName} joined the room`,
-        sentAt: new Date().toISOString(),
-      });
-    },
-
-    onLeave: async (member, ctx) => {
-      await ctx.emit.systemNotice({
-        text: `${member.userName} left the room`,
-        sentAt: new Date().toISOString(),
-      });
-    },
-
-    rpc: {
-      sendMessage: async ({ text }, ctx) => {
-        const messageText = normalizeMessageText(text);
-
-        const message: ChatMessage = {
-          id: randomUUID(),
-          name: ctx.memberProfile.userName,
-          text: messageText,
-          sentAt: new Date().toISOString(),
-        };
-
-        ctx.serverState.history.push(message);
-        if (ctx.serverState.history.length > 50) {
-          ctx.serverState.history.shift();
-        }
-
-        await ctx.emit.message(message);
-        return { id: message.id };
-      },
-    },
-  });
+	const serverRooms = serveRoomType<typeof chatRoomType, ChatAuth>(socket, chatRoomType, {
+		onAuth: () => ({
+			userId: socket.id,
+		}),
+
+		initState: async (join) => {
+			return {
+				roomKey: normalizeRoomKey(join.roomKey),
+				created: new Date().toISOString(),
+				history: [],
+			};
+		},
+
+		admit: async (join, ctx) => {
+			const roomId = normalizeRoomId(join.roomId);
+			const roomKey = normalizeRoomKey(join.roomKey);
+			const userId = normalizeUserId(ctx.auth.userId);
+			const userName = normalizeDisplayName(join.userName);
+
+			if (!timingSafeEqual(ctx.serverState.roomKey, roomKey)) {
+				throw new ClientSafeError("That room key is incorrect.");
+			}
+
+			return {
+				roomId,
+				memberId: userId,
+				memberProfile: {
+					userId,
+					userName,
+					joinedAt: Date.now(),
+				},
+				roomProfile: {
+					roomId,
+					created: ctx.serverState.created,
+					history: ctx.serverState.history.slice(-50),
+				},
+			};
+		},
+
+		onJoin: async (member, ctx) => {
+			await ctx.emit.systemNotice({
+				text: `${member.userName} joined the room`,
+				sentAt: new Date().toISOString(),
+			});
+		},
+
+		onLeave: async (member, ctx) => {
+			await ctx.emit.systemNotice({
+				text: `${member.userName} left the room`,
+				sentAt: new Date().toISOString(),
+			});
+		},
+		events: {
+			message: () => undefined,
+		},
+		rpc: {
+			sendMessage: async ({ text }, ctx) => {
+				const messageText = normalizeMessageText(text);
+
+				const message: ChatMessage = {
+					id: randomUUID(),
+					name: ctx.memberProfile.userName,
+					text: messageText,
+					sentAt: new Date().toISOString(),
+				};
+
+				ctx.serverState.history.push(message);
+				if (ctx.serverState.history.length > 50) {
+					ctx.serverState.history.shift();
+				}
+
+				await ctx.emit.message(message);
+				return { id: message.id };
+			},
+		},
+	});
+
 });
 
+
+// Uses crypto.timingSafeEqual to prevent timing side-channel attacks on
+// secret comparisons like room keys.
+function timingSafeEqual(a: string, b: string): boolean {
+	const bufA = Buffer.from(a, "utf-8");
+	const bufB = Buffer.from(b, "utf-8");
+	if (bufA.length !== bufB.length) {
+		// Compare against self to burn equal time, then return false
+		cryptoTimingSafeEqual(bufA, bufA);
+		return false;
+	}
+	return cryptoTimingSafeEqual(bufA, bufB);
+}
+
 server.listen(port, "127.0.0.1", () => {
-  console.log(`Chat example listening on http://127.0.0.1:${port}`);
+	console.log(`Chat example listening on http://127.0.0.1:${port}`);
 });

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlycliches/room-kit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Type-safe channel primitives for Socket.IO events, requests, streams, and room membership.",
   "exports": "./src/index.ts",
   "publish": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "room-kit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Type-safe room membership, presence, and realtime messaging for Socket.IO.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.ts

@@ -14,6 +14,7 @@ import type {
     RoomDefinition,
     RoomEvents,
     RoomProfileFor,
+    RoomListenApi,
     RoomRpc,
     RpcClientApi,
 } from "./types";
@@ -26,6 +27,8 @@ const SERVER_EVENT = "room-kit:server-event";
 const PRESENCE_EVENT = "room-kit:presence";
 const PRESENCE_QUERY_EVENT = "room-kit:presence-query";
 
+const DEFAULT_ACK_TIMEOUT_MS = 30_000;
+
 type ClientRegistry = {
     serverHandlerInstalled: boolean;
     presenceHandlerInstalled: boolean;
@@ -162,19 +165,41 @@ function createJoinedRoom<TRoom extends RoomDefinition<any>>(
             }
 
             return (handler: (payload: unknown, meta: EventMetaFor<TRoom>) => void) => {
-                const handlers = state.eventListeners.get(key) ?? new Set();
-                handlers.add(handler);
-                state.eventListeners.set(key, handlers);
-                return () => {
-                    handlers.delete(handler);
-                    if (handlers.size === 0) {
-                        state.eventListeners.delete(key);
-                    }
-                };
+                return registerEventListener(state, key, handler);
             };
         },
     });
 
+    const listen = (options: RoomListenApi<TRoom>): (() => void) => {
+        const cleanups: Array<() => void> = [];
+
+        if (options.events) {
+            for (const [key, handler] of Object.entries(options.events) as Array<
+                [string, (payload: unknown, meta: EventMetaFor<TRoom>) => void]
+            >) {
+                if (typeof handler !== "function") {
+                    continue;
+                }
+                cleanups.push(registerEventListener(state, key, handler));
+            }
+        }
+
+        if ("presence" in options && options.presence?.onChange) {
+            cleanups.push(registerPresenceListener(state, options.presence.onChange));
+        }
+
+        let cleaned = false;
+        return () => {
+            if (cleaned) {
+                return;
+            }
+            cleaned = true;
+            for (const cleanup of cleanups) {
+                cleanup();
+            }
+        };
+    };
+
     const base = {
         name: state.name,
         roomId: state.roomId,
@@ -183,6 +208,7 @@ function createJoinedRoom<TRoom extends RoomDefinition<any>>(
         rpc,
         emit,
         on,
+        listen,
         async leave(): Promise<void> {
             await emitAck<void>(socket, LEAVE_EVENT, {
                 roomType: state.name,
@@ -201,10 +227,7 @@ function createJoinedRoom<TRoom extends RoomDefinition<any>>(
                         return state.presenceCurrent as PresenceFor<TRoom>;
                     },
                     onChange(handler: (presence: PresenceFor<TRoom>) => void): () => void {
-                        state.presenceListeners.add(handler);
-                        return () => {
-                            state.presenceListeners.delete(handler);
-                        };
+                        return registerPresenceListener(state, handler);
                     },
                     count(): Promise<number> {
                         return emitAck<number>(socket, PRESENCE_QUERY_EVENT, {
@@ -229,6 +252,32 @@ function createJoinedRoom<TRoom extends RoomDefinition<any>>(
     }) as JoinedRoom<TRoom>;
 }
 
+function registerEventListener<TRoom extends RoomDefinition<any>>(
+    state: JoinedRoomState<TRoom>,
+    key: string,
+    handler: (payload: unknown, meta: EventMetaFor<TRoom>) => void,
+): () => void {
+    const handlers = state.eventListeners.get(key) ?? new Set();
+    handlers.add(handler);
+    state.eventListeners.set(key, handlers);
+    return () => {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+            state.eventListeners.delete(key);
+        }
+    };
+}
+
+function registerPresenceListener<TRoom extends RoomDefinition<any>>(
+    state: JoinedRoomState<TRoom>,
+    handler: (presence: PresenceFor<TRoom>) => void,
+): () => void {
+    state.presenceListeners.add(handler);
+    return () => {
+        state.presenceListeners.delete(handler);
+    };
+}
+
 function getClientRegistry(socket: ClientSocketLike): ClientRegistry {
     const existing = clientRegistries.get(socket);
     if (existing) {
@@ -268,6 +317,19 @@ function installClientHandlers(socket: ClientSocketLike, registry: ClientRegistr
                 source: unknown;
             };
         }) => {
+            if (
+                !frame ||
+                typeof frame !== "object" ||
+                typeof frame.roomType !== "string" ||
+                typeof frame.roomId !== "string" ||
+                typeof frame.name !== "string" ||
+                !frame.meta ||
+                typeof frame.meta !== "object" ||
+                typeof frame.meta.sentAt !== "string"
+            ) {
+                return;
+            }
+
             const state = registry.joinedRooms.get(makeJoinedRoomKey(frame.roomType, frame.roomId));
             if (!state) {
                 return;
@@ -284,7 +346,11 @@ function installClientHandlers(socket: ClientSocketLike, registry: ClientRegistr
             } as EventMetaFor<any>;
 
             for (const handler of handlers) {
-                handler(frame.payload, meta);
+                try {
+                    handler(frame.payload, meta);
+                } catch {
+                    // Swallow per-listener errors to avoid breaking the event loop
+                }
             }
         };
 
@@ -294,6 +360,15 @@ function installClientHandlers(socket: ClientSocketLike, registry: ClientRegistr
 
     if (!registry.presenceHandlerInstalled) {
         const onPresence = (frame: { roomType: string; roomId: string; presence: unknown }) => {
+            if (
+                !frame ||
+                typeof frame !== "object" ||
+                typeof frame.roomType !== "string" ||
+                typeof frame.roomId !== "string"
+            ) {
+                return;
+            }
+
             const state = registry.joinedRooms.get(makeJoinedRoomKey(frame.roomType, frame.roomId));
             if (!state) {
                 return;
@@ -305,7 +380,11 @@ function installClientHandlers(socket: ClientSocketLike, registry: ClientRegistr
             }
 
             for (const handler of state.presenceListeners) {
-                handler(state.presenceCurrent);
+                try {
+                    handler(state.presenceCurrent);
+                } catch {
+                    // Swallow per-listener errors
+                }
             }
         };
 
@@ -405,7 +484,13 @@ function makeJoinedRoomKey(name: string, roomId: string): string {
 
 function emitAck<TValue>(socket: ClientSocketLike, eventName: string, payload: unknown): Promise<TValue> {
     return new Promise<TValue>((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Acknowledgement timeout for '${eventName}'`));
+        }, DEFAULT_ACK_TIMEOUT_MS);
+
         socket.emit(eventName, payload, (result: { ok: true; value: TValue } | { ok: false; error: string }) => {
+            clearTimeout(timer);
+
             if (!result || typeof result !== "object") {
                 reject(new Error("Invalid acknowledgement payload"));
                 return;
@@ -428,6 +513,10 @@ function setConnectionState(registry: ClientRegistry, next: ClientConnectionStat
 
     registry.connectionState = next;
     for (const listener of registry.connectionListeners) {
-        listener(next);
+        try {
+            listener(next);
+        } catch {
+            // Swallow per-listener errors
+        }
     }
 }