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

package/src/mesh-turn-relay.ts

@@ -0,0 +1,238 @@
+/**
+ * The device mesh's relay of last resort: a TURN server on one of the user's always-on devices, used
+ * only by the devices of the same roster, with short-lived credentials each pair derives on its own.
+ *
+ * A credential follows the TURN REST scheme — the username carries its expiry, the password is a MAC
+ * of the username — but the MAC key is the pair's secret rather than one shared by every client: the
+ * username is `<expiry>:<tag>`, where the tag is the pair's rotating relay-user tag, so it names no
+ * device to whoever sees it, and only the relay device can tell whose it is. A device the lists no
+ * longer name, or revoke, derives no tag and no password, and its allocations close.
+ *
+ * The relay moves datagrams between two ends that run DTLS with each other; it never holds a key of
+ * that channel, and a connection through it is admitted by the device handshake exactly as a direct
+ * one is.
+ */
+import { rendezvousEpoch, type IPairRendezvous } from '@robota-sdk/agent-remote-pairing';
+
+import { TurnServer, type ITurnQuotas } from './turn-server.js';
+
+import type { IIceServer } from './webrtc-transport-options.js';
+
+/** Where a paired device's relay listens. */
+export interface IMeshRelayEndpoint {
+  readonly host: string;
+  readonly port: number;
+}
+
+/** A device the relay serves, with the pair's rendezvous. */
+export interface IMeshRelayPeer {
+  readonly deviceId: string;
+  readonly rendezvous: IPairRendezvous;
+}
+
+/** How long a relay credential is good for, by default. */
+export const DEFAULT_RELAY_CREDENTIAL_TTL_MS = 10 * 60 * 1000;
+/** The longest a relay accepts: a credential cannot outlive the tag epochs its relay looks up. */
+export const MAX_RELAY_CREDENTIAL_TTL_MS = 60 * 60 * 1000;
+/** Clocks of two devices may disagree by this much. */
+const CLOCK_SKEW_MS = 60 * 1000;
+const TAG_BYTES = 16;
+const USERNAME = /^(\d{1,12}):([A-Za-z0-9_-]{22})$/;
+
+function base64Url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64url');
+}
+
+/** A relay credential this device presents to `rendezvous`'s peer's relay, good until `now + ttlMs`. */
+export async function meshRelayCredential(
+  rendezvous: IPairRendezvous,
+  now: number,
+  ttlMs: number = DEFAULT_RELAY_CREDENTIAL_TTL_MS,
+): Promise<{ readonly username: string; readonly credential: string }> {
+  const ttl = Math.min(Math.max(ttlMs, 1000), MAX_RELAY_CREDENTIAL_TTL_MS);
+  const tag = (await rendezvous.tag('relay-user', 'outbound', rendezvousEpoch(now))).slice(
+    0,
+    TAG_BYTES,
+  );
+  const username = `${Math.floor((now + ttl) / 1000)}:${base64Url(tag)}`;
+  return { username, credential: await rendezvous.relayPassword('outbound', username) };
+}
+
+function turnUrl(endpoint: IMeshRelayEndpoint): string {
+  const host = endpoint.host.includes(':') ? `[${endpoint.host}]` : endpoint.host;
+  return `turn:${host}:${endpoint.port}?transport=udp`;
+}
+
+/** ICE servers for a paired device's relay endpoints, with this pair's credential. */
+export async function meshRelayIceServers(
+  rendezvous: IPairRendezvous,
+  endpoints: readonly IMeshRelayEndpoint[],
+  now: number,
+  ttlMs?: number,
+): Promise<IIceServer[]> {
+  if (endpoints.length === 0) return [];
+  const { username, credential } = await meshRelayCredential(rendezvous, now, ttlMs);
+  return endpoints.map((endpoint) => ({ urls: turnUrl(endpoint), username, credential }));
+}
+
+/**
+ * Why a relay was needed: only relayed connections are allowed, or a direct attempt got as far as
+ * trying paths and found none.
+ */
+export type TMeshRelayNeed = 'relay-only' | 'no-direct-path';
+
+/**
+ * A connection needed a relay and none could be tried. Never a silent degrade — the connection is
+ * refused with this error, which carries what the direct attempt went through as its `cause`.
+ */
+export class MeshRelayNeededError extends Error {
+  public readonly deviceId: string;
+  public readonly need: TMeshRelayNeed;
+
+  public constructor(
+    deviceId: string,
+    need: TMeshRelayNeed,
+    options?: { readonly cause?: unknown },
+  ) {
+    const why =
+      need === 'relay-only'
+        ? 'only relayed connections are allowed'
+        : `no direct path was found (${
+            options?.cause instanceof Error ? options.cause.message : String(options?.cause)
+          })`;
+    super(
+      `a relay device is needed to reach device ${deviceId}: ${why}, and no paired device ` +
+        'advertises a relay and no TURN server is configured. Run the relay on an always-on ' +
+        'device, or configure a TURN server.',
+      options?.cause !== undefined ? { cause: options.cause } : undefined,
+    );
+    this.name = 'MeshRelayNeededError';
+    this.deviceId = deviceId;
+    this.need = need;
+  }
+}
+
+export interface IMeshTurnRelayOptions {
+  /** Default every IPv4 interface. */
+  readonly host?: string;
+  /** Default 3478; 0 picks a free port. */
+  readonly port?: number;
+  /** The address relayed transport addresses carry, e.g. this device's public address. */
+  readonly relayAddress?: string;
+  /** The ports relayed addresses take; behind a NAT, forward them with the relay's own port. */
+  readonly relayPorts?: { readonly min: number; readonly max: number };
+  readonly quotas?: Partial<ITurnQuotas>;
+  /** Default true: see {@link TurnServer}. */
+  readonly allowPrivatePeers?: boolean;
+  /** Default: see {@link TurnServer}. */
+  readonly allowPeer?: (address: string) => boolean;
+  readonly now?: () => number;
+  readonly onError?: (error: Error) => void;
+}
+
+/** This device's relay for its paired devices. */
+export class MeshTurnRelay {
+  private peers: readonly IMeshRelayPeer[] = [];
+  /** Whose each relay-user tag is, for the peers in force and one epoch: derived once, not per request. */
+  private owners?: {
+    readonly epoch: number;
+    readonly peers: readonly IMeshRelayPeer[];
+    readonly byTag: Promise<ReadonlyMap<string, IMeshRelayPeer>>;
+  };
+
+  private constructor(
+    private readonly server: TurnServer,
+    private readonly now: () => number,
+  ) {}
+
+  public static async start(options: IMeshTurnRelayOptions = {}): Promise<MeshTurnRelay> {
+    const now = options.now ?? Date.now;
+    let relay: MeshTurnRelay | undefined;
+    const server = await TurnServer.start({
+      ...(options.host !== undefined ? { host: options.host } : {}),
+      ...(options.port !== undefined ? { port: options.port } : {}),
+      ...(options.relayAddress !== undefined ? { relayAddress: options.relayAddress } : {}),
+      ...(options.relayPorts !== undefined ? { relayPorts: options.relayPorts } : {}),
+      ...(options.quotas !== undefined ? { quotas: options.quotas } : {}),
+      ...(options.allowPeer !== undefined ? { allowPeer: options.allowPeer } : {}),
+      ...(options.allowPrivatePeers !== undefined
+        ? { allowPrivatePeers: options.allowPrivatePeers }
+        : {}),
+      ...(options.onError !== undefined ? { onError: options.onError } : {}),
+      now,
+      // A request that arrives before the relay exists is refused, as an unknown user is.
+      authorize: (username) =>
+        relay === undefined ? Promise.resolve(undefined) : relay.authorize(username),
+    });
+    relay = new MeshTurnRelay(server, now);
+    return relay;
+  }
+
+  /** Where the relay listens. */
+  public get endpoint(): IMeshRelayEndpoint {
+    const { address, port } = this.server.address;
+    return { host: address, port };
+  }
+
+  /** Allocations held, by one device or in all. */
+  public allocationCount(deviceId?: string): number {
+    return this.server.allocationCount(deviceId);
+  }
+
+  /**
+   * The devices the relay serves: the current, unrevoked peers of the lists in force. Any other
+   * device's credentials stop working, and its allocations close at once.
+   */
+  public declarePeers(peers: readonly IMeshRelayPeer[]): void {
+    this.peers = [...peers];
+    this.server.retain(new Set(peers.map((peer) => peer.deviceId)));
+  }
+
+  private async authorize(
+    username: string,
+  ): Promise<{ readonly owner: string; readonly password: string } | undefined> {
+    const match = USERNAME.exec(username);
+    if (match === null) return undefined;
+    const now = this.now();
+    const expiresAt = Number(match[1]) * 1000;
+    if (expiresAt <= now || expiresAt - now > MAX_RELAY_CREDENTIAL_TTL_MS + CLOCK_SKEW_MS) {
+      return undefined;
+    }
+    const peer = (await this.tagOwners(rendezvousEpoch(now))).get(match[2]!);
+    // Still a peer once the tags are derived: a revocation meanwhile wins.
+    if (peer === undefined || !this.peers.some((p) => p.deviceId === peer.deviceId)) {
+      return undefined;
+    }
+    return {
+      owner: peer.deviceId,
+      password: await peer.rendezvous.relayPassword('inbound', username),
+    };
+  }
+
+  /** The peers' relay-user tags for `epoch` and the adjacent ones, by tag. */
+  private tagOwners(epoch: number): Promise<ReadonlyMap<string, IMeshRelayPeer>> {
+    const held = this.owners;
+    if (held !== undefined && held.epoch === epoch && held.peers === this.peers) return held.byTag;
+    const peers = this.peers;
+    const byTag = (async () => {
+      const out = new Map<string, IMeshRelayPeer>();
+      for (const peer of peers) {
+        for (const tag of await peer.rendezvous.lookupTags('relay-user', epoch)) {
+          out.set(base64Url(tag.slice(0, TAG_BYTES)), peer);
+        }
+      }
+      return out;
+    })();
+    // A failed derivation is tried again by the next request.
+    byTag.catch(() => {
+      if (this.owners?.byTag === byTag) this.owners = undefined;
+    });
+    this.owners = { epoch, peers, byTag };
+    return byTag;
+  }
+
+  public close(): Promise<void> {
+    this.peers = [];
+    return this.server.close();
+  }
+}

