@pluv/platform-pluv 0.0.0-experimental-20250527040415

package/src/PluvPlatform.ts

@@ -0,0 +1,329 @@
+import type {
+    AbstractPlatformConfig,
+    AbstractWebSocket,
+    BaseUser,
+    ConvertWebSocketConfig,
+    GetInitialStorageFn,
+    JWTEncodeParams,
+    PluvContext,
+    WebSocketSerializedState,
+} from "@pluv/io";
+import { AbstractPlatform } from "@pluv/io";
+import type { MaybePromise } from "@pluv/types";
+import stringify from "fast-json-stable-stringify";
+import type { Context } from "hono";
+import { Hono } from "hono";
+import type { BlankEnv, BlankInput } from "hono/types";
+import { SIGNATURE_ALGORITHM, SIGNATURE_HEADER } from "./constants";
+import { ZodEvent } from "./schemas";
+import { createErrorResponse, createSuccessResponse, HttpError, verifyWebhook } from "./shared";
+import type { PluvIOEndpoints, PluvIOListeners } from "./types";
+
+export type PublicKey = string | (() => MaybePromise<string>);
+export type SecretKey = string | (() => MaybePromise<string>);
+export type WebhookSecret = string | (() => MaybePromise<string>);
+
+export interface PluvPlatformConfig<TContext extends Record<string, any> = {}> {
+    /**
+     * @ignore
+     * @readonly
+     * @deprecated Internal use only. Changes to this will never be marked as breaking.
+     */
+    _defs?: {
+        debug?: boolean;
+        endpoints?: PluvIOEndpoints | (() => MaybePromise<PluvIOEndpoints>);
+    };
+    basePath: string;
+    context?: PluvContext<any, TContext>;
+    publicKey: PublicKey;
+    secretKey: SecretKey;
+    webhookSecret?: WebhookSecret;
+}
+
+export class PluvPlatform<
+    TContext extends Record<string, any> = {},
+    TUser extends BaseUser = BaseUser,
+> extends AbstractPlatform<
+    any,
+    {},
+    {},
+    {
+        authorize: {
+            secret: false;
+        };
+        handleMode: "fetch";
+        registrationMode: "attached";
+        requireAuth: true;
+        listeners: {
+            onRoomDeleted: true;
+            onRoomMessage: false;
+            onStorageUpdated: false;
+            onUserConnected: true;
+            onUserDisconnected: true;
+        };
+        router: false;
+    }
+> {
+    public readonly id = Math.random().toString();
+    public readonly _config = {
+        authorize: {
+            secret: false as const,
+        },
+        handleMode: "fetch" as const,
+        registrationMode: "attached" as const,
+        requireAuth: true as const,
+        listeners: {
+            onRoomDeleted: true as const,
+            onRoomMessage: false as const,
+            onStorageUpdated: false as const,
+            onUserConnected: true as const,
+            onUserDisconnected: true as const,
+        },
+        router: false as const,
+    };
+    public readonly _name = "platformPluv";
+
+    private readonly _app: Hono;
+    private readonly _basePath: string;
+    private readonly _context: PluvContext<this, TContext>;
+    private readonly _debug: boolean;
+    private readonly _endpoints: PluvIOEndpoints | (() => MaybePromise<PluvIOEndpoints>);
+    private _getInitialStorage?: GetInitialStorageFn<{}>;
+    private _listeners?: PluvIOListeners;
+    private readonly _publicKey: PublicKey;
+    private readonly _secretKey: SecretKey;
+    private readonly _webhookSecret?: WebhookSecret;
+
+    public _createToken = async (params: JWTEncodeParams<any, any>): Promise<string> => {
+        const parsed = params.authorize.user.parse(params.user);
+
+        const [endpoints, publicKey, secretKey] = await Promise.all([
+            typeof this._endpoints === "object" ? this._endpoints : this._endpoints(),
+            typeof this._publicKey === "string" ? this._publicKey : this._publicKey(),
+            typeof this._secretKey === "string" ? this._secretKey : this._secretKey(),
+        ]);
+
+        this._logDebug({ endpoints, publicKey, secretKey });
+
+        const res = await fetch(endpoints.createToken, {
+            headers: { "content-type": "application/json" },
+            method: "post",
+            body: JSON.stringify({
+                maxAge: params.maxAge ?? null,
+                publicKey,
+                room: params.room,
+                secretKey,
+                user: parsed,
+            }),
+        }).catch((error) => {
+            this._logDebug(error);
+
+            return null;
+        });
+
+        this._logDebug({ response: { status: res?.status ?? null } });
+
+        if (!res || !res.ok || res.status !== 200) {
+            throw new Error("Authorization failed");
+        }
+
+        const token = await res.text().catch(() => null);
+
+        this._logDebug({ token });
+
+        if (typeof token !== "string") throw new Error("Authorization failed");
+
+        return token;
+    };
+
+    constructor(params: PluvPlatformConfig) {
+        super();
+
+        const { _defs, basePath, context, publicKey, secretKey, webhookSecret } = params;
+
+        this._basePath = basePath;
+        this._context = (context ?? {}) as TContext;
+        this._debug = _defs?.debug ?? false;
+        this._endpoints = _defs?.endpoints ?? {
+            createToken: "https://rooms.pluv.io/api/room/token",
+        };
+        this._publicKey = publicKey;
+        this._secretKey = secretKey;
+        this._webhookSecret = webhookSecret;
+
+        this._app = new Hono().basePath(this._basePath).route("/", this._webhooksRouter);
+        this._fetch = this._app.fetch as (req: any) => Promise<any>;
+    }
+
+    public acceptWebSocket(webSocket: AbstractWebSocket): Promise<void> {
+        throw new Error("Not implemented");
+    }
+
+    public convertWebSocket(webSocket: any, config: ConvertWebSocketConfig): AbstractWebSocket {
+        throw new Error("Not implemented");
+    }
+
+    public getLastPing(webSocket: AbstractWebSocket): number | null {
+        throw new Error("Not implemented");
+    }
+
+    public getSerializedState(webSocket: any): WebSocketSerializedState | null {
+        throw new Error("Not implemented");
+    }
+
+    public getSessionId(webSocket: any): string | null {
+        throw new Error("Not implemented");
+    }
+
+    public getWebSockets(): readonly any[] {
+        throw new Error("Not implemented");
+    }
+
+    public initialize(config: AbstractPlatformConfig<{}>): this {
+        throw new Error("Not implemented");
+    }
+
+    public parseData(data: string | ArrayBuffer): Record<string, any> {
+        throw new Error("Not implemented");
+    }
+
+    public randomUUID(): string {
+        throw new Error("Not implemented");
+    }
+
+    public setSerializedState(
+        webSocket: AbstractWebSocket,
+        state: WebSocketSerializedState,
+    ): WebSocketSerializedState {
+        throw new Error("Not implemented");
+    }
+
+    public validateConfig(config: any): void {
+        if (!config.authorize) {
+            throw new Error("Config `authorize` must be provided to `platformPluv`");
+        }
+        if (!!config.onRoomMessage) {
+            throw new Error("Config `onRoomMessage` is not supported on `platformPluv`");
+        }
+        if (!!config.onStorageUpdated) {
+            throw new Error("Config `onStorageUpdated` is not supported on `platformPluv`");
+        }
+
+        this._getInitialStorage = config.getInitialStorage;
+        this._listeners = {
+            onRoomDeleted: (event) => config.onRoomDeleted?.(event),
+            onUserConnected: (event) => config.onUserConnected?.(event),
+            onUserDisconnected: (event) => config.onUserDisconnected?.(event),
+        };
+    }
+
+    private _webhooksRouter = new Hono()
+        .basePath("/")
+        .post("/", async (c: Context<BlankEnv, "/", BlankInput>) => {
+            const [algorithm, signature] = c.req.header(SIGNATURE_HEADER)?.split("=") ?? [];
+
+            try {
+                if (!this._webhookSecret) throw new HttpError("Unauthorized", 401);
+                if (algorithm !== SIGNATURE_ALGORITHM) throw new HttpError("Unauthorized", 401);
+                if (!signature) throw new HttpError("Unauthorized", 401);
+
+                const [payload, webhookSecret] = await Promise.all([
+                    c.req.json(),
+                    typeof this._webhookSecret === "string"
+                        ? this._webhookSecret
+                        : await this._webhookSecret(),
+                ]);
+
+                const verified = await verifyWebhook({
+                    payload: stringify(payload),
+                    signature,
+                    secret: webhookSecret,
+                });
+
+                if (!verified) throw new HttpError("Unauthorized", 401);
+
+                const parsed = ZodEvent.safeParse(payload);
+
+                if (!parsed.success) throw new HttpError("Invalid request", 400);
+
+                const { event, data } = parsed.data;
+                const context = this._getContext();
+
+                switch (event) {
+                    case "initial-storage": {
+                        const room = data.room;
+                        const storage =
+                            typeof room === "string"
+                                ? ((await this._getInitialStorage?.({ context, room })) ?? null)
+                                : null;
+
+                        return createSuccessResponse(c, { event, room, storage });
+                    }
+                    case "room-deleted": {
+                        const room = data.room;
+                        const encodedState = data.storage;
+
+                        await Promise.resolve(
+                            this._listeners?.onRoomDeleted({ context, encodedState, room }),
+                        );
+
+                        return createSuccessResponse(c, { event, room });
+                    }
+                    case "user-connected": {
+                        const room = data.room;
+                        const encodedState = data.storage;
+                        const user = data.user as any;
+
+                        await Promise.resolve(
+                            this._listeners?.onUserConnected({
+                                context,
+                                encodedState,
+                                platform: this,
+                                room,
+                                user,
+                            }),
+                        );
+
+                        return createSuccessResponse(c, { event, room });
+                    }
+                    case "user-disconnected": {
+                        const room = data.room;
+                        const encodedState = data.storage;
+                        const user = data.user as any;
+
+                        await Promise.resolve(
+                            this._listeners?.onUserDisconnected({
+                                context,
+                                encodedState,
+                                platform: this,
+                                room,
+                                user,
+                            }),
+                        );
+
+                        return createSuccessResponse(c, { event, room });
+                    }
+                    default: {
+                        throw new HttpError("Unknown event", 400);
+                    }
+                }
+            } catch (error) {
+                const message = error instanceof Error ? error.message : "Unexpected error";
+                const status = error instanceof HttpError ? error.status : 500;
+
+                return createErrorResponse(c, { message }, status);
+            }
+        });
+
+    private _getContext(): TContext {
+        return typeof this._context === "function"
+            ? this._context(this._roomContext as any)
+            : this._context;
+    }
+
+    private _logDebug(...args: any[]): void {
+        if (!this._debug) return;
+
+        console.log("[PLATFORM PLUV]", ...args);
+    }
+}

