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

package/src/index.ts

@@ -0,0 +1,139 @@
+export { WebRtcTransport } from './webrtc-transport.js';
+export type { IWebRtcTransportOptions, IIceServer } from './webrtc-transport-options.js';
+export type {
+  IConnectionApproval,
+  IConnectionApprovalContext,
+  IHostReconnectConfig,
+} from './pairing-gate.js';
+// The judge and the frame predicate stay internal: they are this package's policy plumbing, and a
+// composition root only needs to SUPPLY the port and, on the peer side, know the frame's shape.
+export { localProofFrame } from './local-peer-proof.js';
+export type { ILocalPeerProof, ILocalProofFrame } from './local-peer-proof.js';
+// SEC-011 (issue #1865): the cross-device hand-off grant gate. The verdict is injected — this
+// package implements no cryptographic policy.
+export { handoffGrantFrame, judgeHandoffGrant } from './handoff-grant-gate.js';
+export type { IHandoffGrantFrame, IHandoffGrantProof } from './handoff-grant-gate.js';
+export { createInMemorySignalingPair } from './signaling.js';
+export type { ISignalingClient, ISignalMessage, TSignalKind } from './signaling.js';
+export { WsSignalingClient } from './ws-signaling-client.js';
+export type { IWsSignalingClientOptions, IWebSocketLike } from './ws-signaling-client.js';
+export { loadDataChannel } from './datachannel-loader.js';
+// One peer connection over the WebRTC implementation this package runs on (hosts, tests, tools).
+export { RtcChannel, RtcPeer } from './rtc-peer.js';
+export type {
+  IRtcCandidate,
+  IRtcPeerDiagnostics,
+  IRtcPeerOptions,
+  TRtcChannelState,
+  TRtcPeerState,
+} from './rtc-peer.js';
+export type { IDataChannelModule, TModuleResolver } from './datachannel-loader.js';
+// The device mesh: CLI↔CLI connections between one user's devices, admitted by the device handshake.
+export { DeviceMeshNode } from './device-mesh-node.js';
+export type {
+  IDeviceMeshLink,
+  IDeviceMeshNodeOptions,
+  IDeviceMeshRefusal,
+  IDeviceMeshRelayOptions,
+} from './device-mesh-node.js';
+// The relay of last resort: a TURN server one of the user's devices runs for its paired devices.
+export {
+  DEFAULT_RELAY_CREDENTIAL_TTL_MS,
+  MAX_RELAY_CREDENTIAL_TTL_MS,
+  MeshRelayNeededError,
+  MeshTurnRelay,
+  meshRelayCredential,
+  meshRelayIceServers,
+} from './mesh-turn-relay.js';
+export type {
+  TMeshRelayNeed,
+  IMeshRelayEndpoint,
+  IMeshRelayPeer,
+  IMeshTurnRelayOptions,
+} from './mesh-turn-relay.js';
+export { DEFAULT_TURN_QUOTAS, DEFAULT_UNAUTHENTICATED_LIMITS, TurnServer } from './turn-server.js';
+export type {
+  ITurnAuthorization,
+  ITurnQuotas,
+  ITurnServerOptions,
+  IUnauthenticatedLimits,
+} from './turn-server.js';
+export { MeshLinkEndedError } from './mesh-peer-link.js';
+export type {
+  IMeshChannelBinding,
+  TMeshLinkEnd,
+  TMeshLinkRole,
+  TMeshLinkStage,
+} from './mesh-peer-link.js';
+export { MAX_MESH_MESSAGE_CHARS } from './mesh-signal.js';
+export { createInMemoryMeshRelayHub } from './mesh-relay.js';
+export type { IInMemoryMeshRelayHub, IMeshRelay } from './mesh-relay.js';
+export { WsMeshRelayClient } from './ws-mesh-relay-client.js';
+export type { IWsMeshRelayClientOptions } from './ws-mesh-relay-client.js';
+// Finding a peer device before the relay: the address cache, mDNS, then public records, each
+// yielding candidates only; then public signaling carriers, then the self-hosted relay.
+export { DiscoveringMeshRelay, startLanMeshRelay } from './discovering-mesh-relay.js';
+export type {
+  IDiscoveringMeshRelayOptions,
+  IMeshAdvertiser,
+  IStartLanMeshRelayOptions,
+} from './discovering-mesh-relay.js';
+export { DEFAULT_MAX_PUBLISH_JITTER_MS, MeshDht } from './mesh-dht.js';
+export type { IFetchedLists, IMeshDhtOptions, IPublishedLists } from './mesh-dht.js';
+export { createInMemoryItemNetwork, createPkarrRelayStore } from './mesh-item-store.js';
+export type {
+  IInMemoryItemNetwork,
+  IPkarrRelayStoreOptions,
+  IRendezvousItemStore,
+} from './mesh-item-store.js';
+export { startMainlineDhtStore } from './mainline-dht-store.js';
+export type { IMainlineDht, IMainlineDhtStoreOptions } from './mainline-dht-store.js';
+export {
+  NostrMeshRelay,
+  createInMemoryNostrHub,
+  createNostrRelayPool,
+} from './nostr-mesh-relay.js';
+export type {
+  IInMemoryNostrHub,
+  INostrEvent,
+  INostrFilter,
+  INostrMeshRelayOptions,
+  INostrRelayPool,
+} from './nostr-mesh-relay.js';
+export {
+  MAX_CACHED_CANDIDATES,
+  addressCacheSource,
+  createInMemoryMeshAddressCache,
+} from './mesh-discovery.js';
+export type {
+  IMeshAddressCache,
+  IMeshCandidate,
+  IMeshCandidateSource,
+  IMeshPeerRoute,
+} from './mesh-discovery.js';
+export { startMeshLanListener } from './mesh-lan-listener.js';
+export type { IMeshLanListener, IMeshLanListenerOptions } from './mesh-lan-listener.js';
+export {
+  MESH_MDNS_SERVICE,
+  MeshMdns,
+  createInMemoryMdnsBus,
+  localInterfaceAddresses,
+  paddedInstanceCount,
+} from './mesh-mdns.js';
+export { DEFAULT_NOSTR_RELAYS, DEFAULT_PKARR_RELAYS } from './mesh-public-relays.js';
+export type {
+  IInMemoryMdnsBus,
+  IMdnsPacket,
+  IMdnsRecord,
+  IMdnsTransport,
+  IMeshMdnsOptions,
+} from './mesh-mdns.js';
+// Enrolling a new device: a data channel bound to its negotiated connection, reached through the relay
+// topic an enrollment code derives. The enrollment protocol itself is `agent-remote-pairing`'s.
+export { EnrollmentLinkError, dialEnrollment, listenForEnrollment } from './enrollment-link.js';
+export type {
+  IEnrollmentChannel,
+  IEnrollmentListener,
+  IEnrollmentRendezvous,
+  TEnrollmentLinkFailure,
+} from './enrollment-link.js';

