elanous 0.2.5 → 0.2.7

package/src/relay/channel.ts

@@ -0,0 +1,184 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import sodium from 'libsodium-wrappers';
+
+/** Maximum size of a complete encrypted frame, including sequence and MAC. */
+export const MAX_FRAME_BYTES = 1024 * 1024;
+const SEQUENCE_BYTES = 8;
+const MAC_BYTES = 16;
+const NONCE_BYTES = 24;
+const MAX_SEQUENCE = (1n << 64n) - 1n;
+
+export type ChannelResult<T> = { ok: true; value: T } | { ok: false; reason: string };
+export interface DaemonKeyPair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+export interface SerializedDaemonKeyPair {
+  publicKey: string;
+  secretKey: string;
+}
+
+function rejected<T>(reason: string): ChannelResult<T> {
+  return { ok: false, reason };
+}
+
+function validKey(key: Uint8Array): boolean {
+  return key instanceof Uint8Array && key.length === 32;
+}
+
+function equalKeys(left: Uint8Array, right: Uint8Array): boolean {
+  return validKey(left) && validKey(right) && timingSafeEqual(left, right);
+}
+
+/** The daemon persists this pair; the phone creates a fresh pair per connection. */
+export async function generateDaemonKeyPair(seed?: Uint8Array): Promise<DaemonKeyPair> {
+  await sodium.ready;
+  if (seed !== undefined && !validKey(seed)) throw new RangeError('X25519 seed must be 32 bytes');
+  const pair = seed === undefined ? sodium.crypto_kx_keypair() : sodium.crypto_kx_seed_keypair(seed);
+  return { publicKey: pair.publicKey, secretKey: pair.privateKey };
+}
+
+export function serverIdFromPublicKey(publicKey: Uint8Array): string {
+  if (!validKey(publicKey)) throw new RangeError('X25519 public key must be 32 bytes');
+  return createHash('sha256').update(publicKey).digest('hex');
+}
+
+export function serializeDaemonKeyPair(pair: DaemonKeyPair): SerializedDaemonKeyPair {
+  if (!validKey(pair.publicKey) || !validKey(pair.secretKey)) throw new RangeError('invalid X25519 key pair');
+  return { publicKey: Buffer.from(pair.publicKey).toString('base64'), secretKey: Buffer.from(pair.secretKey).toString('base64') };
+}
+
+export async function deserializeDaemonKeyPair(serialized: SerializedDaemonKeyPair): Promise<ChannelResult<DaemonKeyPair>> {
+  await sodium.ready;
+  if (typeof serialized?.publicKey !== 'string' || typeof serialized?.secretKey !== 'string' ||
+      !/^[A-Za-z0-9+/]{43}=$/.test(serialized.publicKey) || !/^[A-Za-z0-9+/]{43}=$/.test(serialized.secretKey)) {
+    return rejected('invalid daemon key serialization');
+  }
+  const publicKey = new Uint8Array(Buffer.from(serialized.publicKey, 'base64'));
+  const secretKey = new Uint8Array(Buffer.from(serialized.secretKey, 'base64'));
+  try {
+    if (!validKey(publicKey) || !validKey(secretKey) ||
+        !equalKeys(sodium.crypto_scalarmult_base(secretKey), publicKey)) {
+      return rejected('invalid daemon key pair');
+    }
+  } catch {
+    return rejected('invalid daemon key pair');
+  }
+  return { ok: true, value: { publicKey, secretKey } };
+}
+
+function sequenceBytes(sequence: bigint): Uint8Array {
+  const bytes = new Uint8Array(SEQUENCE_BYTES);
+  new DataView(bytes.buffer).setBigUint64(0, sequence, false);
+  return bytes;
+}
+
+function nonceFor(sequence: bigint): Uint8Array {
+  const nonce = new Uint8Array(NONCE_BYTES);
+  nonce.set(sequenceBytes(sequence), NONCE_BYTES - SEQUENCE_BYTES);
+  return nonce;
+}
+
+/** Each direction uses its own crypto_kx key and monotonically increasing sequence. */
+export class EncryptedChannel {
+  private sendSequence = 0n;
+  private receiveSequence = 0n;
+  private readonly sendKey: Uint8Array;
+  private readonly receiveKey: Uint8Array;
+
+  constructor(sendKey: Uint8Array, receiveKey: Uint8Array) {
+    if (!validKey(sendKey) || !validKey(receiveKey)) throw new RangeError('invalid session keys');
+    this.sendKey = new Uint8Array(sendKey);
+    this.receiveKey = new Uint8Array(receiveKey);
+  }
+
+  seal(plaintext: Uint8Array): ChannelResult<Uint8Array> {
+    if (!(plaintext instanceof Uint8Array)) return rejected('invalid plaintext');
+    if (plaintext.length + SEQUENCE_BYTES + MAC_BYTES > MAX_FRAME_BYTES) return rejected('frame exceeds 1MB');
+    if (this.sendSequence > MAX_SEQUENCE) return rejected('send sequence exhausted');
+    const header = sequenceBytes(this.sendSequence);
+    try {
+      const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
+        plaintext, header, null, nonceFor(this.sendSequence), this.sendKey,
+      );
+      const frame = new Uint8Array(header.length + ciphertext.length);
+      frame.set(header);
+      frame.set(ciphertext, header.length);
+      this.sendSequence++;
+      return { ok: true, value: frame };
+    } catch {
+      return rejected('frame encryption failed');
+    }
+  }
+
+  open(frame: Uint8Array): ChannelResult<Uint8Array> {
+    if (!(frame instanceof Uint8Array) || frame.length < SEQUENCE_BYTES + MAC_BYTES) return rejected('invalid frame');
+    if (frame.length > MAX_FRAME_BYTES) return rejected('frame exceeds 1MB');
+    if (this.receiveSequence > MAX_SEQUENCE) return rejected('receive sequence exhausted');
+    const sequence = new DataView(frame.buffer, frame.byteOffset, SEQUENCE_BYTES).getBigUint64(0, false);
+    if (sequence < this.receiveSequence) return rejected('replayed frame');
+    if (sequence > this.receiveSequence) return rejected('out-of-order frame');
+    const header = frame.subarray(0, SEQUENCE_BYTES);
+    try {
+      const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(
+        null, frame.subarray(SEQUENCE_BYTES), header, nonceFor(sequence), this.receiveKey,
+      );
+      this.receiveSequence++;
+      return { ok: true, value: plaintext };
+    } catch {
+      return rejected('frame authentication failed');
+    }
+  }
+}
+
+export interface PhoneChannel {
+  /** Sent to the daemon during handshake; the private key stays on the phone. */
+  phonePublicKey: Uint8Array;
+  serverId: string;
+  channel: EncryptedChannel;
+}
+
+/** Pin the daemon's public key before deriving any traffic keys. */
+export async function createPhoneChannel(
+  daemonPublicKey: Uint8Array,
+  expectedDaemonPublicKey: Uint8Array,
+  phoneSeed?: Uint8Array,
+): Promise<ChannelResult<PhoneChannel>> {
+  await sodium.ready;
+  if (!validKey(daemonPublicKey) || !equalKeys(daemonPublicKey, expectedDaemonPublicKey)) {
+    return rejected('wrong daemon public key');
+  }
+  if (phoneSeed !== undefined && !validKey(phoneSeed)) return rejected('invalid phone seed');
+  const phoneKeys = phoneSeed === undefined ? sodium.crypto_kx_keypair() : sodium.crypto_kx_seed_keypair(phoneSeed);
+  try {
+    const keys = sodium.crypto_kx_client_session_keys(phoneKeys.publicKey, phoneKeys.privateKey, daemonPublicKey);
+    return { ok: true, value: {
+      phonePublicKey: phoneKeys.publicKey,
+      serverId: serverIdFromPublicKey(daemonPublicKey),
+      channel: new EncryptedChannel(keys.sharedTx, keys.sharedRx),
+    } };
+  } catch {
+    return rejected('invalid daemon public key');
+  }
+}
+
+/** Called with the phone's ephemeral public key; crypto_kx supplies opposite Tx/Rx keys. */
+export async function acceptDaemonChannel(
+  daemonKeys: DaemonKeyPair,
+  phonePublicKey: Uint8Array,
+): Promise<ChannelResult<EncryptedChannel>> {
+  await sodium.ready;
+  if (!validKey(daemonKeys?.publicKey) || !validKey(daemonKeys?.secretKey)) {
+    return rejected('invalid daemon key pair');
+  }
+  if (!validKey(phonePublicKey)) return rejected('invalid phone public key');
+  try {
+    if (!equalKeys(sodium.crypto_scalarmult_base(daemonKeys.secretKey), daemonKeys.publicKey)) {
+      return rejected('invalid daemon key pair');
+    }
+    const keys = sodium.crypto_kx_server_session_keys(daemonKeys.publicKey, daemonKeys.secretKey, phonePublicKey);
+    return { ok: true, value: new EncryptedChannel(keys.sharedTx, keys.sharedRx) };
+  } catch {
+    return rejected('invalid handshake key');
+  }
+}

