@openlivesync/server 1.0.2

package/README.md

@@ -0,0 +1,366 @@
+# @openlivesync/server
+
+Node.js server package for OpenLiveSync. Provides WebSocket-based presence, live collaboration events, and chat with pluggable storage.
+
+## Features
+
+- **Presence** — Track who’s in a room and arbitrary presence state (e.g. cursor, name, color). Join/leave and updates are broadcast to the room.
+- **Broadcast** — Send collaboration events to all other clients in the same room.
+- **Chat** — Room-based messages with optional persistence (in-memory, Postgres, MySQL, or SQLite).
+
+## Installation
+
+```bash
+npm install @openlivesync/server
+```
+
+For database-backed chat, install the driver you need (optional):
+
+```bash
+# One or more, depending on which storage you use:
+npm install pg
+npm install mysql2
+npm install better-sqlite3
+```
+
+## Quick start
+
+**Standalone server** (HTTP + WebSocket on port 3000, default in-memory chat):
+
+```ts
+import { createServer } from "@openlivesync/server";
+
+const server = createServer({ port: 3000 });
+// WebSocket endpoint: ws://localhost:3000/live
+// HTTP GET / returns "openlivesync"
+```
+
+**Attach to an existing HTTP server** (e.g. Express, Fastify):
+
+```ts
+import http from "node:http";
+import { createWebSocketServer } from "@openlivesync/server";
+
+const httpServer = http.createServer((req, res) => {
+  res.writeHead(200, { "Content-Type": "text/plain" });
+  res.end("Hello");
+});
+
+createWebSocketServer(httpServer, { path: "/live" });
+
+httpServer.listen(3000);
+// WebSocket: ws://localhost:3000/live
+```
+
+**Raw upgrade handler** (you control path and routing):
+
+```ts
+import http from "node:http";
+import { createWebSocketHandler } from "@openlivesync/server";
+
+const server = http.createServer(/* ... */);
+const handleUpgrade = createWebSocketHandler({ path: "/live" });
+server.on("upgrade", handleUpgrade);
+server.listen(3000);
+```
+
+## API
+
+### `createServer(options?)`
+
+Creates an `http.Server` that serves a simple root response and handles WebSocket upgrades. Returns the server with a `ws` property (the `WebSocketServer`).
+
+- **Options**: `ServerOptions` (includes `port`, default `3000`, and all `WebSocketServerOptions`).
+
+### `createWebSocketServer(server, options?)`
+
+Attaches WebSocket upgrade handling to an existing Node `http.Server`. Returns the `WebSocketServer` (e.g. for `wss.close()`).
+
+- **Options**: `WebSocketServerOptions`.
+
+### `createWebSocketHandler(options?)`
+
+Returns a function `(request, socket, head) => void` that you pass to `server.on("upgrade", handler)`. Use this when you want to handle the upgrade path yourself.
+
+- **Options**: `WebSocketServerOptions`.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | `string` | `"/live"` | WebSocket upgrade path. |
+| `onAuth` | `(req) => Promise<UserInfo \| null>` | — | If provided, runs on each upgrade. Return `null` to reject the connection (401). Return `{ userId?, name?, email?, provider?, ... }` to attach user info to the connection. |
+| `auth` | `AuthOptions` | — | Optional: decode/verify access tokens sent in `join_room`. Supports Google, Microsoft, and custom OAuth (see [Access token and OAuth](#access-token-and-oauth)). When tokens are decoded, `name`, `email`, and `provider` appear in presence and chat. |
+| `presenceThrottleMs` | `number` | `100` | Minimum ms between presence updates per connection. |
+| `chat` | `{ storage?, historyLimit? }` | — | Chat config. Omit `storage` to use in-memory. `historyLimit` is how many messages to send to new joiners (default `100`). |
+| `port` | `number` | `3000` | Only for `createServer`: port to listen on. |
+
+**Example with auth and custom path:**
+
+```ts
+import { createWebSocketServer } from "@openlivesync/server";
+import type { UserInfo } from "@openlivesync/server";
+import type { IncomingMessage } from "node:http";
+
+createWebSocketServer(httpServer, {
+  path: "/collab",
+  presenceThrottleMs: 50,
+  onAuth: async (req: IncomingMessage): Promise<UserInfo | null> => {
+    const token = req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+    if (!token) return null;
+    const user = await myAuthService.verify(token); // your logic
+    return user ? { userId: user.id, ...user } : null;
+  },
+  chat: { historyLimit: 200 },
+});
+```
+
+### Access token and OAuth
+
+Clients can send an optional **access token** in the `join_room` message payload. If the server is configured with `auth`, it will decode (and optionally verify) the JWT and attach **name**, **email**, and **provider** to the connection. These appear in `PresenceEntry` and in chat messages so other clients can show who is in the room.
+
+**Supported providers:** Google, Microsoft, and custom OAuth (JWKS URL or decode-only).
+
+```ts
+import { createWebSocketServer } from "@openlivesync/server";
+
+// Decode only (no verification) — e.g. for dev or trusted tokens
+createWebSocketServer(httpServer, {
+  auth: {},
+});
+
+// Google: verify with Google JWKS; optional clientId to validate audience
+createWebSocketServer(httpServer, {
+  auth: { google: { clientId: "your-google-client-id.apps.googleusercontent.com" } },
+});
+
+// Microsoft: verify with tenant JWKS
+createWebSocketServer(httpServer, {
+  auth: { microsoft: { tenantId: "your-tenant-id", clientId: "your-client-id" } },
+});
+
+// Custom: JWKS URL or decode-only
+createWebSocketServer(httpServer, {
+  auth: {
+    custom: { jwksUrl: "https://your-issuer/.well-known/jwks.json", issuer: "https://your-issuer" },
+    // or decode-only (no verification): custom: { decodeOnly: true }
+  },
+});
+```
+
+#### Token once at connect (recommended)
+
+Use the access token **only once** when the client connects; the server then recognizes the connection for its lifetime and you do not send the token again in `join_room`.
+
+1. Use **`createTokenAuth(authOptions)`** as your `onAuth` function. It reads the token from the upgrade request (query param `access_token` or header `Authorization: Bearer <token>`), decodes it with `decodeAccessToken`, and returns `UserInfo`. The connection gets identity (userId, name, email, provider) at connect time.
+2. **Client**: Send the token only at connect (e.g. use `getAuthToken` in client config so the token is appended to the WebSocket URL as `?access_token=...`). Do **not** pass `accessToken` to `joinRoom` or `useRoom` when using this flow.
+3. If the connection already has identity (from `onAuth`), the server ignores any `accessToken` in `join_room` and does not overwrite it.
+
+Browser WebSocket cannot send custom headers, so in the browser the token is typically sent as a query param (`access_token`). The default `tokenFromRequest` in `createTokenAuth` supports both query and `Authorization` header (e.g. for Node clients or proxies).
+
+```ts
+import { createWebSocketServer, createTokenAuth } from "@openlivesync/server";
+
+const authOptions = { google: { clientId: "your-client-id.apps.googleusercontent.com" } };
+createWebSocketServer(httpServer, {
+  onAuth: createTokenAuth(authOptions),
+});
+```
+
+You can also use `decodeAccessToken(token, authOptions)` or `createTokenAuth(authOptions)` from the package. Exported types: `AuthOptions`, `DecodedToken`, `CreateTokenAuthOptions`, `AuthGoogleConfig`, `AuthMicrosoftConfig`, `AuthCustomConfig`.
+
+## Chat storage
+
+Chat history can be in-memory (default) or backed by Postgres, MySQL, or SQLite. Pass a `ChatStorage` instance in `chat.storage`. All adapters implement `getHistory(roomId, limit?, offset?)`; messages are returned **oldest first**, and `limit`/`offset` support pagination.
+
+### In-memory (default)
+
+No extra install. Keeps the last N messages per room in process memory.
+
+```ts
+import {
+  createWebSocketServer,
+  createInMemoryChatStorage,
+} from "@openlivesync/server";
+
+const storage = createInMemoryChatStorage({ historyLimit: 100 });
+createWebSocketServer(server, {
+  chat: { storage, historyLimit: 100 },
+});
+```
+
+### Postgres
+
+Requires `pg`. Creates table `openlivesync_chat` if it doesn’t exist.
+
+```ts
+import {
+  createWebSocketServer,
+  createPostgresChatStorage,
+} from "@openlivesync/server";
+
+const storage = await createPostgresChatStorage(
+  { connectionString: process.env.DATABASE_URL },
+  { tableName: "openlivesync_chat", historyLimit: 100 }
+);
+createWebSocketServer(server, { chat: { storage, historyLimit: 100 } });
+```
+
+Connection config can be a string or an object:
+
+```ts
+await createPostgresChatStorage(
+  { host: "localhost", port: 5432, database: "app", user: "app", password: "secret" },
+  { tableName: "my_chat", historyLimit: 200 }
+);
+```
+
+### MySQL
+
+Requires `mysql2`. Creates the chat table if it doesn’t exist.
+
+```ts
+import {
+  createWebSocketServer,
+  createMySQLChatStorage,
+} from "@openlivesync/server";
+
+const storage = await createMySQLChatStorage(
+  {
+    host: "localhost",
+    port: 3306,
+    database: "app",
+    user: "app",
+    password: "secret",
+  },
+  { tableName: "openlivesync_chat", historyLimit: 100 }
+);
+createWebSocketServer(server, { chat: { storage, historyLimit: 100 } });
+```
+
+### SQLite
+
+Requires `better-sqlite3`. Pass a file path or `{ filename: "path/to/db.sqlite" }`.
+
+```ts
+import {
+  createWebSocketServer,
+  createSQLiteChatStorage,
+} from "@openlivesync/server";
+
+const storage = createSQLiteChatStorage("./data/chat.sqlite", {
+  tableName: "openlivesync_chat",
+  historyLimit: 100,
+});
+createWebSocketServer(server, { chat: { storage, historyLimit: 100 } });
+```
+
+### Custom storage
+
+Implement the `ChatStorage` interface and pass it as `chat.storage`:
+
+- **`append(roomId, message)`** — Persist a chat message.
+- **`getHistory(roomId, limit?, offset?)`** — Return messages for the room, **oldest first**. Use `limit` and `offset` for pagination (e.g. `getHistory(roomId, 20, 40)` returns the third page of 20 messages). Defaults: `limit` from adapter config, `offset` = 0.
+- **`close()`** — Optional cleanup.
+
+```ts
+import type { ChatStorage, ChatMessageInput } from "@openlivesync/server";
+import type { StoredChatMessage } from "@openlivesync/server";
+
+const myStorage: ChatStorage = {
+  async append(roomId: string, message: ChatMessageInput): Promise<void> {
+    // persist to your backend
+  },
+  async getHistory(
+    roomId: string,
+    limit?: number,
+    offset?: number
+  ): Promise<StoredChatMessage[]> {
+    // return messages oldest first; use limit/offset for pagination
+    return [];
+  },
+  async close(): Promise<void> {
+    // optional cleanup
+  },
+};
+```
+
+## Wire protocol
+
+Clients connect over WebSocket and send/receive JSON messages with a `type` field. The server handles these message types:
+
+### Client → Server
+
+| `type` | Purpose |
+|--------|--------|
+| `join_room` | Join a room. Payload: `{ roomId, presence?, accessToken? }`. If `accessToken` is sent and server has `auth` (or decode-only), the server decodes it and attaches name, email, provider to the connection; these appear in presence and chat. |
+| `leave_room` | Leave current room. Payload: `{ roomId? }` (optional). |
+| `update_presence` | Update presence. Payload: `{ presence }`. Throttled per connection. |
+| `broadcast_event` | Send collaboration event. Payload: `{ event, payload? }`. |
+| `send_chat` | Send chat message. Payload: `{ message, metadata? }`. |
+
+### Server → Client
+
+| `type` | Purpose |
+|--------|--------|
+| `room_joined` | Sent after join. Payload: `{ roomId, connectionId, presence, chatHistory? }`. Each entry in `presence` may include `userId`, `name`, `email`, `provider` when set from auth/token. |
+| `presence_updated` | Broadcast. Payload: `{ roomId, joined?, left?, updated? }`. `joined`/`updated` entries may include `name`, `email`, `provider`. |
+| `broadcast_event` | Relayed event. Payload: `{ roomId, connectionId, userId?, event, payload? }`. |
+| `chat_message` | Chat message. Payload: `{ roomId, connectionId, userId?, message, metadata? }`. |
+| `error` | Error. Payload: `{ code, message }`. |
+
+Presence is an arbitrary JSON object per connection (e.g. `{ cursor: { x, y }, name, color }`). The server does not interpret it; it only stores and broadcasts it.
+
+Use the same message types and constants in your client; they are exported from this package (see **Types** below).
+
+## Types and constants
+
+For building a compatible client or typing your app, the package exports:
+
+- **Server API**: `createServer`, `createWebSocketServer`, `createWebSocketHandler`, `ServerOptions`, `WebSocketServerOptions`, `ChatOptions`.
+- **Auth**: `decodeAccessToken`, `AuthOptions`, `DecodedToken`, `AuthGoogleConfig`, `AuthMicrosoftConfig`, `AuthCustomConfig`.
+- **Protocol types**: `Presence`, `UserInfo`, `ClientMessage`, `ServerMessage`, `JoinRoomPayload`, `RoomJoinedPayload`, `PresenceEntry`, `StoredChatMessage`, `ChatMessageInput`, etc.
+- **Message type constants**: `MSG_JOIN_ROOM`, `MSG_LEAVE_ROOM`, `MSG_UPDATE_PRESENCE`, `MSG_BROADCAST_EVENT`, `MSG_SEND_CHAT`, `MSG_ROOM_JOINED`, `MSG_PRESENCE_UPDATED`, `MSG_BROADCAST_EVENT_RELAY`, `MSG_CHAT_MESSAGE`, `MSG_ERROR`.
+- **Storage**: `ChatStorage`, `createInMemoryChatStorage`, `createPostgresChatStorage`, `createMySQLChatStorage`, `createSQLiteChatStorage`, and their option types.
+
+Example (client or shared code):
+
+```ts
+import type { ClientMessage, ServerMessage, Presence } from "@openlivesync/server";
+import { MSG_JOIN_ROOM, MSG_ROOM_JOINED } from "@openlivesync/server";
+```
+
+## Scripts
+
+- `npm run build` — Compile TypeScript to `dist/`.
+- `npm run clean` — Remove `dist/`.
+- `npm run test` — Run tests (Vitest).
+- `npm run test:watch` — Run tests in watch mode.
+- `npm run test:coverage` — Run tests with coverage (V8). Reports in `./coverage` (text summary in terminal, HTML in `coverage/index.html`, lcov for CI).
+
+## Testing
+
+Tests use [Vitest](https://vitest.dev/) and live next to the source as `*.test.ts` files.
+
+```bash
+npm run test
+```
+
+Coverage (V8) is available via:
+
+```bash
+npm run test:coverage
+```
+
+Reports are written to `./coverage` (text in the terminal, `coverage/index.html` for a browseable report, and `coverage/lcov.info` for CI). Test files, config, and type declarations are excluded from coverage.
+
+Coverage includes:
+
+- **Protocol** — Message type constants.
+- **In-memory storage** — `append`, `getHistory` (limit, offset), room isolation, cap at `historyLimit`.
+- **Room & RoomManager** — Join (room_joined with presence and chat history), leave (presence_updated), updatePresence, broadcastEvent, sendChat; getOrCreate, get, removeIfEmpty.
+- **WebSocket server** — Integration tests: connect, send `join_room`, receive `room_joined`; two clients in same room, send chat, second client receives `chat_message`.
+
+## License
+
+See repository root.

package/dist/auth/decode-token.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Decode and optionally verify OAuth/OpenID access tokens (JWT).
+ * Supports Google, Microsoft, and custom providers (JWKS or decode-only).
+ */
+export interface DecodedToken {
+    sub: string;
+    email?: string;
+    name?: string;
+    iss?: string;
+    provider?: string;
+}
+export interface AuthGoogleConfig {
+    /** Optional: validate audience (client ID). */
+    clientId?: string;
+}
+export interface AuthMicrosoftConfig {
+    tenantId: string;
+    /** Optional: validate audience (client ID). */
+    clientId?: string;
+}
+export interface AuthCustomConfig {
+    /** JWKS URL for signature verification. */
+    jwksUrl?: string;
+    /** Expected issuer (iss claim). */
+    issuer?: string;
+    /** If true, only decode payload (no verification). Use for dev or trusted tokens. */
+    decodeOnly?: boolean;
+}
+export interface AuthOptions {
+    google?: AuthGoogleConfig;
+    microsoft?: AuthMicrosoftConfig;
+    custom?: AuthCustomConfig;
+}
+/**
+ * Decode (and optionally verify) an access token JWT.
+ * Returns normalized claims (sub, email, name, provider) or null on failure.
+ * If no auth options are provided or a provider uses decodeOnly, only decoding is performed (no signature verification).
+ */
+export declare function decodeAccessToken(token: string, options?: AuthOptions): Promise<DecodedToken | null>;
+//# sourceMappingURL=decode-token.d.ts.map

package/dist/auth/decode-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-token.d.ts","sourceRoot":"","sources":["../../src/auth/decode-token.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAwCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAkD9B"}

package/dist/auth/decode-token.js

@@ -0,0 +1,93 @@
+/**
+ * Decode and optionally verify OAuth/OpenID access tokens (JWT).
+ * Supports Google, Microsoft, and custom providers (JWKS or decode-only).
+ */
+import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
+const GOOGLE_ISSUER = "https://accounts.google.com";
+const GOOGLE_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs";
+function normalizePayload(payload) {
+    const sub = typeof payload.sub === "string" ? payload.sub : "";
+    const email = typeof payload.email === "string"
+        ? payload.email
+        : typeof payload.preferred_username === "string"
+            ? payload.preferred_username
+            : undefined;
+    const name = typeof payload.name === "string"
+        ? payload.name
+        : [payload.given_name, payload.family_name]
+            .filter((x) => typeof x === "string")
+            .join(" ")
+            .trim() || undefined;
+    const iss = typeof payload.iss === "string" ? payload.iss : undefined;
+    let provider;
+    if (iss) {
+        if (iss.includes("accounts.google.com"))
+            provider = "google";
+        else if (iss.includes("login.microsoftonline.com"))
+            provider = "microsoft";
+        else
+            provider = "custom";
+    }
+    return { sub, email, name, iss, provider };
+}
+function getGoogleJwksUrl() {
+    return new URL(GOOGLE_JWKS_URL);
+}
+function getMicrosoftJwksUrl(tenantId) {
+    return new URL(`https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`);
+}
+/**
+ * Decode (and optionally verify) an access token JWT.
+ * Returns normalized claims (sub, email, name, provider) or null on failure.
+ * If no auth options are provided or a provider uses decodeOnly, only decoding is performed (no signature verification).
+ */
+export async function decodeAccessToken(token, options) {
+    if (!token || typeof token !== "string")
+        return null;
+    try {
+        const decoded = decodeJwt(token);
+        const payload = decoded;
+        const iss = typeof payload.iss === "string" ? payload.iss : undefined;
+        // Determine which provider config applies and whether to verify
+        let verifyUrl = null;
+        let issuer;
+        let audience;
+        if (options?.google && iss?.includes("accounts.google.com")) {
+            verifyUrl = getGoogleJwksUrl();
+            issuer = GOOGLE_ISSUER;
+            audience = options.google.clientId;
+        }
+        else if (options?.microsoft &&
+            iss?.includes("login.microsoftonline.com")) {
+            const tenantId = options.microsoft.tenantId;
+            verifyUrl = getMicrosoftJwksUrl(tenantId);
+            issuer = `https://login.microsoftonline.com/${tenantId}/v2.0`;
+            audience = options.microsoft.clientId;
+        }
+        else if (options?.custom) {
+            if (options.custom.decodeOnly) {
+                return normalizePayload(payload);
+            }
+            if (options.custom.jwksUrl) {
+                verifyUrl = new URL(options.custom.jwksUrl);
+                issuer = options.custom.issuer;
+            }
+        }
+        // No verification configured: decode only
+        if (!verifyUrl) {
+            return normalizePayload(payload);
+        }
+        const JWKS = createRemoteJWKSet(verifyUrl);
+        const verifyOptions = {};
+        if (issuer)
+            verifyOptions.issuer = issuer;
+        if (audience)
+            verifyOptions.audience = audience;
+        const { payload: verified } = await jwtVerify(token, JWKS, verifyOptions);
+        return normalizePayload(verified);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=decode-token.js.map

package/dist/auth/decode-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-token.js","sourceRoot":"","sources":["../../src/auth/decode-token.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAoChE,MAAM,aAAa,GAAG,6BAA6B,CAAC;AACpD,MAAM,eAAe,GAAG,4CAA4C,CAAC;AAErE,SAAS,gBAAgB,CAAC,OAAgC;IACxD,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/D,MAAM,KAAK,GACT,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;QAC/B,CAAC,CAAC,OAAO,CAAC,KAAK;QACf,CAAC,CAAC,OAAO,OAAO,CAAC,kBAAkB,KAAK,QAAQ;YAC9C,CAAC,CAAC,OAAO,CAAC,kBAAkB;YAC5B,CAAC,CAAC,SAAS,CAAC;IAClB,MAAM,IAAI,GACR,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAC9B,CAAC,CAAC,OAAO,CAAC,IAAI;QACd,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,WAAW,CAAC;aACtC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;aACpC,IAAI,CAAC,GAAG,CAAC;aACT,IAAI,EAAE,IAAI,SAAS,CAAC;IAC7B,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,IAAI,QAA4B,CAAC;IACjC,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,GAAG,CAAC,QAAQ,CAAC,qBAAqB,CAAC;YAAE,QAAQ,GAAG,QAAQ,CAAC;aACxD,IAAI,GAAG,CAAC,QAAQ,CAAC,2BAA2B,CAAC;YAAE,QAAQ,GAAG,WAAW,CAAC;;YACtE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAC7C,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO,IAAI,GAAG,CAAC,eAAe,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB;IAC3C,OAAO,IAAI,GAAG,CACZ,qCAAqC,QAAQ,sBAAsB,CACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAa,EACb,OAAqB;IAErB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAErD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,OAA6C,CAAC;QAC9D,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAEtE,gEAAgE;QAChE,IAAI,SAAS,GAAe,IAAI,CAAC;QACjC,IAAI,MAA0B,CAAC;QAC/B,IAAI,QAA4B,CAAC;QAEjC,IAAI,OAAO,EAAE,MAAM,IAAI,GAAG,EAAE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;YAC5D,SAAS,GAAG,gBAAgB,EAAE,CAAC;YAC/B,MAAM,GAAG,aAAa,CAAC;YACvB,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;QACrC,CAAC;aAAM,IACL,OAAO,EAAE,SAAS;YAClB,GAAG,EAAE,QAAQ,CAAC,2BAA2B,CAAC,EAC1C,CAAC;YACD,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC5C,SAAS,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAC1C,MAAM,GAAG,qCAAqC,QAAQ,OAAO,CAAC;YAC9D,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QACxC,CAAC;aAAM,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YAC3B,IAAI,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;gBAC9B,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC3B,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC5C,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;YACjC,CAAC;QACH,CAAC;QAED,0CAA0C;QAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAC3C,MAAM,aAAa,GAA2C,EAAE,CAAC;QACjE,IAAI,MAAM;YAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC;QAC1C,IAAI,QAAQ;YAAE,aAAa,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEhD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QAC1E,OAAO,gBAAgB,CAAC,QAA8C,CAAC,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Auth module: decode and verify OAuth/OpenID access tokens.
+ */
+export { decodeAccessToken, type DecodedToken, type AuthOptions, type AuthGoogleConfig, type AuthMicrosoftConfig, type AuthCustomConfig, } from "./decode-token.js";
+export { createTokenAuth, type CreateTokenAuthOptions, } from "./token-auth.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,iBAAiB,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,6 @@
+/**
+ * Auth module: decode and verify OAuth/OpenID access tokens.
+ */
+export { decodeAccessToken, } from "./decode-token.js";
+export { createTokenAuth, } from "./token-auth.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,iBAAiB,GAMlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,GAEhB,MAAM,iBAAiB,CAAC"}

package/dist/auth/token-auth.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Helper to use access token only at WebSocket connect (query or header).
+ * Returns an onAuth function that reads the token from the request and decodes it.
+ */
+import type { IncomingMessage } from "node:http";
+import type { UserInfo } from "../protocol.js";
+import type { AuthOptions } from "./decode-token.js";
+export interface CreateTokenAuthOptions {
+    /** Custom way to extract token from the upgrade request. Default: query access_token or Authorization Bearer. */
+    tokenFromRequest?: (req: IncomingMessage) => string | null;
+}
+/**
+ * Returns an onAuth function that reads the access token from the request (query or header),
+ * decodes it with decodeAccessToken, and returns UserInfo (userId, name, email, provider).
+ * Use this so the token is used only at connect; the connection is then recognized for its lifetime.
+ */
+export declare function createTokenAuth(authOptions: AuthOptions, options?: CreateTokenAuthOptions): (request: IncomingMessage) => Promise<UserInfo | null>;
+//# sourceMappingURL=token-auth.d.ts.map

package/dist/auth/token-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-auth.d.ts","sourceRoot":"","sources":["../../src/auth/token-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAkBrD,MAAM,WAAW,sBAAsB;IACrC,iHAAiH;IACjH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,MAAM,GAAG,IAAI,CAAC;CAC5D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,WAAW,EACxB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAexD"}

package/dist/auth/token-auth.js

@@ -0,0 +1,45 @@
+/**
+ * Helper to use access token only at WebSocket connect (query or header).
+ * Returns an onAuth function that reads the token from the request and decodes it.
+ */
+import { decodeAccessToken } from "./decode-token.js";
+function defaultTokenFromRequest(req) {
+    const url = req.url ?? "";
+    try {
+        const u = new URL(url, "http://localhost");
+        const fromQuery = u.searchParams.get("access_token");
+        if (fromQuery)
+            return fromQuery;
+    }
+    catch {
+        // ignore URL parse errors
+    }
+    const auth = req.headers.authorization;
+    if (typeof auth === "string" && /^Bearer\s+/i.test(auth)) {
+        return auth.replace(/^Bearer\s+/i, "").trim() || null;
+    }
+    return null;
+}
+/**
+ * Returns an onAuth function that reads the access token from the request (query or header),
+ * decodes it with decodeAccessToken, and returns UserInfo (userId, name, email, provider).
+ * Use this so the token is used only at connect; the connection is then recognized for its lifetime.
+ */
+export function createTokenAuth(authOptions, options) {
+    const tokenFromRequest = options?.tokenFromRequest ?? defaultTokenFromRequest;
+    return async (request) => {
+        const token = tokenFromRequest(request);
+        if (!token)
+            return null;
+        const decoded = await decodeAccessToken(token, authOptions);
+        if (!decoded)
+            return null;
+        return {
+            userId: decoded.sub,
+            name: decoded.name,
+            email: decoded.email,
+            provider: decoded.provider,
+        };
+    };
+}
+//# sourceMappingURL=token-auth.js.map

package/dist/auth/token-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-auth.js","sourceRoot":"","sources":["../../src/auth/token-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,SAAS,uBAAuB,CAAC,GAAoB;IACnD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACrD,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IACxD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAOD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,WAAwB,EACxB,OAAgC;IAEhC,MAAM,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,uBAAuB,CAAC;IAE9E,OAAO,KAAK,EAAE,OAAwB,EAA4B,EAAE;QAClE,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAC5D,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC1B,OAAO;YACL,MAAM,EAAE,OAAO,CAAC,GAAG;YACnB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/connection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Wraps a WebSocket: parse messages, throttle presence, dispatch to room.
+ */
+import type { WebSocket } from "ws";
+import type { RoomManager } from "./room-manager.js";
+import type { AuthOptions } from "./auth/index.js";
+export interface ConnectionOptions {
+    connectionId: string;
+    userId?: string;
+    userName?: string;
+    userEmail?: string;
+    provider?: string;
+    presenceThrottleMs: number;
+    roomManager: RoomManager;
+    auth?: AuthOptions;
+}
+export declare class Connection {
+    private readonly ws;
+    private readonly connectionId;
+    private userId;
+    private userName;
+    private userEmail;
+    private provider;
+    private readonly presenceThrottleMs;
+    private readonly roomManager;
+    private readonly auth;
+    private currentRoomId;
+    private lastPresenceUpdate;
+    private closed;
+    constructor(ws: WebSocket, options: ConnectionOptions);
+    private send;
+    private handleMessage;
+    private dispatch;
+    private handleClose;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAcpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAmBnD,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,MAAM,CAAS;gBAEX,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB;IAerD,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,aAAa;YA+BP,QAAQ;IAgFtB,OAAO,CAAC,WAAW;CAQpB"}