package/src/constants.ts

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

package/src/index.ts

@@ -0,0 +1,4 @@
+export { platformPluv } from "./platformPluv";
+export type { PlatformPluvCreateIOParams } from "./platformPluv";
+export { PluvPlatform } from "./PluvPlatform";
+export type { PluvIOEndpoints } from "./types";

package/src/platformPluv.ts

@@ -0,0 +1,35 @@
+import type { CreateIOParams, InferInitContextType, PluvContext, PluvIOAuthorize } from "@pluv/io";
+import type { BaseUser, Id } from "@pluv/types";
+import type { PluvPlatformConfig } from "./PluvPlatform";
+import { PluvPlatform } from "./PluvPlatform";
+
+export type PlatformPluvCreateIOParams<
+    TContext extends Record<string, any> = {},
+    TUser extends BaseUser = BaseUser,
+> = Id<
+    PluvPlatformConfig &
+        Omit<
+            CreateIOParams<PluvPlatform, TContext, TUser>,
+            "authorize" | "context" | "limits" | "platform"
+        > & {
+            authorize: PluvIOAuthorize<PluvPlatform, TUser, InferInitContextType<PluvPlatform>>;
+            context?: PluvContext<PluvPlatform, TContext>;
+        }
+>;
+
+export const platformPluv = <
+    TContext extends Record<string, any> = {},
+    TUser extends BaseUser = BaseUser,
+>(
+    config: PlatformPluvCreateIOParams<TContext, TUser>,
+): CreateIOParams<PluvPlatform<TContext, TUser>, TContext, TUser> => {
+    const { authorize, context, crdt, debug } = config;
+
+    return {
+        authorize,
+        context,
+        crdt,
+        debug,
+        platform: () => new PluvPlatform<TContext, TUser>(config),
+    };
+};

