@camerontaylor/paseo-relay 0.8.0-fork.1

package/dist/base64.d.ts

@@ -0,0 +1,3 @@
+export declare function arrayBufferToBase64(buffer: ArrayBuffer): string;
+export declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.js

@@ -0,0 +1,17 @@
+import { fromByteArray, toByteArray } from "base64-js";
+export function arrayBufferToBase64(buffer) {
+    return fromByteArray(new Uint8Array(buffer));
+}
+export function base64ToArrayBuffer(base64) {
+    const normalized = (() => {
+        const trimmed = base64.trim();
+        const standard = trimmed.replace(/-/g, "+").replace(/_/g, "/");
+        const padLen = (4 - (standard.length % 4)) % 4;
+        return standard + "=".repeat(padLen);
+    })();
+    const bytes = toByteArray(normalized);
+    const out = new Uint8Array(bytes.byteLength);
+    out.set(bytes);
+    return out.buffer;
+}
+//# sourceMappingURL=base64.js.map

package/dist/cloudflare-adapter.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Cloudflare Durable Objects adapter for the relay.
+ *
+ * This module provides a Durable Object class that can be deployed to
+ * Cloudflare Workers. It uses WebSocket hibernation for cost efficiency.
+ *
+ * Each session gets its own Durable Object instance, identified by session ID.
+ *
+ * Wrangler config:
+ * ```jsonc
+ * {
+ *   "durable_objects": {
+ *     "bindings": [{ "name": "RELAY", "class_name": "RelayDurableObject" }]
+ *   },
+ *   "migrations": [{ "tag": "v1", "new_classes": ["RelayDurableObject"] }]
+ * }
+ * ```
+ */
+interface DurableObjectState {
+    acceptWebSocket(ws: WebSocket, tags?: string[]): void;
+    getWebSockets(tag?: string): WebSocket[];
+}
+interface Env {
+    RELAY: DurableObjectNamespace;
+    PASEO_RELAY_UPSTREAM?: string;
+}
+interface DurableObjectNamespace {
+    idFromName(name: string): DurableObjectId;
+    get(id: DurableObjectId): DurableObjectStub;
+}
+interface DurableObjectId {
+    toString(): string;
+}
+interface DurableObjectStub {
+    fetch(request: Request): Promise<Response>;
+}
+export declare class RelayDurableObject {
+    private state;
+    private pendingFrames;
+    constructor(state: DurableObjectState);
+    private createWebSocketPair;
+    private requireWebSocketUpgrade;
+    private asSwitchingProtocolsResponse;
+    private hasServerDataSocket;
+    private hasClientSocket;
+    private closeExistingServerSockets;
+    private handleControlKeepalive;
+    private nudgeOrResetControlForConnection;
+    private bufferFrame;
+    private flushFrames;
+    private listConnectedConnectionIds;
+    private notifyControls;
+    private fetchV1;
+    private fetchV2;
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Called when a WebSocket message is received (wakes from hibernation).
+     */
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void;
+    /**
+     * Called when a WebSocket closes (wakes from hibernation).
+     */
+    webSocketClose(ws: WebSocket, code: number, reason: string, _wasClean: boolean): void;
+    /**
+     * Called on WebSocket error.
+     */
+    webSocketError(ws: WebSocket, error: unknown): void;
+}
+/**
+ * Worker entry point that routes requests to the appropriate Durable Object.
+ */
+declare const _default: {
+    fetch(request: Request, env: Env): Promise<Response>;
+};
+export default _default;
+//# sourceMappingURL=cloudflare-adapter.d.ts.map

package/dist/cloudflare-adapter.js

