@hyperdrive.bot/paseo-relay 0.2.5

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,75 @@
+/**
+ * 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;
+}
+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,500 @@
+/**
+ * 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"] }]
+ * }
+ * ```
+ */
+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) {
+        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...]
+ *
+ * Transport format:
+ *   The encrypted-channel sends the bundle as base64 text over WebSocket.
+ */
+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): string | ArrayBuffer;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.js

@@ -0,0 +1,132 @@
+/// <reference lib="dom" />
+/**
+ * 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...]
+ *
+ * Transport format:
+ *   The encrypted-channel sends the bundle as base64 text over WebSocket.
+ */
+import nacl from "tweetnacl";
+import { fromByteArray, toByteArray } from "base64-js";
+const NONCE_LENGTH = nacl.box.nonceLength; // 24
+let prngReady = false;
+function getGlobalCrypto() {
+    const g = globalThis;
+    return g.crypto;
+}
+function ensurePrng() {
+    if (prngReady)
+        return;
+    try {
+        nacl.randomBytes(1);
+        prngReady = true;
+        return;
+    }
+    catch {
+        // fallthrough
+    }
+    const cryptoObj = getGlobalCrypto();
+    if (cryptoObj?.getRandomValues) {
+        nacl.setPRNG((x, n) => {
+            const buf = new Uint8Array(n);
+            cryptoObj.getRandomValues(buf);
+            x.set(buf, 0);
+        });
+        prngReady = true;
+        return;
+    }
+    throw new Error("No secure PRNG available for tweetnacl (missing crypto.getRandomValues)");
+}
+function encodeBase64(bytes) {
+    return fromByteArray(bytes);
+}
+function decodeBase64(base64) {
+    return toByteArray(base64);
+}
+function toUint8(data) {
+    return typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data);
+}
+function toArrayBuffer(bytes) {
+    const out = new Uint8Array(bytes.byteLength);
+    out.set(bytes);
+    return out.buffer;
+}
+export function generateKeyPair() {
+    ensurePrng();
+    const { publicKey, secretKey } = nacl.box.keyPair();
+    return { publicKey, secretKey };
+}
+export function exportPublicKey(publicKey) {
+    if (!(publicKey instanceof Uint8Array) || publicKey.byteLength !== nacl.box.publicKeyLength) {
+        throw new Error(`Invalid public key length (expected ${nacl.box.publicKeyLength})`);
+    }
+    return encodeBase64(publicKey);
+}
+export function importPublicKey(base64) {
+    const bytes = decodeBase64(base64);
+    if (bytes.byteLength !== nacl.box.publicKeyLength) {
+        throw new Error(`Invalid public key length (expected ${nacl.box.publicKeyLength})`);
+    }
+    return bytes;
+}
+export function exportSecretKey(secretKey) {
+    if (!(secretKey instanceof Uint8Array) || secretKey.byteLength !== nacl.box.secretKeyLength) {
+        throw new Error(`Invalid secret key length (expected ${nacl.box.secretKeyLength})`);
+    }
+    return encodeBase64(secretKey);
+}
+export function importSecretKey(base64) {
+    const bytes = decodeBase64(base64);
+    if (bytes.byteLength !== nacl.box.secretKeyLength) {
+        throw new Error(`Invalid secret key length (expected ${nacl.box.secretKeyLength})`);
+    }
+    return bytes;
+}
+export function deriveSharedKey(ourSecretKey, peerPublicKey) {
+    if (ourSecretKey.byteLength !== nacl.box.secretKeyLength) {
+        throw new Error(`Invalid secret key length (expected ${nacl.box.secretKeyLength})`);
+    }
+    if (peerPublicKey.byteLength !== nacl.box.publicKeyLength) {
+        throw new Error(`Invalid peer public key length (expected ${nacl.box.publicKeyLength})`);
+    }
+    return nacl.box.before(peerPublicKey, ourSecretKey);
+}
+/**
+ * Encrypts data and returns the binary bundle:
+ *   [nonce (24)] [ciphertext...]
+ */
+export function encrypt(sharedKey, data) {
+    ensurePrng();
+    const nonce = nacl.randomBytes(NONCE_LENGTH);
+    const plaintext = toUint8(data);
+    const ciphertext = nacl.box.after(plaintext, nonce, sharedKey);
+    const out = new Uint8Array(nonce.byteLength + ciphertext.byteLength);
+    out.set(nonce, 0);
+    out.set(ciphertext, nonce.byteLength);
+    return toArrayBuffer(out);
+}
+export function decrypt(sharedKey, data) {
+    const bytes = new Uint8Array(data);
+    if (bytes.byteLength < NONCE_LENGTH) {
+        throw new Error("Ciphertext bundle too short");
+    }
+    const nonce = bytes.slice(0, NONCE_LENGTH);
+    const ciphertext = bytes.slice(NONCE_LENGTH);
+    const opened = nacl.box.open.after(ciphertext, nonce, sharedKey);
+    if (!opened) {
+        throw new Error("Decryption failed");
+    }
+    const plaintext = toArrayBuffer(opened);
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+    }
+    catch {
+        return plaintext;
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/e2ee.d.ts

@@ -0,0 +1,5 @@
+export { createClientChannel, createDaemonChannel, EncryptedChannel } from "./encrypted-channel.js";
+export type { Transport, EncryptedChannelEvents } from "./encrypted-channel.js";
+export { generateKeyPair, exportPublicKey, importPublicKey, exportSecretKey, importSecretKey, } from "./crypto.js";
+export type { KeyPair, SharedKey } from "./crypto.js";
+//# sourceMappingURL=e2ee.d.ts.map

package/dist/e2ee.js

@@ -0,0 +1,3 @@
+export { createClientChannel, createDaemonChannel, EncryptedChannel } from "./encrypted-channel.js";
+export { generateKeyPair, exportPublicKey, importPublicKey, exportSecretKey, importSecretKey, } from "./crypto.js";
+//# sourceMappingURL=e2ee.js.map

package/dist/encrypted-channel.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Encrypted channel that wraps a WebSocket-like transport.
+ *
+ * Handles ECDH handshake and encrypts/decrypts all messages.
+ * Works identically for daemon and client sides.
+ */
+import { type KeyPair, type SharedKey } from "./crypto.js";
+export interface Transport {
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    onmessage: ((data: string | ArrayBuffer) => void) | null;
+    onclose: ((code: number, reason: string) => void) | null;
+    onerror: ((error: Error) => void) | null;
+}
+export interface EncryptedChannelEvents {
+    onopen?: () => void;
+    onmessage?: (data: string | ArrayBuffer) => void;
+    onclose?: (code: number, reason: string) => void;
+    onerror?: (error: Error) => void;
+}
+type ChannelState = "connecting" | "handshaking" | "open" | "closed";
+interface EncryptedChannelOptions {
+    /**
+     * If set, the channel can validate repeated plaintext `{type:"e2ee_hello"}`
+     * messages even after it is open.
+     *
+     * This is useful for robustness when the client retries the handshake
+     * (e.g., it didn't observe the daemon's `{type:"e2ee_ready"}` yet). In that case,
+     * the daemon should re-send `{type:"e2ee_ready"}` without changing keys.
+     */
+    daemonKeyPair?: KeyPair;
+}
+/**
+ * Creates an encrypted channel as the initiator (client).
+ *
+ * The client:
+ * 1. Receives daemon's public key via QR code
+ * 2. Generates own keypair
+ * 3. Sends e2ee_hello with own public key
+ * 4. Derives shared key and starts encrypted communication
+ */
+export declare function createClientChannel(transport: Transport, daemonPublicKeyB64: string, events?: EncryptedChannelEvents): Promise<EncryptedChannel>;
+/**
+ * Creates an encrypted channel as the responder (daemon).
+ *
+ * The daemon:
+ * 1. Has pre-generated keypair (public key was in QR)
+ * 2. Waits for client's e2ee_hello with their public key
+ * 3. Derives shared key and starts encrypted communication
+ */
+export declare function createDaemonChannel(transport: Transport, daemonKeyPair: KeyPair, events?: EncryptedChannelEvents): Promise<EncryptedChannel>;
+/**
+ * Encrypted channel that wraps a transport with E2EE.
+ */
+export declare class EncryptedChannel {
+    private transport;
+    private sharedKey;
+    private state;
+    private events;
+    private options;
+    private pendingSends;
+    private onOpenCallbacks;
+    private onCloseCallbacks;
+    constructor(transport: Transport, sharedKey: SharedKey, events?: EncryptedChannelEvents, options?: EncryptedChannelOptions);
+    setState(state: ChannelState): void;
+    private handleMessage;
+    send(data: string | ArrayBuffer): Promise<void>;
+    private flushPendingSends;
+    private handleDaemonRehello;
+    close(code?: number, reason?: string): void;
+    isOpen(): boolean;
+    onTransitionToOpen(cb: () => void): void;
+    onClose(cb: () => void): void;
+}
+export {};
+//# sourceMappingURL=encrypted-channel.d.ts.map

package/dist/encrypted-channel.js

@@ -0,0 +1,350 @@
+/// <reference lib="dom" />
+/**
+ * Encrypted channel that wraps a WebSocket-like transport.
+ *
+ * Handles ECDH handshake and encrypts/decrypts all messages.
+ * Works identically for daemon and client sides.
+ */
+import { generateKeyPair, exportPublicKey, importPublicKey, deriveSharedKey, encrypt, decrypt, } from "./crypto.js";
+import { arrayBufferToBase64, base64ToArrayBuffer } from "./base64.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isE2EEHelloMessage(value) {
+    return (isRecord(value) &&
+        value.type === "e2ee_hello" &&
+        typeof value.key === "string" &&
+        value.key.trim().length > 0);
+}
+function isE2EEReadyMessage(value) {
+    return isRecord(value) && value.type === "e2ee_ready";
+}
+function buildInvalidHelloError(rawText, parsed) {
+    const parsedRecord = isRecord(parsed) ? parsed : null;
+    const rawType = parsedRecord?.type;
+    function describeType(value) {
+        if (typeof value === "string")
+            return value;
+        if (value === undefined)
+            return "undefined";
+        return typeof value;
+    }
+    const receivedType = describeType(rawType);
+    const hasKey = typeof parsedRecord?.key === "string" && parsedRecord.key.trim().length > 0;
+    const compact = rawText.replace(/\s+/g, " ").trim();
+    const preview = compact.length > 160 ? `${compact.slice(0, 157)}...` : compact;
+    return new Error(`Invalid hello message (receivedType=${receivedType}, hasKey=${hasKey}, preview=${JSON.stringify(preview)})`);
+}
+const HANDSHAKE_RETRY_MS = 1000;
+const MAX_PENDING_SENDS = 200;
+const REHANDSHAKE_KEY_MISMATCH_CLOSE_CODE = 1008;
+const REHANDSHAKE_KEY_MISMATCH_CLOSE_REASON = "E2EE re-handshake key mismatch";
+function hasUnref(timeout) {
+    return (typeof timeout === "object" &&
+        timeout !== null &&
+        "unref" in timeout &&
+        typeof timeout.unref === "function");
+}
+/**
+ * Creates an encrypted channel as the initiator (client).
+ *
+ * The client:
+ * 1. Receives daemon's public key via QR code
+ * 2. Generates own keypair
+ * 3. Sends e2ee_hello with own public key
+ * 4. Derives shared key and starts encrypted communication
+ */
+export async function createClientChannel(transport, daemonPublicKeyB64, events = {}) {
+    const keyPair = generateKeyPair();
+    const daemonPublicKey = importPublicKey(daemonPublicKeyB64);
+    const sharedKey = deriveSharedKey(keyPair.secretKey, daemonPublicKey);
+    const channel = new EncryptedChannel(transport, sharedKey, events);
+    // Send e2ee_hello with our public key
+    const ourPublicKeyB64 = exportPublicKey(keyPair.publicKey);
+    const hello = { type: "e2ee_hello", key: ourPublicKeyB64 };
+    const helloText = JSON.stringify(hello);
+    let retry = null;
+    const emitSendError = (error) => {
+        const err = error instanceof Error ? error : new Error(String(error));
+        events.onerror?.(err);
+    };
+    const sendHello = () => {
+        try {
+            transport.send(helloText);
+            return true;
+        }
+        catch (error) {
+            // This can happen during daemon restarts while the socket transitions
+            // through CLOSING/CLOSED states. Report it but do not throw from timers.
+            emitSendError(error);
+            return false;
+        }
+    };
+    const clearRetry = () => {
+        if (retry) {
+            clearInterval(retry);
+            retry = null;
+        }
+    };
+    channel.onTransitionToOpen(() => clearRetry());
+    channel.onClose(() => clearRetry());
+    sendHello();
+    retry = setInterval(() => {
+        if (channel.isOpen()) {
+            clearRetry();
+            return;
+        }
+        sendHello();
+    }, HANDSHAKE_RETRY_MS);
+    // Avoid keeping Node processes alive (e.g. tests) if the handshake is stuck.
+    if (hasUnref(retry)) {
+        retry.unref();
+    }
+    return channel;
+}
+/**
+ * Creates an encrypted channel as the responder (daemon).
+ *
+ * The daemon:
+ * 1. Has pre-generated keypair (public key was in QR)
+ * 2. Waits for client's e2ee_hello with their public key
+ * 3. Derives shared key and starts encrypted communication
+ */
+export async function createDaemonChannel(transport, daemonKeyPair, events = {}) {
+    return new Promise((resolve, reject) => {
+        const bufferedMessages = [];
+        const shouldIgnorePostHelloPlaintext = (data) => {
+            try {
+                const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+                const parsed = JSON.parse(text);
+                return isE2EEHelloMessage(parsed) || isE2EEReadyMessage(parsed);
+            }
+            catch {
+                return false;
+            }
+        };
+        const handleHello = async (data) => {
+            try {
+                const helloText = typeof data === "string" ? data : new TextDecoder().decode(data);
+                let parsed;
+                try {
+                    parsed = JSON.parse(helloText);
+                }
+                catch {
+                    throw buildInvalidHelloError(helloText);
+                }
+                if (!isE2EEHelloMessage(parsed)) {
+                    throw buildInvalidHelloError(helloText, parsed);
+                }
+                const msg = parsed;
+                // Buffer any subsequent messages that arrive while we're doing async
+                // WebCrypto work to derive the shared key. Without this, it's possible
+                // for the next message (already encrypted) to be misinterpreted as a
+                // second hello, causing the handshake to fail.
+                const bufferNext = (next) => {
+                    bufferedMessages.push(next);
+                };
+                Object.assign(transport, { onmessage: bufferNext });
+                const clientPublicKey = importPublicKey(msg.key);
+                const sharedKey = deriveSharedKey(daemonKeyPair.secretKey, clientPublicKey);
+                const channel = new EncryptedChannel(transport, sharedKey, events, { daemonKeyPair });
+                transport.send(JSON.stringify({ type: "e2ee_ready" }));
+                channel.setState("open");
+                events.onopen?.();
+                for (const buffered of bufferedMessages) {
+                    if (shouldIgnorePostHelloPlaintext(buffered))
+                        continue;
+                    transport.onmessage?.(buffered);
+                }
+                resolve(channel);
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        Object.assign(transport, {
+            onmessage: handleHello,
+            onerror: (error) => {
+                reject(error);
+            },
+            onclose: (code, reason) => {
+                reject(new Error(`Connection closed during handshake: ${code} ${reason}`));
+            },
+        });
+    });
+}
+/**
+ * Encrypted channel that wraps a transport with E2EE.
+ */
+export class EncryptedChannel {
+    constructor(transport, sharedKey, events = {}, options = {}) {
+        this.state = "handshaking";
+        this.pendingSends = [];
+        this.onOpenCallbacks = [];
+        this.onCloseCallbacks = [];
+        this.transport = transport;
+        this.sharedKey = sharedKey;
+        this.events = events;
+        this.options = options;
+        Object.assign(transport, {
+            onmessage: (data) => this.handleMessage(data),
+            onclose: (code, reason) => {
+                this.state = "closed";
+                this.events.onclose?.(code, reason);
+                for (const cb of this.onCloseCallbacks)
+                    cb();
+            },
+            onerror: (error) => {
+                this.events.onerror?.(error);
+            },
+        });
+    }
+    setState(state) {
+        this.state = state;
+    }
+    async handleMessage(data) {
+        if (this.state === "handshaking") {
+            try {
+                const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+                const parsed = JSON.parse(text);
+                if (isE2EEReadyMessage(parsed)) {
+                    this.state = "open";
+                    this.events.onopen?.();
+                    for (const cb of this.onOpenCallbacks)
+                        cb();
+                    await this.flushPendingSends();
+                }
+            }
+            catch {
+                // ignore non-ready handshake traffic
+            }
+            return;
+        }
+        if (this.state !== "open")
+            return;
+        try {
+            const ciphertext = await (async () => {
+                // Handle (or ignore) any stray plaintext handshake traffic.
+                try {
+                    const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+                    if (text.trim().startsWith("{")) {
+                        const parsed = JSON.parse(text);
+                        if (isE2EEHelloMessage(parsed)) {
+                            if (this.options.daemonKeyPair) {
+                                await this.handleDaemonRehello(parsed.key);
+                            }
+                            return null;
+                        }
+                        if (isE2EEReadyMessage(parsed)) {
+                            return null;
+                        }
+                        // Any other JSON-looking payload is plaintext app traffic, which
+                        // means the peer is not encrypting (or we are out of sync).
+                        throw new Error("Received plaintext frame on encrypted channel");
+                    }
+                }
+                catch (error) {
+                    // If we detected plaintext protocol mismatch, fail hard.
+                    if (error instanceof Error && error.message.includes("plaintext frame")) {
+                        throw error;
+                    }
+                    // Otherwise ignore JSON parse/TextDecoder failures and fall back to
+                    // decoding ciphertext below.
+                }
+                if (typeof data === "string") {
+                    return base64ToArrayBuffer(data);
+                }
+                // Some WebSocket implementations deliver text frames as ArrayBuffer.
+                // Our protocol always transmits ciphertext as base64 text.
+                try {
+                    const decoded = new TextDecoder().decode(data);
+                    return base64ToArrayBuffer(decoded);
+                }
+                catch {
+                    return data;
+                }
+            })();
+            if (ciphertext) {
+                const plaintext = decrypt(this.sharedKey, ciphertext);
+                this.events.onmessage?.(plaintext);
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            // Treat decryption/protocol errors as fatal so the peer can reconnect and
+            // re-handshake. Emitting an error event here can cause higher-level code
+            // to tear down the session without triggering a clean reconnect.
+            try {
+                this.transport.close(1011, err.message);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    async send(data) {
+        if (this.state === "handshaking") {
+            if (this.pendingSends.length >= MAX_PENDING_SENDS) {
+                this.pendingSends.shift();
+            }
+            this.pendingSends.push(data);
+            return;
+        }
+        if (this.state !== "open") {
+            throw new Error("Channel not open");
+        }
+        const ciphertext = encrypt(this.sharedKey, data);
+        // Send as base64 for WebSocket text compatibility
+        this.transport.send(arrayBufferToBase64(ciphertext));
+    }
+    async flushPendingSends() {
+        if (this.state !== "open")
+            return;
+        const pending = this.pendingSends;
+        this.pendingSends = [];
+        for (const item of pending) {
+            await this.send(item);
+        }
+    }
+    async handleDaemonRehello(clientKeyB64) {
+        if (!this.options.daemonKeyPair)
+            return;
+        const clientPublicKey = importPublicKey(clientKeyB64);
+        const nextSharedKey = deriveSharedKey(this.options.daemonKeyPair.secretKey, clientPublicKey);
+        // If it's the same client key (handshake retry), re-send
+        // "ready" but do not re-key. Re-keying here would desync
+        // the channel and cause decrypt failures.
+        if (keysEqual(nextSharedKey, this.sharedKey)) {
+            this.transport.send(JSON.stringify({ type: "e2ee_ready" }));
+            return;
+        }
+        // A different key on an already-open encrypted channel is not an
+        // authenticated reconnect. Close and require a fresh transport instead of
+        // allowing the relay to switch this channel to an attacker-chosen key.
+        this.state = "closed";
+        this.transport.close(REHANDSHAKE_KEY_MISMATCH_CLOSE_CODE, REHANDSHAKE_KEY_MISMATCH_CLOSE_REASON);
+    }
+    close(code = 1000, reason = "Normal closure") {
+        this.state = "closed";
+        this.transport.close(code, reason);
+    }
+    isOpen() {
+        return this.state === "open";
+    }
+    onTransitionToOpen(cb) {
+        this.onOpenCallbacks.push(cb);
+    }
+    onClose(cb) {
+        this.onCloseCallbacks.push(cb);
+    }
+}
+function keysEqual(a, b) {
+    if (a.byteLength !== b.byteLength)
+        return false;
+    let difference = 0;
+    for (let i = 0; i < a.byteLength; i += 1) {
+        difference |= a[i] ^ b[i];
+    }
+    return difference === 0;
+}
+//# sourceMappingURL=encrypted-channel.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { ConnectionRole, RelaySessionAttachment } from "./types.js";
+export { generateKeyPair, exportPublicKey, importPublicKey, deriveSharedKey, encrypt, decrypt, } from "./crypto.js";
+export { createClientChannel, createDaemonChannel, EncryptedChannel } from "./encrypted-channel.js";
+export type { Transport, EncryptedChannelEvents } from "./encrypted-channel.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export { generateKeyPair, exportPublicKey, importPublicKey, deriveSharedKey, encrypt, decrypt, } from "./crypto.js";
+export { createClientChannel, createDaemonChannel, EncryptedChannel } from "./encrypted-channel.js";
+//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Relay connection types and interfaces.
+ *
+ * The relay bridges two WebSocket connections:
+ * - Server (daemon): The Paseo server connecting to the relay
+ * - Client (app): The mobile/web app connecting to the relay
+ *
+ * Messages are forwarded bidirectionally without modification.
+ */
+export type ConnectionRole = "server" | "client";
+export interface RelaySessionAttachment {
+    serverId: string;
+    role: ConnectionRole;
+    /**
+     * Relay protocol version carried by this socket.
+     * v1: single server/client socket pair
+     * v2: control + per-client data sockets
+     */
+    version?: "1" | "2";
+    /**
+     * Unique id for the connection. Allows the daemon to create an
+     * independent socket + E2EE channel per connected connection.
+     */
+    connectionId?: string | null;
+    createdAt: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Relay connection types and interfaces.
+ *
+ * The relay bridges two WebSocket connections:
+ * - Server (daemon): The Paseo server connecting to the relay
+ * - Client (app): The mobile/web app connecting to the relay
+ *
+ * Messages are forwarded bidirectionally without modification.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hyperdrive.bot/paseo-relay",
+  "version": "0.2.5",
+  "description": "Paseo relay for bridging daemon and client connections",
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./e2ee": {
+      "types": "./dist/e2ee.d.ts",
+      "node": "./dist/e2ee.js",
+      "import": "./src/e2ee.ts",
+      "default": "./src/e2ee.ts"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare-adapter.d.ts",
+      "node": "./dist/cloudflare-adapter.js",
+      "import": "./src/cloudflare-adapter.ts",
+      "default": "./src/cloudflare-adapter.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node ../../scripts/clean-package-dist.mjs",
+    "build": "tsc -p tsconfig.json --incremental false",
+    "build:clean": "npm run clean && npm run build",
+    "prepack": "npm run build:clean",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "base64-js": "^1.5.1",
+    "tweetnacl": "^1.0.3",
+    "ws": "^8.14.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "@types/ws": "^8.5.8",
+    "typescript": "^5.2.2",
+    "vitest": "^4.1.6"
+  }
+}