package/src/schemas.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+export const ZodEventKind = z.union([
+    z.literal("initial-storage"),
+    z.literal("room-deleted"),
+    z.literal("user-connected"),
+    z.literal("user-disconnected"),
+]);
+
+export const ZodEventInitialStorage = z.object({
+    event: z.literal("initial-storage"),
+    data: z.object({
+        room: z.string(),
+    }),
+});
+
+export const ZodEventRoomDeleted = z.object({
+    event: z.literal("room-deleted"),
+    data: z.object({
+        room: z.string(),
+        storage: z.string().nullable(),
+    }),
+});
+
+export 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(),
+    }),
+});
+
+export 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,
+]);
+
+export const ZodInitialStorageResponse = z.object({
+    event: z.literal("initial-storage"),
+    room: z.string(),
+    storage: z.string().nullable(),
+});
+
+export const ZodRoomDeletedResponse = z.object({
+    event: z.literal("room-deleted"),
+    room: z.string(),
+});
+
+export const ZodUserConnectedResponse = z.object({
+    event: z.literal("user-connected"),
+    room: z.string(),
+});
+
+export const ZodUserDisconnectedResponse = z.object({
+    event: z.literal("user-disconnected"),
+    room: z.string(),
+});
+
+export const ZodEventResponse = z.discriminatedUnion("event", [
+    ZodInitialStorageResponse,
+    ZodRoomDeletedResponse,
+    ZodUserConnectedResponse,
+    ZodUserDisconnectedResponse,
+]);