@@ -0,0 +1,504 @@
+/**
+ * Cloudflare Durable Objects adapter for the relay.
+ *
+ * This module provides a Durable Object class that can be deployed to
+ * Cloudflare Workers. It uses WebSocket hibernation for cost efficiency.
+ *
+ * Each session gets its own Durable Object instance, identified by session ID.
+ *
+ * Wrangler config:
+ * ```jsonc
+ * {
+ *   "durable_objects": {
+ *     "bindings": [{ "name": "RELAY", "class_name": "RelayDurableObject" }]
+ *   },
+ *   "migrations": [{ "tag": "v1", "new_classes": ["RelayDurableObject"] }]
+ * }
+ * ```
+ */
+import { createCutoverProxy } from "./cutover-proxy.js";
+const LEGACY_RELAY_VERSION = "1";
+const CURRENT_RELAY_VERSION = "2";
+function resolveRelayVersion(rawValue) {
+    if (rawValue == null)
+        return LEGACY_RELAY_VERSION;
+    const value = rawValue.trim();
+    if (!value)
+        return LEGACY_RELAY_VERSION;
+    if (value === LEGACY_RELAY_VERSION || value === CURRENT_RELAY_VERSION) {
+        return value;
+    }
+    return null;
+}
+function hasAttachmentMethods(ws) {
+    // Type-safe check for attachment methods - required for Cloudflare WebSocket hibernation API
+    // Use Reflect to check for methods without type assertions
+    return ("serializeAttachment" in ws &&
+        "deserializeAttachment" in ws &&
+        typeof Reflect.get(ws, "serializeAttachment") === "function" &&
+        typeof Reflect.get(ws, "deserializeAttachment") === "function");
+}
+function deserializeAttachment(ws) {
+    if (!hasAttachmentMethods(ws))
+        return null;
+    try {
+        return ws.deserializeAttachment();
+    }
+    catch {
+        return null;
+    }
+}
+function serializeAttachment(ws, value) {
+    if (!hasAttachmentMethods(ws)) {
+        throw new Error("WebSocket does not support attachments");
+    }
+    ws.serializeAttachment(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function getString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function getGlobalWebSocketPair() {
+    // Access WebSocketPair from global scope (Cloudflare Workers runtime)
+    // Use Reflect to access global property without type assertions
+    const WebSocketPair = Reflect.get(globalThis, "WebSocketPair");
+    if (typeof WebSocketPair === "function") {
+        return WebSocketPair;
+    }
+    return undefined;
+}
+export class RelayDurableObject {
+    constructor(state) {
+        this.pendingFrames = new Map();
+        this.state = state;
+    }
+    createWebSocketPair() {
+        const WebSocketPairCtor = getGlobalWebSocketPair();
+        if (!WebSocketPairCtor) {
+            throw new Error("WebSocketPair not available in global scope");
+        }
+        const pair = new WebSocketPairCtor();
+        return [pair[0], pair[1]];
+    }
+    requireWebSocketUpgrade(request) {
+        const upgradeHeader = request.headers.get("Upgrade");
+        if (!upgradeHeader || upgradeHeader.toLowerCase() !== "websocket") {
+            return new Response("Expected WebSocket upgrade", { status: 426 });
+        }
+        return null;
+    }
+    asSwitchingProtocolsResponse(client) {
+        return new Response(null, {
+            status: 101,
+            webSocket: client,
+        });
+    }
+    hasServerDataSocket(connectionId) {
+        try {
+            return this.state.getWebSockets(`server:${connectionId}`).length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    hasClientSocket(connectionId) {
+        try {
+            return this.state.getWebSockets(`client:${connectionId}`).length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    closeExistingServerSockets(args) {
+        if (args.isServerControl) {
+            for (const ws of this.state.getWebSockets("server-control")) {
+                ws.close(1008, "Replaced by new connection");
+            }
+        }
+        else if (args.isServerData) {
+            for (const ws of this.state.getWebSockets(`server:${args.resolvedConnectionId}`)) {
+                ws.close(1008, "Replaced by new connection");
+            }
+        }
+    }
+    // COMPAT(relay-json-ping): Old daemons (< v0.1.76) send JSON {type:"ping"} on the control
+    // socket and rely on a JSON {type:"pong"} reply to keep controlLastSeenAt fresh. New daemons
+    // use WebSocket protocol pings (auto-answered at the edge, DO stays hibernated). Remove this
+    // handler once the supported-daemon floor is >= v0.1.76 (target: 2026-11-13).
+    handleControlKeepalive(ws, message) {
+        try {
+            const parsed = JSON.parse(message);
+            const parsedRecord = isRecord(parsed) ? parsed : null;
+            if (parsedRecord?.type !== "ping")
+                return;
+            // Logged so the daemon-side e2e idle test can assert no JSON ping reached the DO
+            // (which would indicate a regression to app-level pings that wake the DO).
+            console.log("[Relay DO] legacy_json_ping_received");
+            try {
+                ws.send(JSON.stringify({ type: "pong", ts: Date.now() }));
+            }
+            catch {
+                // ignore
+            }
+        }
+        catch {
+            // ignore non-JSON control payloads
+        }
+    }
+    nudgeOrResetControlForConnection(connectionId) {
+        // If the daemon's control WS becomes half-open, the DO can't reliably detect it via ws.send errors
+        // (Cloudflare may accept writes even if the other side is no longer reading).
+        //
+        // Instead, observe whether the daemon reacts by opening the per-connection server-data socket.
+        // If it doesn't, nudge with a sync message; if still no reaction, force-close the control
+        // socket(s) so the daemon reconnects.
+        const initialDelayMs = 10000;
+        const secondDelayMs = 5000;
+        setTimeout(() => {
+            if (!this.hasClientSocket(connectionId))
+                return;
+            if (this.hasServerDataSocket(connectionId))
+                return;
+            // First nudge: send a full sync list.
+            this.notifyControls({ type: "sync", connectionIds: this.listConnectedConnectionIds() });
+            setTimeout(() => {
+                if (!this.hasClientSocket(connectionId))
+                    return;
+                if (this.hasServerDataSocket(connectionId))
+                    return;
+                // Still nothing: assume control is stuck and force a reconnect.
+                for (const ws of this.state.getWebSockets("server-control")) {
+                    try {
+                        ws.close(1011, "Control unresponsive");
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }, secondDelayMs);
+        }, initialDelayMs);
+    }
+    bufferFrame(connectionId, message) {
+        const existing = this.pendingFrames.get(connectionId) ?? [];
+        existing.push(message);
+        // Prevent unbounded memory growth if a daemon never connects.
+        if (existing.length > 200) {
+            existing.splice(0, existing.length - 200);
+        }
+        this.pendingFrames.set(connectionId, existing);
+    }
+    flushFrames(connectionId, serverWs) {
+        const frames = this.pendingFrames.get(connectionId);
+        if (!frames || frames.length === 0)
+            return;
+        this.pendingFrames.delete(connectionId);
+        for (const frame of frames) {
+            try {
+                serverWs.send(frame);
+            }
+            catch {
+                // If we can't flush, re-buffer and let the daemon re-establish.
+                this.bufferFrame(connectionId, frame);
+                break;
+            }
+        }
+    }
+    listConnectedConnectionIds() {
+        const out = new Set();
+        for (const ws of this.state.getWebSockets("client")) {
+            try {
+                const attachmentRaw = deserializeAttachment(ws);
+                const attachment = isRecord(attachmentRaw) ? attachmentRaw : null;
+                if (attachment?.role === "client" &&
+                    typeof attachment.connectionId === "string" &&
+                    attachment.connectionId) {
+                    out.add(attachment.connectionId);
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        return Array.from(out);
+    }
+    notifyControls(message) {
+        const text = JSON.stringify(message);
+        for (const ws of this.state.getWebSockets("server-control")) {
+            try {
+                ws.send(text);
+            }
+            catch {
+                // If the control socket is dead, close it so the daemon can reconnect.
+                try {
+                    ws.close(1011, "Control send failed");
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    fetchV1(request, role, serverId) {
+        const upgradeError = this.requireWebSocketUpgrade(request);
+        if (upgradeError)
+            return upgradeError;
+        for (const ws of this.state.getWebSockets(role)) {
+            ws.close(1008, "Replaced by new connection");
+        }
+        const [client, server] = this.createWebSocketPair();
+        this.state.acceptWebSocket(server, [role]);
+        const attachment = {
+            serverId,
+            role,
+            version: LEGACY_RELAY_VERSION,
+            connectionId: null,
+            createdAt: Date.now(),
+        };
+        serializeAttachment(server, attachment);
+        console.log(`[Relay DO] v1:${role} connected to session ${serverId}`);
+        return this.asSwitchingProtocolsResponse(client);
+    }
+    fetchV2(request, role, serverId, connectionId) {
+        const upgradeError = this.requireWebSocketUpgrade(request);
+        if (upgradeError)
+            return upgradeError;
+        // If a client didn't provide a connectionId, the relay assigns one for routing.
+        const resolvedConnectionId = role === "client" && !connectionId
+            ? `conn_${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`
+            : connectionId;
+        const isServerControl = role === "server" && !resolvedConnectionId;
+        const isServerData = role === "server" && !!resolvedConnectionId;
+        // Close any existing server-side connection with the same identity.
+        // - server-control: single per serverId
+        // - server-data: single per connectionId
+        // - client: many sockets per connectionId are allowed
+        this.closeExistingServerSockets({ isServerControl, isServerData, resolvedConnectionId });
+        const [client, server] = this.createWebSocketPair();
+        const tags = [];
+        if (role === "client") {
+            tags.push("client", `client:${resolvedConnectionId}`);
+        }
+        else if (isServerControl) {
+            tags.push("server-control");
+        }
+        else {
+            tags.push("server", `server:${resolvedConnectionId}`);
+        }
+        this.state.acceptWebSocket(server, tags);
+        const attachment = {
+            serverId,
+            role,
+            version: CURRENT_RELAY_VERSION,
+            connectionId: resolvedConnectionId || null,
+            createdAt: Date.now(),
+        };
+        serializeAttachment(server, attachment);
+        let roleSuffix = "";
+        if (isServerControl) {
+            roleSuffix = "(control)";
+        }
+        else if (isServerData) {
+            roleSuffix = `(data:${resolvedConnectionId})`;
+        }
+        else if (role === "client") {
+            roleSuffix = `(${resolvedConnectionId})`;
+        }
+        console.log(`[Relay DO] v2:${role}${roleSuffix} connected to session ${serverId}`);
+        if (role === "client") {
+            this.notifyControls({ type: "connected", connectionId: resolvedConnectionId });
+            this.nudgeOrResetControlForConnection(resolvedConnectionId);
+        }
+        if (isServerControl) {
+            // Send current connection list so the daemon can attach existing connections.
+            try {
+                server.send(JSON.stringify({ type: "sync", connectionIds: this.listConnectedConnectionIds() }));
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (isServerData && resolvedConnectionId) {
+            this.flushFrames(resolvedConnectionId, server);
+        }
+        return this.asSwitchingProtocolsResponse(client);
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        const roleRaw = url.searchParams.get("role");
+        const role = roleRaw === "server" || roleRaw === "client" ? roleRaw : null;
+        const serverId = url.searchParams.get("serverId");
+        const connectionIdRaw = url.searchParams.get("connectionId");
+        const connectionId = typeof connectionIdRaw === "string" ? connectionIdRaw.trim() : "";
+        const version = resolveRelayVersion(url.searchParams.get("v"));
+        if (!role || (role !== "server" && role !== "client")) {
+            return new Response("Missing or invalid role parameter", { status: 400 });
+        }
+        if (!serverId) {
+            return new Response("Missing serverId parameter", { status: 400 });
+        }
+        if (!version) {
+            return new Response("Invalid v parameter (expected 1 or 2)", { status: 400 });
+        }
+        if (version === LEGACY_RELAY_VERSION) {
+            return this.fetchV1(request, role, serverId);
+        }
+        return this.fetchV2(request, role, serverId, connectionId);
+    }
+    /**
+     * Called when a WebSocket message is received (wakes from hibernation).
+     */
+    webSocketMessage(ws, message) {
+        const attachmentRaw = deserializeAttachment(ws);
+        if (!isRecord(attachmentRaw)) {
+            console.error("[Relay DO] Message from WebSocket without attachment");
+            return;
+        }
+        const attachment = attachmentRaw;
+        const version = getString(attachment, "version") ?? LEGACY_RELAY_VERSION;
+        if (version === LEGACY_RELAY_VERSION) {
+            const targetRole = attachment.role === "server" ? "client" : "server";
+            const targets = this.state.getWebSockets(targetRole);
+            for (const target of targets) {
+                try {
+                    target.send(message);
+                }
+                catch (error) {
+                    console.error(`[Relay DO] Failed to forward to ${targetRole}:`, error);
+                }
+            }
+            return;
+        }
+        const role = getString(attachment, "role");
+        const connectionId = getString(attachment, "connectionId");
+        if (!connectionId) {
+            // Control channel: support simple app-level keepalive.
+            if (typeof message === "string") {
+                this.handleControlKeepalive(ws, message);
+            }
+            return;
+        }
+        if (role === "client") {
+            const servers = this.state.getWebSockets(`server:${connectionId}`);
+            if (servers.length === 0) {
+                this.bufferFrame(connectionId, message);
+                return;
+            }
+            for (const target of servers) {
+                try {
+                    target.send(message);
+                }
+                catch (error) {
+                    console.error(`[Relay DO] Failed to forward client->server(${connectionId}):`, error);
+                }
+            }
+            return;
+        }
+        // server data socket -> client
+        const targets = this.state.getWebSockets(`client:${connectionId}`);
+        for (const target of targets) {
+            try {
+                target.send(message);
+            }
+            catch (error) {
+                console.error(`[Relay DO] Failed to forward server->client(${connectionId}):`, error);
+            }
+        }
+    }
+    /**
+     * Called when a WebSocket closes (wakes from hibernation).
+     */
+    webSocketClose(ws, code, reason, _wasClean) {
+        const attachmentRaw = deserializeAttachment(ws);
+        if (!isRecord(attachmentRaw))
+            return;
+        const attachment = attachmentRaw;
+        const version = getString(attachment, "version") ?? LEGACY_RELAY_VERSION;
+        const role = getString(attachment, "role");
+        const connectionId = getString(attachment, "connectionId");
+        const serverId = getString(attachment, "serverId");
+        console.log(`[Relay DO] v${version}:${role ?? "unknown"}${connectionId ? `(${connectionId})` : ""} disconnected from session ${serverId ?? "unknown"} (${code}: ${reason})`);
+        if (version === LEGACY_RELAY_VERSION) {
+            return;
+        }
+        if (role === "client" && connectionId) {
+            const remainingClientSockets = this.state
+                .getWebSockets(`client:${connectionId}`)
+                .some((socket) => socket !== ws);
+            if (remainingClientSockets) {
+                return;
+            }
+            this.pendingFrames.delete(connectionId);
+            // Last socket for this session closed: now clean up matching server-data socket.
+            for (const serverWs of this.state.getWebSockets(`server:${connectionId}`)) {
+                try {
+                    serverWs.close(1001, "Client disconnected");
+                }
+                catch {
+                    // ignore
+                }
+            }
+            this.notifyControls({ type: "disconnected", connectionId });
+            return;
+        }
+        if (role === "server" && connectionId) {
+            // Force the client to reconnect and re-handshake when the daemon side drops.
+            for (const clientWs of this.state.getWebSockets(`client:${connectionId}`)) {
+                try {
+                    clientWs.close(1012, "Server disconnected");
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    /**
+     * Called on WebSocket error.
+     */
+    webSocketError(ws, error) {
+        const attachmentRaw = deserializeAttachment(ws);
+        const attachment = isRecord(attachmentRaw) ? attachmentRaw : null;
+        const role = attachment ? getString(attachment, "role") : undefined;
+        console.error(`[Relay DO] WebSocket error for ${role ?? "unknown"}:`, error);
+    }
+}
+/**
+ * Worker entry point that routes requests to the appropriate Durable Object.
+ */
+export default {
+    async fetch(request, env) {
+        if (env.PASEO_RELAY_UPSTREAM) {
+            return createCutoverProxy(env.PASEO_RELAY_UPSTREAM).fetch(request);
+        }
+        const url = new URL(request.url);
+        // Health check
+        if (url.pathname === "/health") {
+            return new Response(JSON.stringify({ status: "ok" }), {
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        // Relay endpoint
+        if (url.pathname === "/ws") {
+            const serverId = url.searchParams.get("serverId");
+            if (!serverId) {
+                return new Response("Missing serverId parameter", { status: 400 });
+            }
+            const version = resolveRelayVersion(url.searchParams.get("v"));
+            if (!version) {
+                return new Response("Invalid v parameter (expected 1 or 2)", { status: 400 });
+            }
+            // Route to a version-isolated Durable Object instance.
+            const id = env.RELAY.idFromName(`relay-v${version}:${serverId}`);
+            const stub = env.RELAY.get(id);
+            const normalizedUrl = new URL(request.url);
+            normalizedUrl.searchParams.set("v", version);
+            const normalizedRequest = new Request(normalizedUrl.toString(), request);
+            return stub.fetch(normalizedRequest);
+        }
+        return new Response("Not found", { status: 404 });
+    },
+};
+//# sourceMappingURL=cloudflare-adapter.js.map

package/dist/crypto.d.ts

@@ -0,0 +1,30 @@
+/**
+ * E2EE crypto primitives using NaCl (tweetnacl).
+ *
+ * - Key exchange: Curve25519 (nacl.box.before)
+ * - Encryption: XSalsa20-Poly1305 (nacl.box.after / open.after)
+ *
+ * Bundle format (binary):
+ *   [nonce (24 bytes)] [ciphertext...]
+ *
+ * The encrypted channel chooses the WebSocket representation. Crypto remains
+ * byte-oriented so frame kind is never inferred from plaintext contents.
+ */
+export interface KeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+export type SharedKey = Uint8Array;
+export declare function generateKeyPair(): KeyPair;
+export declare function exportPublicKey(publicKey: Uint8Array): string;
+export declare function importPublicKey(base64: string): Uint8Array;
+export declare function exportSecretKey(secretKey: Uint8Array): string;
+export declare function importSecretKey(base64: string): Uint8Array;
+export declare function deriveSharedKey(ourSecretKey: Uint8Array, peerPublicKey: Uint8Array): SharedKey;
+/**
+ * Encrypts data and returns the binary bundle:
+ *   [nonce (24)] [ciphertext...]
+ */
+export declare function encrypt(sharedKey: SharedKey, data: string | ArrayBuffer): ArrayBuffer;
+export declare function decrypt(sharedKey: SharedKey, data: ArrayBuffer): ArrayBuffer;
+//# sourceMappingURL=crypto.d.ts.map