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

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@robota-sdk/agent-transport-webrtc",
+  "version": "3.0.0-beta.81",
+  "description": "WebRTC P2P transport for the Robota SDK (data-channel session bridge; REMOTE-001)",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      },
+      "default": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota.git"
+  },
+  "homepage": "https://robota.io/",
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "ws": "^8.21.1",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-session-mobility": "3.0.0-beta.81",
+    "@robota-sdk/agent-transport": "3.0.0-beta.81",
+    "@robota-sdk/agent-remote-pairing": "3.0.0-beta.81"
+  },
+  "peerDependencies": {
+    "werift": "^0.24.0"
+  },
+  "peerDependenciesMeta": {
+    "werift": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6",
+    "werift": "^0.24.0"
+  },
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "publishConfig": {
+    "access": "public"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "clean": "rimraf dist"
+  }
+}

package/src/__tests__/admission-secure-by-default.test.ts

@@ -0,0 +1,61 @@
+/**
+ * SEC-008 — a WebRTC transport with no pairing secret must not expose the session by omission.
+ *
+ * Two sibling transports made OPPOSITE default choices for one question. The WS transport auto-mints
+ * a credential unless told to stay open; this one's `secret` was optional, and without it the data
+ * channel was wired straight to the session — a remote peer reaching tool execution because a field
+ * was left unset.
+ *
+ * The defect is the DEFAULT, not the open mode. Running without pairing is legitimate for loopback
+ * and for tests; what is not legitimate is that it happened when nobody chose it. So the transport
+ * now refuses to construct unless one of the two was chosen, and the refusal names both ways out.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { WebRtcTransport } from '../webrtc-transport.js';
+import type { ISignalingClient } from '../signaling.js';
+
+/** A signalling channel that is never used — these cases never get past the constructor. */
+const signaling = {
+  send: () => {},
+  onMessage: () => () => {},
+  close: () => {},
+} as unknown as ISignalingClient;
+
+describe('SEC-008: the WebRTC transport requires an admission decision', () => {
+  it('refuses to construct with neither a secret nor an explicit open', () => {
+    expect(() => new WebRtcTransport({ signaling })).toThrow(/openReason|secret/);
+  });
+
+  it('constructs with a pairing secret', () => {
+    expect(() => new WebRtcTransport({ signaling, secret: 'pairing-secret' })).not.toThrow();
+  });
+
+  it('constructs open when the host says so, in writing', () => {
+    expect(
+      () =>
+        new WebRtcTransport({
+          signaling,
+          open: true,
+          openReason: 'loopback only — no remote peer',
+        }),
+    ).not.toThrow();
+  });
+
+  it('refuses an open transport with no reason', () => {
+    // Without this the fix would be an option that means nothing: `open: true` alone would restore
+    // exactly the silent exposure the case above forbids, one keyword further along.
+    expect(() => new WebRtcTransport({ signaling, open: true })).toThrow(/openReason/);
+  });
+
+  it('refuses a secret AND an explicit open together', () => {
+    // Silently ignoring one of two contradictory options is how a caller ends up believing the
+    // channel is gated when it is, or is not, by whichever option happened to win. The constructor
+    // cannot know which they meant, so it does not choose.
+    expect(
+      () =>
+        new WebRtcTransport({ signaling, secret: 'pairing-secret', open: true, openReason: 'x' }),
+    ).toThrow(/contradictory/);
+  });
+});