package/src/local-peer-proof.ts

@@ -0,0 +1,135 @@
+/**
+ * SEC-010 TC-08: joining the rendezvous proof to the channel the session will run on.
+ *
+ * ## What each half proves, and why neither is enough alone
+ *
+ * The pairing handshake binds the CHANNEL: after it, this data channel provably terminates at the
+ * peer that knew the secret, and the DTLS fingerprints are covered so it cannot be spliced. It says
+ * nothing about where that peer runs.
+ *
+ * The guarded rendezvous binds the ENVIRONMENT: a peer that reached a 0700 directory owned by this
+ * user could only have come from this machine, as this user. It says nothing about which channel
+ * that peer later opens.
+ *
+ * Presenting the rendezvous nonce OVER the already-bound channel is what joins them. The channel is
+ * authenticated by the time this runs, so nobody else can inject the frame; the nonce is single-use,
+ * so nobody can re-present one they observed. Together they say: the party on this channel is the
+ * party the kernel vouched for, on this attempt.
+ *
+ * ## Why this runs after the handshake and before the session
+ *
+ * Both edges are load-bearing.
+ *
+ * BEFORE the handshake completes, the channel is not yet authenticated — a nonce presented there
+ * would be a secret handed to an unproven counterpart, and this step would weaken the very thing it
+ * exists to strengthen.
+ *
+ * BEFORE the session is exposed, because "fail closed before content" is SEC-010's first failure
+ * rule. If the proof arrived after exposure, a peer that never presents one would have already been
+ * talking to the session, and refusing it afterwards is not refusing it.
+ *
+ * ## This package decides nothing
+ *
+ * #1810 is explicit that WebRTC must not implement cryptographic policy. Single-use, expiry and
+ * revocation belong to the grant ledger in `@robota-sdk/agent-remote-pairing/local`, which is
+ * node-only; this module takes an injected `redeem` and reports what it was told. That also keeps
+ * `node:fs` out of this package, and keeps the ledger testable without a data channel.
+ */
+
+import type { IPeerAdmission } from '@robota-sdk/agent-interface-session-mobility';
+
+/** The frame a local peer presents to show it reached the guarded rendezvous. */
+export interface ILocalProofFrame {
+  readonly t: 'local-proof';
+  readonly nonce: string;
+}
+
+/**
+ * The local-environment proof this gate requires before exposing the session.
+ *
+ * Absent → the gate behaves exactly as before. Requiring the proof is opt-in because a remote peer
+ * over WebRTC has no rendezvous to have reached, and a gate that demanded one unconditionally would
+ * refuse every legitimate remote session.
+ */
+export interface ILocalPeerProof {
+  /**
+   * Redeem a presented nonce. Owned by the ledger — this package asks and does not decide.
+   *
+   * Returns the admission the consumer receives, so the trust level travels as a value rather than
+   * being re-derived from a boolean by whoever reads it next.
+   */
+  readonly redeem: (nonce: string) => IPeerAdmission;
+  /**
+   * Fired on the outcome, admitted or not.
+   *
+   * On BOTH, deliberately: a consumer told only about successes cannot distinguish "no local peer
+   * connected" from "a local peer was refused", and those call for different operator responses.
+   */
+  readonly onAdmission?: (admission: IPeerAdmission) => void;
+}
+
+/**
+ * True when a parsed pre-accept value is a local-proof frame carrying a nonce.
+ *
+ * Module-private: `judgeLocalProof` is the only thing that should ask. Exporting it would offer a
+ * caller a way to check the shape and then act on it without going through the judge, which is how
+ * an admission decision ends up made in two places.
+ */
+function isLocalProofFrame(value: unknown): value is ILocalProofFrame {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { t?: unknown }).t === 'local-proof' &&
+    typeof (value as { nonce?: unknown }).nonce === 'string'
+  );
+}
+
+/** A refusal shaped like every other admission, so no caller has to special-case the failure path. */
+function refuse(reason: string): IPeerAdmission {
+  return { admitted: false, trust: 'unproven', reason };
+}
+
+/**
+ * Judge one pre-accept frame against the configured proof.
+ *
+ * Every path that is not an admitted redemption returns a refusal — including a missing config,
+ * which cannot happen through the gate but would be a fail-OPEN if it ever did.
+ */
+export function judgeLocalProof(
+  parsed: unknown,
+  proof: ILocalPeerProof | undefined,
+): IPeerAdmission {
+  if (proof === undefined) return refuse('no local-peer proof is configured for this channel');
+  if (!isLocalProofFrame(parsed)) {
+    return refuse('expected a local-proof frame carrying the rendezvous nonce');
+  }
+  try {
+    return proof.redeem(parsed.nonce);
+  } catch (error) {
+    // allow-fallback: fail-CLOSED, not a fallback to a degraded path. A ledger that throws has not
+    // reached a decision, and "not reached" is not "allowed" — the refusal below is strictly more
+    // restrictive than the success path, never less. Letting it propagate would be worse: the throw
+    // unwinds through the channel's message subscription and leaves the gate parked in its proof
+    // state with the channel open, which is a hang — fail-open wearing a crash's clothes.
+    return refuse(
+      `the rendezvous ledger could not decide: ${
+        error instanceof Error ? error.message : 'unknown error'
+      }`,
+    );
+  }
+}
+
+/**
+ * Build the frame a local peer presents on the channel.
+ *
+ * Lives beside the judge that reads it, so the two cannot drift: a sender that hand-built the object
+ * would keep compiling after the frame gains a field, and the failure would surface as a refusal on
+ * the far side with no hint that the SENDER is the stale half.
+ *
+ * Deliberately not a "send" — it returns the frame and leaves transmission to whoever owns the
+ * channel. A helper that both built and sent would need a channel to be testable, and would put the
+ * frame's shape and the carrier's lifecycle in one place.
+ */
+export function localProofFrame(nonce: string): ILocalProofFrame {
+  return { t: 'local-proof', nonce };
+}

