@camerontaylor/paseo-relay 0.8.0-fork.1

package/dist/encrypted-channel.js

@@ -0,0 +1,452 @@
+/// <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 isE2EECapabilities(value) {
+    return (value === undefined ||
+        (isRecord(value) &&
+            (value.binaryCiphertext === undefined || typeof value.binaryCiphertext === "boolean")));
+}
+function isE2EEHelloMessage(value) {
+    return (isRecord(value) &&
+        value.type === "e2ee_hello" &&
+        typeof value.key === "string" &&
+        value.key.trim().length > 0 &&
+        isE2EECapabilities(value.capabilities));
+}
+function isE2EEReadyMessage(value) {
+    return isRecord(value) && value.type === "e2ee_ready" && isE2EECapabilities(value.capabilities);
+}
+function supportsBinaryCiphertext(message) {
+    return message.capabilities?.binaryCiphertext === true;
+}
+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_REJECTION_CODE = 1008;
+const ENCRYPTED_PAYLOAD_OVERHEAD_BYTES = 40;
+export function base64EncryptedWireByteLength(plaintextBytes) {
+    return 4 * Math.ceil((plaintextBytes + ENCRYPTED_PAYLOAD_OVERHEAD_BYTES) / 3);
+}
+export function maxBase64EncryptedPlaintextByteLength(wireBytes) {
+    return Math.floor(wireBytes / 4) * 3 - ENCRYPTED_PAYLOAD_OVERHEAD_BYTES;
+}
+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,
+        capabilities: { binaryCiphertext: true },
+    };
+    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 {
+            const result = transport.send(helloText);
+            if (result) {
+                void result.catch(emitSendError);
+            }
+            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 = (message) => {
+            try {
+                if (message.isBinary)
+                    return false;
+                const text = decodeTransportText(message.data);
+                const parsed = JSON.parse(text);
+                return isE2EEHelloMessage(parsed) || isE2EEReadyMessage(parsed);
+            }
+            catch {
+                return false;
+            }
+        };
+        const handleHello = async (message) => {
+            try {
+                if (message.isBinary) {
+                    throw buildInvalidHelloError("<binary frame>");
+                }
+                const helloText = decodeTransportText(message.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 binaryCiphertext = supportsBinaryCiphertext(msg);
+                await transport.send(JSON.stringify({
+                    type: "e2ee_ready",
+                    ...(binaryCiphertext
+                        ? { capabilities: { binaryCiphertext: true } }
+                        : {}),
+                }));
+                const channel = new EncryptedChannel(transport, sharedKey, events, {
+                    daemonKeyPair,
+                    binaryCiphertext,
+                });
+                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: (message) => this.handleMessage(message),
+            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(message) {
+        if (this.state === "handshaking") {
+            try {
+                if (message.isBinary)
+                    return;
+                const text = decodeTransportText(message.data);
+                const parsed = JSON.parse(text);
+                if (isE2EEReadyMessage(parsed)) {
+                    this.options.binaryCiphertext = supportsBinaryCiphertext(parsed);
+                    this.state = "open";
+                    this.events.onopen?.();
+                    for (const cb of this.onOpenCallbacks)
+                        cb();
+                    try {
+                        await this.flushPendingSends();
+                    }
+                    catch (error) {
+                        const err = error instanceof Error ? error : new Error(String(error));
+                        this.events.onerror?.(err);
+                        this.state = "closed";
+                        this.transport.close(1011, err.message);
+                    }
+                }
+            }
+            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 {
+                    if (message.isBinary)
+                        throw new Error("not plaintext handshake traffic");
+                    const text = decodeTransportText(message.data);
+                    if (text.trim().startsWith("{")) {
+                        const parsed = JSON.parse(text);
+                        if (isE2EEHelloMessage(parsed)) {
+                            if (this.options.daemonKeyPair) {
+                                await this.handleDaemonRehello(parsed);
+                            }
+                            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 (this.options.binaryCiphertext) {
+                    return message.isBinary
+                        ? { data: requireArrayBuffer(message.data), isBinary: true }
+                        : {
+                            data: base64ToArrayBuffer(decodeTransportText(message.data)),
+                            isBinary: false,
+                        };
+                }
+                // COMPAT(binaryCiphertext): added in v0.2.3, remove legacy base64-only
+                // receive mode after 2027-01-27.
+                if (!message.isBinary) {
+                    return { data: base64ToArrayBuffer(decodeTransportText(message.data)), isBinary: null };
+                }
+                // Older transport adapters could lose the opcode. Retain the former
+                // base64-first behavior only in the legacy path.
+                try {
+                    return { data: base64ToArrayBuffer(decodeTransportText(message.data)), isBinary: null };
+                }
+                catch {
+                    return { data: requireArrayBuffer(message.data), isBinary: null };
+                }
+            })();
+            if (ciphertext) {
+                const plaintextBytes = decrypt(this.sharedKey, ciphertext.data);
+                const plaintext = decodePlaintext(plaintextBytes, ciphertext.isBinary);
+                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);
+        if (this.options.binaryCiphertext && data instanceof ArrayBuffer) {
+            await this.transport.send(ciphertext);
+            return;
+        }
+        // COMPAT(binaryCiphertext): added in v0.2.3, remove base64 binary sends
+        // after 2027-01-27 once the supported peer floor includes negotiation.
+        await this.transport.send(arrayBufferToBase64(ciphertext));
+    }
+    outboundWireByteLength(data) {
+        const plaintextBytes = utf8ByteLength(data);
+        const encryptedBytes = plaintextBytes + ENCRYPTED_PAYLOAD_OVERHEAD_BYTES;
+        if (this.options.binaryCiphertext && data instanceof ArrayBuffer) {
+            return encryptedBytes;
+        }
+        return base64EncryptedWireByteLength(plaintextBytes);
+    }
+    async flushPendingSends() {
+        if (this.state !== "open")
+            return;
+        const pending = this.pendingSends;
+        this.pendingSends = [];
+        for (const item of pending) {
+            await this.send(item);
+        }
+    }
+    async handleDaemonRehello(message) {
+        if (!this.options.daemonKeyPair)
+            return;
+        const clientPublicKey = importPublicKey(message.key);
+        const retryKey = deriveSharedKey(this.options.daemonKeyPair.secretKey, clientPublicKey);
+        if (!keysEqual(retryKey, this.sharedKey))
+            return this.rejectKeyRotation();
+        await this.sendReadyForRetry();
+    }
+    async sendReadyForRetry() {
+        await this.transport.send(JSON.stringify({
+            type: "e2ee_ready",
+            ...(this.options.binaryCiphertext
+                ? { capabilities: { binaryCiphertext: true } }
+                : {}),
+        }));
+    }
+    rejectKeyRotation() {
+        this.state = "closed";
+        this.transport.close(REHANDSHAKE_REJECTION_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 decodeTransportText(data) {
+    return typeof data === "string" ? data : new TextDecoder().decode(data);
+}
+function requireArrayBuffer(data) {
+    if (data instanceof ArrayBuffer)
+        return data;
+    throw new Error("Binary WebSocket frame did not contain bytes");
+}
+function decodeLegacyPlaintext(data) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return data;
+    }
+}
+function decodePlaintext(data, isBinary) {
+    if (isBinary === true)
+        return data;
+    if (isBinary === false)
+        return new TextDecoder("utf-8", { fatal: true }).decode(data);
+    return decodeLegacyPlaintext(data);
+}
+function utf8ByteLength(data) {
+    return typeof data === "string" ? new TextEncoder().encode(data).byteLength : data.byteLength;
+}
+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 { base64EncryptedWireByteLength, createClientChannel, createDaemonChannel, EncryptedChannel, maxBase64EncryptedPlaintextByteLength, } 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 { base64EncryptedWireByteLength, createClientChannel, createDaemonChannel, EncryptedChannel, maxBase64EncryptedPlaintextByteLength, } 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": "@camerontaylor/paseo-relay",
+  "version": "0.8.0-fork.1",
+  "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"
+  }
+}