package/src/negotiated-certificate.ts

@@ -0,0 +1,72 @@
+/**
+ * The remote fingerprint a channel binding names: the one of the certificate the DTLS layer accepted,
+ * never SDP text.
+ *
+ * The SDP arrives over an untrusted signaling path. The DTLS layer (OpenSSL, through libdatachannel)
+ * accepts the remote certificate only after the peer has signed its handshake with that certificate's
+ * key and the certificate matches the fingerprint of the remote description. Callers additionally
+ * require the description to advertise exactly one fingerprint, so the accepted certificate and the
+ * bound value cannot differ: binding it names the one party that holds the key.
+ */
+
+import type { RtcPeer } from './rtc-peer.js';
+
+const FINGERPRINT_VALUE = /^[0-9A-F]{2}(?::[0-9A-F]{2})+$/;
+
+/**
+ * Call `onVerified` with the remote certificate's fingerprint once the connection is established, or
+ * `onFailed` if it fails or closes first, or the fingerprint is missing or of another algorithm than
+ * `algorithm`. Returns an unsubscribe function.
+ *
+ * The connection reports `connected` only after DTLS has completed, and the data channel runs over that
+ * DTLS session.
+ */
+export function whenRemoteCertificateVerified(
+  peer: RtcPeer,
+  algorithm: string,
+  onVerified: (fingerprint: string) => void,
+  onFailed: (reason: string) => void,
+): () => void {
+  let done = false;
+  const settle = (): void => {
+    if (done) return;
+    done = true;
+    const fingerprint = peer.remoteFingerprint();
+    if (fingerprint === undefined) {
+      onFailed('the DTLS layer exposed no remote certificate');
+      return;
+    }
+    const value = fingerprint.value.toUpperCase();
+    if (fingerprint.algorithm.toLowerCase() !== algorithm.toLowerCase()) {
+      onFailed(
+        `the remote certificate was checked with ${fingerprint.algorithm}, not ${algorithm}`,
+      );
+      return;
+    }
+    if (!FINGERPRINT_VALUE.test(value)) {
+      onFailed('the remote certificate fingerprint is malformed');
+      return;
+    }
+    onVerified(value);
+  };
+  const fail = (state: string): void => {
+    if (done) return;
+    done = true;
+    onFailed(`the connection ended ${state} before DTLS completed`);
+  };
+  if (peer.state === 'connected') {
+    settle();
+    return () => undefined;
+  }
+  if (peer.state === 'failed' || peer.state === 'closed') {
+    fail(peer.state);
+    return () => undefined;
+  }
+  const unsubscribe = peer.onStateChange((state) => {
+    if (state === 'connected') settle();
+    else if (state === 'failed' || state === 'closed') fail(state);
+    else return;
+    unsubscribe();
+  });
+  return unsubscribe;
+}

