@robota-sdk/agent-transport-webrtc 3.0.0-beta.100

package/src/mesh-item-store.ts

@@ -0,0 +1,287 @@
+/**
+ * Where rendezvous records are published: a store of signed mutable items that anyone may run and
+ * nobody is trusted to run honestly.
+ *
+ * A store checks every item it returns against the key and salt it was asked for, so a node or relay
+ * that serves a tampered item, or one signed by another key, yields nothing. What an item holds is
+ * the pair's ciphertext; opening it is the caller's business. Isomorphic: WebCrypto and `fetch`.
+ */
+import {
+  BEP44_MAX_VALUE_BYTES,
+  concatBytes,
+  signMutableItem,
+  verifyMutableItem,
+  bep44SignedBytes,
+  verifyEd25519,
+  type IItemAddress,
+  type IMutableItem,
+} from './mesh-records.js';
+
+export interface IRendezvousItemStore {
+  /** Publish `value` at `address`, as of `now` (ms); rejects when no holder took it. */
+  put(address: IItemAddress, value: Uint8Array, now: number, signal?: AbortSignal): Promise<void>;
+  /** The verified value at `publicKey` and `salt`; `undefined` when none verifies. Never throws. */
+  get(
+    publicKey: Uint8Array,
+    salt: Uint8Array,
+    signal: AbortSignal,
+  ): Promise<Uint8Array | undefined>;
+  close(): void;
+}
+
+function hex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) out += b.toString(16).padStart(2, '0');
+  return out;
+}
+
+// ── In-process network, for tests and loopback ─────────────────────────────────────────────────
+
+export interface IInMemoryItemNetwork {
+  /** A store client attached to this network. */
+  store(): IRendezvousItemStore;
+  /** Every item the network holds, as stored. */
+  items(): readonly IMutableItem[];
+  /** Replace what the network serves (a hostile node): return the item to serve, or `undefined`. */
+  serve(rewrite: (item: IMutableItem) => IMutableItem | undefined): void;
+}
+
+/**
+ * An in-process item network with a DHT node's rules: it refuses an item whose signature does not
+ * verify, and a sequence number lower than the one it holds.
+ */
+export function createInMemoryItemNetwork(): IInMemoryItemNetwork {
+  const held = new Map<string, IMutableItem>();
+  let rewrite: (item: IMutableItem) => IMutableItem | undefined = (item) => item;
+  const target = (k: Uint8Array, salt: Uint8Array | undefined): string =>
+    `${hex(k)}/${hex(salt ?? new Uint8Array(0))}`;
+  return {
+    store: () => ({
+      async put(address, value, now) {
+        const item = await signMutableItem(
+          address.key,
+          address.salt,
+          Math.floor(now / 1000),
+          value,
+        );
+        if (!(await verifyMutableItem(item, item.k, item.salt))) throw new Error('item refused');
+        const at = target(item.k, item.salt);
+        const current = held.get(at);
+        if (current !== undefined && current.seq > item.seq)
+          throw new Error('item refused: older seq');
+        held.set(at, item);
+      },
+      async get(publicKey, salt) {
+        await Promise.resolve();
+        const stored = held.get(target(publicKey, salt));
+        const served = stored === undefined ? undefined : rewrite(stored);
+        if (served === undefined) return undefined;
+        return (await verifyMutableItem(served, publicKey, salt)) ? served.v : undefined;
+      },
+      close: () => undefined,
+    }),
+    items: () => [...held.values()],
+    serve: (next) => {
+      rewrite = next;
+    },
+  };
+}
+
+// ── pkarr relays (HTTP), for clients that cannot reach the DHT ─────────────────────────────────
+
+const Z_BASE32 = 'ybndrfg8ejkmcpqxot1uwisza345h769';
+
+/** z-base-32, as pkarr names keys. */
+export function zBase32(bytes: Uint8Array): string {
+  let out = '';
+  let buffer = 0;
+  let bits = 0;
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += Z_BASE32[(buffer >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += Z_BASE32[(buffer << (5 - bits)) & 31];
+  return out;
+}
+
+const DNS_TYPE_TXT = 16;
+const DNS_CLASS_IN = 1;
+const TXT_TTL_S = 300;
+const RECORD_LABEL = '_r';
+
+function u16(value: number): Uint8Array {
+  return Uint8Array.from([(value >>> 8) & 0xff, value & 0xff]);
+}
+
+/**
+ * The DNS packet a pkarr relay carries: one TXT answer holding `value`. pkarr relays accept only a
+ * DNS packet as the value, and no salt, so the pkarr form of a record is the salt-less item under
+ * the same one-time key, whose value is this packet.
+ */
+export function encodePkarrPacket(publicKey: Uint8Array, value: Uint8Array): Uint8Array {
+  const labels = [RECORD_LABEL, zBase32(publicKey)];
+  const name = concatBytes([
+    ...labels.flatMap((l) => [Uint8Array.of(l.length), new TextEncoder().encode(l)]),
+    Uint8Array.of(0),
+  ]);
+  const chunks: Uint8Array[] = [];
+  for (let i = 0; i < value.length; i += 255) {
+    const part = value.subarray(i, i + 255);
+    chunks.push(Uint8Array.of(part.length), part);
+  }
+  if (value.length === 0) chunks.push(Uint8Array.of(0));
+  const rdata = concatBytes(chunks);
+  return concatBytes([
+    // id 0, flags: response + authoritative, 0 questions, 1 answer, 0 authority, 0 additional
+    Uint8Array.from([0, 0, 0x84, 0, 0, 0, 0, 1, 0, 0, 0, 0]),
+    name,
+    u16(DNS_TYPE_TXT),
+    u16(DNS_CLASS_IN),
+    Uint8Array.from([0, 0, (TXT_TTL_S >>> 8) & 0xff, TXT_TTL_S & 0xff]),
+    u16(rdata.length),
+    rdata,
+  ]);
+}
+
+/** The value of the first TXT answer of a pkarr packet; `undefined` when there is none. */
+export function decodePkarrPacket(packet: Uint8Array): Uint8Array | undefined {
+  const read16 = (at: number): number => ((packet[at] ?? 0) << 8) | (packet[at + 1] ?? 0);
+  if (packet.length < 12) return undefined;
+  const questions = read16(4);
+  const answers = read16(6);
+  let at = 12;
+  const skipName = (): boolean => {
+    for (let hops = 0; hops < 128; hops += 1) {
+      const len = packet[at];
+      if (len === undefined) return false;
+      if (len === 0) {
+        at += 1;
+        return true;
+      }
+      if ((len & 0xc0) === 0xc0) {
+        at += 2;
+        return true;
+      }
+      at += 1 + len;
+    }
+    return false;
+  };
+  for (let q = 0; q < questions; q += 1) {
+    if (!skipName()) return undefined;
+    at += 4;
+  }
+  for (let a = 0; a < answers; a += 1) {
+    if (!skipName() || at + 10 > packet.length) return undefined;
+    const type = read16(at);
+    const rdLength = read16(at + 8);
+    const start = at + 10;
+    const end = start + rdLength;
+    if (end > packet.length) return undefined;
+    if (type === DNS_TYPE_TXT) {
+      const parts: Uint8Array[] = [];
+      let p = start;
+      while (p < end) {
+        const len = packet[p]!;
+        if (p + 1 + len > end) return undefined;
+        parts.push(packet.subarray(p + 1, p + 1 + len));
+        p += 1 + len;
+      }
+      return concatBytes(parts);
+    }
+    at = end;
+  }
+  return undefined;
+}
+
+export interface IPkarrRelayStoreOptions {
+  /** Relay base URLs (`https://…`), each run by whoever the user chose; several operators. */
+  readonly relays: readonly string[];
+  /** Default: the global `fetch`. */
+  readonly fetch?: typeof fetch;
+}
+
+const PKARR_CONTENT_TYPE = 'application/pkarr.org/relays#payload';
+const SIG_BYTES = 64;
+const SEQ_BYTES = 8;
+
+function seqBytes(seq: number): Uint8Array {
+  const out = new Uint8Array(SEQ_BYTES);
+  new DataView(out.buffer).setBigUint64(0, BigInt(seq));
+  return out;
+}
+
+function withoutTrailingSlashes(url: string): string {
+  let end = url.length;
+  while (end > 0 && url[end - 1] === '/') end -= 1;
+  return url.slice(0, end);
+}
+
+/**
+ * A store over several pkarr relays. A put goes to every relay and succeeds when one took it; a get
+ * asks every relay and keeps the newest item that verifies. A relay is only a cache in front of the
+ * DHT: it can withhold or serve stale items, never forge one.
+ */
+export function createPkarrRelayStore(options: IPkarrRelayStoreOptions): IRendezvousItemStore {
+  const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const urlOf = (relay: string, publicKey: Uint8Array): string =>
+    `${withoutTrailingSlashes(relay)}/${zBase32(publicKey)}`;
+  return {
+    async put(address, value, now, signal) {
+      const packet = encodePkarrPacket(address.key.publicKey, value);
+      if (packet.length > BEP44_MAX_VALUE_BYTES)
+        throw new Error('record too large for a pkarr relay');
+      const seq = Math.floor(now) * 1000;
+      const sig = await address.key.sign(bep44SignedBytes(undefined, seq, packet));
+      const body = concatBytes([sig, seqBytes(seq), packet]);
+      const results = await Promise.allSettled(
+        options.relays.map(async (relay) => {
+          const response = await doFetch(urlOf(relay, address.key.publicKey), {
+            method: 'PUT',
+            headers: { 'content-type': PKARR_CONTENT_TYPE },
+            body: body.slice().buffer,
+            ...(signal !== undefined ? { signal } : {}),
+          });
+          if (!response.ok) throw new Error(`pkarr relay refused (${response.status})`);
+        }),
+      );
+      if (!results.some((r) => r.status === 'fulfilled')) {
+        throw new Error('no pkarr relay took the record');
+      }
+    },
+    async get(publicKey, _salt, signal) {
+      const found = await Promise.all(
+        options.relays.map(async (relay) => {
+          try {
+            const response = await doFetch(urlOf(relay, publicKey), { signal });
+            if (!response.ok) return undefined;
+            const body = new Uint8Array(await response.arrayBuffer());
+            if (body.length <= SIG_BYTES + SEQ_BYTES || body.length > 1_200) return undefined;
+            const sig = body.subarray(0, SIG_BYTES);
+            const seq = Number(
+              new DataView(body.buffer, body.byteOffset + SIG_BYTES, SEQ_BYTES).getBigUint64(0),
+            );
+            const packet = body.slice(SIG_BYTES + SEQ_BYTES);
+            if (!Number.isSafeInteger(seq)) return undefined;
+            if (!(await verifyEd25519(publicKey, bep44SignedBytes(undefined, seq, packet), sig))) {
+              return undefined;
+            }
+            const value = decodePkarrPacket(packet);
+            return value === undefined ? undefined : { seq, value };
+          } catch {
+            // allow-fallback: a relay that fails or times out has nothing; the others are asked too
+            return undefined;
+          }
+        }),
+      );
+      let best: { seq: number; value: Uint8Array } | undefined;
+      for (const entry of found)
+        if (entry !== undefined && (best === undefined || entry.seq > best.seq)) best = entry;
+      return best?.value;
+    },
+    close: () => undefined,
+  };
+}

package/src/mesh-lan-listener.ts

@@ -0,0 +1,193 @@
+/**
+ * This device's direct signaling endpoint on the local network: a peer that found it (by the address
+ * cache or mDNS) delivers mesh signals here instead of through a relay.
+ *
+ * It is a mailbox with a relay's rules and nothing more. It delivers only to the rotating pairwise
+ * topics this device holds and treats every byte as hostile: frames and connections are bounded, a
+ * connection that floods is closed, a browser page is turned away, and nothing that arrives here is
+ * trusted — the peer is admitted by the device handshake over the WebRTC channel these signals set
+ * up, or not at all.
+ *
+ * A topic never crosses the network. Frames are addressed by its hash, and an endpoint proves it
+ * holds a topic by a MAC under the topic over the prober's nonce, so an endpoint that merely echoes
+ * what it is sent, or replays what it overheard, cannot pass for the peer and capture the pair's
+ * signals.
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+
+import { WebSocketServer, type WebSocket } from 'ws';
+
+/** A LAN address (a topic's hash) or a nonce: base64url. */
+const LAN_ADDRESS = /^[A-Za-z0-9_-]{43}$/;
+const NONCE = /^[A-Za-z0-9_-]{22}$/;
+/** Largest frame accepted; an SDP with its candidates fits well within it. */
+export const MAX_LAN_FRAME_BYTES = 64 * 1024;
+const MAX_CONNECTIONS = 32;
+/** Frames a connection may send per window before it is closed. */
+const MAX_FRAMES_PER_WINDOW = 128;
+const FRAME_WINDOW_MS = 10_000;
+/** A connection that says nothing for this long is closed. */
+const IDLE_MS = 120_000;
+const POLICY_VIOLATION = 1008;
+
+export interface IMeshLanListener {
+  /** The port it listens on. */
+  readonly port: number;
+  /** Hold exactly these topics (replaces any earlier set). */
+  setPresence(topics: readonly string[]): void;
+  /** A signal delivered to a held topic, named by the topic. Returns an unsubscribe. */
+  onMessage(handler: (topic: string, data: unknown) => void): () => void;
+  close(): Promise<void>;
+}
+
+export interface IMeshLanListenerOptions {
+  /** The port to listen on; when it is taken, any free port. Default: any free port. */
+  readonly port?: number;
+  /** The address to bind; default: every interface. */
+  readonly host?: string;
+}
+
+/** Where frames for `topic` are addressed on the network. */
+export function lanAddressOf(topic: string): string {
+  return createHash('sha256').update(`lan-address:${topic}`).digest('base64url');
+}
+
+/** What an endpoint holding `topic` answers a probe carrying `nonce` with. */
+export function lanPresenceProof(topic: string, nonce: string): string {
+  return createHmac('sha256', topic).update(`lan-present:${nonce}`).digest('base64url');
+}
+
+/** Whether `proof` shows its sender holds `topic`. */
+export function verifyLanPresenceProof(topic: string, nonce: string, proof: unknown): boolean {
+  if (typeof proof !== 'string') return false;
+  const expected = Buffer.from(lanPresenceProof(topic, nonce));
+  const given = Buffer.from(proof);
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+function listen(port: number, host: string | undefined): Promise<WebSocketServer> {
+  return new Promise((resolve, reject) => {
+    const server = new WebSocketServer({
+      port,
+      ...(host !== undefined ? { host } : {}),
+      maxPayload: MAX_LAN_FRAME_BYTES,
+      perMessageDeflate: false,
+      // A peer device sends no Origin; a browser always does, and no web page has business here.
+      verifyClient: (info: { origin?: string }) => info.origin === undefined || info.origin === '',
+    });
+    const onError = (error: Error): void => {
+      server.close();
+      reject(error);
+    };
+    server.once('error', onError);
+    server.once('listening', () => {
+      server.off('error', onError);
+      resolve(server);
+    });
+  });
+}
+
+function decodeFrame(
+  raw: unknown,
+): { type: string; to: string; nonce?: string; data?: unknown } | undefined {
+  let frame: unknown;
+  try {
+    frame = JSON.parse(String(raw));
+  } catch {
+    return undefined;
+  }
+  if (typeof frame !== 'object' || frame === null || Array.isArray(frame)) return undefined;
+  const r = frame as Record<string, unknown>;
+  if (typeof r.type !== 'string' || typeof r.to !== 'string' || !LAN_ADDRESS.test(r.to)) {
+    return undefined;
+  }
+  if (r.type === 'probe') {
+    return typeof r.nonce === 'string' && NONCE.test(r.nonce)
+      ? { type: r.type, to: r.to, nonce: r.nonce }
+      : undefined;
+  }
+  return { type: r.type, to: r.to, data: r.data };
+}
+
+export async function startMeshLanListener(
+  options: IMeshLanListenerOptions = {},
+): Promise<IMeshLanListener> {
+  let server: WebSocketServer;
+  try {
+    server = await listen(options.port ?? 0, options.host);
+  } catch (error) {
+    // allow-fallback: the remembered port is only a preference; any free port serves, peers find it again
+    if (options.port === undefined || options.port === 0) throw error;
+    server = await listen(0, options.host);
+  }
+  const address = server.address();
+  const port = typeof address === 'object' && address !== null ? address.port : 0;
+  /** Address → topic. */
+  let held = new Map<string, string>();
+  const handlers = new Set<(topic: string, data: unknown) => void>();
+
+  server.on('connection', (socket: WebSocket) => {
+    if (server.clients.size > MAX_CONNECTIONS) {
+      socket.close(POLICY_VIOLATION);
+      return;
+    }
+    let frames = 0;
+    let windowStart = Date.now();
+    let idle = setTimeout(() => socket.close(), IDLE_MS);
+    idle.unref?.();
+    socket.on('close', () => clearTimeout(idle));
+    socket.on('error', () => socket.close());
+    socket.on('message', (raw: unknown) => {
+      const now = Date.now();
+      if (now - windowStart > FRAME_WINDOW_MS) {
+        windowStart = now;
+        frames = 0;
+      }
+      frames += 1;
+      if (frames > MAX_FRAMES_PER_WINDOW) {
+        socket.close(POLICY_VIOLATION);
+        return;
+      }
+      clearTimeout(idle);
+      idle = setTimeout(() => socket.close(), IDLE_MS);
+      idle.unref?.();
+      const frame = decodeFrame(raw);
+      if (frame === undefined) return;
+      const topic = held.get(frame.to);
+      if (topic === undefined) {
+        socket.send(JSON.stringify({ type: 'absent', to: frame.to }));
+        return;
+      }
+      if (frame.type === 'probe' && frame.nonce !== undefined) {
+        socket.send(
+          JSON.stringify({
+            type: 'present',
+            to: frame.to,
+            nonce: frame.nonce,
+            proof: lanPresenceProof(topic, frame.nonce),
+          }),
+        );
+        return;
+      }
+      if (frame.type !== 'message') return;
+      for (const handler of handlers) handler(topic, frame.data);
+    });
+  });
+
+  return {
+    port,
+    setPresence(topics) {
+      held = new Map(topics.map((topic) => [lanAddressOf(topic), topic]));
+    },
+    onMessage(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    close() {
+      handlers.clear();
+      held = new Map();
+      for (const client of server.clients) client.terminate();
+      return new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}