@getpaseo/relay 0.2.2 → 0.2.4

package/dist/crypto.d.ts

@@ -7,8 +7,8 @@
  * Bundle format (binary):
  *   [nonce (24 bytes)] [ciphertext...]
  *
- * Transport format:
- *   The encrypted-channel sends the bundle as base64 text over WebSocket.
+ * 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;
@@ -26,5 +26,5 @@ export declare function deriveSharedKey(ourSecretKey: Uint8Array, peerPublicKey:
  *   [nonce (24)] [ciphertext...]
  */
 export declare function encrypt(sharedKey: SharedKey, data: string | ArrayBuffer): ArrayBuffer;
-export declare function decrypt(sharedKey: SharedKey, data: ArrayBuffer): string | ArrayBuffer;
+export declare function decrypt(sharedKey: SharedKey, data: ArrayBuffer): ArrayBuffer;
 //# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.js

@@ -8,8 +8,8 @@
  * Bundle format (binary):
  *   [nonce (24 bytes)] [ciphertext...]
  *
- * Transport format:
- *   The encrypted-channel sends the bundle as base64 text over WebSocket.
+ * The encrypted channel chooses the WebSocket representation. Crypto remains
+ * byte-oriented so frame kind is never inferred from plaintext contents.
  */
 import nacl from "tweetnacl";
 import { fromByteArray, toByteArray } from "base64-js";
@@ -121,12 +121,6 @@ export function decrypt(sharedKey, data) {
     if (!opened) {
         throw new Error("Decryption failed");
     }
-    const plaintext = toArrayBuffer(opened);
-    try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
-    }
-    catch {
-        return plaintext;
-    }
+    return toArrayBuffer(opened);
 }
 //# sourceMappingURL=crypto.js.map

package/dist/e2ee.d.ts

@@ -1,5 +1,5 @@
 export { createClientChannel, createDaemonChannel, EncryptedChannel } from "./encrypted-channel.js";
