@walkhi/code-relax 0.1.0-beta.1

package/dist/src/self-relay/p2p-probe.mjs

@@ -0,0 +1,83 @@
+import { randomUUID } from 'node:crypto';
+import P2pDiagnostics from '../../shared/p2p-diagnostics.cjs';
+
+// Reserve this narrow range so a full-TUN client can identify only the P2P UDP flow.
+const PROBE_UDP_PORT_RANGE = Object.freeze({ begin: 42000, end: 42031 });
+
+// Capability probe only: never accepts or forwards Bridge business messages.
+export async function createP2pProbe({ signal, report = () => {}, iceServers = [] }) {
+  if (!validProbeIceServers(iceServers)) throw new Error('Invalid probe STUN configuration');
+  const { default: rtc } = await import('node-datachannel');
+  const peer = new rtc.PeerConnection('code-relax-probe', {
+    iceServers,
+    maxMessageSize: 4096,
+    portRangeBegin: PROBE_UDP_PORT_RANGE.begin,
+    portRangeEnd: PROBE_UDP_PORT_RANGE.end
+  });
+  const diagnostic = new P2pDiagnostics();
+  let channel, closed = false, answered = false, candidates = [], received = 0, verified = false;
+  const nonce = randomUUID();
+  const timer = setTimeout(() => finish(verified ? 'closed' : 'timeout'), 15000);
+  function finish(state) {
+    if (closed) return;
+    closed = true; clearTimeout(timer); candidates = [];
+    const summary = diagnostic.snapshot(state);
+    channel?.close(); peer.close(); report(state, summary);
+  }
+  peer.onIceStateChange(state => { if (!closed) diagnostic.ice = state; });
+  peer.onGatheringStateChange(state => { if (!closed) diagnostic.gathering = state; });
+  peer.onStateChange(state => { if (!closed && (state === 'failed' || state === 'closed')) { diagnostic.error = 'peer'; finish('failed'); } });
+  peer.onLocalDescription((sdp, type) => { if (!closed) { diagnostic.offer = type === 'offer'; signal({ kind: type, sdp, iceServers }); } });
+  peer.onLocalCandidate((candidate, mid) => { if (!closed) { diagnostic.candidate('local', candidate); signal({ kind: 'candidate', candidate, mid }); } });
+  channel = peer.createDataChannel('code-relax-probe-v1');
+  channel.onOpen(() => { if (!closed) { diagnostic.open = true; channel.sendMessage(JSON.stringify({ type: 'ping', nonce })); } });
+  channel.onError(() => { if (!closed) diagnostic.error = 'channel'; finish('failed'); });
+  channel.onClosed(() => finish('closed'));
+  channel.onMessage(value => {
+    try {
+      if (closed) return;
+      if (typeof value !== 'string' || value.length > 4096 || ++received > 4) throw new Error('Invalid probe frame');
+      const message = JSON.parse(value);
+      if (message.type === 'ping' && /^[\w-]{16,128}$/.test(message.nonce)) {
+        diagnostic.ping = true;
+        channel.sendMessage(JSON.stringify({ type: 'pong', nonce: message.nonce }));
+      } else if (message.type === 'pong' && message.nonce === nonce) {
+        diagnostic.pong = true; verified = true; report('verified', diagnostic.snapshot('verified'));
+      } else throw new Error('Invalid probe response');
+    } catch { diagnostic.error = 'frame'; finish('failed'); }
+  });
+  return {
+    receive(message) {
+      if (closed) return;
+      if (message.kind === 'answer' && !answered) {
+        try { peer.setRemoteDescription(message.sdp, 'answer'); }
+        catch { diagnostic.error = 'description'; finish('failed'); return; }
+        answered = true; diagnostic.answer = true;
+        for (const item of candidates) peer.addRemoteCandidate(item.candidate, item.mid);
+        candidates = [];
+      } else if (message.kind === 'candidate') {
+        diagnostic.candidate('remote', message.candidate);
+        if (answered) peer.addRemoteCandidate(message.candidate, message.mid);
+        else if (candidates.length < 64) candidates.push(message);
+        else finish('failed');
+      } else if (message.kind === 'close') finish('closed');
+      else finish('failed');
+    },
+    close() { finish('closed'); }
+  };
+}
+
+export function validProbeSignal(value) {
+  if (!value || value.version !== 1 || !/^[\w-]{16,128}$/.test(value.probeId || '')) return false;
+  if (['start', 'close'].includes(value.kind)) return true;
+  if (['offer', 'answer'].includes(value.kind)) return typeof value.sdp === 'string' && value.sdp.length <= 65536 &&
+    (value.iceServers === undefined || validProbeIceServers(value.iceServers));
+  if (value.kind === 'candidate') return typeof value.candidate === 'string' && value.candidate.length <= 2048 &&
+    typeof value.mid === 'string' && value.mid.length <= 64;
+  return false;
+}
+
+export function validProbeIceServers(value) {
+  return Array.isArray(value) && value.length <= 4 && value.every(item =>
+    typeof item === 'string' && /^stun:[a-zA-Z0-9.-]+:[0-9]{1,5}$/.test(item) && Number(item.split(':').at(-1)) <= 65535);
+}