package/src/relay/mux.ts

@@ -0,0 +1,182 @@
+import { MAX_FRAME_BYTES } from './channel.js';
+import type { ChannelResult } from './channel.js';
+
+export type MuxFrame =
+  | { streamId: number; kind: 'open'; protocol: 'http'; method: string; path: string; headers: Record<string, string> }
+  | { streamId: number; kind: 'open'; protocol: 'ws'; path: string; headers: Record<string, string> }
+  | { streamId: number; kind: 'data'; data: Uint8Array }
+  | { streamId: number; kind: 'close'; reason: string };
+
+// u32 BE length (remaining bytes), u32 BE stream ID, u8 kind (1=open, 2=data, 3=close).
+// Open: u8 protocol (1=http, 2=ws), [http: u16 method bytes + UTF-8 method],
+// u32 path bytes + UTF-8 path, u16 header count, then u16 name bytes + UTF-8 name,
+// u16 value bytes + UTF-8 value per header. Data: remaining raw bytes.
+// Close: u16 reason bytes + UTF-8 reason. One frame per encrypted plaintext.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const HEADER_BYTES = 9;
+// EncryptedChannel appends an 8-byte sequence and 16-byte MAC to each plaintext.
+export const MAX_MUX_FRAME_BYTES = MAX_FRAME_BYTES - 24;
+
+type Result<T> = ChannelResult<T>;
+function reject<T>(reason: string): Result<T> { return { ok: false, reason }; }
+
+class Writer {
+  private parts: Uint8Array[] = [];
+  length = 0;
+  bytes(value: Uint8Array) { this.parts.push(value); this.length += value.length; }
+  number(value: number, size: 1 | 2 | 4) {
+    const bytes = new Uint8Array(size);
+    const view = new DataView(bytes.buffer);
+    if (size === 1) view.setUint8(0, value);
+    else if (size === 2) view.setUint16(0, value, false);
+    else view.setUint32(0, value, false);
+    this.bytes(bytes);
+  }
+  text(value: string, size: 2 | 4): boolean {
+    if (typeof value !== 'string') return false;
+    const bytes = encoder.encode(value);
+    if (bytes.length > (size === 2 ? 0xffff : 0xffffffff)) return false;
+    this.number(bytes.length, size);
+    this.bytes(bytes);
+    return true;
+  }
+  finish(): Uint8Array {
+    const out = new Uint8Array(this.length);
+    let offset = 0;
+    for (const part of this.parts) { out.set(part, offset); offset += part.length; }
+    return out;
+  }
+}
+
+class Reader {
+  offset = 0;
+  constructor(readonly bytes: Uint8Array) {}
+  number(size: 1 | 2 | 4): number | undefined {
+    if (this.offset + size > this.bytes.length) return undefined;
+    const view = new DataView(this.bytes.buffer, this.bytes.byteOffset + this.offset, size);
+    this.offset += size;
+    return size === 1 ? view.getUint8(0) : size === 2 ? view.getUint16(0, false) : view.getUint32(0, false);
+  }
+  text(size: 2 | 4): string | undefined {
+    const length = this.number(size);
+    if (length === undefined || this.offset + length > this.bytes.length) return undefined;
+    const bytes = this.bytes.subarray(this.offset, this.offset + length);
+    this.offset += length;
+    return decoder.decode(bytes);
+  }
+}
+
+function validId(id: number): boolean { return Number.isInteger(id) && id >= 0 && id <= 0xffffffff; }
+
+/** Share one instance between the encoder and decoder of a single endpoint. */
+export class MuxStreamState {
+  private readonly active = new Set<number>();
+
+  isOpen(id: number): boolean { return this.active.has(id); }
+  opened(id: number): void { this.active.add(id); }
+  closed(id: number): void { this.active.delete(id); }
+}
+
+/** No network I/O; shares stream IDs with the receiving decoder when supplied a state. */
+export class MuxEncoder {
+  constructor(private readonly streams: MuxStreamState = new MuxStreamState()) {}
+
+  encode(frame: MuxFrame): Result<Uint8Array> {
+    if (!frame || !validId(frame.streamId)) return reject('invalid stream ID');
+    if (frame.kind !== 'open' && frame.kind !== 'data' && frame.kind !== 'close') return reject('unknown frame kind');
+    if (frame.kind === 'open' ? this.streams.isOpen(frame.streamId) : !this.streams.isOpen(frame.streamId)) {
+      return reject(frame.kind === 'open' ? 'stream already open' : 'stream not open');
+    }
+    const writer = new Writer();
+    writer.number(0, 4);
+    writer.number(frame.streamId, 4);
+    if (frame.kind === 'open') {
+      writer.number(1, 1);
+      if (frame.protocol !== 'http' && frame.protocol !== 'ws') return reject('unknown protocol');
+      writer.number(frame.protocol === 'http' ? 1 : 2, 1);
+      if (frame.protocol === 'http' && (!frame.method || !writer.text(frame.method, 2))) return reject('invalid method');
+      if (!frame.path || !writer.text(frame.path, 4)) return reject('invalid path');
+      if (!frame.headers || typeof frame.headers !== 'object' || Array.isArray(frame.headers)) return reject('invalid headers');
+      const entries = Object.entries(frame.headers);
+      if (entries.length > 0xffff) return reject('invalid headers');
+      writer.number(entries.length, 2);
+      for (const [name, value] of entries) {
+        if (!name || !writer.text(name, 2) || !writer.text(value, 2)) return reject('invalid headers');
+      }
+    } else if (frame.kind === 'data') {
+      if (!(frame.data instanceof Uint8Array)) return reject('invalid data');
+      writer.number(2, 1);
+      writer.bytes(frame.data);
+    } else if (frame.kind === 'close') {
+      writer.number(3, 1);
+      if (!writer.text(frame.reason, 2)) return reject('invalid reason');
+    }
+    if (writer.length > MAX_MUX_FRAME_BYTES) return reject('frame exceeds 1MB');
+    const out = writer.finish();
+    new DataView(out.buffer).setUint32(0, out.length - 4, false);
+    if (frame.kind === 'open') this.streams.opened(frame.streamId);
+    if (frame.kind === 'close') this.streams.closed(frame.streamId);
+    return { ok: true, value: out };
+  }
+}
+
+/** Rejected frames never change stream state. Share state with the sending encoder per endpoint. */
+export class MuxDecoder {
+  constructor(private readonly streams: MuxStreamState = new MuxStreamState()) {}
+
+  decode(bytes: Uint8Array): Result<MuxFrame> {
+    if (!(bytes instanceof Uint8Array)) return reject('invalid frame');
+    if (bytes.length > MAX_MUX_FRAME_BYTES) return reject('frame exceeds 1MB');
+    if (bytes.length < HEADER_BYTES) return reject('truncated frame');
+    const reader = new Reader(bytes);
+    const length = reader.number(4)!;
+    if (length !== bytes.length - 4) return reject(length > bytes.length - 4 ? 'truncated frame' : 'trailing frame bytes');
+    const streamId = reader.number(4)!;
+    const kind = reader.number(1)!;
+    if (kind !== 1 && kind !== 2 && kind !== 3) return reject('unknown frame kind');
+    if (kind === 1 ? this.streams.isOpen(streamId) : !this.streams.isOpen(streamId)) {
+      return reject(kind === 1 ? 'stream already open' : 'stream not open');
+    }
+    try {
+      let frame: MuxFrame;
+      if (kind === 1) {
+        const protocolByte = reader.number(1);
+        if (protocolByte !== 1 && protocolByte !== 2) return reject(protocolByte === undefined ? 'truncated frame' : 'unknown protocol');
+        const method = protocolByte === 1 ? reader.text(2) : undefined;
+        if (protocolByte === 1 && method === undefined) return reject('truncated frame');
+        const path = reader.text(4);
+        const count = reader.number(2);
+        if (path === undefined || count === undefined) return reject('truncated frame');
+        if (!path || (protocolByte === 1 && !method)) return reject('invalid open frame');
+        const entries: [string, string][] = [];
+        const names = new Set<string>();
+        for (let i = 0; i < count; i++) {
+          const name = reader.text(2);
+          const value = reader.text(2);
+          if (name === undefined || value === undefined) return reject('truncated frame');
+          if (!name || names.has(name)) return reject('invalid headers');
+          names.add(name);
+          entries.push([name, value]);
+        }
+        const headers = Object.fromEntries(entries);
+        frame = protocolByte === 1
+          ? { streamId, kind: 'open', protocol: 'http', method: method!, path, headers }
+          : { streamId, kind: 'open', protocol: 'ws', path, headers };
+      } else if (kind === 2) {
+        frame = { streamId, kind: 'data', data: bytes.slice(reader.offset) };
+        reader.offset = bytes.length;
+      } else {
+        const reason = reader.text(2);
+        if (reason === undefined) return reject('truncated frame');
+        frame = { streamId, kind: 'close', reason };
+      }
+      if (reader.offset !== bytes.length) return reject('trailing frame bytes');
+      if (kind === 1) this.streams.opened(streamId);
+      if (kind === 3) this.streams.closed(streamId);
+      return { ok: true, value: frame };
+    } catch {
+      return reject('invalid UTF-8 frame');
+    }
+  }
+}