-export type { Transport, EncryptedChannelEvents } from "./encrypted-channel.js";
+export type { Transport, TransportMessage, 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/encrypted-channel.d.ts

@@ -6,12 +6,16 @@
  */
 import { type KeyPair, type SharedKey } from "./crypto.js";
 export interface Transport {
-    send(data: string | ArrayBuffer): void;
+    send(data: string | ArrayBuffer): void | Promise<void>;
     close(code?: number, reason?: string): void;
-    onmessage: ((data: string | ArrayBuffer) => void) | null;
+    onmessage: ((message: TransportMessage) => void) | null;
     onclose: ((code: number, reason: string) => void) | null;
     onerror: ((error: Error) => void) | null;
 }
+export interface TransportMessage {
+    data: string | ArrayBuffer;
+    isBinary: boolean;
+}
 export interface EncryptedChannelEvents {
     onopen?: () => void;
     onmessage?: (data: string | ArrayBuffer) => void;
@@ -29,7 +33,10 @@ interface EncryptedChannelOptions {
      * the daemon should re-send `{type:"e2ee_ready"}` without changing keys.
      */
     daemonKeyPair?: KeyPair;
+    binaryCiphertext?: boolean;
 }
+export declare function base64EncryptedWireByteLength(plaintextBytes: number): number;
+export declare function maxBase64EncryptedPlaintextByteLength(wireBytes: number): number;
 /**
  * Creates an encrypted channel as the initiator (client).
  *
@@ -65,6 +72,7 @@ export declare class EncryptedChannel {
     setState(state: ChannelState): void;
     private handleMessage;
     send(data: string | ArrayBuffer): Promise<void>;
+    outboundWireByteLength(data: string | ArrayBuffer): number;
     private flushPendingSends;
     private handleDaemonRehello;
     close(code?: number, reason?: string): void;

package/dist/encrypted-channel.js

@@ -10,14 +10,23 @@ 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);
+        value.key.trim().length > 0 &&
+        isE2EECapabilities(value.capabilities));
 }
 function isE2EEReadyMessage(value) {
-    return isRecord(value) && value.type === "e2ee_ready";
+    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;
@@ -38,6 +47,13 @@ function buildInvalidHelloError(rawText, parsed) {
 const HANDSHAKE_RETRY_MS = 1000;
 const MAX_PENDING_SENDS = 200;
 const REHANDSHAKE_KEY_MISMATCH_CLOSE_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" &&
@@ -61,7 +77,11 @@ export async function createClientChannel(transport, daemonPublicKeyB64, events
     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 hello = {
+        type: "e2ee_hello",
+        key: ourPublicKeyB64,
+        capabilities: { binaryCiphertext: true },
+    };
     const helloText = JSON.stringify(hello);
     let retry = null;
     const emitSendError = (error) => {
@@ -70,7 +90,10 @@ export async function createClientChannel(transport, daemonPublicKeyB64, events
     };
     const sendHello = () => {
         try {
-            transport.send(helloText);
+            const result = transport.send(helloText);
+            if (result) {
+                void result.catch(emitSendError);
+            }
             return true;
         }
         catch (error) {
@@ -113,9 +136,11 @@ export async function createClientChannel(transport, daemonPublicKeyB64, events
 export async function createDaemonChannel(transport, daemonKeyPair, events = {}) {
     return new Promise((resolve, reject) => {
         const bufferedMessages = [];
-        const shouldIgnorePostHelloPlaintext = (data) => {
+        const shouldIgnorePostHelloPlaintext = (message) => {
             try {
-                const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+                if (message.isBinary)
+                    return false;
+                const text = decodeTransportText(message.data);
                 const parsed = JSON.parse(text);
                 return isE2EEHelloMessage(parsed) || isE2EEReadyMessage(parsed);
             }
@@ -123,9 +148,12 @@ export async function createDaemonChannel(transport, daemonKeyPair, events = {})
                 return false;
             }
         };
-        const handleHello = async (data) => {
+        const handleHello = async (message) => {
             try {
-                const helloText = typeof data === "string" ? data : new TextDecoder().decode(data);
+                if (message.isBinary) {
+                    throw buildInvalidHelloError("<binary frame>");
+                }
+                const helloText = decodeTransportText(message.data);
                 let parsed;
                 try {
                     parsed = JSON.parse(helloText);
@@ -147,8 +175,17 @@ export async function createDaemonChannel(transport, daemonKeyPair, events = {})
                 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" }));
+                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) {
@@ -187,7 +224,7 @@ export class EncryptedChannel {
         this.events = events;
         this.options = options;
         Object.assign(transport, {
-            onmessage: (data) => this.handleMessage(data),
+            onmessage: (message) => this.handleMessage(message),
             onclose: (code, reason) => {
                 this.state = "closed";
                 this.events.onclose?.(code, reason);
@@ -202,17 +239,28 @@ export class EncryptedChannel {
     setState(state) {
         this.state = state;
     }
-    async handleMessage(data) {
+    async handleMessage(message) {
         if (this.state === "handshaking") {
             try {
-                const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+                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();
-                    await this.flushPendingSends();
+                    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 {
@@ -226,12 +274,14 @@ export class EncryptedChannel {
             const ciphertext = await (async () => {
                 // Handle (or ignore) any stray plaintext handshake traffic.
                 try {
-                    const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+                    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.key);
+                                await this.handleDaemonRehello(parsed);
                             }
                             return null;
                         }
@@ -251,21 +301,31 @@ export class EncryptedChannel {
                     // Otherwise ignore JSON parse/TextDecoder failures and fall back to
                     // decoding ciphertext below.
                 }
-                if (typeof data === "string") {
-                    return base64ToArrayBuffer(data);
+                if (this.options.binaryCiphertext) {
+                    return message.isBinary
+                        ? { data: requireArrayBuffer(message.data), isBinary: true }
+                        : {
+                            data: base64ToArrayBuffer(decodeTransportText(message.data)),
+                            isBinary: false,
+                        };
                 }
-                // Some WebSocket implementations deliver text frames as ArrayBuffer.
-                // Our protocol always transmits ciphertext as base64 text.
+                // 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 {
-                    const decoded = new TextDecoder().decode(data);
-                    return base64ToArrayBuffer(decoded);
+                    return { data: base64ToArrayBuffer(decodeTransportText(message.data)), isBinary: null };
                 }
                 catch {
-                    return data;
+                    return { data: requireArrayBuffer(message.data), isBinary: null };
                 }
             })();
             if (ciphertext) {
-                const plaintext = decrypt(this.sharedKey, ciphertext);
+                const plaintextBytes = decrypt(this.sharedKey, ciphertext.data);
+                const plaintext = decodePlaintext(plaintextBytes, ciphertext.isBinary);
                 this.events.onmessage?.(plaintext);
             }
         }
@@ -294,8 +354,21 @@ export class EncryptedChannel {
             throw new Error("Channel not open");
         }
         const ciphertext = encrypt(this.sharedKey, data);
-        // Send as base64 for WebSocket text compatibility
-        this.transport.send(arrayBufferToBase64(ciphertext));
+        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")
@@ -306,16 +379,21 @@ export class EncryptedChannel {
             await this.send(item);
         }
     }
-    async handleDaemonRehello(clientKeyB64) {
+    async handleDaemonRehello(message) {
         if (!this.options.daemonKeyPair)
             return;
-        const clientPublicKey = importPublicKey(clientKeyB64);
+        const clientPublicKey = importPublicKey(message.key);
         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" }));
+            await this.transport.send(JSON.stringify({
+                type: "e2ee_ready",
+                ...(this.options.binaryCiphertext
+                    ? { capabilities: { binaryCiphertext: true } }
+                    : {}),
+            }));
             return;
         }
         // A different key on an already-open encrypted channel is not an
@@ -338,6 +416,32 @@ export class EncryptedChannel {
         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;

package/dist/index.d.ts

@@ -1,5 +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 { 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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Paseo relay for bridging daemon and client connections",
   "files": [
     "dist",