package/dist/src/self-relay/server.mjs

@@ -0,0 +1,340 @@
+import http from 'node:http';
+import { deviceStore, validId } from './device-store.mjs';
+import { randomUUID } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { secret, digest, matches, validSecret, send, decode } from './wire.mjs';
+import { readDebugAllowlist, debugAllowed } from './debug-allowlist.mjs';
+import { validProbeSignal } from './p2p-probe.mjs';
+
+// Always loopback; a TLS reverse proxy supplies the private-trial Internet endpoint.
+export async function startSelfRelay({ port = 0, hostKey = secret(), pairingTtlMs = 120000,
+  maxConnections = 32, maxClientsPerHost = 16, maxPayload = 8 * 1024 * 1024, stateFile,
+  publicRelayUrl = '', appDownloadUrl = '', debugAllowlistFile, log = () => {} } = {}) {
+  if (!validSecret(hostKey)) throw new Error('Invalid host credential');
+  if (!Number.isSafeInteger(maxClientsPerHost) || maxClientsPerHost < 1 || maxClientsPerHost > 64) throw new Error('Invalid mobile device limit');
+  if (publicRelayUrl) relayPublicAddress(publicRelayUrl);
+  // Harmony's native WebSocket supplies the endpoint Origin automatically.
+  // libwebsockets can use http even for WSS; trust only the configured endpoint.
+  const nativeOrigins = publicRelayUrl ? ['http:', 'https:'].map(protocol => `${protocol}//${new URL(publicRelayUrl).host}`) : [];
+  if (appDownloadUrl && !/^https:\/\/[^\s]+$/.test(appDownloadUrl)) throw new Error('Invalid app download URL');
+  const hostHash = digest(hostKey), rooms = new Map();
+  const store = deviceStore(stateFile);
+  const debugAllowlist = readDebugAllowlist(debugAllowlistFile);
+  for (const record of store.entries()) rooms.set(record.id, { ...record, durable: true, connections: new Map(), observers: new Map() });
+  function commit(room, changes) {
+    const next = { ...room, ...changes, updatedAt: new Date().toISOString() };
+    if (room.durable) {
+      const { id, hostHash, clients, revision, status, createdAt, updatedAt, officialComputer } = next;
+      store.save({ id, hostHash, clients, revision, status, createdAt, updatedAt, ...(officialComputer ? { officialComputer } : {}) });
+    }
+    Object.assign(room, changes, { updatedAt: next.updatedAt });
+  }
+  function invitation(room) {
+    const code = secret(); room.pairingHash = digest(code); room.expires = Date.now() + pairingTtlMs;
+    return { code, expires: room.expires };
+  }
+  let listenUrl = '';
+  function relayUrl(request) {
+    if (publicRelayUrl) return relayPublicAddress(publicRelayUrl);
+    const host = request.headers.host || new URL(listenUrl).host;
+    const secure = request.socket.encrypted || request.headers['x-forwarded-proto'] === 'https';
+    return `${secure ? 'wss' : 'ws'}://${host}/relay`;
+  }
+  function findInvitation(code) {
+    if (!validSecret(code)) return undefined;
+    return [...rooms.values()].find(room => room.status === 'active' && room.pairingHash && Date.now() < room.expires && matches(code, room.pairingHash));
+  }
+  const server = http.createServer((request, response) => {
+    const target = new URL(request.url || '/', `http://${request.headers.host || 'localhost'}`);
+    if (request.method !== 'GET' || !['/pair', '/pair/resolve'].includes(target.pathname)) {
+      response.writeHead(404, { 'Cache-Control': 'no-store' }); response.end(); return;
+    }
+    const code = target.searchParams.get('invite') || '';
+    const room = findInvitation(code);
+    if (!room) {
+      const json = target.pathname === '/pair/resolve' || /application\/json/i.test(request.headers.accept || '');
+      const body = json ? JSON.stringify({ error: '配对邀请已过期或已使用' }) : pairingPage({ expired: true });
+      response.writeHead(410, pairingHeaders(json ? 'application/json; charset=utf-8' : 'text/html; charset=utf-8', body)); response.end(body); return;
+    }
+    if (target.pathname === '/pair/resolve' || /application\/json/i.test(request.headers.accept || '')) {
+      const body = JSON.stringify({ version: 3, relayUrl: relayUrl(request), room: room.id, expires: room.expires });
+      response.writeHead(200, pairingHeaders('application/json; charset=utf-8', body)); response.end(body); return;
+    }
+    const secure = request.socket.encrypted || request.headers['x-forwarded-proto'] === 'https';
+    const current = new URL(target.pathname + target.search, `${secure ? 'https' : 'http'}://${request.headers.host || new URL(listenUrl).host}`);
+    const body = pairingPage({ deepLink: `codex-remote://pair?url=${encodeURIComponent(current.href)}`, expires: room.expires, appDownloadUrl });
+    response.writeHead(200, pairingHeaders('text/html; charset=utf-8', body)); response.end(body);
+  });
+  const wss = new WebSocketServer({ noServer: true, maxPayload, perMessageDeflate: {
+    serverNoContextTakeover: true, clientNoContextTakeover: true,
+    threshold: 1024, concurrencyLimit: 4, zlibDeflateOptions: { level: 3 },
+  } });
+  let admissionStart = Date.now(), admissions = 0;
+  server.on('upgrade', (request, socket, head) => {
+    if (request.url !== '/relay' || (request.headers.origin && request.headers.origin !== 'null' && !nativeOrigins.includes(request.headers.origin))) {
+      log({ event: 'upgrade-rejected', reason: request.url !== '/relay' ? 'path' : 'origin' });
+      socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return;
+    }
+    if (Date.now() - admissionStart >= 60000) { admissionStart = Date.now(); admissions = 0; }
+    if (wss.clients.size >= maxConnections || ++admissions > 60) {
+      socket.end('HTTP/1.1 429 Too Many Requests\r\nConnection: close\r\n\r\n'); return;
+    }
+    wss.handleUpgrade(request, socket, head, ws => wss.emit('connection', ws));
+  });
+  wss.on('connection', ws => {
+    let role, room, session, clientId, alive = true;
+    const authTimer = setTimeout(() => ws.close(1008, 'Authentication timeout'), 5000);
+    ws.on('pong', () => { alive = true; });
+    const heartbeat = setInterval(() => { if (!alive) ws.terminate(); else { alive = false; ws.ping(); } }, 30000);
+    const fail = (code = 4401, reason = 'Device authorization rejected') => ws.close(code, reason);
+    ws.on('error', () => {}); // close owns routing cleanup.
+    ws.on('close', (code, reason) => {
+      log({ event: 'closed', role: role || 'unauthenticated', device: room?.id, code, reason: reason.toString() });
+      clearTimeout(authTimer); clearInterval(heartbeat);
+      if (role === 'host' && room?.host === ws) {
+        room.host = undefined; room.hostName = undefined; room.lanCandidates = [];
+        for (const observer of room.observers.values()) send(observer.ws, { type: 'observing', online: false });
+        if (!room.durable) rooms.delete(room.id);
+        for (const connection of room.connections.values()) connection.ws.close(4410, 'Computer offline; authorization retained');
+      } else if (role === 'client' && room?.connections.get(clientId)?.ws === ws) {
+        room.connections.delete(clientId);
+        if (room.host) send(room.host, { type: 'detach', session });
+      } else if (role === 'observer' && room?.observers.get(clientId)?.ws === ws) {
+        room.observers.delete(clientId);
+      }
+    });
+    ws.on('message', (bytes, binary) => {
+      try {
+        const message = decode(bytes, binary);
+        if (!role) {
+          if (message.type === 'host') {
+            const durable = message.deviceId !== undefined;
+            if (durable && (!validId(message.deviceId) || !validSecret(message.deviceSecret))) return fail();
+            if (!durable && stateFile) return fail(4406, 'Device protocol upgrade required');
+            let lanCandidates, hostName;
+            try {
+              lanCandidates = normalizeLanCandidates(message.lanCandidates);
+              hostName = normalizeHostName(message.hostName);
+            }
+            catch { return fail(1008, 'Invalid LAN candidates'); }
+            room = durable ? rooms.get(message.deviceId) : undefined;
+            if (room && (room.status !== 'active' || !matches(message.deviceSecret, room.hostHash))) return fail();
+            if (!room) {
+              if (!matches(message.key, hostHash)) return fail();
+              if (rooms.size >= 256) return fail(4429, 'Device limit reached');
+              const now = new Date().toISOString();
+              room = { id: durable ? message.deviceId : randomUUID(), durable,
+                revision: 0, status: 'active', clients: [], connections: new Map(), observers: new Map(), createdAt: now, updatedAt: now,
+                ...(durable ? { hostHash: digest(message.deviceSecret) } : {}) };
+              commit(room, {}); rooms.set(room.id, room);
+            }
+            const oldHost = room.host;
+            room.observers ||= new Map();
+            room.host = ws; room.hostName = hostName; room.lanCandidates = lanCandidates;
+            room.p2pProbe = message.p2pProbe === 1; room.p2pProbeRepeat = message.p2pProbeRepeat === true;
+            role = 'host'; clearTimeout(authTimer);
+            if (oldHost && oldHost !== ws) {
+              oldHost.close(4409, 'Computer connection replaced');
+              for (const connection of room.connections.values()) connection.ws.close(4410, 'Computer reconnecting');
+            }
+            for (const observer of room.observers.values()) {
+              send(observer.ws, { type: 'observing', online: true });
+              send(observer.ws, { type: 'computer-info', hostName: room.hostName });
+              send(observer.ws, { type: 'lan-candidates', candidates: room.lanCandidates });
+            }
+            const invite = room.clients.length ? {} : invitation(room);
+            send(ws, { type: 'registered', protocolVersion: 3, room: room.id, paired: room.clients.length > 0,
+              clientCount: room.clients.length, clients: room.clients, revision: room.revision, ...invite }); return;
+          }
+          room = rooms.get(message.room);
+          if (!room || room.status !== 'active') return fail();
+          let credential;
+          if (message.type === 'pair' && room.pairingHash && Date.now() < room.expires && matches(message.code, room.pairingHash)) {
+            if (!room.host) return fail(4410, 'Computer offline; authorization retained');
+            credential = message.credential || secret();
+            clientId = message.clientId || (!room.durable ? randomUUID() : undefined);
+            if (!validSecret(credential) || !validId(clientId)) return fail();
+            const existing = room.clients.find(client => client.id === clientId);
+            if (!existing && room.clients.length >= maxClientsPerHost) return fail(4429, 'Mobile device limit reached');
+            const now = new Date().toISOString();
+            const client = { id: clientId, hash: digest(credential), createdAt: existing?.createdAt || now, updatedAt: now };
+            commit(room, { clients: [...room.clients.filter(item => item.id !== clientId), client], revision: room.revision + 1 });
+            room.pairingHash = undefined;
+            send(room.host, { type: 'authorization-changed', clients: room.clients, revision: room.revision });
+          } else {
+            clientId = message.clientId;
+            const client = room.clients.find(item => item.id === clientId) ||
+              (!room.durable && !clientId ? room.clients.find(item => matches(message.credential, item.hash)) : undefined);
+            if (client) clientId = client.id;
+            if (!['resume', 'pair', 'observe'].includes(message.type) || !client || !matches(message.credential, client.hash)) {
+            return fail(message.type === 'pair' ? 4408 : 4401, message.type === 'pair' ? 'Pairing code expired or used' : 'Device authorization rejected');
+            }
+          }
+          if (message.type === 'observe') {
+            role = 'observer'; clearTimeout(authTimer); room.observers ||= new Map();
+            const oldObserver = room.observers.get(clientId);
+            if (oldObserver?.ws && oldObserver.ws !== ws) oldObserver.ws.close(4409, 'Metadata connection replaced by same identity');
+            room.observers.set(clientId, { ws });
+            send(ws, { type: 'observing', online: Boolean(room.host) });
+            send(ws, { type: 'debug-permissions', enabled: debugAllowed(debugAllowlist, room.id, room.clients.find(client => client.id === clientId)) });
+            if (room.hostName) send(ws, { type: 'computer-info', hostName: room.hostName });
+            if (room.lanCandidates?.length) send(ws, { type: 'lan-candidates', candidates: room.lanCandidates });
+            if (room.officialComputer) send(ws, { type: 'official-computer', computer: room.officialComputer });
+            return;
+          }
+          if (!room.host) return fail(4410, 'Computer offline; authorization retained');
+          const oldConnection = room.connections.get(clientId);
+          role = 'client'; clearTimeout(authTimer); session = randomUUID();
+          if (oldConnection?.ws && oldConnection.ws !== ws) {
+            send(room.host, { type: 'detach', session: oldConnection.session });
+            oldConnection.ws.close(4409, 'Phone connection replaced by same identity');
+          }
+          room.connections.set(clientId, { ws, session, p2pProbe: room.p2pProbe && message.p2pProbe === 1,
+            repeat: room.p2pProbeRepeat, signals: 0, probeStarted: 0 });
+          send(ws, { type: 'paired', protocolVersion: 3, room: room.id, clientId, revision: room.revision, ...(credential ? { credential } : {}) });
+          send(ws, { type: 'computer-info', hostName: room.hostName });
+          if (room.lanCandidates?.length) send(ws, { type: 'lan-candidates', candidates: room.lanCandidates });
+          send(room.host, { type: 'attach', session, clientId, p2pProbe: room.connections.get(clientId).p2pProbe ? 1 : 0 }); return;
+        }
+        if (role === 'host') {
+          if (room.host !== ws) return;
+          if (message.type === 'lan-candidates') {
+            room.lanCandidates = normalizeLanCandidates(message.candidates);
+            for (const connection of room.connections.values()) send(connection.ws, { type: 'lan-candidates', candidates: room.lanCandidates });
+            for (const observer of room.observers.values()) send(observer.ws, { type: 'lan-candidates', candidates: room.lanCandidates });
+            return;
+          }
+          if (message.type === 'status') {
+            send(ws, { type: 'status', commandId: message.commandId, paired: room.clients.length > 0, clientCount: room.clients.length, revision: room.revision }); return;
+          }
+          if (message.type === 'pair-code') {
+            send(ws, { type: 'pair-code', commandId: message.commandId, room: room.id, ...invitation(room) }); return;
+          }
+          if (message.type === 'revoke') {
+            commit(room, { clients: [], revision: room.revision + 1 });
+            room.pairingHash = undefined;
+            for (const connection of room.connections.values()) {
+              send(ws, { type: 'detach', session: connection.session });
+              connection.ws.close(4401, 'Device authorization revoked');
+            }
+            room.connections.clear();
+            for (const observer of room.observers.values()) observer.ws.close(4401, 'Device authorization revoked');
+            room.observers.clear();
+            send(ws, { type: 'authorization-changed', clients: [], revision: room.revision });
+            send(ws, { type: 'revoked', commandId: message.commandId, room: room.id }); return;
+          }
+          const connection = [...room.connections.values()].find(item => item.session === message.session);
+          if (!connection) return; // Late frames from an ended session.
+          if (message.type === 'data' && typeof message.payload === 'string') send(connection.ws, { type: 'data', payload: message.payload });
+          else if (message.type === 'ready') send(connection.ws, { type: 'ready', p2pProbe: connection.p2pProbe ? 1 : 0,
+            p2pProbeRepeat: connection.p2pProbe && connection.repeat });
+          else if (message.type === 'p2p-probe' && connection.p2pProbe && validProbeSignal(message)) {
+            if (connection.probeId !== message.probeId) return;
+            if (++connection.signals > 150) return fail(1008, 'Probe signal limit');
+            send(connection.ws, { ...message, session: undefined });
+          }
+          else if (message.type === 'detach') connection.ws.close(1011, 'Local Bridge unavailable');
+          else fail();
+        } else if (role === 'observer' && room.observers.get(clientId)?.ws === ws && message.type === 'official-computer') {
+          const computer = normalizeOfficialComputer(message);
+          commit(room, { officialComputer: computer });
+          send(ws, { type: 'official-computer-saved', computer });
+        } else if (role === 'client' && room.connections.get(clientId)?.ws === ws && message.type === 'p2p-probe') {
+          const connection = room.connections.get(clientId);
+          if (!connection.p2pProbe || !validProbeSignal(message)) return fail(1008, 'Invalid probe signal');
+          if (message.kind === 'start') {
+            if (connection.probeId && (!connection.repeat || Date.now() - connection.probeStarted < 2000)) {
+              send(ws, { type: 'p2p-probe', version: 1, probeId: message.probeId, kind: 'close' }); return;
+            }
+            connection.probeId = message.probeId; connection.signals = 0; connection.probeStarted = Date.now();
+          }
+          if (connection.probeId !== message.probeId) return;
+          if (++connection.signals > 150) return fail(1008, 'Probe signal limit');
+          send(room.host, { ...message, session });
+        } else if (room.connections.get(clientId)?.ws === ws && message.type === 'data' && typeof message.payload === 'string') {
+          send(room.host, { type: 'data', session, payload: message.payload });
+        } else fail();
+      } catch (error) { log({ event: 'request-error', role, message: 'Relay operation failed' }); ws.close(1011, 'Relay operation failed'); }
+    });
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+  listenUrl = `ws://127.0.0.1:${server.address().port}/relay`;
+  return {
+    url: listenUrl, hostKey,
+    async close() {
+      for (const ws of wss.clients) ws.terminate();
+      await new Promise(resolve => wss.close(resolve));
+      await new Promise(resolve => server.close(resolve));
+    },
+  };
+}
+
+function relayPublicAddress(value) {
+  const parsed = new URL(value);
+  if (!['ws:', 'wss:'].includes(parsed.protocol) || parsed.pathname !== '/relay' || parsed.search || parsed.hash || parsed.username || parsed.password) {
+    throw new Error('Invalid public relay URL');
+  }
+  return parsed.href;
+}
+
+function pairingHeaders(type, body) {
+  return { 'Content-Type': type, 'Content-Length': Buffer.byteLength(body), 'Cache-Control': 'no-store',
+    'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'" };
+}
+
+function pairingPage({ deepLink = '', expires = 0, appDownloadUrl = '', expired = false }) {
+  const open = deepLink ? `<a class="primary" href="${escapeHtml(deepLink)}">打开 Code Relax</a>` : '';
+  const download = appDownloadUrl ? `<a href="${escapeHtml(appDownloadUrl)}">安装 Code Relax</a>` : '<p>尚未安装时，请通过当前私测渠道安装 App，再重新打开此页面。</p>';
+  const text = expired ? '这条设备配对邀请已过期或已经使用，请在电脑重新生成。'
+    : `这是一次性设备配对邀请，有效期至 ${escapeHtml(new Date(expires).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' }))}。每台移动设备只需配对一次。`;
+  return `<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Code Relax 配对</title><style>body{margin:0;background:#0d1210;color:#eef4f0;font:16px system-ui,sans-serif}main{max-width:520px;margin:12vh auto;padding:32px}h1{font-size:28px}p{color:#aab7af;line-height:1.7}a{display:block;margin-top:16px;padding:14px 18px;border:1px solid #496257;border-radius:12px;color:#dce9e1;text-align:center;text-decoration:none}.primary{background:#1f5a40;border-color:#367c5b}</style><main><h1>Code Relax</h1><p>${text}</p>${expired ? '' : open + download}</main></html>`;
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+}
+
+function normalizeLanCandidates(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 8) throw new Error('Invalid LAN candidates');
+  return value.map(candidate => {
+    const endpoint = new URL(candidate?.address || '');
+    if (endpoint.protocol !== 'http:' || !endpoint.port || endpoint.pathname !== '/' || endpoint.search || endpoint.hash ||
+        endpoint.username || endpoint.password || !privateIpv4(endpoint.hostname) ||
+        !['wifi', 'ethernet'].includes(candidate.networkType) || !plainLabel(candidate.networkName) || !plainLabel(candidate.interfaceName)) {
+      throw new Error('Invalid LAN candidate');
+    }
+    return { address: endpoint.href.replace(/\/$/, ''), networkType: candidate.networkType,
+      networkName: candidate.networkName.trim(), interfaceName: candidate.interfaceName.trim() };
+  });
+}
+
+function normalizeHostName(value) {
+  if (!plainLabel(value)) throw new Error('Invalid host name');
+  return value.trim();
+}
+
+function normalizeOfficialComputer(value) {
+  if (!plainText(value.environmentId, 256, false) || !plainText(value.name ?? '', 80, true) ||
+      !plainText(value.hostname ?? '', 80, true)) throw new Error('Invalid official computer');
+  return { environmentId: value.environmentId.trim(), name: (value.name || '').trim(),
+    hostname: (value.hostname || '').trim(), updatedAt: new Date().toISOString() };
+}
+
+function privateIpv4(value) {
+  const parts = value.split('.').map(Number);
+  if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  return parts[0] === 10 || (parts[0] === 192 && parts[1] === 168) ||
+    (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) ||
+    (parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127);
+}
+
+function plainLabel(value) {
+  return typeof value === 'string' && value.trim().length > 0 && value.trim().length <= 80 && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+
+function plainText(value, limit, empty) {
+  return typeof value === 'string' && (empty || value.trim().length > 0) && value.trim().length <= limit && !/[\u0000-\u001f\u007f]/.test(value);
+}

package/dist/src/self-relay/windows-route-helper.mjs

@@ -0,0 +1,75 @@
+import net from 'node:net';
+
+const pipePath = String.raw`\\.\pipe\CodeRelaxRtcRouteHelper`;
+
+export function createWindowsRouteHelper({ enabled = false, token = '', iceServers = [], report = () => {} } = {}) {
+  const addresses = new Set();
+  const routeAddresses = new Set(iceServers.map(stunAddress).filter(publicIpv4));
+  let chain = Promise.resolve();
+  const enqueue = task => chain = chain.then(task, task);
+  if (!enabled || process.platform !== 'win32') return { prepare() { return Promise.resolve(); }, include() { return Promise.resolve(); } };
+  if (!/^[A-Za-z0-9_-]{32,128}$/.test(token)) throw new Error('Windows RTC 路由辅助凭据无效');
+  const add = values => enqueue(async () => {
+    for (const value of values) addresses.add(value);
+    if (!values.length) return;
+    const result = await request({ token, action: 'add', addresses: [...addresses], ttlSeconds: 120 });
+    if (!result.ok) throw new Error(result.error || 'Windows RTC 路由辅助不可用');
+    report('windows-route-helper', { count: addresses.size });
+  });
+  return {
+    prepare() { return add([...routeAddresses]); },
+    include(message) {
+      const discovered = candidateAddresses(message);
+      return add(discovered.filter(value => !addresses.has(value)));
+    }
+  };
+}
+
+function stunAddress(value) {
+  const match = /^stun:([^:]+):\d{1,5}$/i.exec(value || '');
+  return match?.[1] || '';
+}
+
+function candidateAddresses(message) {
+  const text = message?.kind === 'candidate' ? message.candidate : ['offer', 'answer'].includes(message?.kind) ? message.sdp : '';
+  const result = new Set();
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const parts = line.trim().replace(/^a=/, '').split(/\s+/);
+    if (parts[0]?.startsWith('candidate:') && parts[6] === 'typ' && publicIpv4(parts[4])) result.add(parts[4]);
+  }
+  return [...result];
+}
+
+function publicIpv4(value) {
+  const parts = String(value).split('.').map(Number);
+  if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  const [a, b] = parts;
+  return a !== 0 && a !== 10 && a !== 127 && a < 224 && !(a === 169 && b === 254) && !(a === 172 && b >= 16 && b <= 31) &&
+    !(a === 192 && b === 168) && !(a === 100 && b >= 64 && b <= 127) && !(a === 198 && (b === 18 || b === 19));
+}
+
+function request(value) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(pipePath);
+    let text = '';
+    let settled = false;
+    const rejectOnce = error => { if (!settled) { settled = true; reject(error); } };
+    const resolveOnce = result => { if (!settled) { settled = true; resolve(result); } };
+    socket.setTimeout(3000);
+    socket.setEncoding('utf8');
+    socket.once('connect', () => socket.write(`${JSON.stringify(value)}\n`));
+    socket.on('data', chunk => {
+      text += chunk;
+      const line = text.indexOf('\n');
+      if (line < 0) return;
+      try { resolveOnce(JSON.parse(text.slice(0, line))); socket.end(); }
+      catch { rejectOnce(new Error('Windows RTC 路由辅助响应无效')); socket.destroy(); }
+    });
+    socket.once('timeout', () => socket.destroy(new Error('Windows RTC 路由辅助超时')));
+    socket.once('error', rejectOnce);
+    socket.once('close', hadError => {
+      if (hadError || settled) return;
+      rejectOnce(new Error('Windows RTC 路由辅助响应无效'));
+    });
+  });
+}