package/src/relay/relay-cli.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+
+/** `elanous relay serve` — 릴레이 서버(R2 · 내부 문서 `RFC-mobile-relay-without-tailscale-2026-09-30` A5).
+ *  index.ts 원문을 잘라 보는 시험(첫 `.command('serve')` = mcp)을 흔들지 않게 등록을 여기 둔다. */
+export function registerRelayCommand(program: Command): void {
+  const relayCmd = program.command('relay').description('Encrypted WebSocket relay');
+  relayCmd.command('serve')
+    .description('Serve paired relay connections using operator-provisioned host signing keys')
+    .requiredOption('--trusted-host-keys <file>', 'JSON object of X25519-derived serverId to Ed25519 public key (base64url)')
+    .option('--port <port>', 'Listening port', '8765')
+    .action(async (opts: { trustedHostKeys: string; port: string }) => {
+      const port = Number(opts.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('invalid relay port');
+      const { loadTrustedHostKeys, startRelayServer } = await import('./relay-server.js');
+      const relay = startRelayServer({ port, trustedHostKeys: loadTrustedHostKeys(opts.trustedHostKeys) });
+      console.log(`relay listening on 127.0.0.1:${relay.port}`);
+      process.once('SIGINT', () => { relay.stop(); });
+      process.once('SIGTERM', () => { relay.stop(); });
+    });
+}

package/src/relay/relay-server.ts

@@ -0,0 +1,220 @@
+import { createPublicKey, randomBytes, verify } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import type { ServerWebSocket } from 'bun';
+import { MAX_FRAME_BYTES } from './channel.js';
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const MAX_CLIENTS_PER_SERVER = 8;
+const BYTES_PER_SECOND = 1024 * 1024;
+const BURST_BYTES = 2 * BYTES_PER_SECOND;
+const PING_INTERVAL_MS = 30_000;
+const DEAD_PEER_MS = 90_000;
+const AUTH_TIMEOUT_MS = 10_000;
+
+type SocketData = { role: 'host' | 'client'; serverId: string; clientId?: number; challenge?: string; authenticated: boolean; lastSeen: number; tokens: number; refillAt: number; authTimer?: ReturnType<typeof setTimeout> };
+type Socket = ServerWebSocket<SocketData>;
+type Room = { host?: Socket; clients: Map<number, Socket>; nextId: number; bytes: number; failures: Record<string, number> };
+
+export interface RelayServerOptions {
+  port?: number;
+  hostname?: string;
+  /** Ed25519 signing public keys (base64url raw 32 bytes), pinned by X25519-derived serverId. */
+  trustedHostKeys?: ReadonlyMap<string, string>;
+}
+
+/** Load operator-provisioned pins, never keys claimed by connecting hosts. */
+export function loadTrustedHostKeys(file: string): ReadonlyMap<string, string> {
+  const raw: unknown = JSON.parse(readFileSync(file, 'utf8'));
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('invalid relay trusted host keys');
+  const result = new Map<string, string>();
+  for (const [id, key] of Object.entries(raw)) {
+    if (!/^[a-f0-9]{64}$/.test(id) || typeof key !== 'string' || !decodeKey(key)) {
+      throw new Error('invalid relay trusted host key entry');
+    }
+    result.set(id, key);
+  }
+  return result;
+}
+
+export function challengeMessage(serverId: string, nonce: string): Uint8Array {
+  return Buffer.from(`elanous-relay-v1:${serverId}:${nonce}`, 'utf8');
+}
+
+function decodeKey(value: string): Buffer | undefined {
+  if (!/^[A-Za-z0-9_-]{43}$/.test(value)) return undefined;
+  const decoded = Buffer.from(value, 'base64url');
+  return decoded.length === 32 && decoded.toString('base64url') === value ? decoded : undefined;
+}
+
+function encodeClientId(id: number, payload: Uint8Array): Uint8Array {
+  const result = new Uint8Array(payload.length + 4);
+  new DataView(result.buffer).setUint32(0, id, false);
+  result.set(payload, 4);
+  return result;
+}
+
+/** The relay never parses or logs encrypted channel payloads. Host binary frames carry a
+ * four-byte big-endian clientId prefix; phone binary frames are raw ciphertext. */
+export function startRelayServer(options: RelayServerOptions = {}) {
+  if (!options.trustedHostKeys?.size) throw new Error('relay trusted host keys required');
+  const trustedHostKeys = new Map(options.trustedHostKeys);
+  for (const [id, key] of trustedHostKeys) {
+    if (!/^[a-f0-9]{64}$/.test(id) || !decodeKey(key)) throw new Error('invalid relay trusted host key entry');
+  }
+  const rooms = new Map<string, Room>();
+  const sockets = new Set<Socket>();
+  const roomFor = (id: string): Room => {
+    let room = rooms.get(id);
+    if (!room) { room = { clients: new Map(), nextId: 1, bytes: 0, failures: {} }; rooms.set(id, room); }
+    return room;
+  };
+  const fail = (room: Room, reason: string) => { room.failures[reason] = (room.failures[reason] ?? 0) + 1; };
+  const sendControl = (ws: Socket, value: object) => { if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(value)); };
+  const drop = (ws: Socket) => {
+    const data = ws.data;
+    if (data.authTimer) clearTimeout(data.authTimer);
+    sockets.delete(ws);
+    const room = rooms.get(data.serverId);
+    if (!room) return;
+    if (!data.authenticated) {
+      if (!room.host && room.clients.size === 0 &&
+          !Array.from(sockets).some(peer => peer.data.serverId === data.serverId)) rooms.delete(data.serverId);
+      return;
+    }
+    if (data.role === 'host' && room.host === ws) {
+      room.host = undefined;
+      const clients = [...room.clients.values()];
+      room.clients.clear();
+      for (const client of clients) client.close(1012, 'host disconnected');
+    } else if (data.role === 'client' && data.clientId !== undefined && room.clients.get(data.clientId) === ws) {
+      room.clients.delete(data.clientId);
+      if (room.host) sendControl(room.host, { type: 'client-disconnected', clientId: data.clientId });
+    }
+    if (!room.host && room.clients.size === 0 &&
+        !Array.from(sockets).some(peer => peer.data.serverId === data.serverId)) rooms.delete(data.serverId);
+  };
+  const capacity = (ws: Socket, length: number): boolean => {
+    const data = ws.data;
+    const now = Date.now();
+    data.tokens = Math.min(BURST_BYTES, data.tokens + (now - data.refillAt) * BYTES_PER_SECOND / 1000);
+    data.refillAt = now;
+    if (length > data.tokens) return false;
+    data.tokens -= length;
+    return true;
+  };
+  const server = Bun.serve<SocketData>({
+    hostname: options.hostname ?? '127.0.0.1', port: options.port ?? 0,
+    fetch(req, server) {
+      const url = new URL(req.url);
+      if (url.pathname !== '/host' && url.pathname !== '/client') return new Response('not found', { status: 404 });
+      const serverId = url.searchParams.get('serverId');
+      if (!serverId || !/^[a-f0-9]{64}$/.test(serverId)) return new Response('invalid serverId', { status: 400 });
+      if (!trustedHostKeys.has(serverId)) return new Response('unknown serverId', { status: 403 });
+      if (req.headers.get('upgrade')?.toLowerCase() !== 'websocket') return new Response('upgrade required', { status: 426 });
+      const role = url.pathname === '/host' ? 'host' : 'client';
+      const now = Date.now();
+      if (!server.upgrade(req, { data: { role, serverId, authenticated: false, lastSeen: now, tokens: BURST_BYTES, refillAt: now } })) {
+        return new Response('upgrade required', { status: 426 });
+      }
+      return undefined;
+    },
+    websocket: {
+      maxPayloadLength: MAX_FRAME_BYTES + 4,
+      open(ws) {
+        sockets.add(ws);
+        const data = ws.data;
+        const room = roomFor(data.serverId);
+        if (data.role === 'host') {
+          if (room.host) { fail(room, 'duplicate-host'); ws.close(1008, 'host already connected'); return; }
+          data.challenge = randomBytes(32).toString('base64url');
+          sendControl(ws, { type: 'challenge', nonce: data.challenge });
+        } else {
+          if (!room.host || room.clients.size >= MAX_CLIENTS_PER_SERVER) {
+            fail(room, !room.host ? 'host-offline' : 'client-limit');
+            ws.close(1008, !room.host ? 'host offline' : 'client limit reached');
+            return;
+          }
+          const id = room.nextId++;
+          data.clientId = id;
+          data.authenticated = true;
+          room.clients.set(id, ws);
+          sendControl(ws, { type: 'connected', clientId: id });
+          sendControl(room.host, { type: 'client-connected', clientId: id });
+        }
+        if (!data.authenticated) data.authTimer = setTimeout(() => ws.close(1008, 'authentication timeout'), AUTH_TIMEOUT_MS);
+      },
+      message(ws, message) {
+        const data = ws.data;
+        const room = rooms.get(data.serverId);
+        if (!room) { ws.close(1008, 'room missing'); return; }
+        data.lastSeen = Date.now();
+        if (!data.authenticated) {
+          if (data.role !== 'host' || typeof message !== 'string') { fail(room, 'invalid-auth'); ws.close(1008, 'authentication required'); return; }
+          let auth: unknown;
+          try { auth = JSON.parse(message); } catch { /* reject below */ }
+          const value = auth as { type?: unknown; publicKey?: unknown; signature?: unknown } | undefined;
+          const key = typeof value?.publicKey === 'string' ? decodeKey(value.publicKey) : undefined;
+          const signature = typeof value?.signature === 'string' && /^[A-Za-z0-9_-]{86}$/.test(value.signature)
+            ? Buffer.from(value.signature, 'base64url') : undefined;
+          const expected = trustedHostKeys.get(data.serverId);
+          let valid = false;
+          if (value?.type === 'auth' && key && signature?.length === 64 && data.challenge &&
+              value.publicKey === expected) {
+            try {
+              valid = verify(null, challengeMessage(data.serverId, data.challenge),
+                createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, key]), format: 'der', type: 'spki' }), signature);
+            } catch { /* invalid public key */ }
+          }
+          if (!valid || (room.host && room.host !== ws)) { fail(room, 'invalid-auth'); ws.close(1008, 'invalid host signature'); return; }
+          data.authenticated = true;
+          data.challenge = undefined;
+          if (data.authTimer) clearTimeout(data.authTimer);
+          room.host = ws;
+          sendControl(ws, { type: 'authenticated' });
+          return;
+        }
+        if (typeof message === 'string') { fail(room, 'plaintext-data'); ws.close(1003, 'binary ciphertext required'); return; }
+        const bytes = new Uint8Array(message);
+        if (bytes.length > MAX_FRAME_BYTES + (data.role === 'host' ? 4 : 0) || bytes.length < (data.role === 'host' ? 5 : 1)) {
+          fail(room, 'invalid-frame'); ws.close(1009, 'invalid frame size'); return;
+        }
+        if (!capacity(ws, bytes.length)) { fail(room, 'rate-limit'); ws.close(1008, 'rate limit exceeded'); return; }
+        if (data.role === 'client') {
+          if (!room.host || data.clientId === undefined) { ws.close(1012, 'host offline'); return; }
+          room.bytes += bytes.length;
+          room.host.send(encodeClientId(data.clientId, bytes));
+        } else {
+          if (room.host !== ws) { ws.close(1008, 'host replaced'); return; }
+          const clientId = new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0, false);
+          const client = room.clients.get(clientId);
+          if (!client) { fail(room, 'unknown-client'); return; }
+          room.bytes += bytes.length - 4;
+          client.send(bytes.subarray(4));
+        }
+      },
+      pong(ws) { ws.data.lastSeen = Date.now(); },
+      close(ws) { drop(ws); },
+    },
+  });
+  const heartbeat = setInterval(() => {
+    for (const ws of sockets) {
+      if (Date.now() - ws.data.lastSeen > DEAD_PEER_MS) ws.close(1001, 'heartbeat timeout');
+      else ws.ping();
+    }
+  }, PING_INTERVAL_MS);
+  heartbeat.unref();
+  return {
+    server,
+    get port() { return server.port; },
+    stats(serverId: string) {
+      const room = rooms.get(serverId);
+      return room ? { host: !!room.host, clients: room.clients.size, bytes: room.bytes, failures: { ...room.failures } } :
+        { host: false, clients: 0, bytes: 0, failures: {} as Record<string, number> };
+    },
+    stop() {
+      clearInterval(heartbeat);
+      for (const ws of sockets) ws.close(1001, 'relay stopping');
+      server.stop(true);
+    },
+  };
+}