package/src/__tests__/admission-steps.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { nextAdmissionStep } from '../admission-steps.js';
+
+/**
+ * The ordering carries the security argument, so it is asserted directly rather than only through a
+ * channel: each step must run on a channel the previous one has already bound.
+ */
+
+const PROOF = {};
+
+describe('what a channel still owes', () => {
+  it('owes nothing when nothing is configured — the handshake alone admits', () => {
+    expect(nextAdmissionStep({}, 'pairing')).toBe(null);
+  });
+
+  it.each([
+    ['only the rendezvous', { localPeer: PROOF }, 'local-proof'],
+    ['only the grant', { handoffGrant: PROOF }, 'handoff-grant'],
+    ['both — the rendezvous first', { localPeer: PROOF, handoffGrant: PROOF }, 'local-proof'],
+  ])('with %s configured, owes %s', (_label, configured, expected) => {
+    expect(nextAdmissionStep(configured, 'pairing')).toBe(expected);
+  });
+
+  it('owes the grant once the rendezvous has run', () => {
+    expect(nextAdmissionStep({ localPeer: PROOF, handoffGrant: PROOF }, 'local-proof')).toBe(
+      'handoff-grant',
+    );
+  });
+
+  it('owes nothing once both have run', () => {
+    expect(nextAdmissionStep({ localPeer: PROOF, handoffGrant: PROOF }, 'handoff-grant')).toBe(
+      null,
+    );
+  });
+
+  it('does not re-demand the rendezvous after the grant state is reached', () => {
+    // The loop this prevents: a gate that asked for the rendezvous again from `handoff-grant` would
+    // never admit anyone, because the peer has no second nonce to present.
+    expect(nextAdmissionStep({ localPeer: PROOF }, 'handoff-grant')).toBe(null);
+  });
+
+  it('owes nothing after a rendezvous-only channel has satisfied it', () => {
+    expect(nextAdmissionStep({ localPeer: PROOF }, 'local-proof')).toBe(null);
+  });
+});

package/src/__tests__/cve-2024-29415-reachability.test.ts