package/src/nostr-mesh-relay.ts

@@ -0,0 +1,391 @@
+/**
+ * Live signaling between two devices over public Nostr relays, as ephemeral events (kinds
+ * 20000–29999, which relays forward and do not store).
+ *
+ * Nostr is only a mailbox run by strangers, so nothing in an event tells them whose it is:
+ * - the author key is a one-time key of the pair, the direction and the epoch;
+ * - the kind is drawn from the ephemeral range per pair, direction and epoch, so no constant kind
+ *   marks the product;
+ * - there are no tags, and the content is the pair's own AEAD ciphertext of the signal, padded to a
+ *   step so its length says little about what it carries.
+ *
+ * Events go to several relays of different operators. What arrives is checked (shape, signature,
+ * author key and kind for that pair and epoch, age, duplicates) and opened before it reaches the
+ * node, which decodes it as hostile input like any relay-delivered signal and admits a peer by the
+ * device handshake alone. The draft WebRTC-signaling NIP is not used: the event format here is ours.
+ */
+import { rendezvousEpoch, RENDEZVOUS_EPOCH_MS } from '@robota-sdk/agent-remote-pairing';
+import { SimplePool } from 'nostr-tools/pool';
+import { finalizeEvent, getPublicKey, verifyEvent, type Event } from 'nostr-tools/pure';
+
+import { padJson, unpadJson } from './mesh-records.js';
+
+import type { IMeshPeerRoute } from './mesh-discovery.js';
+import type { IMeshRelay } from './mesh-relay.js';
+
+/** A Nostr event as relays carry it. */
+export interface INostrEvent {
+  readonly id: string;
+  readonly pubkey: string;
+  readonly created_at: number;
+  readonly kind: number;
+  readonly tags: readonly (readonly string[])[];
+  readonly content: string;
+  readonly sig: string;
+}
+
+export interface INostrFilter {
+  readonly kinds: readonly number[];
+  readonly authors: readonly string[];
+  readonly since?: number;
+}
+
+/** The relays a device signals through. */
+export interface INostrRelayPool {
+  /** Send `event` to every relay; resolves `true` when at least one took it. Never rejects. */
+  publish(event: INostrEvent): Promise<boolean>;
+  /** Events matching `filter` from any relay, as received. */
+  subscribe(filter: INostrFilter, onEvent: (event: unknown) => void): { close(): void };
+  close(): void;
+}
+
+const EPHEMERAL_KIND_BASE = 20_000;
+const EPHEMERAL_KIND_SPAN = 10_000;
+/** Plaintext is padded up to a multiple of this. */
+export const NOSTR_SIGNAL_PAD_STEP = 512;
+/** Largest signal plaintext sent; relays refuse large events. */
+const MAX_SIGNAL_BYTES = 32 * 1024;
+/** Largest event content accepted. */
+const MAX_CONTENT_CHARS = 48 * 1024;
+/** An event older or newer than this is not taken: a relay could replay it. */
+const DEFAULT_MAX_EVENT_AGE_S = 120;
+/** Event ids remembered to drop the copies several relays deliver. */
+const SEEN_IDS = 2048;
+const HEX64 = /^[0-9a-f]{64}$/;
+const HEX128 = /^[0-9a-f]{128}$/;
+
+/** The ephemeral kind of `tag`: a pair's kind for one direction and epoch. */
+export function ephemeralKindOf(tag: Uint8Array): number {
+  return EPHEMERAL_KIND_BASE + ((((tag[0] ?? 0) << 8) | (tag[1] ?? 0)) % EPHEMERAL_KIND_SPAN);
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+function fromBase64(value: string): Uint8Array | undefined {
+  try {
+    const binary = atob(value);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+    return out;
+  } catch {
+    return undefined;
+  }
+}
+
+/** An event's fields, copied out of whatever arrived, or `undefined` when it is not an event. */
+function readEvent(value: unknown): Event | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const r = value as Record<string, unknown>;
+  if (typeof r.id !== 'string' || !HEX64.test(r.id)) return undefined;
+  if (typeof r.pubkey !== 'string' || !HEX64.test(r.pubkey)) return undefined;
+  if (typeof r.sig !== 'string' || !HEX128.test(r.sig)) return undefined;
+  if (typeof r.kind !== 'number' || !Number.isInteger(r.kind)) return undefined;
+  if (typeof r.created_at !== 'number' || !Number.isInteger(r.created_at)) return undefined;
+  if (typeof r.content !== 'string' || r.content.length > MAX_CONTENT_CHARS) return undefined;
+  if (!Array.isArray(r.tags) || r.tags.length !== 0) return undefined;
+  // A fresh object: nothing the sender attached (such as a cached verdict) comes along.
+  return {
+    id: r.id,
+    pubkey: r.pubkey,
+    sig: r.sig,
+    kind: r.kind,
+    created_at: r.created_at,
+    content: r.content,
+    tags: [],
+  };
+}
+
+interface IOutbound {
+  readonly route: IMeshPeerRoute;
+  readonly epoch: number;
+  readonly secretKey: Uint8Array;
+  readonly kind: number;
+}
+
+interface IInbound {
+  readonly route: IMeshPeerRoute;
+  readonly epoch: number;
+  readonly kind: number;
+}
+
+export interface INostrMeshRelayOptions {
+  readonly pool: INostrRelayPool;
+  readonly maxEventAgeS?: number;
+  readonly now?: () => number;
+  readonly onError?: (error: Error) => void;
+}
+
+/**
+ * A mesh relay over Nostr. It needs the peers (see {@link IMeshRelay.declarePeers}) to derive their
+ * keys, and addresses a pair by its outbound topic. It reports a topic absent only when it knows no
+ * pair by it: whether the peer is listening, a relay that forwards ephemeral events cannot tell.
+ */
+export class NostrMeshRelay implements IMeshRelay {
+  private readonly messages = new Set<(topic: string, data: unknown) => void>();
+  private readonly absents = new Set<(topic: string) => void>();
+  private outbound = new Map<string, IOutbound>();
+  private inbound = new Map<string, IInbound>();
+  private subscription?: { close(): void };
+  private chain: Promise<void> = Promise.resolve();
+  private readonly seen = new Set<string>();
+  private routes: readonly IMeshPeerRoute[] = [];
+  private epoch?: number;
+  private timer?: ReturnType<typeof setTimeout>;
+  private closed = false;
+
+  public constructor(private readonly options: INostrMeshRelayOptions) {}
+
+  private now(): number {
+    return (this.options.now ?? Date.now)();
+  }
+
+  private report(error: unknown): void {
+    this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+  }
+
+  /** Run `task` after everything queued before it, so keys are in place before a send uses them. */
+  private enqueue(task: () => Promise<void> | void): void {
+    this.chain = this.chain.then(task).catch((error: unknown) => this.report(error));
+  }
+
+  /** Resolves once every declaration, send and receipt queued so far has run. */
+  public whenIdle(): Promise<void> {
+    return this.chain;
+  }
+
+  public declarePresence(): void {
+    // Nostr addresses a pair by its derived keys, not by the relay inbox topics.
+  }
+
+  public declarePeers(peers: readonly IMeshPeerRoute[]): void {
+    this.enqueue(() => this.derive(peers));
+  }
+
+  /** The pairs' keys and kinds for this epoch, and a subscription for the peers' adjacent epochs. */
+  private async derive(peers: readonly IMeshPeerRoute[]): Promise<void> {
+    if (this.closed) return;
+    this.routes = peers;
+    const epoch = rendezvousEpoch(this.now());
+    const outbound = new Map<string, IOutbound>();
+    const inbound = new Map<string, IInbound>();
+    for (const route of peers) {
+      const secretKey = await route.rendezvous.signingSeed('outbound', epoch, 'signal');
+      const kind = ephemeralKindOf(await route.rendezvous.tag('nostr-kind', 'outbound', epoch));
+      outbound.set(route.outbound, { route, epoch, secretKey, kind });
+      for (const e of [epoch - 1, epoch, epoch + 1]) {
+        const seed = await route.rendezvous.signingSeed('inbound', e, 'signal');
+        const peerKind = ephemeralKindOf(await route.rendezvous.tag('nostr-kind', 'inbound', e));
+        inbound.set(getPublicKey(seed), { route, epoch: e, kind: peerKind });
+      }
+    }
+    if (this.closed) return;
+    this.outbound = outbound;
+    this.inbound = inbound;
+    this.epoch = epoch;
+    this.subscription?.close();
+    this.subscription =
+      inbound.size === 0
+        ? undefined
+        : this.options.pool.subscribe(
+            {
+              kinds: [...new Set([...inbound.values()].map((i) => i.kind))],
+              authors: [...inbound.keys()],
+              since:
+                Math.floor(this.now() / 1000) -
+                (this.options.maxEventAgeS ?? DEFAULT_MAX_EVENT_AGE_S),
+            },
+            (event) => this.enqueue(() => this.receive(event)),
+          );
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    this.timer = setTimeout(
+      () => this.declarePeers(this.routes),
+      Math.max(0, (epoch + 1) * RENDEZVOUS_EPOCH_MS - this.now()),
+    );
+    this.timer.unref?.();
+  }
+
+  public send(topic: string, data: unknown): void {
+    if (this.closed) return;
+    this.enqueue(async () => {
+      if (this.closed) return;
+      // A send that outlived its epoch waits for the new keys.
+      if (this.epoch !== undefined && rendezvousEpoch(this.now()) !== this.epoch) {
+        await this.derive(this.routes);
+      }
+      const out = this.outbound.get(topic);
+      if (out === undefined) {
+        for (const handler of this.absents) handler(topic);
+        return;
+      }
+      const json = new TextEncoder().encode(JSON.stringify(data)).length;
+      if (json > MAX_SIGNAL_BYTES) throw new Error('signal too large for a Nostr event');
+      const padded = padJson(data, Math.ceil(json / NOSTR_SIGNAL_PAD_STEP) * NOSTR_SIGNAL_PAD_STEP);
+      const sealed = await out.route.rendezvous.sealRecord(padded, out.epoch, 'signal');
+      const event = finalizeEvent(
+        {
+          kind: out.kind,
+          created_at: Math.floor(this.now() / 1000),
+          tags: [],
+          content: toBase64(sealed),
+        },
+        out.secretKey,
+      );
+      if (!(await this.options.pool.publish(event))) {
+        throw new Error('no Nostr relay took the signal');
+      }
+    });
+  }
+
+  private async receive(raw: unknown): Promise<void> {
+    if (this.closed) return;
+    const event = readEvent(raw);
+    if (event === undefined || this.seen.has(event.id)) return;
+    const from = this.inbound.get(event.pubkey);
+    if (from === undefined || event.kind !== from.kind) return;
+    const ageS = Math.abs(Math.floor(this.now() / 1000) - event.created_at);
+    if (ageS > (this.options.maxEventAgeS ?? DEFAULT_MAX_EVENT_AGE_S)) return;
+    if (!verifyEvent(event)) return;
+    this.remember(event.id);
+    const sealed = fromBase64(event.content);
+    if (sealed === undefined) return;
+    const opened = await from.route.rendezvous.openRecord(sealed, from.epoch, 'signal');
+    if (opened?.epoch !== from.epoch) return;
+    const data = unpadJson(opened.hints);
+    if (data === undefined || this.closed) return;
+    for (const handler of this.messages) handler(from.route.inbound, data);
+  }
+
+  private remember(id: string): void {
+    this.seen.add(id);
+    if (this.seen.size <= SEEN_IDS) return;
+    const oldest = this.seen.values().next().value;
+    if (oldest !== undefined) this.seen.delete(oldest);
+  }
+
+  public onMessage(handler: (topic: string, data: unknown) => void): () => void {
+    this.messages.add(handler);
+    return () => this.messages.delete(handler);
+  }
+
+  public onAbsent(handler: (topic: string) => void): () => void {
+    this.absents.add(handler);
+    return () => this.absents.delete(handler);
+  }
+
+  public close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    this.subscription?.close();
+    this.messages.clear();
+    this.absents.clear();
+    this.options.pool.close();
+  }
+}
+
+// ── In-process relays, for tests and loopback ──────────────────────────────────────────────────
+
+export interface IInMemoryNostrHub {
+  /** A client of every relay of this hub. */
+  pool(): INostrRelayPool;
+  /** Every event the hub forwarded, as received. */
+  readonly events: readonly INostrEvent[];
+  /** Deliver `event` as a relay would, to every matching subscription (a hostile relay's injection). */
+  inject(event: unknown): void;
+}
+
+function matches(filter: INostrFilter, event: INostrEvent): boolean {
+  return filter.kinds.includes(event.kind) && filter.authors.includes(event.pubkey);
+}
+
+/**
+ * In-process relays with a relay's rules for ephemeral events: an event whose signature does not
+ * verify is refused, and one that passes is forwarded to matching subscriptions and not stored.
+ * Deliveries run on a microtask, as a network would never deliver synchronously.
+ */
+export function createInMemoryNostrHub(): IInMemoryNostrHub {
+  const subscriptions = new Set<{ filter: INostrFilter; onEvent: (event: unknown) => void }>();
+  const events: INostrEvent[] = [];
+  const deliver = (event: unknown): void => {
+    const copy: unknown = JSON.parse(JSON.stringify(event));
+    queueMicrotask(() => {
+      for (const sub of [...subscriptions]) {
+        if (matches(sub.filter, copy as INostrEvent)) sub.onEvent(copy);
+      }
+    });
+  };
+  return {
+    pool: () => {
+      const mine = new Set<{ filter: INostrFilter; onEvent: (event: unknown) => void }>();
+      return {
+        publish: (event) => {
+          const read = readEvent(event);
+          if (read === undefined || !verifyEvent(read)) return Promise.resolve(false);
+          events.push(JSON.parse(JSON.stringify(event)) as INostrEvent);
+          deliver(event);
+          return Promise.resolve(true);
+        },
+        subscribe: (filter, onEvent) => {
+          const sub = { filter, onEvent };
+          subscriptions.add(sub);
+          mine.add(sub);
+          return {
+            close: () => {
+              subscriptions.delete(sub);
+              mine.delete(sub);
+            },
+          };
+        },
+        close: () => {
+          for (const sub of mine) subscriptions.delete(sub);
+          mine.clear();
+        },
+      };
+    },
+    events,
+    inject: (event) => deliver(event),
+  };
+}
+
+// ── Public relays, through nostr-tools ─────────────────────────────────────────────────────────
+
+/**
+ * A pool over `relays` (`wss://…`, several operators) with `nostr-tools`, connecting on first use.
+ * The relays see one-time keys, rotating kinds and ciphertext; they are trusted with nothing.
+ */
+export function createNostrRelayPool(relays: readonly string[]): INostrRelayPool {
+  if (relays.length === 0) throw new Error('a Nostr relay pool needs at least one relay');
+  const pool = new SimplePool();
+  const urls = [...relays];
+  return {
+    publish: async (event) => {
+      const results = await Promise.allSettled(pool.publish(urls, event as Event));
+      return results.some((r) => r.status === 'fulfilled');
+    },
+    subscribe: (filter, onEvent) =>
+      pool.subscribeMany(
+        urls,
+        {
+          kinds: [...filter.kinds],
+          authors: [...filter.authors],
+          ...(filter.since !== undefined ? { since: filter.since } : {}),
+        },
+        { onevent: (event) => onEvent(event) },
+      ),
+    close: () => pool.destroy(),
+  };
+}