package/src/shared/HttpError.ts

@@ -0,0 +1,11 @@
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+export class HttpError extends Error {
+    readonly status: ContentfulStatusCode;
+
+    constructor(message: string, status: ContentfulStatusCode) {
+        super(message);
+
+        this.status = status;
+    }
+}

package/src/shared/createErrorResponse.ts

@@ -0,0 +1,11 @@
+import type { Context } from "hono";
+import type { BlankEnv, BlankInput } from "hono/types";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+export const createErrorResponse = <TStatus extends ContentfulStatusCode>(
+    c: Context<BlankEnv, "/", BlankInput>,
+    error: { message: string },
+    status: TStatus,
+) => {
+    return c.json({ ok: false, error: { message: error.message } }, status);
+};

package/src/shared/createHmac.ts

@@ -0,0 +1,41 @@
+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/createSuccessResponse.ts

@@ -0,0 +1,24 @@
+import type { Context } from "hono";
+import type { BlankEnv, BlankInput } from "hono/types";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { ZodEventResponse } from "../schemas";
+import type { EventResponse } from "../types";
+
+export interface CreateSuccessResponseParams<TStatus extends ContentfulStatusCode> {
+    data: EventResponse;
+    status?: TStatus;
+}
+
+export const createSuccessResponse = <TStatus extends ContentfulStatusCode = 200>(
+    c: Context<BlankEnv, "/", BlankInput>,
+    data: EventResponse,
+    status: TStatus = 200 as TStatus,
+) => {
+    return c.json(
+        {
+            ok: true,
+            data: ZodEventResponse.parse(data),
+        },
+        status,
+    );
+};

package/src/shared/getCrypto.ts

@@ -0,0 +1,17 @@
+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`
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require("node:crypto").webcrypto as webcrypto.Crypto;
+    }
+
+    throw new Error("Missing crypto module");
+};

package/src/shared/index.ts

@@ -0,0 +1,13 @@
+export { createErrorResponse } from "./createErrorResponse";
+export type { CreateErrorResponseParams } from "./createErrorResponse";
+export { createHmac } from "./createHmac";
+export type { CreateHmacParams } from "./createHmac";
+export { createSuccessResponse } from "./createSuccessResponse";
+export type { CreateSuccessResponseParams } from "./createSuccessResponse";
+export { getCrypto } from "./getCrypto";
+export { HttpError } from "./HttpError";
+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);
+};