@pluv/platform-pluv 0.32.5 → 0.32.6

package/.turbo/turbo-build.log

@@ -1,18 +1,18 @@
 
-> @pluv/platform-pluv@0.32.5 build /home/runner/work/pluv/pluv/packages/platform-pluv
+> @pluv/platform-pluv@0.32.6 build /home/runner/work/pluv/pluv/packages/platform-pluv
 > tsup src/index.ts --format esm,cjs --dts
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
-CLI tsup v8.3.0
+CLI tsup v8.3.5
 CLI Target: es6
 ESM Build start
 CJS Build start
-ESM dist/index.mjs 4.82 KB
-ESM ⚡️ Build success in 114ms
-CJS dist/index.js 5.91 KB
-CJS ⚡️ Build success in 114ms
+ESM dist/index.mjs 8.83 KB
+ESM ⚡️ Build success in 80ms
+CJS dist/index.js 9.70 KB
+CJS ⚡️ Build success in 81ms
 DTS Build start
-DTS ⚡️ Build success in 6259ms
-DTS dist/index.d.mts 2.89 KB
-DTS dist/index.d.ts  2.89 KB
+DTS ⚡️ Build success in 6208ms
+DTS dist/index.d.mts 3.54 KB
+DTS dist/index.d.ts  3.54 KB

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @pluv/platform-pluv
 
+## 0.32.6
+
+### Patch Changes
+
+- 25292d4: Fix event payload types to only contain serializable fields.
+- c0956e7: Add `onUserConnected` and `onUserDisconnected` events on `PluvServer`.
+
+  ```ts
+  import { createIO } from "@pluv/io";
+
+  const io = createIO({
+    /* ... */
+  });
+
+  const ioServer = io.server({
+    // ...
+    onUserConnected: (event) => {
+      // ...
+    },
+    onUserDisconnected: (event) => {
+      // ...
+    },
+  });
+  ```
+
+- fc83a44: Enable `onUserConnected` and `onUserDisconnected` event listeners.
+- be1488f: Validate webhook signatures via webhook secrets.
+
+  ```ts
+  import { createIO } from "@pluv/platform-pluv";
+
+  const io = createIO({
+    // ...
+    // If you provide a webhookSecret
+    webhookSecret: "whsec_...",
+
+    // The following properties will be made available to configure
+    getInitialStorage: (event) => {
+      /* ... */
+    },
+    onRoomDeleted: (event) => {
+      /* ... */
+    },
+    onUserConnected: (event) => {
+      /* ... */
+    },
+    onUserDisconnected: (event) => {
+      /* ... */
+    },
+  });
+  ```
+
+- Updated dependencies [c0956e7]
+  - @pluv/io@0.32.6
+  - @pluv/crdt@0.32.6
+  - @pluv/types@0.32.6
+
 ## 0.32.5
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,5 +1,4 @@
-import { AbstractPlatform, WebSocketRegistrationMode, AbstractWebSocket, ConvertWebSocketConfig, WebSocketSerializedState, AbstractPlatformConfig, PluvIOListeners, GetInitialStorageFn, JWTEncodeParams, BaseUser as BaseUser$1 } from '@pluv/io';
-import * as hono_types from 'hono/types';
+import { AbstractPlatform, WebSocketRegistrationMode, AbstractWebSocket, ConvertWebSocketConfig, WebSocketSerializedState, AbstractPlatformConfig, JWTEncodeParams, GetInitialStorageFn, BaseUser as BaseUser$1 } from '@pluv/io';
 import * as hono from 'hono';
 import { BaseUser, InputZodLike, IOLike } from '@pluv/types';
 