package/dist/src/self-relay/wire.mjs

@@ -0,0 +1,36 @@
+import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+import { WebSocket } from 'ws';
+
+export const secret = () => randomBytes(32).toString('base64url');
+export const digest = value => createHash('sha256').update(value).digest('hex');
+export const validSecret = value => typeof value === 'string' && /^[\w-]{43}$/.test(value);
+export function matches(value, hash) {
+  return validSecret(value) && typeof hash === 'string' && timingSafeEqual(Buffer.from(digest(value)), Buffer.from(hash));
+}
+export function send(socket, message) {
+  if (socket.readyState !== WebSocket.OPEN) return false;
+  if (socket.bufferedAmount > 64 * 1024 * 1024) { socket.close(1013, 'Receiver too slow'); return false; }
+  socket.send(JSON.stringify(message)); return true;
+}
+export function decode(bytes, binary) {
+  if (binary) throw new Error('Text frames required');
+  const value = JSON.parse(bytes.toString());
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Object required');
+  return value;
+}
+export function loopbackUrl(value, pathname) {
+  const url = new URL(value);
+  if (url.protocol !== 'ws:' || url.hostname !== '127.0.0.1' || url.pathname !== pathname || url.search || url.hash || url.username || url.password) {
+    throw new Error('本地原型仅接受指定路径的 ws://127.0.0.1 地址');
+  }
+  return url.href;
+}
+
+export function relayAddress(value) {
+  const url = new URL(value);
+  if (url.protocol === 'ws:') return loopbackUrl(value, '/relay');
+  if (url.protocol !== 'wss:' || url.pathname !== '/relay' || url.search || url.hash || url.username || url.password) {
+    throw new Error('远程中继必须使用无查询凭据的 wss://主机/relay 地址');
+  }
+  return url.href;
+}