Merge pull request #147 from Lykhoyda/fix/134.4-cdp-multiplexer-trust

Lykhoyda · web-flow · commit e50980a76296 · 2026-05-12T21:17:08.000+02:00
fix: CDP multiplexer trust boundary — closes 1 HIGH (Phase 134.4)
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
     {
       "name": "rn-dev-agent",
       "description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",
-      "version": "0.44.33",
+      "version": "0.44.34",
       "source": "./",
       "category": "mobile-development",
       "homepage": "https://github.com/Lykhoyda/rn-dev-agent"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "rn-dev-agent",
-  "version": "0.44.33",
+  "version": "0.44.34",
   "description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",
   "author": {
     "name": "Anton Lykhoyda",
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,44 @@ All notable changes to rn-dev-agent will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.44.34] — 2026-05-12
+
+### Fixed (Phase 134.4 — CDP multiplexer trust boundary, closes 1 HIGH)
+
+- **CDP multiplexer now requires a per-instance capability token** in
+  the WebSocket upgrade path. Previously any process that could
+  discover the ephemeral loopback port could connect and send
+  arbitrary CDP commands (`Runtime.evaluate`, `Page.navigate`, etc.)
+  to the running Hermes runtime, **bypassing Claude Code's
+  tool-permission prompts entirely**. This included a browser tab
+  scanning local ports, a sibling shell, or any malicious process
+  with loopback access.
+- The token is 32 bytes of `crypto.randomBytes` (43 char base64url),
+  unique per multiplexer instance, included in the WebSocket URL
+  path as `ws://127.0.0.1:<port>/<token>`. The `verifyClient`
+  handler uses `timingSafeEqual` on equal-length buffers to compare
+  — no timing side channel leaks the token.
+- The exposed `proxyUrl` (from `client.startProxy()`) and the
+  DevTools URL (from `cdp_open_devtools`) automatically include the
+  token. Without the token in the path, the multiplexer returns
+  `401 Unauthorized` at upgrade time.
+- **Token never appears in logs** — log lines reference
+  `ws://127.0.0.1:<port>/<token>` literally, not the actual value.
+
+### Internal
+
+- New exports from `cdp/multiplexer.ts`: `generateCapabilityToken()`
+  and `verifyConsumerPath(reqUrl, expectedToken)`. Both pure
+  functions for unit testing. `CDPMultiplexer.token` getter for
+  callers building DevTools URLs.
+- 9 new unit tests cover the token verification truth table:
+  legitimate token accepted; wrong token / missing token / empty
+  token / length mismatch / query-style appendage / non-string
+  inputs all rejected. Plus uniqueness across instances.
+- Implements the deepsec recommendation: per-proxy high-entropy
+  capability token required during WebSocket upgrade, rejection
+  before consumer registration.
+
 ## [0.44.33] — 2026-05-12
 
 ### Fixed (Phase 134.3 — path containment, closes 2 HIGH + 3 MEDIUM)
diff --git a/scripts/cdp-bridge/dist/cdp-client.js b/scripts/cdp-bridge/dist/cdp-client.js
@@ -197,8 +197,13 @@ export class CDPClient {
         const multiplexer = new CDPMultiplexer({ hermesUrl, ...opts });
         const port = await multiplexer.start();
         this._multiplexer = multiplexer;
-        this._proxyUrl = `ws://127.0.0.1:${port}`;
-        logger.info('CDP', `Proxy started on ${this._proxyUrl}, soft-reconnecting current session`);
+        // Phase 134.4: include the per-instance capability token in the
+        // exposed URL. DevTools (or any other consumer the user authorizes)
+        // connects to `ws://127.0.0.1:<port>/<token>`. Without the token
+        // in the path, the multiplexer rejects the WebSocket upgrade.
+        // The token itself never appears in logs.
+        this._proxyUrl = `ws://127.0.0.1:${port}/${multiplexer.token}`;
+        logger.info('CDP', `Proxy started on ws://127.0.0.1:${port}/<token>, soft-reconnecting current session`);
         try {
             // B132: call `_softReconnectDirect` instead of `this.softReconnect()`. The
             // wrapper would observe _proxyUrl just set above and try to suspend the
diff --git a/scripts/cdp-bridge/dist/cdp/multiplexer.js b/scripts/cdp-bridge/dist/cdp/multiplexer.js
@@ -1,6 +1,40 @@
 import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { Buffer } from 'node:buffer';
 import WebSocket, { WebSocketServer } from 'ws';
 import { logger } from '../logger.js';
+/**
+ * Phase 134.4 (deepsec HIGH): generate a per-multiplexer capability
+ * token that consumers must include in the WebSocket upgrade path.
+ * 32 bytes of crypto.randomBytes → 43 char base64url string. Never
+ * logged, never exposed in error messages.
+ */
+export function generateCapabilityToken() {
+    return randomBytes(32).toString('base64url');
+}
+/**
+ * Pure verification helper. Returns true iff the request path is
+ * exactly `/<expectedToken>`. Uses timingSafeEqual on equal-length
+ * buffers to avoid leaking the token via response-timing side
+ * channels. Fails closed on missing/empty/non-string inputs and on
+ * empty expectedToken (never accept an unauthenticated multiplexer).
+ */
+export function verifyConsumerPath(reqUrl, expectedToken) {
+    if (typeof expectedToken !== 'string' || expectedToken.length === 0)
+        return false;
+    if (typeof reqUrl !== 'string' || reqUrl.length === 0)
+        return false;
+    if (!reqUrl.startsWith('/'))
+        return false;
+    const submitted = reqUrl.slice(1);
+    if (submitted.length !== expectedToken.length)
+        return false;
+    const a = Buffer.from(submitted);
+    const b = Buffer.from(expectedToken);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
 const HERMES_BUFFER_MAX_DEFAULT = 1000;
 const ROUTING_TIMEOUT_MS_DEFAULT = 60_000;
 export class CDPMultiplexer {
@@ -15,6 +49,14 @@ export class CDPMultiplexer {
     hermesBuffer = [];
     state = 'stopped';
     boundPort = null;
+    /**
+     * Phase 134.4: per-instance capability token. Required in the
+     * WebSocket upgrade path. Never logged. Exposed via `token` getter
+     * so the caller can include it in the URL it hands to DevTools.
+     */
+    capabilityToken = generateCapabilityToken();
+    /** Phase 134.4: the capability token for this multiplexer instance. */
+    get token() { return this.capabilityToken; }
     routingSweeper = null;
     constructor(opts) {
         this.opts = {
@@ -74,7 +116,24 @@ export class CDPMultiplexer {
     startConsumerServer() {
         return new Promise((resolve, reject) => {
             this.httpServer = createServer();
-            this.wss = new WebSocketServer({ server: this.httpServer });
+            this.wss = new WebSocketServer({
+                server: this.httpServer,
+                // Phase 134.4 (deepsec HIGH): reject any upgrade that doesn't
+                // include the capability token in the path. Any sibling
+                // process that learned the loopback port (or a browser tab
+                // scanning local ports) is refused before reaching
+                // onConsumerConnect / onConsumerMessage. Token comparison
+                // uses timingSafeEqual to avoid leaking the secret via
+                // timing side channels.
+                verifyClient: (info, callback) => {
+                    if (verifyConsumerPath(info.req.url, this.capabilityToken)) {
+                        callback(true);
+                        return;
+                    }
+                    logger.warn(this.opts.logTag, 'rejected upgrade: missing or invalid capability token');
+                    callback(false, 401, 'Unauthorized');
+                },
+            });
             this.wss.on('connection', (ws) => this.onConsumerConnect(ws));
             this.wss.on('error', (err) => {
                 logger.warn(this.opts.logTag, `WebSocketServer error: ${err instanceof Error ? err.message : err}`);
diff --git a/scripts/cdp-bridge/dist/tools/open-devtools.js b/scripts/cdp-bridge/dist/tools/open-devtools.js
@@ -70,9 +70,17 @@ export function createOpenDevToolsHandler(getClient) {
             // internal state drift — fail loudly rather than return a half-working URL.
             return failResult('cdp_open_devtools: multiplexer started but has no bound port');
         }
+        const proxyToken = client.proxyMultiplexer?.token ?? null;
+        if (proxyToken === null) {
+            return failResult('cdp_open_devtools: multiplexer started but capability token is missing');
+        }
         // DevTools frontend still lives on Metro (it's static HTML + JS served over HTTP).
         // Only the WS destination changes: DevTools → proxy (loopback); proxy → Hermes.
-        const devtoolsUrl = `http://127.0.0.1:${metroPort}/debugger-frontend/rn_fusebox.html?ws=127.0.0.1:${proxyPort}`;
+        // Phase 134.4: the proxy now requires a per-instance capability token in
+        // the WebSocket path. DevTools includes it via the `ws=` query value;
+        // any browser tab that learns the loopback port without the token gets
+        // a 401 upgrade rejection from verifyClient.
+        const devtoolsUrl = `http://127.0.0.1:${metroPort}/debugger-frontend/rn_fusebox.html?ws=127.0.0.1:${proxyPort}/${proxyToken}`;
         return okResult({
             devtoolsUrl,
             inspectorWsUrl: proxyUrl,
diff --git a/scripts/cdp-bridge/package.json b/scripts/cdp-bridge/package.json
@@ -1,6 +1,6 @@
 {
   "name": "rn-dev-agent-cdp",
-  "version": "0.38.28",
+  "version": "0.38.29",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
diff --git a/scripts/cdp-bridge/src/cdp-client.ts b/scripts/cdp-bridge/src/cdp-client.ts
@@ -237,8 +237,13 @@ export class CDPClient {
     const multiplexer = new CDPMultiplexer({ hermesUrl, ...opts });
     const port = await multiplexer.start();
     this._multiplexer = multiplexer;
-    this._proxyUrl = `ws://127.0.0.1:${port}`;
-    logger.info('CDP', `Proxy started on ${this._proxyUrl}, soft-reconnecting current session`);
+    // Phase 134.4: include the per-instance capability token in the
+    // exposed URL. DevTools (or any other consumer the user authorizes)
+    // connects to `ws://127.0.0.1:<port>/<token>`. Without the token
+    // in the path, the multiplexer rejects the WebSocket upgrade.
+    // The token itself never appears in logs.
+    this._proxyUrl = `ws://127.0.0.1:${port}/${multiplexer.token}`;
+    logger.info('CDP', `Proxy started on ws://127.0.0.1:${port}/<token>, soft-reconnecting current session`);
     try {
       // B132: call `_softReconnectDirect` instead of `this.softReconnect()`. The
       // wrapper would observe _proxyUrl just set above and try to suspend the
diff --git a/scripts/cdp-bridge/src/cdp/multiplexer.ts b/scripts/cdp-bridge/src/cdp/multiplexer.ts
@@ -1,9 +1,40 @@
 import { createServer, type Server } from 'node:http';
 import { type AddressInfo } from 'node:net';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { Buffer } from 'node:buffer';
 import WebSocket, { WebSocketServer } from 'ws';
 
 import { logger } from '../logger.js';
 
+/**
+ * Phase 134.4 (deepsec HIGH): generate a per-multiplexer capability
+ * token that consumers must include in the WebSocket upgrade path.
+ * 32 bytes of crypto.randomBytes → 43 char base64url string. Never
+ * logged, never exposed in error messages.
+ */
+export function generateCapabilityToken(): string {
+  return randomBytes(32).toString('base64url');
+}
+
+/**
+ * Pure verification helper. Returns true iff the request path is
+ * exactly `/<expectedToken>`. Uses timingSafeEqual on equal-length
+ * buffers to avoid leaking the token via response-timing side
+ * channels. Fails closed on missing/empty/non-string inputs and on
+ * empty expectedToken (never accept an unauthenticated multiplexer).
+ */
+export function verifyConsumerPath(reqUrl: unknown, expectedToken: string): boolean {
+  if (typeof expectedToken !== 'string' || expectedToken.length === 0) return false;
+  if (typeof reqUrl !== 'string' || reqUrl.length === 0) return false;
+  if (!reqUrl.startsWith('/')) return false;
+  const submitted = reqUrl.slice(1);
+  if (submitted.length !== expectedToken.length) return false;
+  const a = Buffer.from(submitted);
+  const b = Buffer.from(expectedToken);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
 /**
  * CDP Multiplexer proxy (M1 / Phase 90 Tier 1).
  *
@@ -53,6 +84,15 @@ export class CDPMultiplexer {
   private hermesBuffer: string[] = [];
   private state: 'stopped' | 'starting' | 'running' | 'stopping' = 'stopped';
   private boundPort: number | null = null;
+  /**
+   * Phase 134.4: per-instance capability token. Required in the
+   * WebSocket upgrade path. Never logged. Exposed via `token` getter
+   * so the caller can include it in the URL it hands to DevTools.
+   */
+  private readonly capabilityToken: string = generateCapabilityToken();
+
+  /** Phase 134.4: the capability token for this multiplexer instance. */
+  get token(): string { return this.capabilityToken; }
   private routingSweeper: NodeJS.Timeout | null = null;
 
   constructor(opts: MultiplexerOptions) {
@@ -120,7 +160,24 @@ export class CDPMultiplexer {
   private startConsumerServer(): Promise<number> {
     return new Promise((resolve, reject) => {
       this.httpServer = createServer();
-      this.wss = new WebSocketServer({ server: this.httpServer });
+      this.wss = new WebSocketServer({
+        server: this.httpServer,
+        // Phase 134.4 (deepsec HIGH): reject any upgrade that doesn't
+        // include the capability token in the path. Any sibling
+        // process that learned the loopback port (or a browser tab
+        // scanning local ports) is refused before reaching
+        // onConsumerConnect / onConsumerMessage. Token comparison
+        // uses timingSafeEqual to avoid leaking the secret via
+        // timing side channels.
+        verifyClient: (info, callback) => {
+          if (verifyConsumerPath(info.req.url, this.capabilityToken)) {
+            callback(true);
+            return;
+          }
+          logger.warn(this.opts.logTag, 'rejected upgrade: missing or invalid capability token');
+          callback(false, 401, 'Unauthorized');
+        },
+      });
 
       this.wss.on('connection', (ws) => this.onConsumerConnect(ws));
       this.wss.on('error', (err) => {
diff --git a/scripts/cdp-bridge/src/tools/open-devtools.ts b/scripts/cdp-bridge/src/tools/open-devtools.ts
@@ -110,9 +110,17 @@ export function createOpenDevToolsHandler(getClient: () => CDPClient) {
       // internal state drift — fail loudly rather than return a half-working URL.
       return failResult('cdp_open_devtools: multiplexer started but has no bound port');
     }
+    const proxyToken = client.proxyMultiplexer?.token ?? null;
+    if (proxyToken === null) {
+      return failResult('cdp_open_devtools: multiplexer started but capability token is missing');
+    }
     // DevTools frontend still lives on Metro (it's static HTML + JS served over HTTP).
     // Only the WS destination changes: DevTools → proxy (loopback); proxy → Hermes.
-    const devtoolsUrl = `http://127.0.0.1:${metroPort}/debugger-frontend/rn_fusebox.html?ws=127.0.0.1:${proxyPort}`;
+    // Phase 134.4: the proxy now requires a per-instance capability token in
+    // the WebSocket path. DevTools includes it via the `ws=` query value;
+    // any browser tab that learns the loopback port without the token gets
+    // a 401 upgrade rejection from verifyClient.
+    const devtoolsUrl = `http://127.0.0.1:${metroPort}/debugger-frontend/rn_fusebox.html?ws=127.0.0.1:${proxyPort}/${proxyToken}`;
 
     return okResult({
       devtoolsUrl,
diff --git a/scripts/cdp-bridge/test/helpers/mock-cdp-client.js b/scripts/cdp-bridge/test/helpers/mock-cdp-client.js
@@ -107,10 +107,13 @@ export function createMockClient(overrides = {}) {
 
     async startProxy() {
       // Mock mirrors real behavior: idempotent, sets URL + multiplexer-like stub,
-      // returns URL. Tests that want failure override this.
+      // returns URL. Tests that want failure override this. Phase 134.4: the
+      // mock multiplexer now exposes a `token` field so open-devtools.ts can
+      // build the token-bearing DevTools URL.
       if (client._proxyUrl) return client._proxyUrl;
-      client._proxyUrl = 'ws://127.0.0.1:45678';
-      client._proxyMultiplexer = { port: 45678, isRunning: true, consumerCount: 0 };
+      const mockToken = 'mock-test-token-AbCdEf1234567890_dashOk';
+      client._proxyUrl = `ws://127.0.0.1:45678/${mockToken}`;
+      client._proxyMultiplexer = { port: 45678, token: mockToken, isRunning: true, consumerCount: 0 };
       return client._proxyUrl;
     },
 
diff --git a/scripts/cdp-bridge/test/unit/cdp-client-proxy.test.js b/scripts/cdp-bridge/test/unit/cdp-client-proxy.test.js
@@ -139,7 +139,7 @@ test('CDPClient.startProxy rolls back multiplexer when softReconnect throws (D66
   let reconnects = 0;
   client._softReconnectDirect = async () => { reconnects++; };
   const url = await client.startProxy();
-  assert.match(url, /^ws:\/\/127\.0\.0\.1:\d+$/, 'fresh startProxy succeeds after rollback');
+  assert.match(url, /^ws:\/\/127\.0\.0\.1:\d+\/[A-Za-z0-9_-]+$/, 'fresh startProxy succeeds after rollback');
   assert.equal(reconnects, 1);
 
   await client.disconnect();
@@ -165,7 +165,7 @@ test('CDPClient.startProxy is concurrency-safe — parallel callers share one mu
 
   assert.equal(u1, u2, 'first and second callers get identical URL');
   assert.equal(u2, u3, 'third caller also joins the same in-flight');
-  assert.match(u1, /^ws:\/\/127\.0\.0\.1:\d+$/);
+  assert.match(u1, /^ws:\/\/127\.0\.0\.1:\d+\/[A-Za-z0-9_-]+$/);
   assert.ok(client.proxyMultiplexer, 'exactly one multiplexer stored');
   assert.equal(client.proxyUrl, u1);
 
@@ -193,7 +193,7 @@ test('CDPClient.startProxy: after failed start, in-flight guard clears so next c
 
   // Second call must create a NEW multiplexer (previous one was torn down).
   const url = await client.startProxy();
-  assert.match(url, /^ws:\/\/127\.0\.0\.1:\d+$/);
+  assert.match(url, /^ws:\/\/127\.0\.0\.1:\d+\/[A-Za-z0-9_-]+$/);
   assert.equal(attempts, 2, 'second attempt ran (in-flight cache did not poison retry)');
 
   await client.disconnect();
diff --git a/scripts/cdp-bridge/test/unit/multiplexer.test.js b/scripts/cdp-bridge/test/unit/multiplexer.test.js
diff --git a/scripts/cdp-bridge/test/unit/phase-134-4-multiplexer-auth.test.js b/scripts/cdp-bridge/test/unit/phase-134-4-multiplexer-auth.test.js

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`{`
`10`	`10`	`"name": "rn-dev-agent",`
`11`	`11`	`"description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",`
`12`		`- "version": "0.44.33",`
	`12`	`+ "version": "0.44.34",`
`13`	`13`	`"source": "./",`
`14`	`14`	`"category": "mobile-development",`
`15`	`15`	`"homepage": "https://github.com/Lykhoyda/rn-dev-agent"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "rn-dev-agent",`
`3`		`- "version": "0.44.33",`
	`3`	`+ "version": "0.44.34",`
`4`	`4`	`"description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Anton Lykhoyda",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "rn-dev-agent-cdp",`
`3`		`- "version": "0.38.28",`
	`3`	`+ "version": "0.38.29",`
`4`	`4`	`"type": "module",`
`5`	`5`	`"main": "dist/index.js",`
`6`	`6`	`"scripts": {`