@@ -25,7 +24,34 @@ interface PluvAuthorize<TUser extends BaseUser> {
 interface PluvIOEndpoints {
     createToken: string;
 }
-type PluvIOConfig<TUser extends BaseUser> = Partial<Pick<PluvIOListeners<PluvPlatform, PluvAuthorize<TUser>, {}, {}>, "onRoomDeleted">> & {
+type RoomDeletedMessageEventData = {
+    encodedState: string | null;
+    room: string;
+};
+type UserConnectedEventData<TUser extends BaseUser> = {
+    encodedState: string | null;
+    room: string;
+    user: TUser;
+};
+type UserDisconnectedEventData<TUser extends BaseUser> = {
+    encodedState: string | null;
+    room: string;
+    user: TUser;
+};
+type PluvIOListeners<TUser extends BaseUser> = {
+    getInitialStorage?: GetInitialStorageFn;
+    onRoomDeleted: (event: RoomDeletedMessageEventData) => void;
+    onUserConnected: (event: UserConnectedEventData<TUser>) => void;
+    onUserDisconnected: (event: UserDisconnectedEventData<TUser>) => void;
+};
+type WebhooksConfig<TUser extends BaseUser> = ({
+    webhookSecret?: undefined;
+} & {
+    [P in keyof PluvIOListeners<TUser>]?: undefined;
+}) | ({
+    webhookSecret: string;
+} & Partial<PluvIOListeners<TUser>>);
+type PluvIOConfig<TUser extends BaseUser> = WebhooksConfig<TUser> & {
     /**
      * @ignore
      * @readonly
@@ -38,7 +64,6 @@ type PluvIOConfig<TUser extends BaseUser> = Partial<Pick<PluvIOListeners<PluvPla
         user: InputZodLike<TUser>;
     };
     basePath: string;
-    getInitialStorage?: GetInitialStorageFn<PluvPlatform>;
     publicKey: string;
     secretKey: string;
 };
@@ -50,6 +75,7 @@ declare class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUs
     private readonly _listeners;
     private readonly _publicKey;
     private readonly _secretKey;
+    private readonly _webhookSecret?;
     /**
      * @ignore
      * @readonly
@@ -62,7 +88,7 @@ declare class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUs
         readonly platform: void;
     };
     get fetch(): (request: Request, Env?: unknown, executionCtx?: hono.ExecutionContext) => Response | Promise<Response>;
-    get handler(): (req: Request, requestContext: hono_types.FetchEventLike) => Response | Promise<Response>;
+    get handler(): (req: Request) => Response | Promise<Response>;
     private _webhooks;
     constructor(options: PluvIOConfig<TUser>);
     createToken(params: JWTEncodeParams<TUser, PluvPlatform>): Promise<string>;

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { AbstractPlatform, WebSocketRegistrationMode, AbstractWebSocket, ConvertWebSocketConfig, WebSocketSerializedState, AbstractPlatformConfig, PluvIOListeners, GetInitialStorageFn, JWTEncodeParams, BaseUser as BaseUser$1 } from '@pluv/io';
-import * as hono_types from 'hono/types';
+import { AbstractPlatform, WebSocketRegistrationMode, AbstractWebSocket, ConvertWebSocketConfig, WebSocketSerializedState, AbstractPlatformConfig, JWTEncodeParams, GetInitialStorageFn, BaseUser as BaseUser$1 } from '@pluv/io';
 import * as hono from 'hono';
 import { BaseUser, InputZodLike, IOLike } from '@pluv/types';
 
@@ -25,7 +24,34 @@ interface PluvAuthorize<TUser extends BaseUser> {
 interface PluvIOEndpoints {
     createToken: string;
 }
-type PluvIOConfig<TUser extends BaseUser> = Partial<Pick<PluvIOListeners<PluvPlatform, PluvAuthorize<TUser>, {}, {}>, "onRoomDeleted">> & {
+type RoomDeletedMessageEventData = {
+    encodedState: string | null;
+    room: string;
+};
+type UserConnectedEventData<TUser extends BaseUser> = {
+    encodedState: string | null;
+    room: string;
+    user: TUser;
+};
+type UserDisconnectedEventData<TUser extends BaseUser> = {
+    encodedState: string | null;
+    room: string;
+    user: TUser;
+};
+type PluvIOListeners<TUser extends BaseUser> = {
+    getInitialStorage?: GetInitialStorageFn;
+    onRoomDeleted: (event: RoomDeletedMessageEventData) => void;
+    onUserConnected: (event: UserConnectedEventData<TUser>) => void;
+    onUserDisconnected: (event: UserDisconnectedEventData<TUser>) => void;
+};
+type WebhooksConfig<TUser extends BaseUser> = ({
+    webhookSecret?: undefined;
+} & {
+    [P in keyof PluvIOListeners<TUser>]?: undefined;
+}) | ({
+    webhookSecret: string;
+} & Partial<PluvIOListeners<TUser>>);
+type PluvIOConfig<TUser extends BaseUser> = WebhooksConfig<TUser> & {
     /**
      * @ignore
      * @readonly
@@ -38,7 +64,6 @@ type PluvIOConfig<TUser extends BaseUser> = Partial<Pick<PluvIOListeners<PluvPla
         user: InputZodLike<TUser>;
     };
     basePath: string;
-    getInitialStorage?: GetInitialStorageFn<PluvPlatform>;
     publicKey: string;
     secretKey: string;
 };
@@ -50,6 +75,7 @@ declare class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUs
     private readonly _listeners;
     private readonly _publicKey;
     private readonly _secretKey;
+    private readonly _webhookSecret?;
     /**
      * @ignore
      * @readonly
@@ -62,7 +88,7 @@ declare class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUs
         readonly platform: void;
     };
     get fetch(): (request: Request, Env?: unknown, executionCtx?: hono.ExecutionContext) => Response | Promise<Response>;
-    get handler(): (req: Request, requestContext: hono_types.FetchEventLike) => Response | Promise<Response>;
+    get handler(): (req: Request) => Response | Promise<Response>;
     private _webhooks;
     constructor(options: PluvIOConfig<TUser>);
     createToken(params: JWTEncodeParams<TUser, PluvPlatform>): Promise<string>;

package/dist/index.js

@@ -62,6 +62,9 @@ module.exports = __toCommonJS(src_exports);
 var import_hono = require("hono");
 var import_vercel = require("hono/vercel");
 
+// src/constants.ts
+var SIGNATURE_HEADER = "x-pluv-signature-256";
+
 // src/schemas.ts
 var import_zod = require("zod");
 var ZodEventInitialStorage = import_zod.z.object({
@@ -77,15 +80,100 @@ var ZodEventRoomDeleted = import_zod.z.object({
     storage: import_zod.z.string().nullable()
   })
 });
-var ZodEvent = import_zod.z.discriminatedUnion("event", [ZodEventInitialStorage, ZodEventRoomDeleted]);
+var ZodEventUserConnected = import_zod.z.object({
+  event: import_zod.z.literal("user-connected"),
+  data: import_zod.z.object({
+    room: import_zod.z.string(),
+    storage: import_zod.z.string().nullable(),
+    user: import_zod.z.object({
+      id: import_zod.z.string()
+    }).passthrough()
+  })
+});
+var ZodEventUserDisconnected = import_zod.z.object({
+  event: import_zod.z.literal("user-disconnected"),
+  data: import_zod.z.object({
+    room: import_zod.z.string(),
+    storage: import_zod.z.string().nullable(),
+    user: import_zod.z.object({
+      id: import_zod.z.string()
+    }).passthrough()
+  })
+});
+var ZodEvent = import_zod.z.discriminatedUnion("event", [
+  ZodEventInitialStorage,
+  ZodEventRoomDeleted,
+  ZodEventUserConnected,
+  ZodEventUserDisconnected
+]);
+
+// src/shared/getCrypto.ts
+var getCrypto = () => {
+  if (typeof crypto !== "undefined") {
+    return crypto;
+  }
+  if (typeof require === "function") {
+    return require("crypto").webcrypto;
+  }
+  throw new Error("Missing crypto module");
+};
+
+// src/shared/createHmac.ts
+var createHmac = (params) => __async(void 0, null, function* () {
+  const { payload, secret } = params;
+  if (!payload || !secret) throw new Error("Secret and payload are required to sign payload");
+  const encoder = new TextEncoder();
+  const keyBytes = encoder.encode(secret);
+  const crypto2 = getCrypto();
+  const algorithm = { name: "HMAC", hash: { name: "SHA-256" } };
+  const extractable = false;
+  const key = yield crypto2.subtle.importKey("raw", keyBytes, algorithm, extractable, ["sign", "verify"]);
+  const payloadBytes = encoder.encode(payload);
+  const signature = yield crypto2.subtle.sign("HMAC", key, payloadBytes);
+  const hmac = Array.from(new Uint8Array(signature)).map((b) => ("0" + b.toString(16)).slice(-2)).join("");
+  return { algorithm: "sha256", hmac };
+});
+
+// src/shared/timingSafeEqual.ts
+var timingSafeEqual = (a, b) => {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a[i] ^ b[i];
+  }
+  return result === 0;
+};
+
+// src/shared/verifyWebhook.ts
+var verifyWebhook = (params) => __async(void 0, null, function* () {
+  const { payload, secret, signature } = params;
+  if (!secret || !payload || !signature) {
+    throw new Error("Secret, payload and signature are required to verify payload");
+  }
+  const { hmac } = yield createHmac({ payload, secret });
+  if (hmac.length !== signature.length) return false;
+  const encoder = new TextEncoder();
+  const verificationBytes = encoder.encode(hmac);
+  const signatureBytes = encoder.encode(signature);
+  if (verificationBytes.length !== signatureBytes.length) return false;
+  return timingSafeEqual(verificationBytes, signatureBytes);
+});
 
 // src/PluvIO.ts
 var PluvIO = class {
   constructor(options) {
     this._webhooks = new import_hono.Hono().basePath("/").post("/event", (c) => __async(this, null, function* () {
       var _a, _b;
-      const body = yield c.req.json();
-      const parsed = ZodEvent.safeParse(body);
+      const signature = c.req.header(SIGNATURE_HEADER);
+      if (!this._webhookSecret || !signature) return c.json({ error: "Unauthorized" }, 401);
+      const payload = yield c.req.json();
+      const verified = yield verifyWebhook({
+        payload,
+        signature,
+        secret: this._webhookSecret
+      });
+      if (!verified) return c.json({ error: "Unauthorized" }, 401);
+      const parsed = ZodEvent.safeParse(payload);
       if (!parsed.success) return c.json({ data: { ok: true } }, 200);
       const { event, data } = parsed.data;
       switch (event) {
@@ -97,14 +185,37 @@ var PluvIO = class {
         case "room-deleted": {
           const room = data.room;
           const encodedState = data.storage;
-          yield Promise.resolve(this._listeners.onRoomDeleted({ context: {}, encodedState, room }));
+          yield Promise.resolve(this._listeners.onRoomDeleted({ encodedState, room }));
           return c.json({ data: { room } }, 200);
         }
+        case "user-connected": {
+          const room = data.room;
+          const encodedState = data.storage;
+          const user = data.user;
+          yield Promise.resolve(this._listeners.onUserConnected({ encodedState, room, user }));
+        }
+        case "user-disconnected": {
+          const room = data.room;
+          const encodedState = data.storage;
+          const user = data.user;
+          yield Promise.resolve(this._listeners.onUserDisconnected({ encodedState, room, user }));
+        }
         default:
           return c.json({ data: { ok: true } }, 200);
       }
     }));
-    const { _defs, authorize, basePath, onRoomDeleted, getInitialStorage, publicKey, secretKey } = options;
+    const {
+      _defs,
+      authorize,
+      basePath,
+      getInitialStorage,
+      onRoomDeleted,
+      onUserConnected,
+      onUserDisconnected,
+      publicKey,
+      secretKey,
+      webhookSecret
+    } = options;
     this._authorize = {
       required: true,
       secret: "",
@@ -115,9 +226,14 @@ var PluvIO = class {
       createToken: "https://pluv.io/api/room/token"
     }, _defs == null ? void 0 : _defs.endpoints);
     this._getInitialStorage = getInitialStorage;
-    this._listeners = { onRoomDeleted: (event) => onRoomDeleted == null ? void 0 : onRoomDeleted(event) };
+    this._listeners = {
+      onRoomDeleted: (event) => onRoomDeleted == null ? void 0 : onRoomDeleted(event),
+      onUserConnected: (event) => onUserConnected == null ? void 0 : onUserConnected(event),
+      onUserDisconnected: (event) => onUserDisconnected == null ? void 0 : onUserDisconnected(event)
+    };
     this._publicKey = publicKey;
     this._secretKey = secretKey;
+    this._webhookSecret = webhookSecret;
   }
   /**
    * @ignore
@@ -161,9 +277,7 @@ var PluvIO = class {
         throw new Error("Authorization failed");
       }
       const token = yield res.text().catch(() => null);
-      if (typeof token !== "string") {
-        throw new Error("Authorization failed");
-      }
+      if (typeof token !== "string") throw new Error("Authorization failed");
       return token;
     });
   }

package/dist/index.mjs

@@ -14,6 +14,12 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -39,6 +45,9 @@ var __async = (__this, __arguments, generator) => {
 import { Hono } from "hono";
 import { handle } from "hono/vercel";
 
+// src/constants.ts
+var SIGNATURE_HEADER = "x-pluv-signature-256";
+
 // src/schemas.ts
 import { z } from "zod";
 var ZodEventInitialStorage = z.object({
@@ -54,15 +63,100 @@ var ZodEventRoomDeleted = z.object({
     storage: z.string().nullable()
   })
 });
-var ZodEvent = z.discriminatedUnion("event", [ZodEventInitialStorage, ZodEventRoomDeleted]);
+var ZodEventUserConnected = z.object({
+  event: z.literal("user-connected"),
+  data: z.object({
+    room: z.string(),
+    storage: z.string().nullable(),
+    user: z.object({
+      id: z.string()
+    }).passthrough()
+  })
+});
+var ZodEventUserDisconnected = z.object({
+  event: z.literal("user-disconnected"),
+  data: z.object({
+    room: z.string(),
+    storage: z.string().nullable(),
+    user: z.object({
+      id: z.string()
+    }).passthrough()
+  })
+});
+var ZodEvent = z.discriminatedUnion("event", [
+  ZodEventInitialStorage,
+  ZodEventRoomDeleted,
+  ZodEventUserConnected,
+  ZodEventUserDisconnected
+]);
+
+// src/shared/getCrypto.ts
+var getCrypto = () => {
+  if (typeof crypto !== "undefined") {
+    return crypto;
+  }
+  if (typeof __require === "function") {
+    return __require("node:crypto").webcrypto;
+  }
+  throw new Error("Missing crypto module");
+};
+
+// src/shared/createHmac.ts
+var createHmac = (params) => __async(void 0, null, function* () {
+  const { payload, secret } = params;
+  if (!payload || !secret) throw new Error("Secret and payload are required to sign payload");
+  const encoder = new TextEncoder();
+  const keyBytes = encoder.encode(secret);
+  const crypto2 = getCrypto();
+  const algorithm = { name: "HMAC", hash: { name: "SHA-256" } };
+  const extractable = false;
+  const key = yield crypto2.subtle.importKey("raw", keyBytes, algorithm, extractable, ["sign", "verify"]);
+  const payloadBytes = encoder.encode(payload);
+  const signature = yield crypto2.subtle.sign("HMAC", key, payloadBytes);
+  const hmac = Array.from(new Uint8Array(signature)).map((b) => ("0" + b.toString(16)).slice(-2)).join("");
+  return { algorithm: "sha256", hmac };
+});
+
+// src/shared/timingSafeEqual.ts
+var timingSafeEqual = (a, b) => {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a[i] ^ b[i];
+  }
+  return result === 0;
+};
+
+// src/shared/verifyWebhook.ts
+var verifyWebhook = (params) => __async(void 0, null, function* () {
+  const { payload, secret, signature } = params;
+  if (!secret || !payload || !signature) {
+    throw new Error("Secret, payload and signature are required to verify payload");
+  }
+  const { hmac } = yield createHmac({ payload, secret });
+  if (hmac.length !== signature.length) return false;
+  const encoder = new TextEncoder();
+  const verificationBytes = encoder.encode(hmac);
+  const signatureBytes = encoder.encode(signature);
+  if (verificationBytes.length !== signatureBytes.length) return false;
+  return timingSafeEqual(verificationBytes, signatureBytes);
+});
 
 // src/PluvIO.ts
 var PluvIO = class {
   constructor(options) {
     this._webhooks = new Hono().basePath("/").post("/event", (c) => __async(this, null, function* () {
       var _a, _b;
-      const body = yield c.req.json();
-      const parsed = ZodEvent.safeParse(body);
+      const signature = c.req.header(SIGNATURE_HEADER);
+      if (!this._webhookSecret || !signature) return c.json({ error: "Unauthorized" }, 401);
+      const payload = yield c.req.json();
+      const verified = yield verifyWebhook({
+        payload,
+        signature,
+        secret: this._webhookSecret
+      });
+      if (!verified) return c.json({ error: "Unauthorized" }, 401);
+      const parsed = ZodEvent.safeParse(payload);
       if (!parsed.success) return c.json({ data: { ok: true } }, 200);
       const { event, data } = parsed.data;
       switch (event) {
@@ -74,14 +168,37 @@ var PluvIO = class {
         case "room-deleted": {
           const room = data.room;
           const encodedState = data.storage;
-          yield Promise.resolve(this._listeners.onRoomDeleted({ context: {}, encodedState, room }));
+          yield Promise.resolve(this._listeners.onRoomDeleted({ encodedState, room }));
           return c.json({ data: { room } }, 200);
         }
+        case "user-connected": {
+          const room = data.room;
+          const encodedState = data.storage;
+          const user = data.user;
+          yield Promise.resolve(this._listeners.onUserConnected({ encodedState, room, user }));
+        }
+        case "user-disconnected": {
+          const room = data.room;
+          const encodedState = data.storage;
+          const user = data.user;
+          yield Promise.resolve(this._listeners.onUserDisconnected({ encodedState, room, user }));
+        }
         default:
           return c.json({ data: { ok: true } }, 200);
       }
     }));
-    const { _defs, authorize, basePath, onRoomDeleted, getInitialStorage, publicKey, secretKey } = options;
+    const {
+      _defs,
+      authorize,
+      basePath,
+      getInitialStorage,
+      onRoomDeleted,
+      onUserConnected,
+      onUserDisconnected,
+      publicKey,
+      secretKey,
+      webhookSecret
+    } = options;
     this._authorize = {
       required: true,
       secret: "",
@@ -92,9 +209,14 @@ var PluvIO = class {
       createToken: "https://pluv.io/api/room/token"
     }, _defs == null ? void 0 : _defs.endpoints);
     this._getInitialStorage = getInitialStorage;
-    this._listeners = { onRoomDeleted: (event) => onRoomDeleted == null ? void 0 : onRoomDeleted(event) };
+    this._listeners = {
+      onRoomDeleted: (event) => onRoomDeleted == null ? void 0 : onRoomDeleted(event),
+      onUserConnected: (event) => onUserConnected == null ? void 0 : onUserConnected(event),
+      onUserDisconnected: (event) => onUserDisconnected == null ? void 0 : onUserDisconnected(event)
+    };
     this._publicKey = publicKey;
     this._secretKey = secretKey;
+    this._webhookSecret = webhookSecret;
   }
   /**
    * @ignore
@@ -138,9 +260,7 @@ var PluvIO = class {
         throw new Error("Authorization failed");
       }
       const token = yield res.text().catch(() => null);
-      if (typeof token !== "string") {
-        throw new Error("Authorization failed");
-      }
+      if (typeof token !== "string") throw new Error("Authorization failed");
       return token;
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pluv/platform-pluv",
-  "version": "0.32.5",
+  "version": "0.32.6",
   "description": "@pluv/io adapter for pluv.io",
   "author": "leedavidcs",
   "license": "MIT",
@@ -17,19 +17,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@types/node": "^22.7.8",
-    "hono": "^4.6.6",
+    "@types/node": "^22.8.1",
+    "hono": "^4.6.7",
     "zod": "^3.23.8",
-    "@pluv/crdt": "^0.32.5",
-    "@pluv/io": "^0.32.5",
-    "@pluv/types": "^0.32.5"
+    "@pluv/crdt": "^0.32.6",
+    "@pluv/io": "^0.32.6",
+    "@pluv/types": "^0.32.6"
   },
   "devDependencies": {
     "eslint": "^8.57.0",
-    "tsup": "^8.3.0",
+    "tsup": "^8.3.5",
     "typescript": "^5.6.3",
-    "@pluv/tsconfig": "^0.32.5",
-    "eslint-config-pluv": "^0.32.5"
+    "@pluv/tsconfig": "^0.32.6",
+    "eslint-config-pluv": "^0.32.6"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",

package/src/PluvIO.ts

@@ -1,9 +1,11 @@
-import type { GetInitialStorageFn, JWTEncodeParams, PluvIOListeners } from "@pluv/io";
+import type { GetInitialStorageFn, JWTEncodeParams } from "@pluv/io";
 import type { BaseUser, IOLike, InputZodLike } from "@pluv/types";
 import { Hono } from "hono";
 import { handle } from "hono/vercel";
+import { SIGNATURE_HEADER } from "./constants";
 import type { PluvPlatform } from "./PluvPlatform";
 import { ZodEvent } from "./schemas";
+import { verifyWebhook } from "./shared";
 
 interface PluvAuthorize<TUser extends BaseUser> {
     required: true;
@@ -15,9 +17,35 @@ interface PluvIOEndpoints {
     createToken: string;
 }
 
-export type PluvIOConfig<TUser extends BaseUser> = Partial<
-    Pick<PluvIOListeners<PluvPlatform, PluvAuthorize<TUser>, {}, {}>, "onRoomDeleted">
-> & {
+type RoomDeletedMessageEventData = {
+    encodedState: string | null;
+    room: string;
+};
+
+type UserConnectedEventData<TUser extends BaseUser> = {
+    encodedState: string | null;
+    room: string;
+    user: TUser;
+};
+
+type UserDisconnectedEventData<TUser extends BaseUser> = {
+    encodedState: string | null;
+    room: string;
+    user: TUser;
+};
+
+type PluvIOListeners<TUser extends BaseUser> = {
+    getInitialStorage?: GetInitialStorageFn;
+    onRoomDeleted: (event: RoomDeletedMessageEventData) => void;
+    onUserConnected: (event: UserConnectedEventData<TUser>) => void;
+    onUserDisconnected: (event: UserDisconnectedEventData<TUser>) => void;
+};
+
+type WebhooksConfig<TUser extends BaseUser> =
+    | ({ webhookSecret?: undefined } & { [P in keyof PluvIOListeners<TUser>]?: undefined })
+    | ({ webhookSecret: string } & Partial<PluvIOListeners<TUser>>);
+
+export type PluvIOConfig<TUser extends BaseUser> = WebhooksConfig<TUser> & {
     /**
      * @ignore
      * @readonly
@@ -30,7 +58,6 @@ export type PluvIOConfig<TUser extends BaseUser> = Partial<
         user: InputZodLike<TUser>;
     };
     basePath: string;
-    getInitialStorage?: GetInitialStorageFn<PluvPlatform>;
     publicKey: string;
     secretKey: string;
 };
@@ -39,10 +66,11 @@ export class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUse
     private readonly _authorize: PluvAuthorize<TUser>;
     private readonly _basePath: string;
     private readonly _endpoints: PluvIOEndpoints;
-    private readonly _getInitialStorage?: GetInitialStorageFn<PluvPlatform>;
-    private readonly _listeners: Pick<PluvIOListeners<PluvPlatform, PluvAuthorize<TUser>, {}, {}>, "onRoomDeleted">;
+    private readonly _getInitialStorage?: GetInitialStorageFn;
+    private readonly _listeners: PluvIOListeners<TUser>;
     private readonly _publicKey: string;
     private readonly _secretKey: string;
+    private readonly _webhookSecret?: string;
 
     /**
      * @ignore
@@ -73,8 +101,21 @@ export class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUse
     }
 
     private _webhooks = new Hono().basePath("/").post("/event", async (c) => {
-        const body = await c.req.json();
-        const parsed = ZodEvent.safeParse(body);
+        const signature = c.req.header(SIGNATURE_HEADER);
+
+        if (!this._webhookSecret || !signature) return c.json({ error: "Unauthorized" }, 401);
+
+        const payload = await c.req.json();
+
+        const verified = await verifyWebhook({
+            payload,
+            signature,
+            secret: this._webhookSecret,
+        });
+
+        if (!verified) return c.json({ error: "Unauthorized" }, 401);
+
+        const parsed = ZodEvent.safeParse(payload);
 
         if (!parsed.success) return c.json({ data: { ok: true } }, 200);
 
@@ -91,17 +132,42 @@ export class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUse
                 const room = data.room;
                 const encodedState = data.storage;
 
-                await Promise.resolve(this._listeners.onRoomDeleted({ context: {}, encodedState, room }));
+                await Promise.resolve(this._listeners.onRoomDeleted({ encodedState, room }));
 
                 return c.json({ data: { room } }, 200);
             }
+            case "user-connected": {
+                const room = data.room;
+                const encodedState = data.storage;
+                const user = data.user as TUser;
+
+                await Promise.resolve(this._listeners.onUserConnected({ encodedState, room, user }));
+            }
+            case "user-disconnected": {
+                const room = data.room;
+                const encodedState = data.storage;
+                const user = data.user as TUser;
+
+                await Promise.resolve(this._listeners.onUserDisconnected({ encodedState, room, user }));
+            }
             default:
                 return c.json({ data: { ok: true } }, 200);
         }
     });
 
     constructor(options: PluvIOConfig<TUser>) {
-        const { _defs, authorize, basePath, onRoomDeleted, getInitialStorage, publicKey, secretKey } = options;
+        const {
+            _defs,
+            authorize,
+            basePath,
+            getInitialStorage,
+            onRoomDeleted,
+            onUserConnected,
+            onUserDisconnected,
+            publicKey,
+            secretKey,
+            webhookSecret,
+        } = options;
 
         this._authorize = {
             required: true,
@@ -114,9 +180,14 @@ export class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUse
             ..._defs?.endpoints,
         };
         this._getInitialStorage = getInitialStorage;
-        this._listeners = { onRoomDeleted: (event) => onRoomDeleted?.(event) };
+        this._listeners = {
+            onRoomDeleted: (event) => onRoomDeleted?.(event),
+            onUserConnected: (event) => onUserConnected?.(event),
+            onUserDisconnected: (event) => onUserDisconnected?.(event),
+        };
         this._publicKey = publicKey;
         this._secretKey = secretKey;
+        this._webhookSecret = webhookSecret;
     }
 
     public async createToken(params: JWTEncodeParams<TUser, PluvPlatform>): Promise<string> {
@@ -140,9 +211,7 @@ export class PluvIO<TUser extends BaseUser> implements IOLike<PluvAuthorize<TUse
 
         const token = await res.text().catch(() => null);
 
-        if (typeof token !== "string") {
-            throw new Error("Authorization failed");
-        }
+        if (typeof token !== "string") throw new Error("Authorization failed");
 
         return token;
     }

package/src/constants.ts

@@ -0,0 +1 @@
+export const SIGNATURE_HEADER = "x-pluv-signature-256";

package/src/schemas.ts

@@ -15,4 +15,35 @@ const ZodEventRoomDeleted = z.object({
     }),
 });
 
-export const ZodEvent = z.discriminatedUnion("event", [ZodEventInitialStorage, ZodEventRoomDeleted]);
+const ZodEventUserConnected = z.object({
+    event: z.literal("user-connected"),
+    data: z.object({
+        room: z.string(),
+        storage: z.string().nullable(),
+        user: z
+            .object({
+                id: z.string(),
+            })
+            .passthrough(),
+    }),
+});
+
+const ZodEventUserDisconnected = z.object({
+    event: z.literal("user-disconnected"),
+    data: z.object({
+        room: z.string(),
+        storage: z.string().nullable(),
+        user: z
+            .object({
+                id: z.string(),
+            })
+            .passthrough(),
+    }),
+});
+
+export const ZodEvent = z.discriminatedUnion("event", [
+    ZodEventInitialStorage,
+    ZodEventRoomDeleted,
+    ZodEventUserConnected,
+    ZodEventUserDisconnected,
+]);

package/src/shared/createHmac.ts

@@ -0,0 +1,38 @@
+import type { webcrypto } from "crypto";
+import { getCrypto } from "./getCrypto";
+
+export interface CreateHmacParams {
+    payload: string;
+    secret: string;
+}
+
+export type CreateHmacResult = {
+    algorithm: "sha256";
+    hmac: string;
+};
+
+export const createHmac = async (params: CreateHmacParams): Promise<CreateHmacResult> => {
+    const { payload, secret } = params;
+
+    if (!payload || !secret) throw new Error("Secret and payload are required to sign payload");
+
+    const encoder = new TextEncoder();
+    const keyBytes = encoder.encode(secret);
+
+    const crypto = getCrypto();
+
+    const algorithm: webcrypto.HmacImportParams = { name: "HMAC", hash: { name: "SHA-256" } };
+    const extractable = false;
+
+    const key = await crypto.subtle.importKey("raw", keyBytes, algorithm, extractable, ["sign", "verify"]);
+    const payloadBytes = encoder.encode(payload);
+
+    const signature = await crypto.subtle.sign("HMAC", key, payloadBytes);
+
+    // Convert the signature to a hex string
+    const hmac = Array.from(new Uint8Array(signature))
+        .map((b) => ("0" + b.toString(16)).slice(-2))
+        .join("");
+
+    return { algorithm: "sha256", hmac };
+};

package/src/shared/getCrypto.ts

@@ -0,0 +1,16 @@
+import type { webcrypto } from "crypto";
+
+export const getCrypto = (): webcrypto.Crypto => {
+    if (typeof crypto !== "undefined") {
+        // In a browser or Web Worker (including Cloudflare Workers)
+        return crypto;
+    }
+
+    if (typeof require === "function") {
+        // In Node.js
+        // Node 15+ supports `crypto.webcrypto`
+        return require("node:crypto").webcrypto as webcrypto.Crypto;
+    }
+
+    throw new Error("Missing crypto module");
+};

package/src/shared/index.ts

@@ -0,0 +1,8 @@
+export { createHmac } from "./createHmac";
+export type { CreateHmacParams } from "./createHmac";
+export { getCrypto } from "./getCrypto";
+export { signWebhook } from "./signWebhook";
+export type { SignWebhookParams } from "./signWebhook";
+export { timingSafeEqual } from "./timingSafeEqual";
+export { verifyWebhook } from "./verifyWebhook";
+export type { VerifyWebhookParams } from "./verifyWebhook";

package/src/shared/signWebhook.ts

@@ -0,0 +1,10 @@
+import type { CreateHmacParams } from "./createHmac";
+import { createHmac } from "./createHmac";
+
+export type SignWebhookParams = CreateHmacParams;
+
+export const signWebhook = async (params: SignWebhookParams): Promise<string> => {
+    const { algorithm, hmac } = await createHmac(params);
+
+    return `${algorithm}=${hmac}`;
+};

package/src/shared/timingSafeEqual.ts

@@ -0,0 +1,10 @@
+export const timingSafeEqual = (a: Uint8Array, b: Uint8Array): boolean => {
+    if (a.length !== b.length) return false; // Lengths are different
+
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a[i] ^ b[i]; // XOR each byte
+    }
+
+    return result === 0; // If all bytes are equal, result will be 0
+};

package/src/shared/verifyWebhook.ts

@@ -0,0 +1,28 @@
+import { createHmac } from "./createHmac";
+import { timingSafeEqual } from "./timingSafeEqual";
+
+export interface VerifyWebhookParams {
+    payload: string;
+    secret: string;
+    signature: string;
+}
+
+export const verifyWebhook = async (params: VerifyWebhookParams): Promise<boolean> => {
+    const { payload, secret, signature } = params;
+
+    if (!secret || !payload || !signature) {
+        throw new Error("Secret, payload and signature are required to verify payload");
+    }
+
+    const { hmac } = await createHmac({ payload, secret });
+
+    if (hmac.length !== signature.length) return false;
+
+    const encoder = new TextEncoder();
+    const verificationBytes = encoder.encode(hmac);
+    const signatureBytes = encoder.encode(signature);
+
+    if (verificationBytes.length !== signatureBytes.length) return false;
+
+    return timingSafeEqual(verificationBytes, signatureBytes);
+};