@@ -0,0 +1,80 @@
+import { createRequire } from 'node:module';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * REMOTE-004 B2 TC-05 — regression guard for the CVE-2024-29415 evidence-based re-accept.
+ *
+ * The `ip` package's SSRF advisory (CVE-2024-29415) affects `ip.isPublic` / `ip.isPrivate` (and `ip.address()`,
+ * which calls them). werift/werift-ice reach `ip` only through STUN codec helpers (`isV4Format`/`toBuffer`/
+ * `toString`) and `ip.isLoopback` over the host's own `os.networkInterfaces()` — never the vulnerable functions,
+ * so the SSRF vector is unreachable and the root `pnpm.auditConfig.ignoreCves` entry is a reviewed re-accept.
+ * This test fails if a future werift version starts calling the vulnerable functions, forcing a re-evaluation.
+ */
+
+/**
+ * The package root above a resolved entry point.
+ *
+ * werift 0.24 ships an `exports` map that does not list `./package.json`, so `require.resolve
+ * ('werift/package.json')` throws `ERR_PACKAGE_PATH_NOT_EXPORTED` — and did so silently here from
+ * the dependabot bump that brought 0.24 (issue #1315) until the resolver was read: the `catch` below
+ * used to swallow it and the guard measured zero directories. The entry point IS exported, so the
+ * root is found from it, by walking up to the nearest `package.json`.
+ */
+function packageRootOf(entry: string): string {
+  let dir = dirname(entry);
+  while (!existsSync(join(dir, 'package.json'))) {
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error(`no package.json above ${entry}`);
+    dir = parent;
+  }
+  return dir;
+}
+
+/**
+ * Both packages that reach `ip`: `werift` (a devDep, resolvable from here) and `werift-ice` (its
+ * transitive dependency — under pnpm's strict layout resolvable only from werift's own location,
+ * which is where it is asked for). Neither is optional: a resolver that returned fewer directories
+ * than it names would let the scan pass over an empty set, which is the failure this guard exists to
+ * refuse, so an unresolvable package throws instead of being skipped.
+ */
+function resolveWeriftLibDirs(): string[] {
+  const requireFromHere = createRequire(import.meta.url);
+  const weriftEntry = requireFromHere.resolve('werift');
+  const requireFromWerift = createRequire(weriftEntry);
+  return [packageRootOf(weriftEntry), packageRootOf(requireFromWerift.resolve('werift-ice'))];
+}
+
+function collectJsFiles(dir: string, acc: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry !== 'node_modules') collectJsFiles(full, acc);
+    } else if (/\.(js|mjs|cjs)$/.test(entry)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+describe('CVE-2024-29415 non-reachability in werift (REMOTE-004 B2 — TC-05)', () => {
+  it('werift never calls the vulnerable ip.isPublic / ip.isPrivate / ip.address', () => {
+    const dirs = resolveWeriftLibDirs();
+    expect(dirs, 'werift and werift-ice must both be scanned').toHaveLength(2);
+
+    const offenders: string[] = [];
+    for (const dir of dirs) {
+      for (const file of collectJsFiles(dir)) {
+        const text = readFileSync(file, 'utf8');
+        // Match property access on the `ip` module: `.isPublic(`, `.isPrivate(`, `.address(`.
+        if (/\.isPublic\s*\(|\.isPrivate\s*\(|ip[_0-9]*\.(?:default\.)?address\s*\(/.test(text)) {
+          offenders.push(file);
+        }
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/__tests__/dtls-fingerprint-binding.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { RTCPeerConnection } from 'werift';
+
+/**
+ * REMOTE-005 B3 TC-09 — the load-bearing premise behind the pairing channel-binding: werift's DTLS verifies the
+ * negotiated remote certificate's fingerprint against the SDP-advertised value and FAILS the connection on a
+ * mismatch (`verifyRemoteCertificateFingerprint`, RFC 8122). This is what guarantees a MITM relay cannot advertise
+ * a fingerprint that differs from the cert it actually presents — so its advertised fingerprint necessarily
+ * differs from the honest peer's, which the pairing confirmation detects.
+ */
+
+function tamperFingerprint(sdp: string): string {
+  // Flip the advertised fingerprint to a value that will NOT match the real negotiated certificate.
+  return sdp.replace(/a=fingerprint:(\S+) (\S+)/, (_m, hash: string) => {
+    const bogus = Array.from({ length: 32 }, () => 'AA').join(':');
+    return `a=fingerprint:${hash} ${bogus}`;
+  });
+}
+
+describe('werift DTLS fingerprint verification (REMOTE-005 B3 — TC-09)', () => {
+  it('fails the connection when the advertised remote fingerprint does not match the negotiated cert', async () => {
+    const host = new RTCPeerConnection();
+    const remote = new RTCPeerConnection();
+    const dc = host.createDataChannel('robota-session');
+
+    let opened = false;
+    dc.stateChanged.subscribe((s) => {
+      if (s === 'open') opened = true;
+    });
+
+    // Trickle ICE both ways (serialized on the remote side is unnecessary here — no answer-before-ICE issue since
+    // we tamper the answer and expect DTLS to fail regardless).
+    host.onIceCandidate.subscribe((c) => {
+      if (c) void remote.addIceCandidate(c.toJSON());
+    });
+    remote.onIceCandidate.subscribe((c) => {
+      if (c) void host.addIceCandidate(c.toJSON());
+    });
+
+    const offer = await host.createOffer();
+    await host.setLocalDescription(offer);
+    await remote.setRemoteDescription(host.localDescription!);
+    const answer = await remote.createAnswer();
+    await remote.setLocalDescription(answer);
+
+    // MITM substitution: the host consumes an answer whose advertised fingerprint has been tampered.
+    const tampered = {
+      type: 'answer' as const,
+      sdp: tamperFingerprint(remote.localDescription!.sdp),
+    };
+    await host.setRemoteDescription(tampered);
+
+    // Give DTLS time to (fail to) establish; the data channel must NEVER open.
+    await new Promise((r) => setTimeout(r, 4000));
+    expect(opened).toBe(false);
+
+    await host.close();
+    await remote.close();
+  }, 15000);
+});