package/src/mainline-dht-store.ts

@@ -0,0 +1,174 @@
+/**
+ * Rendezvous records on the BitTorrent Mainline DHT, as BEP 44 mutable items, straight from this
+ * process over UDP — no relay in between.
+ *
+ * DHT nodes are strangers: they see the one-time key, the rotating salt and ciphertext, and the
+ * publisher's address, never who the record is for. Every item a lookup returns is checked here
+ * against the key and salt asked for, whatever the nodes claimed to check.
+ */
+import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
+
+import {
+  BEP44_MAX_VALUE_BYTES,
+  concatBytes,
+  signMutableItem,
+  verifyMutableItem,
+  type IMutableItem,
+} from './mesh-records.js';
+
+import type { IRendezvousItemStore } from './mesh-item-store.js';
+
+/** A BEP 44 item as `bittorrent-dht` hands it over. */
+interface IDhtGetResult {
+  readonly v?: Uint8Array;
+  readonly k?: Uint8Array;
+  readonly sig?: Uint8Array;
+  readonly seq?: number;
+  readonly salt?: Uint8Array;
+}
+
+/** The slice of a `bittorrent-dht` instance this store drives. */
+export interface IMainlineDht {
+  put(
+    item: {
+      readonly k: Buffer;
+      readonly salt: Buffer;
+      readonly seq: number;
+      readonly v: Buffer;
+      readonly sig: Buffer;
+    },
+    callback: (error: Error | null, hash: Buffer, responses?: number) => void,
+  ): void;
+  get(
+    target: Buffer,
+    options: { readonly salt: Buffer; readonly cache: false },
+    callback: (error: Error | null, result: IDhtGetResult | null) => void,
+  ): void;
+  on(event: 'error' | 'warning', listener: (error: Error) => void): void;
+  destroy(callback?: () => void): void;
+}
+
+export interface IMainlineDhtStoreOptions {
+  /** Test seam: the DHT client; default a `bittorrent-dht` node on the public bootstrap nodes. */
+  readonly createDht?: (verify: TDhtVerify) => IMainlineDht | Promise<IMainlineDht>;
+  readonly onError?: (error: Error) => void;
+}
+
+type TDhtVerify = (signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array) => boolean;
+
+const ED25519_SPKI_PREFIX = Uint8Array.from([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+
+/** Synchronous Ed25519 verification, as the DHT client asks for it. Never throws. */
+export const verifyEd25519Sync: TDhtVerify = (signature, message, publicKey) => {
+  if (publicKey.length !== 32 || signature.length !== 64) return false;
+  try {
+    const key = createPublicKey({
+      key: Buffer.from(concatBytes([ED25519_SPKI_PREFIX, publicKey])),
+      format: 'der',
+      type: 'spki',
+    });
+    return verifySignature(null, message, key, signature);
+  } catch {
+    // allow-fallback: a key or signature that cannot be read verifies nothing
+    return false;
+  }
+};
+
+/** The DHT client package; it ships no types, so it is loaded by name and narrowed here. */
+const DHT_MODULE: string = 'bittorrent-dht';
+
+/** A DHT node on the public bootstrap nodes. */
+async function defaultDht(verify: TDhtVerify): Promise<IMainlineDht> {
+  // eslint-disable-next-line no-restricted-syntax -- truly conditional: only a device that turns the DHT on loads it, and the package is ESM-only
+  const module = (await import(DHT_MODULE)) as {
+    default: new (options: { verify: TDhtVerify }) => IMainlineDht;
+  };
+  return new module.default({ verify });
+}
+
+function toBuffer(bytes: Uint8Array): Buffer {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+function aborted(signal: AbortSignal | undefined): Promise<never> | undefined {
+  if (signal === undefined) return undefined;
+  return new Promise((_resolve, reject) => {
+    if (signal.aborted) reject(new Error('aborted'));
+    signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+  });
+}
+
+/**
+ * A Mainline DHT store. The node joins the DHT when the store is created and stays for the life of
+ * the store, since joining takes seconds a lookup should not wait on each time.
+ */
+export async function startMainlineDhtStore(
+  options: IMainlineDhtStoreOptions = {},
+): Promise<IRendezvousItemStore> {
+  const dht = await (options.createDht ?? defaultDht)(verifyEd25519Sync);
+  const report = (error: Error): void => options.onError?.(error);
+  dht.on('error', report);
+  dht.on('warning', report);
+  let closed = false;
+
+  return {
+    async put(address, value, now, signal) {
+      if (closed) throw new Error('DHT store closed');
+      if (value.length > BEP44_MAX_VALUE_BYTES) throw new Error('record value exceeds 999 bytes');
+      const item = await signMutableItem(address.key, address.salt, Math.floor(now / 1000), value);
+      const put = new Promise<void>((resolve, reject) => {
+        dht.put(
+          {
+            k: toBuffer(item.k),
+            salt: toBuffer(address.salt),
+            seq: item.seq,
+            v: toBuffer(item.v),
+            sig: toBuffer(item.sig),
+          },
+          (error, _hash, responses) => {
+            if (error !== null) reject(error);
+            else if (responses === 0) reject(new Error('no DHT node took the record'));
+            else resolve();
+          },
+        );
+      });
+      const abort = aborted(signal);
+      await (abort === undefined ? put : Promise.race([put, abort]));
+    },
+    async get(publicKey, salt, signal) {
+      if (closed || signal.aborted) return undefined;
+      const target = createHash('sha1')
+        .update(concatBytes([publicKey, salt]))
+        .digest();
+      const lookup = new Promise<IDhtGetResult | null>((resolve) => {
+        dht.get(target, { salt: toBuffer(salt), cache: false }, (error, result) =>
+          resolve(error === null ? result : null),
+        );
+      });
+      try {
+        const result = await Promise.race([lookup, aborted(signal)!]);
+        if (result?.v === undefined || result.k === undefined || result.sig === undefined) {
+          return undefined;
+        }
+        const item: IMutableItem = {
+          k: new Uint8Array(result.k),
+          salt,
+          seq: result.seq ?? 0,
+          v: new Uint8Array(result.v),
+          sig: new Uint8Array(result.sig),
+        };
+        return (await verifyMutableItem(item, publicKey, salt)) ? item.v : undefined;
+      } catch {
+        // allow-fallback: an aborted or failed lookup found nothing; the next source is tried
+        return undefined;
+      }
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      dht.destroy();
+    },
+  };
+}