package/src/relay/test-vectors.json

@@ -0,0 +1,29 @@
+{
+  "daemonSeedHex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+  "phoneSeedHex": "202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f",
+  "daemonPublicKeyHex": "0e0216223f147143d32615a91189c288c1728cba3cc5f9f621b1026e03d83129",
+  "phonePublicKeyHex": "99f4674ecc87c0b8e712f192b8f49e7442a9376b4875967ababa28471019a93e",
+  "serverId": "4bc447d530c4044729c44372319cebfcbe079462826a6d39ea4828b149f9c685",
+  "phoneToDaemonKeySha256": "1fd0e0a3bd4e5afff9efb91653c4e67f549b2aaf26e8fea9a5fb263cbd987ea0",
+  "daemonToPhoneKeySha256": "534f8e2462d2bfe07a31cc43a2fd7a46d6109c31289c971c17626324b9806ee8",
+  "nonceHex": "000000000000000000000000000000000000000000000000",
+  "request": {
+    "streamId": 16909060,
+    "kind": "open",
+    "protocol": "http",
+    "method": "POST",
+    "path": "/v1/health",
+    "headers": {
+      "authorization": "Bearer vector-token"
+    }
+  },
+  "requestMuxHex": "000000400102030401010004504f53540000000a2f76312f6865616c74680001000d617574686f72697a6174696f6e001342656172657220766563746f722d746f6b656e",
+  "requestEncryptedHex": "0000000000000000d793343f86630442fcf3812bc1375c4b102aa1ffd546ac4ecbd5f5f4e9e4b3c2de47616a01df19b25b317cd0c5f3c2f0aa7a8b12f307c9872c5f03765a0b1c0e6b6f46dcbda1758ae286b475870eb7ad957f409e",
+  "response": {
+    "streamId": 16909060,
+    "kind": "data",
+    "dataHex": "00ff1020"
+  },
+  "responseMuxHex": "00000009010203040200ff1020",
+  "responseEncryptedHex": "0000000000000000bf589589e25e990a1c7da5fb7a773f0a798e84d1f444d51bd8e3e0bdb4"
+}