@ait-co/devtools 0.1.66 → 0.1.68

package/dist/chii-relay-BNd3G3UG.js

@@ -0,0 +1,152 @@
+import { createRequire } from "node:module";
+import { createServer } from "node:http";
+//#region src/mcp/chii-relay.ts
+/**
+* Boots the local Chii relay server.
+*
+* Chii (liriliri/chii) is a chobitsu-based CDP relay that lets non-Chrome
+* WebViews (iOS WKWebView / Android WebView — i.e. the Toss app) expose CDP.
+* The relay accepts a `target` websocket from the phone's injected `target.js`
+* and `client` websockets from CDP frontends (our MCP connection).
+*
+* Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app
+* entries.
+*
+* TOTP auth (relay-side, authoritative gate):
+*   When `verifyAuth` is provided, this module registers HTTP 'upgrade' and
+*   'request' listeners on the server BEFORE calling `chii.start({server})`.
+*   Node's `http.Server` calls listeners in registration order; the first to
+*   call `socket.destroy()` (upgrade) or `res.end()` (request) wins. Invalid
+*   auth → 401 + destroy (chii never sees the connection). Valid auth →
+*   return without side-effect (chii handles it).
+*
+* TOTP code transports (issue #466) — two equivalent ways to carry the code:
+*   1. Query param `at=<code>` — used by the daemon-side `/client` connection
+*      (`chii-connection.ts` appends it; it holds the secret).
+*   2. Path prefix `/at/<code>/…` — used by the phone-side target. Chii's
+*      stock `target.js` derives its WS endpoint from the script `src`
+*      (`scriptEl.src.replace('target.js','')`), so the only way for the
+*      phone to carry a code is to embed it in the script URL path. The
+*      in-app attach injects `https://<host>/at/<code>/target.js`; both the
+*      script fetch and the derived `wss://<host>/at/<code>/target/<id>` WS
+*      dial then carry the prefix. The listeners below rewrite the prefix
+*      into the query form (`rewriteAtPathPrefix`) and MUTATE `req.url`
+*      before chii's own handlers (registered later) parse it — chii only
+*      ever sees the stripped URL.
+*
+* Threat model: "URL leak" — someone obtains the tunnel URL (Slack paste, QR
+*   screenshot, shoulder-surfing) but does not have the shared TOTP secret.
+*   Rotating 6-digit code makes the URL stale after 30 s.
+*   A determined attacker who extracts the secret from the dogfood bundle can
+*   still compute valid codes; that is out of scope (see umbrella CLAUDE.md §4).
+*
+* SECRET-HANDLING: The secret value and computed TOTP codes MUST NOT appear
+*   in any log, error message, or process output. `verifyAuth` is a black-box
+*   predicate from the caller's perspective; this module only forwards pass/fail.
+*/
+const require = createRequire(import.meta.url);
+function loadChiiServer() {
+	const mod = require("chii");
+	if (typeof mod === "object" && mod !== null && "start" in mod && typeof mod.start === "function") return mod;
+	throw new Error("chii server module did not expose start()");
+}
+/**
+* Rewrites a `/at/<code>/…` path-prefixed request URL into the equivalent
+* query-based form, e.g.:
+*
+*   `/at/123456/target.js`        → `/target.js?at=123456`
+*   `/at/123456/target/x?url=u`   → `/target/x?url=u&at=123456`
+*   `/at/123456/`                 → `/?at=123456`
+*
+* Returns `null` when the URL does not carry the prefix (including an empty
+* code segment) — callers fall back to the unmodified URL and the existing
+* query-based auth path.
+*
+* Pure string surgery — this function knows nothing about secrets or code
+* validity; verification stays inside the caller-provided `verifyAuth`
+* predicate (which parses the query). The raw path segment is appended
+* verbatim to the query: both path segments and query values are
+* percent-decoded exactly once by their consumers, so no re-encoding is
+* needed (TOTP codes are 6 digits and never percent-encoded in practice).
+*/
+function rewriteAtPathPrefix(rawUrl) {
+	const match = /^\/at\/([^/?]+)(\/[^?]*)?(\?.*)?$/.exec(rawUrl);
+	if (match === null) return null;
+	const code = match[1];
+	const path = match[2] === void 0 || match[2] === "" ? "/" : match[2];
+	const query = match[3] ?? "";
+	return `${path}${query}${query === "" ? "?" : "&"}at=${code}`;
+}
+/**
+* Starts the Chii relay and resolves once listening.
+*
+* Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral
+* port on every start, so a stale cloudflared orphan holding any particular
+* port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`
+* always reflect the actual bound port.
+*
+* chii.start() is called with `server` (our pre-created httpServer) BEFORE
+* httpServer.listen(). This is intentional: chii attaches its Koa handler and
+* WS upgrade listener to the server object, but the actual TCP bind is
+* performed by our httpServer.listen() call below. The `port`/`domain` values
+* passed to chii.start() are used for display/banner purposes inside chii and
+* do not affect which port the server binds. The connection path (clients
+* connecting to `relay.baseUrl`) always uses the post-listen confirmed port.
+*/
+async function startChiiRelay(options = {}) {
+	const requestedPort = options.port ?? 0;
+	const host = options.host ?? "127.0.0.1";
+	const { verifyAuth, onAuthReject } = options;
+	const httpServer = createServer();
+	const notifyAuthReject = (kind) => {
+		if (onAuthReject === void 0) return;
+		try {
+			onAuthReject({ kind });
+		} catch {}
+	};
+	if (verifyAuth) {
+		httpServer.on("upgrade", (req, socket) => {
+			const rewritten = rewriteAtPathPrefix(req.url ?? "");
+			if (rewritten !== null) req.url = rewritten;
+			if (!verifyAuth(req)) {
+				socket.write("HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n");
+				socket.destroy();
+				notifyAuthReject("ws-upgrade");
+				return;
+			}
+		});
+		httpServer.on("request", (req, res) => {
+			const rewritten = rewriteAtPathPrefix(req.url ?? "");
+			if (rewritten === null) return;
+			req.url = rewritten;
+			if (!verifyAuth(req)) {
+				res.statusCode = 401;
+				res.end();
+				notifyAuthReject("http-request");
+			}
+		});
+	}
+	await loadChiiServer().start({
+		server: httpServer,
+		domain: `${host}:${requestedPort}`,
+		port: requestedPort
+	});
+	const actualPort = await new Promise((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(requestedPort, host, () => {
+			httpServer.off("error", reject);
+			resolve(httpServer.address().port);
+		});
+	});
+	return {
+		port: actualPort,
+		baseUrl: `http://${host}:${actualPort}`,
+		close: () => new Promise((resolve) => {
+			httpServer.close(() => resolve());
+		})
+	};
+}
+//#endregion
+export { startChiiRelay };
+
+//# sourceMappingURL=chii-relay-BNd3G3UG.js.map

package/dist/chii-relay-BNd3G3UG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chii-relay-BNd3G3UG.js","names":[],"sources":["../src/mcp/chii-relay.ts"],"sourcesContent":["/**\n * Boots the local Chii relay server.\n *\n * Chii (liriliri/chii) is a chobitsu-based CDP relay that lets non-Chrome\n * WebViews (iOS WKWebView / Android WebView — i.e. the Toss app) expose CDP.\n * The relay accepts a `target` websocket from the phone's injected `target.js`\n * and `client` websockets from CDP frontends (our MCP connection).\n *\n * Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app\n * entries.\n *\n * TOTP auth (relay-side, authoritative gate):\n *   When `verifyAuth` is provided, this module registers HTTP 'upgrade' and\n *   'request' listeners on the server BEFORE calling `chii.start({server})`.\n *   Node's `http.Server` calls listeners in registration order; the first to\n *   call `socket.destroy()` (upgrade) or `res.end()` (request) wins. Invalid\n *   auth → 401 + destroy (chii never sees the connection). Valid auth →\n *   return without side-effect (chii handles it).\n *\n * TOTP code transports (issue #466) — two equivalent ways to carry the code:\n *   1. Query param `at=<code>` — used by the daemon-side `/client` connection\n *      (`chii-connection.ts` appends it; it holds the secret).\n *   2. Path prefix `/at/<code>/…` — used by the phone-side target. Chii's\n *      stock `target.js` derives its WS endpoint from the script `src`\n *      (`scriptEl.src.replace('target.js','')`), so the only way for the\n *      phone to carry a code is to embed it in the script URL path. The\n *      in-app attach injects `https://<host>/at/<code>/target.js`; both the\n *      script fetch and the derived `wss://<host>/at/<code>/target/<id>` WS\n *      dial then carry the prefix. The listeners below rewrite the prefix\n *      into the query form (`rewriteAtPathPrefix`) and MUTATE `req.url`\n *      before chii's own handlers (registered later) parse it — chii only\n *      ever sees the stripped URL.\n *\n * Threat model: \"URL leak\" — someone obtains the tunnel URL (Slack paste, QR\n *   screenshot, shoulder-surfing) but does not have the shared TOTP secret.\n *   Rotating 6-digit code makes the URL stale after 30 s.\n *   A determined attacker who extracts the secret from the dogfood bundle can\n *   still compute valid codes; that is out of scope (see umbrella CLAUDE.md §4).\n *\n * SECRET-HANDLING: The secret value and computed TOTP codes MUST NOT appear\n *   in any log, error message, or process output. `verifyAuth` is a black-box\n *   predicate from the caller's perspective; this module only forwards pass/fail.\n */\n\nimport { createServer, type IncomingMessage, type Server } from 'node:http';\nimport { createRequire } from 'node:module';\nimport type { AddressInfo } from 'node:net';\nimport type { Duplex } from 'node:stream';\n\nconst require = createRequire(import.meta.url);\n\n/** `chii/server` is CommonJS and shipped without TypeScript types. */\ninterface ChiiServerModule {\n  start(options: {\n    port?: number;\n    host?: string;\n    domain?: string;\n    server?: Server;\n    basePath?: string;\n  }): Promise<void>;\n}\n\nfunction loadChiiServer(): ChiiServerModule {\n  // `chii`'s package `main` is `./server/index.js`, exposing `{ start }`.\n  const mod: unknown = require('chii');\n  if (\n    typeof mod === 'object' &&\n    mod !== null &&\n    'start' in mod &&\n    typeof (mod as { start: unknown }).start === 'function'\n  ) {\n    return mod as ChiiServerModule;\n  }\n  throw new Error('chii server module did not expose start()');\n}\n\nexport interface ChiiRelay {\n  port: number;\n  /** Base URL for the relay HTTP/WS server, e.g. `http://127.0.0.1:54321`. */\n  baseUrl: string;\n  close(): Promise<void>;\n}\n\n/**\n * Secret-free metadata about a single auth rejection (issue #467).\n *\n * SECRET-HANDLING: this event carries ONLY the surface kind. It must never\n * grow fields for `req.url`, query strings, codes, or secrets — observers\n * (diagnostics counters, console hints) only need \"a rejection happened\".\n */\nexport interface RelayAuthRejectEvent {\n  /** Which inbound surface was rejected. */\n  kind: 'ws-upgrade' | 'http-request';\n}\n\n/**\n * Rewrites a `/at/<code>/…` path-prefixed request URL into the equivalent\n * query-based form, e.g.:\n *\n *   `/at/123456/target.js`        → `/target.js?at=123456`\n *   `/at/123456/target/x?url=u`   → `/target/x?url=u&at=123456`\n *   `/at/123456/`                 → `/?at=123456`\n *\n * Returns `null` when the URL does not carry the prefix (including an empty\n * code segment) — callers fall back to the unmodified URL and the existing\n * query-based auth path.\n *\n * Pure string surgery — this function knows nothing about secrets or code\n * validity; verification stays inside the caller-provided `verifyAuth`\n * predicate (which parses the query). The raw path segment is appended\n * verbatim to the query: both path segments and query values are\n * percent-decoded exactly once by their consumers, so no re-encoding is\n * needed (TOTP codes are 6 digits and never percent-encoded in practice).\n */\nexport function rewriteAtPathPrefix(rawUrl: string): string | null {\n  const match = /^\\/at\\/([^/?]+)(\\/[^?]*)?(\\?.*)?$/.exec(rawUrl);\n  if (match === null) return null;\n  const code = match[1];\n  const path = match[2] === undefined || match[2] === '' ? '/' : match[2];\n  const query = match[3] ?? '';\n  const separator = query === '' ? '?' : '&';\n  return `${path}${query}${separator}at=${code}`;\n}\n\nexport interface StartChiiRelayOptions {\n  /**\n   * Local port for the relay. Default 0 (OS-assigned ephemeral port).\n   *\n   * Using 0 means the OS picks a free port — this is the safe default because\n   * a stale cloudflared child process (PPID 1, orphaned after SIGKILL) may still\n   * be holding a fixed port. A fixed port causes EADDRINUSE on the next startup,\n   * which makes the MCP handshake fail with -32000. With port 0 the new relay\n   * always gets a fresh port, making any orphaned process harmless.\n   *\n   * Pass an explicit number to restore fixed-port behaviour (backwards-compatible).\n   */\n  port?: number;\n  /** Bind host. Default 127.0.0.1 (tunnel reaches it locally). */\n  host?: string;\n  /**\n   * Optional auth predicate for WebSocket upgrade requests.\n   *\n   * When provided, every inbound WebSocket upgrade is checked by calling\n   * `verifyAuth(req)` before Chii processes it. Return `true` to allow the\n   * upgrade; return `false` to reject with HTTP 401 and destroy the socket.\n   *\n   * The predicate MUST NOT log the secret or any TOTP code — it is a black-box\n   * from this module's perspective.\n   *\n   * @param req - The raw HTTP `IncomingMessage` from the upgrade handshake.\n   *   Inspect `req.url` for query parameters (e.g. `at=<code>`). Path-prefixed\n   *   URLs (`/at/<code>/…`, the phone-target transport — issue #466) are\n   *   rewritten into the query form BEFORE this predicate runs, so a\n   *   query-only predicate covers both transports.\n   * @returns `true` if the upgrade is authorised, `false` to reject.\n   */\n  verifyAuth?: (req: IncomingMessage) => boolean;\n  /**\n   * Secret-free observability callback fired on every auth rejection\n   * (issue #467). Only meaningful together with `verifyAuth`.\n   *\n   * SECRET-HANDLING: the event carries ONLY the rejection kind — never\n   * `req.url`, query strings, TOTP codes, or the secret. Implementations must\n   * keep it that way (e.g. increment a counter + timestamp). Exceptions thrown\n   * by the callback are swallowed so observability can never break the gate.\n   */\n  onAuthReject?: (event: RelayAuthRejectEvent) => void;\n}\n\n/**\n * Starts the Chii relay and resolves once listening.\n *\n * Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral\n * port on every start, so a stale cloudflared orphan holding any particular\n * port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`\n * always reflect the actual bound port.\n *\n * chii.start() is called with `server` (our pre-created httpServer) BEFORE\n * httpServer.listen(). This is intentional: chii attaches its Koa handler and\n * WS upgrade listener to the server object, but the actual TCP bind is\n * performed by our httpServer.listen() call below. The `port`/`domain` values\n * passed to chii.start() are used for display/banner purposes inside chii and\n * do not affect which port the server binds. The connection path (clients\n * connecting to `relay.baseUrl`) always uses the post-listen confirmed port.\n */\nexport async function startChiiRelay(options: StartChiiRelayOptions = {}): Promise<ChiiRelay> {\n  const requestedPort = options.port ?? 0;\n  const host = options.host ?? '127.0.0.1';\n  const { verifyAuth, onAuthReject } = options;\n\n  const httpServer = createServer();\n\n  // Secret-free observability hook (issue #467). Swallow callback exceptions —\n  // a broken observer must never turn into an open gate or a crashed relay.\n  const notifyAuthReject = (kind: RelayAuthRejectEvent['kind']): void => {\n    if (onAuthReject === undefined) return;\n    try {\n      onAuthReject({ kind });\n    } catch {\n      // Ignore — observability is best-effort.\n    }\n  };\n\n  // Register our auth listeners BEFORE chii.start() so they fire first.\n  // Node's http.Server emits 'upgrade'/'request' to all listeners in\n  // registration order; the first to destroy() the socket (upgrade) or end()\n  // the response (request) wins. Valid requests return without side-effect so\n  // chii's own handlers take over normally — and because listeners run\n  // synchronously in order, mutating `req.url` here (path-prefix strip,\n  // issue #466) means chii's later-registered handlers only ever see the\n  // stripped URL.\n  //\n  // We only register when verifyAuth is provided so the no-auth path is\n  // zero-overhead for tests and local-only dev sessions. (The phone-side\n  // `/at/<code>/` prefix only ever appears when TOTP is armed — the launcher\n  // QR carries the `at` code — so the no-auth path never needs the strip.)\n  if (verifyAuth) {\n    httpServer.on('upgrade', (req: IncomingMessage, socket: Duplex) => {\n      // Phone-target transport (issue #466): normalise a `/at/<code>/…` path\n      // prefix into the query form before verification, and strip it from the\n      // URL chii will see. No-prefix URLs pass through untouched (daemon\n      // client query transport — back-compat).\n      const rewritten = rewriteAtPathPrefix(req.url ?? '');\n      if (rewritten !== null) {\n        req.url = rewritten;\n      }\n      if (!verifyAuth(req)) {\n        // Reject: send a minimal HTTP 401 response and close the socket.\n        // We do NOT log req.url or any auth param here to avoid leaking codes.\n        socket.write('HTTP/1.1 401 Unauthorized\\r\\nContent-Length: 0\\r\\n\\r\\n');\n        socket.destroy();\n        notifyAuthReject('ws-upgrade');\n        // Early return — chii's handler is NOT called for this socket.\n        return;\n      }\n      // Auth passed: no-op. Chii's upgrade listener (registered below by\n      // chii.start) will handle the rest.\n    });\n\n    // Plain HTTP requests: only the path-prefixed form is ours — the phone\n    // fetches `target.js` via `https://<host>/at/<code>/target.js` (issue\n    // #466), which must be verified + stripped so chii's Koa static handler\n    // serves `/target.js`. Non-prefixed requests keep today's behaviour\n    // (ungated pass-through to chii).\n    httpServer.on('request', (req, res) => {\n      const rewritten = rewriteAtPathPrefix(req.url ?? '');\n      if (rewritten === null) return;\n      req.url = rewritten;\n      if (!verifyAuth(req)) {\n        // We do NOT log req.url or any auth param here to avoid leaking codes.\n        res.statusCode = 401;\n        res.end();\n        notifyAuthReject('http-request');\n      }\n      // Auth passed: no-op — chii's Koa 'request' listener (registered below\n      // by chii.start) serves the rewritten URL. (Koa skips writing when an\n      // earlier listener already ended the response, so the 401 path is safe\n      // even though Koa still runs.)\n    });\n  }\n\n  const chii = loadChiiServer();\n  // Passing an existing `server` makes chii attach its Koa handler + WS upgrade\n  // to our HTTP server rather than creating its own listener.\n  // Note: port/domain here are display-only inside chii — the TCP bind is ours.\n  await chii.start({ server: httpServer, domain: `${host}:${requestedPort}`, port: requestedPort });\n\n  const actualPort = await new Promise<number>((resolve, reject) => {\n    httpServer.once('error', reject);\n    httpServer.listen(requestedPort, host, () => {\n      httpServer.off('error', reject);\n      // httpServer.address() is non-null immediately after the listen callback.\n      const addr = httpServer.address() as AddressInfo;\n      resolve(addr.port);\n    });\n  });\n\n  return {\n    port: actualPort,\n    baseUrl: `http://${host}:${actualPort}`,\n    close: () =>\n      new Promise<void>((resolve) => {\n        httpServer.close(() => resolve());\n      }),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,MAAM,UAAU,cAAc,OAAO,KAAK,IAAI;AAa9C,SAAS,iBAAmC;CAE1C,MAAM,MAAe,QAAQ,OAAO;AACpC,KACE,OAAO,QAAQ,YACf,QAAQ,QACR,WAAW,OACX,OAAQ,IAA2B,UAAU,WAE7C,QAAO;AAET,OAAM,IAAI,MAAM,4CAA4C;;;;;;;;;;;;;;;;;;;;;AAyC9D,SAAgB,oBAAoB,QAA+B;CACjE,MAAM,QAAQ,oCAAoC,KAAK,OAAO;AAC9D,KAAI,UAAU,KAAM,QAAO;CAC3B,MAAM,OAAO,MAAM;CACnB,MAAM,OAAO,MAAM,OAAO,KAAA,KAAa,MAAM,OAAO,KAAK,MAAM,MAAM;CACrE,MAAM,QAAQ,MAAM,MAAM;AAE1B,QAAO,GAAG,OAAO,QADC,UAAU,KAAK,MAAM,IACJ,KAAK;;;;;;;;;;;;;;;;;;AAgE1C,eAAsB,eAAe,UAAiC,EAAE,EAAsB;CAC5F,MAAM,gBAAgB,QAAQ,QAAQ;CACtC,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,YAAY,iBAAiB;CAErC,MAAM,aAAa,cAAc;CAIjC,MAAM,oBAAoB,SAA6C;AACrE,MAAI,iBAAiB,KAAA,EAAW;AAChC,MAAI;AACF,gBAAa,EAAE,MAAM,CAAC;UAChB;;AAkBV,KAAI,YAAY;AACd,aAAW,GAAG,YAAY,KAAsB,WAAmB;GAKjE,MAAM,YAAY,oBAAoB,IAAI,OAAO,GAAG;AACpD,OAAI,cAAc,KAChB,KAAI,MAAM;AAEZ,OAAI,CAAC,WAAW,IAAI,EAAE;AAGpB,WAAO,MAAM,yDAAyD;AACtE,WAAO,SAAS;AAChB,qBAAiB,aAAa;AAE9B;;IAIF;AAOF,aAAW,GAAG,YAAY,KAAK,QAAQ;GACrC,MAAM,YAAY,oBAAoB,IAAI,OAAO,GAAG;AACpD,OAAI,cAAc,KAAM;AACxB,OAAI,MAAM;AACV,OAAI,CAAC,WAAW,IAAI,EAAE;AAEpB,QAAI,aAAa;AACjB,QAAI,KAAK;AACT,qBAAiB,eAAe;;IAMlC;;AAOJ,OAJa,gBAAgB,CAIlB,MAAM;EAAE,QAAQ;EAAY,QAAQ,GAAG,KAAK,GAAG;EAAiB,MAAM;EAAe,CAAC;CAEjG,MAAM,aAAa,MAAM,IAAI,SAAiB,SAAS,WAAW;AAChE,aAAW,KAAK,SAAS,OAAO;AAChC,aAAW,OAAO,eAAe,YAAY;AAC3C,cAAW,IAAI,SAAS,OAAO;AAG/B,WADa,WAAW,SAAS,CACpB,KAAK;IAClB;GACF;AAEF,QAAO;EACL,MAAM;EACN,SAAS,UAAU,KAAK,GAAG;EAC3B,aACE,IAAI,SAAe,YAAY;AAC7B,cAAW,YAAY,SAAS,CAAC;IACjC;EACL"}

package/dist/chii-relay-DngjQ2_A.cjs

@@ -0,0 +1,151 @@
+let node_http = require("node:http");
+//#region src/mcp/chii-relay.ts
+/**
+* Boots the local Chii relay server.
+*
+* Chii (liriliri/chii) is a chobitsu-based CDP relay that lets non-Chrome
+* WebViews (iOS WKWebView / Android WebView — i.e. the Toss app) expose CDP.
+* The relay accepts a `target` websocket from the phone's injected `target.js`
+* and `client` websockets from CDP frontends (our MCP connection).
+*
+* Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app
+* entries.
+*
+* TOTP auth (relay-side, authoritative gate):
+*   When `verifyAuth` is provided, this module registers HTTP 'upgrade' and
+*   'request' listeners on the server BEFORE calling `chii.start({server})`.
+*   Node's `http.Server` calls listeners in registration order; the first to
+*   call `socket.destroy()` (upgrade) or `res.end()` (request) wins. Invalid
+*   auth → 401 + destroy (chii never sees the connection). Valid auth →
+*   return without side-effect (chii handles it).
+*
+* TOTP code transports (issue #466) — two equivalent ways to carry the code:
+*   1. Query param `at=<code>` — used by the daemon-side `/client` connection
+*      (`chii-connection.ts` appends it; it holds the secret).
+*   2. Path prefix `/at/<code>/…` — used by the phone-side target. Chii's
+*      stock `target.js` derives its WS endpoint from the script `src`
+*      (`scriptEl.src.replace('target.js','')`), so the only way for the
+*      phone to carry a code is to embed it in the script URL path. The
+*      in-app attach injects `https://<host>/at/<code>/target.js`; both the
+*      script fetch and the derived `wss://<host>/at/<code>/target/<id>` WS
+*      dial then carry the prefix. The listeners below rewrite the prefix
+*      into the query form (`rewriteAtPathPrefix`) and MUTATE `req.url`
+*      before chii's own handlers (registered later) parse it — chii only
+*      ever sees the stripped URL.
+*
+* Threat model: "URL leak" — someone obtains the tunnel URL (Slack paste, QR
+*   screenshot, shoulder-surfing) but does not have the shared TOTP secret.
+*   Rotating 6-digit code makes the URL stale after 30 s.
+*   A determined attacker who extracts the secret from the dogfood bundle can
+*   still compute valid codes; that is out of scope (see umbrella CLAUDE.md §4).
+*
+* SECRET-HANDLING: The secret value and computed TOTP codes MUST NOT appear
+*   in any log, error message, or process output. `verifyAuth` is a black-box
+*   predicate from the caller's perspective; this module only forwards pass/fail.
+*/
+const require$1 = (0, require("node:module").createRequire)(require("url").pathToFileURL(__filename).href);
+function loadChiiServer() {
+	const mod = require$1("chii");
+	if (typeof mod === "object" && mod !== null && "start" in mod && typeof mod.start === "function") return mod;
+	throw new Error("chii server module did not expose start()");
+}
+/**
+* Rewrites a `/at/<code>/…` path-prefixed request URL into the equivalent
+* query-based form, e.g.:
+*
+*   `/at/123456/target.js`        → `/target.js?at=123456`
+*   `/at/123456/target/x?url=u`   → `/target/x?url=u&at=123456`
+*   `/at/123456/`                 → `/?at=123456`
+*
+* Returns `null` when the URL does not carry the prefix (including an empty
+* code segment) — callers fall back to the unmodified URL and the existing
+* query-based auth path.
+*
+* Pure string surgery — this function knows nothing about secrets or code
+* validity; verification stays inside the caller-provided `verifyAuth`
+* predicate (which parses the query). The raw path segment is appended
+* verbatim to the query: both path segments and query values are
+* percent-decoded exactly once by their consumers, so no re-encoding is
+* needed (TOTP codes are 6 digits and never percent-encoded in practice).
+*/
+function rewriteAtPathPrefix(rawUrl) {
+	const match = /^\/at\/([^/?]+)(\/[^?]*)?(\?.*)?$/.exec(rawUrl);
+	if (match === null) return null;
+	const code = match[1];
+	const path = match[2] === void 0 || match[2] === "" ? "/" : match[2];
+	const query = match[3] ?? "";
+	return `${path}${query}${query === "" ? "?" : "&"}at=${code}`;
+}
+/**
+* Starts the Chii relay and resolves once listening.
+*
+* Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral
+* port on every start, so a stale cloudflared orphan holding any particular
+* port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`
+* always reflect the actual bound port.
+*
+* chii.start() is called with `server` (our pre-created httpServer) BEFORE
+* httpServer.listen(). This is intentional: chii attaches its Koa handler and
+* WS upgrade listener to the server object, but the actual TCP bind is
+* performed by our httpServer.listen() call below. The `port`/`domain` values
+* passed to chii.start() are used for display/banner purposes inside chii and
+* do not affect which port the server binds. The connection path (clients
+* connecting to `relay.baseUrl`) always uses the post-listen confirmed port.
+*/
+async function startChiiRelay(options = {}) {
+	const requestedPort = options.port ?? 0;
+	const host = options.host ?? "127.0.0.1";
+	const { verifyAuth, onAuthReject } = options;
+	const httpServer = (0, node_http.createServer)();
+	const notifyAuthReject = (kind) => {
+		if (onAuthReject === void 0) return;
+		try {
+			onAuthReject({ kind });
+		} catch {}
+	};
+	if (verifyAuth) {
+		httpServer.on("upgrade", (req, socket) => {
+			const rewritten = rewriteAtPathPrefix(req.url ?? "");
+			if (rewritten !== null) req.url = rewritten;
+			if (!verifyAuth(req)) {
+				socket.write("HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n");
+				socket.destroy();
+				notifyAuthReject("ws-upgrade");
+				return;
+			}
+		});
+		httpServer.on("request", (req, res) => {
+			const rewritten = rewriteAtPathPrefix(req.url ?? "");
+			if (rewritten === null) return;
+			req.url = rewritten;
+			if (!verifyAuth(req)) {
+				res.statusCode = 401;
+				res.end();
+				notifyAuthReject("http-request");
+			}
+		});
+	}
+	await loadChiiServer().start({
+		server: httpServer,
+		domain: `${host}:${requestedPort}`,
+		port: requestedPort
+	});
+	const actualPort = await new Promise((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(requestedPort, host, () => {
+			httpServer.off("error", reject);
+			resolve(httpServer.address().port);
+		});
+	});
+	return {
+		port: actualPort,
+		baseUrl: `http://${host}:${actualPort}`,
+		close: () => new Promise((resolve) => {
+			httpServer.close(() => resolve());
+		})
+	};
+}
+//#endregion
+exports.startChiiRelay = startChiiRelay;
+
+//# sourceMappingURL=chii-relay-DngjQ2_A.cjs.map

package/dist/chii-relay-DngjQ2_A.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chii-relay-DngjQ2_A.cjs","names":["require"],"sources":["../src/mcp/chii-relay.ts"],"sourcesContent":["/**\n * Boots the local Chii relay server.\n *\n * Chii (liriliri/chii) is a chobitsu-based CDP relay that lets non-Chrome\n * WebViews (iOS WKWebView / Android WebView — i.e. the Toss app) expose CDP.\n * The relay accepts a `target` websocket from the phone's injected `target.js`\n * and `client` websockets from CDP frontends (our MCP connection).\n *\n * Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app\n * entries.\n *\n * TOTP auth (relay-side, authoritative gate):\n *   When `verifyAuth` is provided, this module registers HTTP 'upgrade' and\n *   'request' listeners on the server BEFORE calling `chii.start({server})`.\n *   Node's `http.Server` calls listeners in registration order; the first to\n *   call `socket.destroy()` (upgrade) or `res.end()` (request) wins. Invalid\n *   auth → 401 + destroy (chii never sees the connection). Valid auth →\n *   return without side-effect (chii handles it).\n *\n * TOTP code transports (issue #466) — two equivalent ways to carry the code:\n *   1. Query param `at=<code>` — used by the daemon-side `/client` connection\n *      (`chii-connection.ts` appends it; it holds the secret).\n *   2. Path prefix `/at/<code>/…` — used by the phone-side target. Chii's\n *      stock `target.js` derives its WS endpoint from the script `src`\n *      (`scriptEl.src.replace('target.js','')`), so the only way for the\n *      phone to carry a code is to embed it in the script URL path. The\n *      in-app attach injects `https://<host>/at/<code>/target.js`; both the\n *      script fetch and the derived `wss://<host>/at/<code>/target/<id>` WS\n *      dial then carry the prefix. The listeners below rewrite the prefix\n *      into the query form (`rewriteAtPathPrefix`) and MUTATE `req.url`\n *      before chii's own handlers (registered later) parse it — chii only\n *      ever sees the stripped URL.\n *\n * Threat model: \"URL leak\" — someone obtains the tunnel URL (Slack paste, QR\n *   screenshot, shoulder-surfing) but does not have the shared TOTP secret.\n *   Rotating 6-digit code makes the URL stale after 30 s.\n *   A determined attacker who extracts the secret from the dogfood bundle can\n *   still compute valid codes; that is out of scope (see umbrella CLAUDE.md §4).\n *\n * SECRET-HANDLING: The secret value and computed TOTP codes MUST NOT appear\n *   in any log, error message, or process output. `verifyAuth` is a black-box\n *   predicate from the caller's perspective; this module only forwards pass/fail.\n */\n\nimport { createServer, type IncomingMessage, type Server } from 'node:http';\nimport { createRequire } from 'node:module';\nimport type { AddressInfo } from 'node:net';\nimport type { Duplex } from 'node:stream';\n\nconst require = createRequire(import.meta.url);\n\n/** `chii/server` is CommonJS and shipped without TypeScript types. */\ninterface ChiiServerModule {\n  start(options: {\n    port?: number;\n    host?: string;\n    domain?: string;\n    server?: Server;\n    basePath?: string;\n  }): Promise<void>;\n}\n\nfunction loadChiiServer(): ChiiServerModule {\n  // `chii`'s package `main` is `./server/index.js`, exposing `{ start }`.\n  const mod: unknown = require('chii');\n  if (\n    typeof mod === 'object' &&\n    mod !== null &&\n    'start' in mod &&\n    typeof (mod as { start: unknown }).start === 'function'\n  ) {\n    return mod as ChiiServerModule;\n  }\n  throw new Error('chii server module did not expose start()');\n}\n\nexport interface ChiiRelay {\n  port: number;\n  /** Base URL for the relay HTTP/WS server, e.g. `http://127.0.0.1:54321`. */\n  baseUrl: string;\n  close(): Promise<void>;\n}\n\n/**\n * Secret-free metadata about a single auth rejection (issue #467).\n *\n * SECRET-HANDLING: this event carries ONLY the surface kind. It must never\n * grow fields for `req.url`, query strings, codes, or secrets — observers\n * (diagnostics counters, console hints) only need \"a rejection happened\".\n */\nexport interface RelayAuthRejectEvent {\n  /** Which inbound surface was rejected. */\n  kind: 'ws-upgrade' | 'http-request';\n}\n\n/**\n * Rewrites a `/at/<code>/…` path-prefixed request URL into the equivalent\n * query-based form, e.g.:\n *\n *   `/at/123456/target.js`        → `/target.js?at=123456`\n *   `/at/123456/target/x?url=u`   → `/target/x?url=u&at=123456`\n *   `/at/123456/`                 → `/?at=123456`\n *\n * Returns `null` when the URL does not carry the prefix (including an empty\n * code segment) — callers fall back to the unmodified URL and the existing\n * query-based auth path.\n *\n * Pure string surgery — this function knows nothing about secrets or code\n * validity; verification stays inside the caller-provided `verifyAuth`\n * predicate (which parses the query). The raw path segment is appended\n * verbatim to the query: both path segments and query values are\n * percent-decoded exactly once by their consumers, so no re-encoding is\n * needed (TOTP codes are 6 digits and never percent-encoded in practice).\n */\nexport function rewriteAtPathPrefix(rawUrl: string): string | null {\n  const match = /^\\/at\\/([^/?]+)(\\/[^?]*)?(\\?.*)?$/.exec(rawUrl);\n  if (match === null) return null;\n  const code = match[1];\n  const path = match[2] === undefined || match[2] === '' ? '/' : match[2];\n  const query = match[3] ?? '';\n  const separator = query === '' ? '?' : '&';\n  return `${path}${query}${separator}at=${code}`;\n}\n\nexport interface StartChiiRelayOptions {\n  /**\n   * Local port for the relay. Default 0 (OS-assigned ephemeral port).\n   *\n   * Using 0 means the OS picks a free port — this is the safe default because\n   * a stale cloudflared child process (PPID 1, orphaned after SIGKILL) may still\n   * be holding a fixed port. A fixed port causes EADDRINUSE on the next startup,\n   * which makes the MCP handshake fail with -32000. With port 0 the new relay\n   * always gets a fresh port, making any orphaned process harmless.\n   *\n   * Pass an explicit number to restore fixed-port behaviour (backwards-compatible).\n   */\n  port?: number;\n  /** Bind host. Default 127.0.0.1 (tunnel reaches it locally). */\n  host?: string;\n  /**\n   * Optional auth predicate for WebSocket upgrade requests.\n   *\n   * When provided, every inbound WebSocket upgrade is checked by calling\n   * `verifyAuth(req)` before Chii processes it. Return `true` to allow the\n   * upgrade; return `false` to reject with HTTP 401 and destroy the socket.\n   *\n   * The predicate MUST NOT log the secret or any TOTP code — it is a black-box\n   * from this module's perspective.\n   *\n   * @param req - The raw HTTP `IncomingMessage` from the upgrade handshake.\n   *   Inspect `req.url` for query parameters (e.g. `at=<code>`). Path-prefixed\n   *   URLs (`/at/<code>/…`, the phone-target transport — issue #466) are\n   *   rewritten into the query form BEFORE this predicate runs, so a\n   *   query-only predicate covers both transports.\n   * @returns `true` if the upgrade is authorised, `false` to reject.\n   */\n  verifyAuth?: (req: IncomingMessage) => boolean;\n  /**\n   * Secret-free observability callback fired on every auth rejection\n   * (issue #467). Only meaningful together with `verifyAuth`.\n   *\n   * SECRET-HANDLING: the event carries ONLY the rejection kind — never\n   * `req.url`, query strings, TOTP codes, or the secret. Implementations must\n   * keep it that way (e.g. increment a counter + timestamp). Exceptions thrown\n   * by the callback are swallowed so observability can never break the gate.\n   */\n  onAuthReject?: (event: RelayAuthRejectEvent) => void;\n}\n\n/**\n * Starts the Chii relay and resolves once listening.\n *\n * Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral\n * port on every start, so a stale cloudflared orphan holding any particular\n * port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`\n * always reflect the actual bound port.\n *\n * chii.start() is called with `server` (our pre-created httpServer) BEFORE\n * httpServer.listen(). This is intentional: chii attaches its Koa handler and\n * WS upgrade listener to the server object, but the actual TCP bind is\n * performed by our httpServer.listen() call below. The `port`/`domain` values\n * passed to chii.start() are used for display/banner purposes inside chii and\n * do not affect which port the server binds. The connection path (clients\n * connecting to `relay.baseUrl`) always uses the post-listen confirmed port.\n */\nexport async function startChiiRelay(options: StartChiiRelayOptions = {}): Promise<ChiiRelay> {\n  const requestedPort = options.port ?? 0;\n  const host = options.host ?? '127.0.0.1';\n  const { verifyAuth, onAuthReject } = options;\n\n  const httpServer = createServer();\n\n  // Secret-free observability hook (issue #467). Swallow callback exceptions —\n  // a broken observer must never turn into an open gate or a crashed relay.\n  const notifyAuthReject = (kind: RelayAuthRejectEvent['kind']): void => {\n    if (onAuthReject === undefined) return;\n    try {\n      onAuthReject({ kind });\n    } catch {\n      // Ignore — observability is best-effort.\n    }\n  };\n\n  // Register our auth listeners BEFORE chii.start() so they fire first.\n  // Node's http.Server emits 'upgrade'/'request' to all listeners in\n  // registration order; the first to destroy() the socket (upgrade) or end()\n  // the response (request) wins. Valid requests return without side-effect so\n  // chii's own handlers take over normally — and because listeners run\n  // synchronously in order, mutating `req.url` here (path-prefix strip,\n  // issue #466) means chii's later-registered handlers only ever see the\n  // stripped URL.\n  //\n  // We only register when verifyAuth is provided so the no-auth path is\n  // zero-overhead for tests and local-only dev sessions. (The phone-side\n  // `/at/<code>/` prefix only ever appears when TOTP is armed — the launcher\n  // QR carries the `at` code — so the no-auth path never needs the strip.)\n  if (verifyAuth) {\n    httpServer.on('upgrade', (req: IncomingMessage, socket: Duplex) => {\n      // Phone-target transport (issue #466): normalise a `/at/<code>/…` path\n      // prefix into the query form before verification, and strip it from the\n      // URL chii will see. No-prefix URLs pass through untouched (daemon\n      // client query transport — back-compat).\n      const rewritten = rewriteAtPathPrefix(req.url ?? '');\n      if (rewritten !== null) {\n        req.url = rewritten;\n      }\n      if (!verifyAuth(req)) {\n        // Reject: send a minimal HTTP 401 response and close the socket.\n        // We do NOT log req.url or any auth param here to avoid leaking codes.\n        socket.write('HTTP/1.1 401 Unauthorized\\r\\nContent-Length: 0\\r\\n\\r\\n');\n        socket.destroy();\n        notifyAuthReject('ws-upgrade');\n        // Early return — chii's handler is NOT called for this socket.\n        return;\n      }\n      // Auth passed: no-op. Chii's upgrade listener (registered below by\n      // chii.start) will handle the rest.\n    });\n\n    // Plain HTTP requests: only the path-prefixed form is ours — the phone\n    // fetches `target.js` via `https://<host>/at/<code>/target.js` (issue\n    // #466), which must be verified + stripped so chii's Koa static handler\n    // serves `/target.js`. Non-prefixed requests keep today's behaviour\n    // (ungated pass-through to chii).\n    httpServer.on('request', (req, res) => {\n      const rewritten = rewriteAtPathPrefix(req.url ?? '');\n      if (rewritten === null) return;\n      req.url = rewritten;\n      if (!verifyAuth(req)) {\n        // We do NOT log req.url or any auth param here to avoid leaking codes.\n        res.statusCode = 401;\n        res.end();\n        notifyAuthReject('http-request');\n      }\n      // Auth passed: no-op — chii's Koa 'request' listener (registered below\n      // by chii.start) serves the rewritten URL. (Koa skips writing when an\n      // earlier listener already ended the response, so the 401 path is safe\n      // even though Koa still runs.)\n    });\n  }\n\n  const chii = loadChiiServer();\n  // Passing an existing `server` makes chii attach its Koa handler + WS upgrade\n  // to our HTTP server rather than creating its own listener.\n  // Note: port/domain here are display-only inside chii — the TCP bind is ours.\n  await chii.start({ server: httpServer, domain: `${host}:${requestedPort}`, port: requestedPort });\n\n  const actualPort = await new Promise<number>((resolve, reject) => {\n    httpServer.once('error', reject);\n    httpServer.listen(requestedPort, host, () => {\n      httpServer.off('error', reject);\n      // httpServer.address() is non-null immediately after the listen callback.\n      const addr = httpServer.address() as AddressInfo;\n      resolve(addr.port);\n    });\n  });\n\n  return {\n    port: actualPort,\n    baseUrl: `http://${host}:${actualPort}`,\n    close: () =>\n      new Promise<void>((resolve) => {\n        httpServer.close(() => resolve());\n      }),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,MAAMA,aAAAA,0BAAAA,eAAAA,QAAAA,MAAAA,CAAAA,cAAAA,WAAAA,CAAAA,KAAwC;AAa9C,SAAS,iBAAmC;CAE1C,MAAM,MAAeA,UAAQ,OAAO;AACpC,KACE,OAAO,QAAQ,YACf,QAAQ,QACR,WAAW,OACX,OAAQ,IAA2B,UAAU,WAE7C,QAAO;AAET,OAAM,IAAI,MAAM,4CAA4C;;;;;;;;;;;;;;;;;;;;;AAyC9D,SAAgB,oBAAoB,QAA+B;CACjE,MAAM,QAAQ,oCAAoC,KAAK,OAAO;AAC9D,KAAI,UAAU,KAAM,QAAO;CAC3B,MAAM,OAAO,MAAM;CACnB,MAAM,OAAO,MAAM,OAAO,KAAA,KAAa,MAAM,OAAO,KAAK,MAAM,MAAM;CACrE,MAAM,QAAQ,MAAM,MAAM;AAE1B,QAAO,GAAG,OAAO,QADC,UAAU,KAAK,MAAM,IACJ,KAAK;;;;;;;;;;;;;;;;;;AAgE1C,eAAsB,eAAe,UAAiC,EAAE,EAAsB;CAC5F,MAAM,gBAAgB,QAAQ,QAAQ;CACtC,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,YAAY,iBAAiB;CAErC,MAAM,cAAA,GAAA,UAAA,eAA2B;CAIjC,MAAM,oBAAoB,SAA6C;AACrE,MAAI,iBAAiB,KAAA,EAAW;AAChC,MAAI;AACF,gBAAa,EAAE,MAAM,CAAC;UAChB;;AAkBV,KAAI,YAAY;AACd,aAAW,GAAG,YAAY,KAAsB,WAAmB;GAKjE,MAAM,YAAY,oBAAoB,IAAI,OAAO,GAAG;AACpD,OAAI,cAAc,KAChB,KAAI,MAAM;AAEZ,OAAI,CAAC,WAAW,IAAI,EAAE;AAGpB,WAAO,MAAM,yDAAyD;AACtE,WAAO,SAAS;AAChB,qBAAiB,aAAa;AAE9B;;IAIF;AAOF,aAAW,GAAG,YAAY,KAAK,QAAQ;GACrC,MAAM,YAAY,oBAAoB,IAAI,OAAO,GAAG;AACpD,OAAI,cAAc,KAAM;AACxB,OAAI,MAAM;AACV,OAAI,CAAC,WAAW,IAAI,EAAE;AAEpB,QAAI,aAAa;AACjB,QAAI,KAAK;AACT,qBAAiB,eAAe;;IAMlC;;AAOJ,OAJa,gBAAgB,CAIlB,MAAM;EAAE,QAAQ;EAAY,QAAQ,GAAG,KAAK,GAAG;EAAiB,MAAM;EAAe,CAAC;CAEjG,MAAM,aAAa,MAAM,IAAI,SAAiB,SAAS,WAAW;AAChE,aAAW,KAAK,SAAS,OAAO;AAChC,aAAW,OAAO,eAAe,YAAY;AAC3C,cAAW,IAAI,SAAS,OAAO;AAG/B,WADa,WAAW,SAAS,CACpB,KAAK;IAClB;GACF;AAEF,QAAO;EACL,MAAM;EACN,SAAS,UAAU,KAAK,GAAG;EAC3B,aACE,IAAI,SAAe,YAAY;AAC7B,cAAW,YAAY,SAAS,CAAC;IACjC;EACL"}

package/dist/in-app/index.d.ts

@@ -214,18 +214,36 @@ declare function evaluateDebugGate(input: GateInput): GateResult;
  * Converts a validated `wss:` relay URL into the Chii `target.js` script URL.
  *
  * Scheme is mapped `wss:` → `https:`. Host and port are preserved.
- * Pathname is set to `/target.js` regardless of the relay path.
- * Query params and hash from the relay URL are dropped — the target script
- * URL is a static asset path on the same host.
+ * Pathname is set to `/target.js` (or `/at/<code>/target.js` when a TOTP code
+ * is given) regardless of the relay path. Query params and hash from the
+ * relay URL are dropped — the target script URL is a static asset path on the
+ * same host.
+ *
+ * TOTP path-prefix transport (issue #466): chii's stock `target.js` derives
+ * its WS endpoint from the script `src` (`scriptEl.src.replace('target.js',
+ * '')`), so embedding the current TOTP code in the script URL *path* is the
+ * only way the phone-side WS upgrade can carry it — both the script fetch and
+ * the derived `wss://<host>/at/<code>/target/<id>` dial inherit the prefix,
+ * and the relay verifies + strips it before chii parses the URL. The
+ * `window.ChiiServerUrl` + query alternative does NOT work: chii appends
+ * `target/<id>` to the serverUrl string, which would land after a `?`.
+ *
+ * SECRET-HANDLING: `atCode` rides only inside the returned URL (the intended
+ * transport — same exposure grade as the daemon client's `at=` query). It is
+ * never logged here.
  *
  * @example
  * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')
  * // → 'https://abc.trycloudflare.com/target.js'
  *
- * deriveTargetScriptUrl('wss://h.example.com:9100/')
- * // → 'https://h.example.com:9100/target.js'
+ * deriveTargetScriptUrl('wss://h.example.com:9100/', '123456')
+ * // → 'https://h.example.com:9100/at/123456/target.js'
+ *
+ * @param relayUrl - Validated `wss:` relay URL from the gate result.
+ * @param atCode - Current TOTP code from the page URL's `at` query param, or
+ *   `null`/`undefined`/`''` to keep the legacy un-prefixed URL.
  */
-declare function deriveTargetScriptUrl(relayUrl: string): string;
+declare function deriveTargetScriptUrl(relayUrl: string, atCode?: string | null): string;
 /**
  * Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii
  * `target.js` script into `document.head`.

package/dist/in-app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"mappings":";;AA4EA;;;;;;;;;AASA;;;;;AAmBA;;;;;AAQA;;;;;;;;;;;AA8EA;;;;;AAuBA;;;;;AAyBA;;;;;;;;;;;;AChNA;;;;;AAmCA;;;;;;;;ACrBA;;;;;;;;;UFgCiB,gBAAA;EAAA,SACN,MAAA;;WAEA,QAAA;;WAEA,YAAA;AAAA;;UAIM,iBAAA;EAAA,SACN,MAAA;;;;;;;;;;;;;;;WAeA,MAAA;AAAA;AAAA,KAGC,UAAA,GAAa,gBAAA,GAAmB,iBAAA;;;;;;;UAQ3B,SAAA;;;;;;;;;;;;;WAaN,QAAA;;;;;;;WAQA,YAAA,EAAc,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;WA0Bd,cAAA,IAAkB,IAAA;AAAA;;;;;;;;;;;;iBA+Bb,iBAAA,CAAkB,QAAA;;;;;;;;;;;;;;;;;;;;iBAuBlB,mBAAA,CAAoB,QAAA;;;;;;;;;;;;;;;;;;;;;;iBAyBpB,iBAAA,CAAkB,KAAA,EAAO,SAAA,GAAY,UAAA;;;;;;AAtIrD;;;;;AAQA;;;;;;;iBClFgB,qBAAA,CAAsB,QAAA;;;;ADgKtC;;;;;AAuBA;;;;;AAyBA;;;;;;;;;;iBC7KgB,WAAA,CAAY,UAAA,GAAY,UAAA;;;;;;;AD6HxC;;;;;AAuBA;;;;;iBEzKgB,cAAA,CAAA,GAAkB,UAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"mappings":";;AA4EA;;;;;;;;;AASA;;;;;AAmBA;;;;;AAQA;;;;;;;;;;;AA8EA;;;;;AAuBA;;;;;AAyBA;;;;;;;;;;;;AC9LA;;;;;AAsCA;;;;;;;;AC1CA;;;;;;;;;UFgCiB,gBAAA;EAAA,SACN,MAAA;;WAEA,QAAA;;WAEA,YAAA;AAAA;;UAIM,iBAAA;EAAA,SACN,MAAA;;;;;;;;;;;;;;;WAeA,MAAA;AAAA;AAAA,KAGC,UAAA,GAAa,gBAAA,GAAmB,iBAAA;;;;;;;UAQ3B,SAAA;;;;;;;;;;;;;WAaN,QAAA;;;;;;;WAQA,YAAA,EAAc,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;WA0Bd,cAAA,IAAkB,IAAA;AAAA;;;;;;;;;;;;iBA+Bb,iBAAA,CAAkB,QAAA;;;;;;;;;;;;;;;;;;;;iBAuBlB,mBAAA,CAAoB,QAAA;;;;;;;;;;;;;;;;;;;;;;iBAyBpB,iBAAA,CAAkB,KAAA,EAAO,SAAA,GAAY,UAAA;;;;;;AAtIrD;;;;;AAQA;;;;;;;;;;;AA8EA;;;;;AAuBA;;;;;AAyBA;;;;iBC9LgB,qBAAA,CAAsB,QAAA,UAAkB,MAAA;;;;;;;;AAAxD;;;;;AAsCA;;;;;;;;AC1CA;;;iBD0CgB,WAAA,CAAY,UAAA,GAAY,UAAA;;;;;;;ADwGxC;;;;;AAuBA;;;;;iBEzKgB,cAAA,CAAA,GAAkB,UAAA"}

package/dist/in-app/index.js

@@ -138,21 +138,39 @@ function evaluateDebugGate(input) {
 * Converts a validated `wss:` relay URL into the Chii `target.js` script URL.
 *
 * Scheme is mapped `wss:` → `https:`. Host and port are preserved.
-* Pathname is set to `/target.js` regardless of the relay path.
-* Query params and hash from the relay URL are dropped — the target script
-* URL is a static asset path on the same host.
+* Pathname is set to `/target.js` (or `/at/<code>/target.js` when a TOTP code
+* is given) regardless of the relay path. Query params and hash from the
+* relay URL are dropped — the target script URL is a static asset path on the
+* same host.
+*
+* TOTP path-prefix transport (issue #466): chii's stock `target.js` derives
+* its WS endpoint from the script `src` (`scriptEl.src.replace('target.js',
+* '')`), so embedding the current TOTP code in the script URL *path* is the
+* only way the phone-side WS upgrade can carry it — both the script fetch and
+* the derived `wss://<host>/at/<code>/target/<id>` dial inherit the prefix,
+* and the relay verifies + strips it before chii parses the URL. The
+* `window.ChiiServerUrl` + query alternative does NOT work: chii appends
+* `target/<id>` to the serverUrl string, which would land after a `?`.
+*
+* SECRET-HANDLING: `atCode` rides only inside the returned URL (the intended
+* transport — same exposure grade as the daemon client's `at=` query). It is
+* never logged here.
 *
 * @example
 * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')
 * // → 'https://abc.trycloudflare.com/target.js'
 *
-* deriveTargetScriptUrl('wss://h.example.com:9100/')
-* // → 'https://h.example.com:9100/target.js'
+* deriveTargetScriptUrl('wss://h.example.com:9100/', '123456')
+* // → 'https://h.example.com:9100/at/123456/target.js'
+*
+* @param relayUrl - Validated `wss:` relay URL from the gate result.
+* @param atCode - Current TOTP code from the page URL's `at` query param, or
+*   `null`/`undefined`/`''` to keep the legacy un-prefixed URL.
 */
-function deriveTargetScriptUrl(relayUrl) {
+function deriveTargetScriptUrl(relayUrl, atCode) {
 	const u = new URL(relayUrl);
 	u.protocol = "https:";
-	u.pathname = "/target.js";
+	u.pathname = atCode !== void 0 && atCode !== null && atCode !== "" ? `/at/${encodeURIComponent(atCode)}/target.js` : "/target.js";
 	u.search = "";
 	u.hash = "";
 	return u.toString();
@@ -193,7 +211,8 @@ function maybeAttach(gateResult = checkDebugGate()) {
 	}
 	if (attached) return;
 	if (typeof document === "undefined") return;
-	const src = deriveTargetScriptUrl(gateResult.relayUrl);
+	const atCode = typeof window !== "undefined" ? new URLSearchParams(window.location.search).get("at") : null;
+	const src = deriveTargetScriptUrl(gateResult.relayUrl, atCode);
 	if (document.querySelector(`script[src="${src}"]`) !== null) {
 		attached = true;
 		return;

package/dist/in-app/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"sourcesContent":["/**\n * Runtime activation gate for the in-app debug surface.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"3-layer activation gate\". This is the pure gate decision; the Chii client,\n * WebSocket transport, MCP server, and CLI that consume it live in src/mcp/.\n *\n * This function evaluates the two RUNTIME layers, B and C. Layer A — the\n * build-time gate — is NOT evaluated here, and deliberately so: it is enforced\n * entirely by the consumer's `if (__DEBUG_BUILD__) { … }` guard around the\n * import site (see sdk-example `src/main.tsx`). `__DEBUG_BUILD__` is a\n * consumer-build-time constant; a release consumer build folds it to `false`\n * and dead-code-eliminates the whole import of `@ait-co/devtools/in-app`, so\n * this code is simply absent from release bundles. A pre-built npm package\n * cannot re-check that flag — it was already baked at devtools' own publish\n * time — so any `isDebugBuild` check inside this function would be permanently\n * `false` and could never pass. Layer A is the consumer guard; B and C are\n * here.\n *\n * Layer B has two parts:\n *   B1 — host allowlist: `hostname` must be a `*.private-apps.tossmini.com`\n *        subdomain (Toss dogfood entry) OR a `*.trycloudflare.com` host (env 2\n *        PWA dev tunnel). The Toss app serves dogfood / private mini-apps from\n *        a separate `private-apps` host; a production (`intoss://`) entry is\n *        served from `*.apps.tossmini.com` WITHOUT the `private-apps` segment.\n *        This is the security gate against a dogfood build that somehow lands\n *        on a production entry — see the comment on {@link isPrivateAppsHost}.\n *        The env 2 tunnel host is allowed because it has no production runtime\n *        (mock SDK, the developer's own dev server) — see {@link\n *        isTrycloudflareHost}.\n *   B2 — entry query: `_deploymentId` must be present and non-empty. Applies to\n *        the Toss path only; the env 2 tunnel has no deployed bundle, so B2 is\n *        skipped for `*.trycloudflare.com` hosts.\n *\n * Layer C — opt-in + relay + optional TOTP auth:\n *   C1 — opt-in:       `debug=1` must be present.\n *   C2 — relay URL:    `relay=<wss-url>` must be a valid `wss:` URL.\n *   C3 — TOTP auth:    When `verifyTotpCode` is provided (consumer injected the\n *                      baked secret at build time via `__DEBUG_TOTP_SECRET__`),\n *                      `at=<code>` is checked. Invalid or absent code → BLOCKED.\n *                      When no verifier is provided (TOTP disabled), `at` is\n *                      ignored (backward compatible).\n *\n * Security note on baked secrets:\n *   The TOTP secret baked in via `__DEBUG_TOTP_SECRET__` is present in the\n *   dogfood bundle and is extractable by a determined reverse engineer.\n *   The practical bar raised is: \"URL leak\" (Slack paste, QR screenshot) →\n *   blocked; \"URL + bundle extraction + live TOTP code\" → not blocked.\n *   This is the intended threat model. Do not overpromise on this guarantee.\n *\n * SECRET-HANDLING: `verifyTotpCode` is a black-box predicate. This module\n *   does NOT log the secret, any code value, or pass/fail details beyond the\n *   `'auth'` reason enum.\n *\n * Decision matrix (gate only runs in a debug build — Layer A already passed):\n *\n *   host        | _deploymentId | debug=1 | relay ok | TOTP ok* | result\n *   neither     | (any)         | (any)   | (any)    | (any)    | BLOCKED (host)\n *   private-apps| absent        | (any)   | (any)    | (any)    | BLOCKED (entry)\n *   private-apps| present       | absent  | (any)    | (any)    | BLOCKED (opt-in)\n *   private-apps| present       | present | invalid  | (any)    | BLOCKED (invalid-relay)\n *   private-apps| present       | present | valid    | fail*    | BLOCKED (auth)\n *   private-apps| present       | present | valid    | pass/n/a | ATTACH\n *   trycloudflare| (skipped)    | absent  | (any)    | (any)    | BLOCKED (opt-in)\n *   trycloudflare| (skipped)    | present | invalid  | (any)    | BLOCKED (invalid-relay)\n *   trycloudflare| (skipped)    | present | valid    | fail*    | BLOCKED (auth)\n *   trycloudflare| (skipped)    | present | valid    | pass/n/a | ATTACH\n *\n *   * \"TOTP ok\" column only applies when `verifyTotpCode` is provided.\n *     When no verifier is injected, TOTP check is skipped entirely.\n *   For trycloudflare (env 2 tunnel) hosts B1 is bypassed and B2 is skipped;\n *   C1/C2/C3 still apply identically. The ATTACH result carries\n *   `deploymentId: ''` for tunnel hosts.\n */\n\n/** Shape returned when the gate allows attachment. */\nexport interface GateResultAttach {\n  readonly attach: true;\n  /** The validated `wss:` relay URL from the `relay` query param. */\n  readonly relayUrl: string;\n  /** The deployment ID extracted from the `_deploymentId` query param. */\n  readonly deploymentId: string;\n}\n\n/** Shape returned when the gate blocks attachment, with a reason code. */\nexport interface GateResultBlocked {\n  readonly attach: false;\n  /**\n   * - `'host'`          Layer B1: `hostname` is not a `*.private-apps.tossmini.com` host.\n   * - `'entry'`         Layer B2: `_deploymentId` param is absent or empty.\n   * - `'opt-in'`        Layer C1: `debug=1` param is absent.\n   * - `'invalid-relay'` Layer C2: `relay` param is absent, empty, or not a `wss:` URL.\n   * - `'auth'`          Layer C3: TOTP `at=` code is absent, invalid, or expired\n   *                     (only when a `verifyTotpCode` predicate is injected).\n   *\n   * There is no `'build'` reason: Layer A is enforced by the consumer's\n   * `if (__DEBUG_BUILD__)` guard, not by this function.\n   *\n   * SECRET-HANDLING: `'auth'` is the only value surfaced for auth failures —\n   * no code value, expected value, or secret fragment is ever exposed.\n   */\n  readonly reason: 'host' | 'entry' | 'opt-in' | 'invalid-relay' | 'auth';\n}\n\nexport type GateResult = GateResultAttach | GateResultBlocked;\n\n/**\n * Input for {@link evaluateDebugGate}.\n *\n * All fields are explicit so the function is trivially testable without\n * touching `window`.\n */\nexport interface GateInput {\n  /**\n   * The host the page is served from — `window.location.hostname`.\n   *\n   * This is the Layer B1 security signal. Why hostname and not the entry\n   * scheme: the Toss SDK normalises `intoss-private://` to `intoss://` in\n   * `getSchemeUri()`, and `getOperationalEnvironment()` / `getWebViewType()`\n   * return the same value (`\"toss\"` / `\"partner\"`) for both dogfood and\n   * production entries — none of them distinguish a dogfood entry. The host\n   * does: a dogfood / private-apps entry is served from\n   * `*.private-apps.tossmini.com`, a production entry is not. This was\n   * confirmed live over CDP against mini-app 31146 (see spec open question 2).\n   */\n  readonly hostname: string;\n\n  /**\n   * The URL search params to inspect for gate signals (Layers B2 and C).\n   *\n   * Prefer `URLSearchParams` so callers can pass `new URLSearchParams(location.search)`\n   * without coupling the pure function to `window`.\n   */\n  readonly searchParams: URLSearchParams;\n\n  /**\n   * Optional TOTP code verifier for Layer C3 auth gate.\n   *\n   * When provided, `evaluateDebugGate` reads the `at` query param and passes\n   * it to this predicate. Return `true` to allow, `false` to block with\n   * `reason: 'auth'`.\n   *\n   * Inject via the consumer's build define, e.g.:\n   * ```ts\n   * // dogfood build entry — consumer's build injects __DEBUG_TOTP_SECRET__\n   * declare const __DEBUG_TOTP_SECRET__: string | undefined;\n   * const verifyTotpCode = typeof __DEBUG_TOTP_SECRET__ !== 'undefined'\n   *   ? (code: string) => verifyTotp(__DEBUG_TOTP_SECRET__, code)\n   *   : undefined;\n   * maybeAttach(evaluateDebugGate({ ...params, verifyTotpCode }));\n   * ```\n   *\n   * Security note: this predicate is a black-box from the gate's perspective.\n   * The gate only surfaces pass/fail and the `'auth'` reason code — no code\n   * value or secret fragment is ever logged or returned.\n   *\n   * When `undefined` (TOTP disabled), `at=` is silently ignored and the gate\n   * proceeds to ATTACH if all other layers pass.\n   */\n  readonly verifyTotpCode?: (code: string) => boolean;\n}\n\n/**\n * The host suffix the Toss app uses to serve dogfood / private mini-apps.\n *\n * A `intoss-private://` (dogfood) entry maps to a host such as\n * `aitc-sdk-example.private-apps.tossmini.com`. A production `intoss://`\n * entry is served from `*.apps.tossmini.com` — the `.private-apps.` segment\n * is absent. Confirmed live over CDP for mini-app 31146; the exact production\n * host is to be re-confirmed once 31146 passes review (spec open question 2).\n */\nconst PRIVATE_APPS_HOST_SUFFIX = '.private-apps.tossmini.com';\n\n/**\n * The host suffix Cloudflare quick-tunnels serve from — the env 2 (PWA) entry.\n * See {@link isTrycloudflareHost} for why this host kind bypasses Layer B1.\n */\nconst TRYCLOUDFLARE_HOST_SUFFIX = '.trycloudflare.com';\n\n/**\n * Returns whether `hostname` is a `*.private-apps.tossmini.com` subdomain —\n * the host the Toss app reserves for dogfood / private mini-app entries.\n *\n * The match is an exact suffix check, not a substring `.includes()`: a\n * substring test would also accept an attacker-controlled host like\n * `private-apps.tossmini.com.evil.example`, which ends in `.example`, not in\n * `.tossmini.com`. Requiring the string to END with the suffix closes that.\n * The leading `.` in the suffix also forces a real subdomain label, so a\n * bare `private-apps.tossmini.com` (no mini-app subdomain) does not match.\n */\nexport function isPrivateAppsHost(hostname: string): boolean {\n  return hostname.endsWith(PRIVATE_APPS_HOST_SUFFIX);\n}\n\n/**\n * The host suffix Cloudflare quick-tunnels use — the env 2 (PWA) entry.\n *\n * Env 2 serves the local Vite dev server through a `*.trycloudflare.com` quick\n * tunnel (`src/unplugin/tunnel.ts`). It has no Toss app, no `intoss-private://`\n * scheme, and — critically — no production runtime: the SDK is the devtools\n * mock, and the page is the developer's own dev build. The Layer B1 safety net\n * (which stops a dogfood build that lands on a Toss *production* host from\n * attaching) has nothing to protect against here, because env 2 has no\n * production host. So a trycloudflare host is allowed past B1 — but ONLY past\n * B1: the remaining layers (C1 opt-in, C2 relay, C3 TOTP) still apply, so a\n * leaked tunnel URL is still blocked by TOTP exactly as on the Toss path.\n *\n * The match is the same exact-suffix `endsWith` check as\n * {@link isPrivateAppsHost} — never a substring `.includes()`, which would\n * accept an attacker-controlled `evil.trycloudflare.com.example.com`. The\n * leading `.` forces a real subdomain label, so a bare `trycloudflare.com`\n * (no tunnel subdomain) does not match.\n */\nexport function isTrycloudflareHost(hostname: string): boolean {\n  return hostname.endsWith(TRYCLOUDFLARE_HOST_SUFFIX);\n}\n\n/**\n * Pure function that evaluates the runtime debug activation layers (B and C).\n *\n * Has no side effects. The input is explicit. Returns a discriminated union\n * so callers can pattern-match on `result.attach`.\n *\n * Layer A (build-time) is intentionally not evaluated here — see the file-level\n * comment. By the time this function runs, the consumer's `if (__DEBUG_BUILD__)`\n * guard has already passed; this function only decides B and C.\n *\n * @example\n * ```ts\n * const result = evaluateDebugGate({\n *   hostname: window.location.hostname,\n *   searchParams: new URLSearchParams(window.location.search),\n * });\n * if (result.attach) {\n *   // Proceed to load Chii client\n * }\n * ```\n */\nexport function evaluateDebugGate(input: GateInput): GateResult {\n  // Layer B1 — host allowlist (the security gate).\n  // Two host kinds are allowed past B1:\n  //   - Toss dogfood: `*.private-apps.tossmini.com`. A production `intoss://`\n  //     entry is served from `*.apps.tossmini.com` and is rejected here. This\n  //     is what stops a dogfood build that somehow reaches a production entry\n  //     from attaching: Layer A keeps debug code out of release bundles, and\n  //     this layer keeps a dogfood bundle that lands on a production host from\n  //     attaching even though its code is present.\n  //   - Env 2 PWA tunnel: `*.trycloudflare.com`. This is the developer's own\n  //     local dev server (mock SDK, no production runtime), so the\n  //     production-entry hazard B1 guards against cannot occur. It bypasses B1\n  //     but NOT the remaining layers — C1/C2/C3 (incl. TOTP) still apply, so a\n  //     leaked tunnel URL is blocked exactly as on the Toss path. See\n  //     {@link isTrycloudflareHost}.\n  const isTunnel = isTrycloudflareHost(input.hostname);\n  if (!isPrivateAppsHost(input.hostname) && !isTunnel) {\n    return { attach: false, reason: 'host' };\n  }\n\n  // Layer B2 — runtime entry query gate (Toss path only).\n  // `_deploymentId` must be present and non-empty. The `intoss-private://`\n  // scheme used for dogfood entries includes this param; general user entry\n  // paths do not. The env 2 tunnel has no deployed bundle and therefore no\n  // `_deploymentId` — B2 is skipped for it, and `deploymentId` is reported as\n  // the empty string on a tunnel attach (no consumer reads it; see attach.ts).\n  let deploymentId = '';\n  if (!isTunnel) {\n    deploymentId = input.searchParams.get('_deploymentId') ?? '';\n    if (deploymentId === '') {\n      return { attach: false, reason: 'entry' };\n    }\n  }\n\n  // Layer C — explicit opt-in gate.\n  // Require `debug=1` so that an operator who opens a dogfood URL by accident\n  // does not inadvertently trigger the debug surface.\n  const debugParam = input.searchParams.get('debug');\n  if (debugParam !== '1') {\n    return { attach: false, reason: 'opt-in' };\n  }\n\n  // Layer C continued — relay URL validation.\n  // `relay=<wss-url>` must be present and must use the `wss:` scheme.\n  // Plain `ws:` is rejected (no TLS). `http:`/`https:` are rejected.\n  const relayRaw = input.searchParams.get('relay') ?? '';\n  if (relayRaw === '') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  let relayUrl: URL;\n  try {\n    relayUrl = new URL(relayRaw);\n  } catch {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  if (relayUrl.protocol !== 'wss:') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  // Layer C3 — TOTP auth gate (fail-fast, only when a verifier is injected).\n  // The `at` query param carries the current TOTP code. Absent or invalid code\n  // → BLOCKED. When no verifier is provided (TOTP disabled), this check is\n  // skipped entirely for backward compatibility.\n  //\n  // SECRET-HANDLING: we do NOT log `code`, the verifier's result, or anything\n  // derived from the secret. Only the `'auth'` enum is surfaced on failure.\n  if (input.verifyTotpCode !== undefined) {\n    const code = input.searchParams.get('at') ?? '';\n    if (!input.verifyTotpCode(code)) {\n      return { attach: false, reason: 'auth' };\n    }\n  }\n\n  return { attach: true, relayUrl: relayUrl.href, deploymentId };\n}\n","/**\n * In-app Chii target injection for the debug attach flow.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"MCP attach\" topology section — Phase 1 browser-side implementation.\n *\n * This module bridges the 3-layer gate result to a Chii `target.js` script\n * injection. The Chii npm package is the relay SERVER — the in-app side is\n * a plain `<script src=\"…/target.js\">` pointing at the relay host. No chii\n * npm dependency is needed here.\n */\n\nimport { setScreenAwakeMode } from '@apps-in-toss/web-framework';\nimport { checkDebugGate, type GateResult } from './index.js';\n\n/**\n * Converts a validated `wss:` relay URL into the Chii `target.js` script URL.\n *\n * Scheme is mapped `wss:` → `https:`. Host and port are preserved.\n * Pathname is set to `/target.js` regardless of the relay path.\n * Query params and hash from the relay URL are dropped — the target script\n * URL is a static asset path on the same host.\n *\n * @example\n * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')\n * // → 'https://abc.trycloudflare.com/target.js'\n *\n * deriveTargetScriptUrl('wss://h.example.com:9100/')\n * // → 'https://h.example.com:9100/target.js'\n */\nexport function deriveTargetScriptUrl(relayUrl: string): string {\n  const u = new URL(relayUrl);\n  u.protocol = 'https:';\n  u.pathname = '/target.js';\n  u.search = '';\n  u.hash = '';\n  return u.toString();\n}\n\n/** Module-level guard against double-injection within a page lifecycle. */\nlet attached = false;\n\n/**\n * Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii\n * `target.js` script into `document.head`.\n *\n * Idempotent — calling more than once is safe. The second call is a no-op if\n * a script with the same `src` is already present in the document, and the\n * module-level `attached` flag prevents redundant DOM queries after the first\n * successful injection.\n *\n * Safe to call even if `document` is somehow unavailable (defensive boundary\n * guard — in practice this always runs in a real WebView).\n *\n * **keepAwake side effect**: on a successful attach, `setScreenAwakeMode({\n * enabled: true })` is called so the phone screen stays awake during the debug\n * session. A `beforeunload` handler restores normal sleep on page unload.\n * Opt out by adding `noKeepAwake=1` to the page URL query string — the check\n * reads `window.location.search` directly, consistent with other guards in\n * this file.\n *\n * @param gateResult - Optional pre-evaluated gate result for testability.\n *   Defaults to `checkDebugGate()` which reads the current page URL. Passing a\n *   custom value avoids the need to manipulate `window.location` in tests.\n */\nexport function maybeAttach(gateResult: GateResult = checkDebugGate()): void {\n  if (!gateResult.attach) {\n    console.debug(\n      `[@ait-co/devtools] debug attach skipped — gate blocked (reason: ${gateResult.reason})`,\n    );\n    // Defect 2: a wrong/expired TOTP code is the ONLY block reason that is a\n    // user-actionable failure inside a deliberate debug session — the operator\n    // scanned a QR expecting an attach. Surface it to the parent launcher shell\n    // so it can show a \"rescan the QR\" banner. Every other reason\n    // ('host'/'entry'/'opt-in'/'invalid-relay') fires on ordinary non-debug page\n    // loads and must stay silent to avoid a banner on every plain pageview.\n    // SECRET-HANDLING: the message carries ONLY the 'auth' reason enum — never\n    // the code, secret, host, or relay URL.\n    if (gateResult.reason === 'auth' && typeof window !== 'undefined' && window.parent !== window) {\n      window.parent.postMessage({ type: 'ait:debug-attach-blocked', reason: 'auth' }, '*');\n    }\n    return;\n  }\n\n  // Guard against double-injection across repeated calls.\n  if (attached) {\n    return;\n  }\n\n  // Defensive: if document is not available (unusual, but possible in some\n  // SSR-adjacent edge cases), bail silently rather than throwing.\n  if (typeof document === 'undefined') {\n    return;\n  }\n\n  const src = deriveTargetScriptUrl(gateResult.relayUrl);\n\n  // Also guard against a script with the same src already in the DOM\n  // (e.g. injected by a different code path or a page reload within SPA).\n  const existing = document.querySelector<HTMLScriptElement>(`script[src=\"${src}\"]`);\n  if (existing !== null) {\n    attached = true;\n    return;\n  }\n\n  const script = document.createElement('script');\n  script.src = src;\n  script.async = true;\n  (document.head ?? document.documentElement).appendChild(script);\n\n  attached = true;\n\n  // keepAwake — keep phone screen on during the debug session.\n  // Opt out via noKeepAwake=1 in the URL (consistent with direct window reads\n  // used throughout this file).\n  if (\n    typeof window !== 'undefined' &&\n    new URLSearchParams(window.location.search).get('noKeepAwake') === '1'\n  ) {\n    return;\n  }\n\n  setScreenAwakeMode({ enabled: true })\n    .then(() => {\n      // Restore normal sleep on page unload — only if the enable call succeeded\n      // (nothing to restore if it failed).\n      window.addEventListener(\n        'beforeunload',\n        () => {\n          setScreenAwakeMode({ enabled: false }).catch(() => {});\n        },\n        { once: true },\n      );\n    })\n    .catch((err) => {\n      // Swallow rejection so attach never breaks — some platforms/mock reject.\n      console.debug('[@ait-co/devtools] setScreenAwakeMode failed:', err);\n    });\n}\n","/**\n * @ait-co/devtools/in-app entry point.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n *\n * Phase 1 — gate + browser-side Chii target injection.\n * WebSocket relay, QR/paste UI, and AI-host MCP bin are later phases that\n * require real-device validation and are not included here.\n *\n * This thin entry reads `window.location` and calls the pure\n * {@link evaluateDebugGate} function. All testable logic lives in `./gate.ts`\n * and `./attach.ts`, not here.\n *\n * Layer A of the activation gate (build-time) is NOT enforced in this module.\n * It is the consumer's responsibility: the consumer wraps its\n * `import('@ait-co/devtools/in-app')` call site in `if (__DEBUG_BUILD__) { … }`\n * (see sdk-example `src/main.tsx`), where `__DEBUG_BUILD__` is a\n * consumer-build-time constant. A release consumer build folds that constant\n * to `false` and dead-code-eliminates this whole module. This package is\n * pre-built and ships with `__DEBUG_BUILD__` already resolved at devtools'\n * publish time, so it could never re-evaluate the consumer's build channel —\n * which is exactly why Layer A lives at the consumer guard, not here.\n */\n\nimport { evaluateDebugGate, type GateResult } from './gate.js';\n\nexport { deriveTargetScriptUrl, maybeAttach } from './attach.js';\nexport type { GateInput, GateResult, GateResultAttach, GateResultBlocked } from './gate.js';\nexport { evaluateDebugGate, isPrivateAppsHost, isTrycloudflareHost } from './gate.js';\n\n/**\n * Evaluates the runtime debug activation layers (B and C) against the current\n * page URL.\n *\n * Returns the gate result. Callers can check `result.attach` to decide whether\n * to proceed with debug surface attachment.\n *\n * This function reads `window.location` only — both the hostname (Layer B1\n * host allowlist) and the search params (Layers B2 and C). Layer A\n * (build-time) is enforced by the consumer's `if (__DEBUG_BUILD__)` guard\n * around the import site, not here — see the file-level comment. Consumers\n * call this with no arguments, so the Layer B1 host check is picked up with\n * no change at the call site.\n */\nexport function checkDebugGate(): GateResult {\n  return evaluateDebugGate({\n    hostname: window.location.hostname,\n    searchParams: new URLSearchParams(window.location.search),\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"sourcesContent":["/**\n * Runtime activation gate for the in-app debug surface.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"3-layer activation gate\". This is the pure gate decision; the Chii client,\n * WebSocket transport, MCP server, and CLI that consume it live in src/mcp/.\n *\n * This function evaluates the two RUNTIME layers, B and C. Layer A — the\n * build-time gate — is NOT evaluated here, and deliberately so: it is enforced\n * entirely by the consumer's `if (__DEBUG_BUILD__) { … }` guard around the\n * import site (see sdk-example `src/main.tsx`). `__DEBUG_BUILD__` is a\n * consumer-build-time constant; a release consumer build folds it to `false`\n * and dead-code-eliminates the whole import of `@ait-co/devtools/in-app`, so\n * this code is simply absent from release bundles. A pre-built npm package\n * cannot re-check that flag — it was already baked at devtools' own publish\n * time — so any `isDebugBuild` check inside this function would be permanently\n * `false` and could never pass. Layer A is the consumer guard; B and C are\n * here.\n *\n * Layer B has two parts:\n *   B1 — host allowlist: `hostname` must be a `*.private-apps.tossmini.com`\n *        subdomain (Toss dogfood entry) OR a `*.trycloudflare.com` host (env 2\n *        PWA dev tunnel). The Toss app serves dogfood / private mini-apps from\n *        a separate `private-apps` host; a production (`intoss://`) entry is\n *        served from `*.apps.tossmini.com` WITHOUT the `private-apps` segment.\n *        This is the security gate against a dogfood build that somehow lands\n *        on a production entry — see the comment on {@link isPrivateAppsHost}.\n *        The env 2 tunnel host is allowed because it has no production runtime\n *        (mock SDK, the developer's own dev server) — see {@link\n *        isTrycloudflareHost}.\n *   B2 — entry query: `_deploymentId` must be present and non-empty. Applies to\n *        the Toss path only; the env 2 tunnel has no deployed bundle, so B2 is\n *        skipped for `*.trycloudflare.com` hosts.\n *\n * Layer C — opt-in + relay + optional TOTP auth:\n *   C1 — opt-in:       `debug=1` must be present.\n *   C2 — relay URL:    `relay=<wss-url>` must be a valid `wss:` URL.\n *   C3 — TOTP auth:    When `verifyTotpCode` is provided (consumer injected the\n *                      baked secret at build time via `__DEBUG_TOTP_SECRET__`),\n *                      `at=<code>` is checked. Invalid or absent code → BLOCKED.\n *                      When no verifier is provided (TOTP disabled), `at` is\n *                      ignored (backward compatible).\n *\n * Security note on baked secrets:\n *   The TOTP secret baked in via `__DEBUG_TOTP_SECRET__` is present in the\n *   dogfood bundle and is extractable by a determined reverse engineer.\n *   The practical bar raised is: \"URL leak\" (Slack paste, QR screenshot) →\n *   blocked; \"URL + bundle extraction + live TOTP code\" → not blocked.\n *   This is the intended threat model. Do not overpromise on this guarantee.\n *\n * SECRET-HANDLING: `verifyTotpCode` is a black-box predicate. This module\n *   does NOT log the secret, any code value, or pass/fail details beyond the\n *   `'auth'` reason enum.\n *\n * Decision matrix (gate only runs in a debug build — Layer A already passed):\n *\n *   host        | _deploymentId | debug=1 | relay ok | TOTP ok* | result\n *   neither     | (any)         | (any)   | (any)    | (any)    | BLOCKED (host)\n *   private-apps| absent        | (any)   | (any)    | (any)    | BLOCKED (entry)\n *   private-apps| present       | absent  | (any)    | (any)    | BLOCKED (opt-in)\n *   private-apps| present       | present | invalid  | (any)    | BLOCKED (invalid-relay)\n *   private-apps| present       | present | valid    | fail*    | BLOCKED (auth)\n *   private-apps| present       | present | valid    | pass/n/a | ATTACH\n *   trycloudflare| (skipped)    | absent  | (any)    | (any)    | BLOCKED (opt-in)\n *   trycloudflare| (skipped)    | present | invalid  | (any)    | BLOCKED (invalid-relay)\n *   trycloudflare| (skipped)    | present | valid    | fail*    | BLOCKED (auth)\n *   trycloudflare| (skipped)    | present | valid    | pass/n/a | ATTACH\n *\n *   * \"TOTP ok\" column only applies when `verifyTotpCode` is provided.\n *     When no verifier is injected, TOTP check is skipped entirely.\n *   For trycloudflare (env 2 tunnel) hosts B1 is bypassed and B2 is skipped;\n *   C1/C2/C3 still apply identically. The ATTACH result carries\n *   `deploymentId: ''` for tunnel hosts.\n */\n\n/** Shape returned when the gate allows attachment. */\nexport interface GateResultAttach {\n  readonly attach: true;\n  /** The validated `wss:` relay URL from the `relay` query param. */\n  readonly relayUrl: string;\n  /** The deployment ID extracted from the `_deploymentId` query param. */\n  readonly deploymentId: string;\n}\n\n/** Shape returned when the gate blocks attachment, with a reason code. */\nexport interface GateResultBlocked {\n  readonly attach: false;\n  /**\n   * - `'host'`          Layer B1: `hostname` is not a `*.private-apps.tossmini.com` host.\n   * - `'entry'`         Layer B2: `_deploymentId` param is absent or empty.\n   * - `'opt-in'`        Layer C1: `debug=1` param is absent.\n   * - `'invalid-relay'` Layer C2: `relay` param is absent, empty, or not a `wss:` URL.\n   * - `'auth'`          Layer C3: TOTP `at=` code is absent, invalid, or expired\n   *                     (only when a `verifyTotpCode` predicate is injected).\n   *\n   * There is no `'build'` reason: Layer A is enforced by the consumer's\n   * `if (__DEBUG_BUILD__)` guard, not by this function.\n   *\n   * SECRET-HANDLING: `'auth'` is the only value surfaced for auth failures —\n   * no code value, expected value, or secret fragment is ever exposed.\n   */\n  readonly reason: 'host' | 'entry' | 'opt-in' | 'invalid-relay' | 'auth';\n}\n\nexport type GateResult = GateResultAttach | GateResultBlocked;\n\n/**\n * Input for {@link evaluateDebugGate}.\n *\n * All fields are explicit so the function is trivially testable without\n * touching `window`.\n */\nexport interface GateInput {\n  /**\n   * The host the page is served from — `window.location.hostname`.\n   *\n   * This is the Layer B1 security signal. Why hostname and not the entry\n   * scheme: the Toss SDK normalises `intoss-private://` to `intoss://` in\n   * `getSchemeUri()`, and `getOperationalEnvironment()` / `getWebViewType()`\n   * return the same value (`\"toss\"` / `\"partner\"`) for both dogfood and\n   * production entries — none of them distinguish a dogfood entry. The host\n   * does: a dogfood / private-apps entry is served from\n   * `*.private-apps.tossmini.com`, a production entry is not. This was\n   * confirmed live over CDP against mini-app 31146 (see spec open question 2).\n   */\n  readonly hostname: string;\n\n  /**\n   * The URL search params to inspect for gate signals (Layers B2 and C).\n   *\n   * Prefer `URLSearchParams` so callers can pass `new URLSearchParams(location.search)`\n   * without coupling the pure function to `window`.\n   */\n  readonly searchParams: URLSearchParams;\n\n  /**\n   * Optional TOTP code verifier for Layer C3 auth gate.\n   *\n   * When provided, `evaluateDebugGate` reads the `at` query param and passes\n   * it to this predicate. Return `true` to allow, `false` to block with\n   * `reason: 'auth'`.\n   *\n   * Inject via the consumer's build define, e.g.:\n   * ```ts\n   * // dogfood build entry — consumer's build injects __DEBUG_TOTP_SECRET__\n   * declare const __DEBUG_TOTP_SECRET__: string | undefined;\n   * const verifyTotpCode = typeof __DEBUG_TOTP_SECRET__ !== 'undefined'\n   *   ? (code: string) => verifyTotp(__DEBUG_TOTP_SECRET__, code)\n   *   : undefined;\n   * maybeAttach(evaluateDebugGate({ ...params, verifyTotpCode }));\n   * ```\n   *\n   * Security note: this predicate is a black-box from the gate's perspective.\n   * The gate only surfaces pass/fail and the `'auth'` reason code — no code\n   * value or secret fragment is ever logged or returned.\n   *\n   * When `undefined` (TOTP disabled), `at=` is silently ignored and the gate\n   * proceeds to ATTACH if all other layers pass.\n   */\n  readonly verifyTotpCode?: (code: string) => boolean;\n}\n\n/**\n * The host suffix the Toss app uses to serve dogfood / private mini-apps.\n *\n * A `intoss-private://` (dogfood) entry maps to a host such as\n * `aitc-sdk-example.private-apps.tossmini.com`. A production `intoss://`\n * entry is served from `*.apps.tossmini.com` — the `.private-apps.` segment\n * is absent. Confirmed live over CDP for mini-app 31146; the exact production\n * host is to be re-confirmed once 31146 passes review (spec open question 2).\n */\nconst PRIVATE_APPS_HOST_SUFFIX = '.private-apps.tossmini.com';\n\n/**\n * The host suffix Cloudflare quick-tunnels serve from — the env 2 (PWA) entry.\n * See {@link isTrycloudflareHost} for why this host kind bypasses Layer B1.\n */\nconst TRYCLOUDFLARE_HOST_SUFFIX = '.trycloudflare.com';\n\n/**\n * Returns whether `hostname` is a `*.private-apps.tossmini.com` subdomain —\n * the host the Toss app reserves for dogfood / private mini-app entries.\n *\n * The match is an exact suffix check, not a substring `.includes()`: a\n * substring test would also accept an attacker-controlled host like\n * `private-apps.tossmini.com.evil.example`, which ends in `.example`, not in\n * `.tossmini.com`. Requiring the string to END with the suffix closes that.\n * The leading `.` in the suffix also forces a real subdomain label, so a\n * bare `private-apps.tossmini.com` (no mini-app subdomain) does not match.\n */\nexport function isPrivateAppsHost(hostname: string): boolean {\n  return hostname.endsWith(PRIVATE_APPS_HOST_SUFFIX);\n}\n\n/**\n * The host suffix Cloudflare quick-tunnels use — the env 2 (PWA) entry.\n *\n * Env 2 serves the local Vite dev server through a `*.trycloudflare.com` quick\n * tunnel (`src/unplugin/tunnel.ts`). It has no Toss app, no `intoss-private://`\n * scheme, and — critically — no production runtime: the SDK is the devtools\n * mock, and the page is the developer's own dev build. The Layer B1 safety net\n * (which stops a dogfood build that lands on a Toss *production* host from\n * attaching) has nothing to protect against here, because env 2 has no\n * production host. So a trycloudflare host is allowed past B1 — but ONLY past\n * B1: the remaining layers (C1 opt-in, C2 relay, C3 TOTP) still apply, so a\n * leaked tunnel URL is still blocked by TOTP exactly as on the Toss path.\n *\n * The match is the same exact-suffix `endsWith` check as\n * {@link isPrivateAppsHost} — never a substring `.includes()`, which would\n * accept an attacker-controlled `evil.trycloudflare.com.example.com`. The\n * leading `.` forces a real subdomain label, so a bare `trycloudflare.com`\n * (no tunnel subdomain) does not match.\n */\nexport function isTrycloudflareHost(hostname: string): boolean {\n  return hostname.endsWith(TRYCLOUDFLARE_HOST_SUFFIX);\n}\n\n/**\n * Pure function that evaluates the runtime debug activation layers (B and C).\n *\n * Has no side effects. The input is explicit. Returns a discriminated union\n * so callers can pattern-match on `result.attach`.\n *\n * Layer A (build-time) is intentionally not evaluated here — see the file-level\n * comment. By the time this function runs, the consumer's `if (__DEBUG_BUILD__)`\n * guard has already passed; this function only decides B and C.\n *\n * @example\n * ```ts\n * const result = evaluateDebugGate({\n *   hostname: window.location.hostname,\n *   searchParams: new URLSearchParams(window.location.search),\n * });\n * if (result.attach) {\n *   // Proceed to load Chii client\n * }\n * ```\n */\nexport function evaluateDebugGate(input: GateInput): GateResult {\n  // Layer B1 — host allowlist (the security gate).\n  // Two host kinds are allowed past B1:\n  //   - Toss dogfood: `*.private-apps.tossmini.com`. A production `intoss://`\n  //     entry is served from `*.apps.tossmini.com` and is rejected here. This\n  //     is what stops a dogfood build that somehow reaches a production entry\n  //     from attaching: Layer A keeps debug code out of release bundles, and\n  //     this layer keeps a dogfood bundle that lands on a production host from\n  //     attaching even though its code is present.\n  //   - Env 2 PWA tunnel: `*.trycloudflare.com`. This is the developer's own\n  //     local dev server (mock SDK, no production runtime), so the\n  //     production-entry hazard B1 guards against cannot occur. It bypasses B1\n  //     but NOT the remaining layers — C1/C2/C3 (incl. TOTP) still apply, so a\n  //     leaked tunnel URL is blocked exactly as on the Toss path. See\n  //     {@link isTrycloudflareHost}.\n  const isTunnel = isTrycloudflareHost(input.hostname);\n  if (!isPrivateAppsHost(input.hostname) && !isTunnel) {\n    return { attach: false, reason: 'host' };\n  }\n\n  // Layer B2 — runtime entry query gate (Toss path only).\n  // `_deploymentId` must be present and non-empty. The `intoss-private://`\n  // scheme used for dogfood entries includes this param; general user entry\n  // paths do not. The env 2 tunnel has no deployed bundle and therefore no\n  // `_deploymentId` — B2 is skipped for it, and `deploymentId` is reported as\n  // the empty string on a tunnel attach (no consumer reads it; see attach.ts).\n  let deploymentId = '';\n  if (!isTunnel) {\n    deploymentId = input.searchParams.get('_deploymentId') ?? '';\n    if (deploymentId === '') {\n      return { attach: false, reason: 'entry' };\n    }\n  }\n\n  // Layer C — explicit opt-in gate.\n  // Require `debug=1` so that an operator who opens a dogfood URL by accident\n  // does not inadvertently trigger the debug surface.\n  const debugParam = input.searchParams.get('debug');\n  if (debugParam !== '1') {\n    return { attach: false, reason: 'opt-in' };\n  }\n\n  // Layer C continued — relay URL validation.\n  // `relay=<wss-url>` must be present and must use the `wss:` scheme.\n  // Plain `ws:` is rejected (no TLS). `http:`/`https:` are rejected.\n  const relayRaw = input.searchParams.get('relay') ?? '';\n  if (relayRaw === '') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  let relayUrl: URL;\n  try {\n    relayUrl = new URL(relayRaw);\n  } catch {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  if (relayUrl.protocol !== 'wss:') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  // Layer C3 — TOTP auth gate (fail-fast, only when a verifier is injected).\n  // The `at` query param carries the current TOTP code. Absent or invalid code\n  // → BLOCKED. When no verifier is provided (TOTP disabled), this check is\n  // skipped entirely for backward compatibility.\n  //\n  // SECRET-HANDLING: we do NOT log `code`, the verifier's result, or anything\n  // derived from the secret. Only the `'auth'` enum is surfaced on failure.\n  if (input.verifyTotpCode !== undefined) {\n    const code = input.searchParams.get('at') ?? '';\n    if (!input.verifyTotpCode(code)) {\n      return { attach: false, reason: 'auth' };\n    }\n  }\n\n  return { attach: true, relayUrl: relayUrl.href, deploymentId };\n}\n","/**\n * In-app Chii target injection for the debug attach flow.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"MCP attach\" topology section — Phase 1 browser-side implementation.\n *\n * This module bridges the 3-layer gate result to a Chii `target.js` script\n * injection. The Chii npm package is the relay SERVER — the in-app side is\n * a plain `<script src=\"…/target.js\">` pointing at the relay host. No chii\n * npm dependency is needed here.\n */\n\nimport { setScreenAwakeMode } from '@apps-in-toss/web-framework';\nimport { checkDebugGate, type GateResult } from './index.js';\n\n/**\n * Converts a validated `wss:` relay URL into the Chii `target.js` script URL.\n *\n * Scheme is mapped `wss:` → `https:`. Host and port are preserved.\n * Pathname is set to `/target.js` (or `/at/<code>/target.js` when a TOTP code\n * is given) regardless of the relay path. Query params and hash from the\n * relay URL are dropped — the target script URL is a static asset path on the\n * same host.\n *\n * TOTP path-prefix transport (issue #466): chii's stock `target.js` derives\n * its WS endpoint from the script `src` (`scriptEl.src.replace('target.js',\n * '')`), so embedding the current TOTP code in the script URL *path* is the\n * only way the phone-side WS upgrade can carry it — both the script fetch and\n * the derived `wss://<host>/at/<code>/target/<id>` dial inherit the prefix,\n * and the relay verifies + strips it before chii parses the URL. The\n * `window.ChiiServerUrl` + query alternative does NOT work: chii appends\n * `target/<id>` to the serverUrl string, which would land after a `?`.\n *\n * SECRET-HANDLING: `atCode` rides only inside the returned URL (the intended\n * transport — same exposure grade as the daemon client's `at=` query). It is\n * never logged here.\n *\n * @example\n * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')\n * // → 'https://abc.trycloudflare.com/target.js'\n *\n * deriveTargetScriptUrl('wss://h.example.com:9100/', '123456')\n * // → 'https://h.example.com:9100/at/123456/target.js'\n *\n * @param relayUrl - Validated `wss:` relay URL from the gate result.\n * @param atCode - Current TOTP code from the page URL's `at` query param, or\n *   `null`/`undefined`/`''` to keep the legacy un-prefixed URL.\n */\nexport function deriveTargetScriptUrl(relayUrl: string, atCode?: string | null): string {\n  const u = new URL(relayUrl);\n  u.protocol = 'https:';\n  u.pathname =\n    atCode !== undefined && atCode !== null && atCode !== ''\n      ? `/at/${encodeURIComponent(atCode)}/target.js`\n      : '/target.js';\n  u.search = '';\n  u.hash = '';\n  return u.toString();\n}\n\n/** Module-level guard against double-injection within a page lifecycle. */\nlet attached = false;\n\n/**\n * Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii\n * `target.js` script into `document.head`.\n *\n * Idempotent — calling more than once is safe. The second call is a no-op if\n * a script with the same `src` is already present in the document, and the\n * module-level `attached` flag prevents redundant DOM queries after the first\n * successful injection.\n *\n * Safe to call even if `document` is somehow unavailable (defensive boundary\n * guard — in practice this always runs in a real WebView).\n *\n * **keepAwake side effect**: on a successful attach, `setScreenAwakeMode({\n * enabled: true })` is called so the phone screen stays awake during the debug\n * session. A `beforeunload` handler restores normal sleep on page unload.\n * Opt out by adding `noKeepAwake=1` to the page URL query string — the check\n * reads `window.location.search` directly, consistent with other guards in\n * this file.\n *\n * @param gateResult - Optional pre-evaluated gate result for testability.\n *   Defaults to `checkDebugGate()` which reads the current page URL. Passing a\n *   custom value avoids the need to manipulate `window.location` in tests.\n */\nexport function maybeAttach(gateResult: GateResult = checkDebugGate()): void {\n  if (!gateResult.attach) {\n    console.debug(\n      `[@ait-co/devtools] debug attach skipped — gate blocked (reason: ${gateResult.reason})`,\n    );\n    // Defect 2: a wrong/expired TOTP code is the ONLY block reason that is a\n    // user-actionable failure inside a deliberate debug session — the operator\n    // scanned a QR expecting an attach. Surface it to the parent launcher shell\n    // so it can show a \"rescan the QR\" banner. Every other reason\n    // ('host'/'entry'/'opt-in'/'invalid-relay') fires on ordinary non-debug page\n    // loads and must stay silent to avoid a banner on every plain pageview.\n    // SECRET-HANDLING: the message carries ONLY the 'auth' reason enum — never\n    // the code, secret, host, or relay URL.\n    if (gateResult.reason === 'auth' && typeof window !== 'undefined' && window.parent !== window) {\n      window.parent.postMessage({ type: 'ait:debug-attach-blocked', reason: 'auth' }, '*');\n    }\n    return;\n  }\n\n  // Guard against double-injection across repeated calls.\n  if (attached) {\n    return;\n  }\n\n  // Defensive: if document is not available (unusual, but possible in some\n  // SSR-adjacent edge cases), bail silently rather than throwing.\n  if (typeof document === 'undefined') {\n    return;\n  }\n\n  // TOTP path-prefix transport (issue #466): forward the page URL's `at` code\n  // (delivered by the dashboard QR → launcher deep-link) into the target\n  // script URL so the WS upgrade derived from it passes the relay's TOTP\n  // gate. Absent `at` → legacy un-prefixed URL (relay without TOTP, tests).\n  // Read window.location.search directly, consistent with other guards in\n  // this file. SECRET-HANDLING: the code is never logged; it rides only in\n  // the script src (the intended transport).\n  //\n  // TTL note: the code is verified within the relay's ±1-step window (90 s),\n  // so the initial attach always fits. A much-later automatic reconnect by\n  // target.js reuses the stale prefix and is rejected (401) — by design under\n  // the URL-leak threat model; recover by rescanning the QR (the relay-side\n  // auth-reject counter from issue #467 makes this visible).\n  const atCode =\n    typeof window !== 'undefined' ? new URLSearchParams(window.location.search).get('at') : null;\n\n  const src = deriveTargetScriptUrl(gateResult.relayUrl, atCode);\n\n  // Also guard against a script with the same src already in the DOM\n  // (e.g. injected by a different code path or a page reload within SPA).\n  const existing = document.querySelector<HTMLScriptElement>(`script[src=\"${src}\"]`);\n  if (existing !== null) {\n    attached = true;\n    return;\n  }\n\n  const script = document.createElement('script');\n  script.src = src;\n  script.async = true;\n  (document.head ?? document.documentElement).appendChild(script);\n\n  attached = true;\n\n  // keepAwake — keep phone screen on during the debug session.\n  // Opt out via noKeepAwake=1 in the URL (consistent with direct window reads\n  // used throughout this file).\n  if (\n    typeof window !== 'undefined' &&\n    new URLSearchParams(window.location.search).get('noKeepAwake') === '1'\n  ) {\n    return;\n  }\n\n  setScreenAwakeMode({ enabled: true })\n    .then(() => {\n      // Restore normal sleep on page unload — only if the enable call succeeded\n      // (nothing to restore if it failed).\n      window.addEventListener(\n        'beforeunload',\n        () => {\n          setScreenAwakeMode({ enabled: false }).catch(() => {});\n        },\n        { once: true },\n      );\n    })\n    .catch((err) => {\n      // Swallow rejection so attach never breaks — some platforms/mock reject.\n      console.debug('[@ait-co/devtools] setScreenAwakeMode failed:', err);\n    });\n}\n","/**\n * @ait-co/devtools/in-app entry point.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n *\n * Phase 1 — gate + browser-side Chii target injection.\n * WebSocket relay, QR/paste UI, and AI-host MCP bin are later phases that\n * require real-device validation and are not included here.\n *\n * This thin entry reads `window.location` and calls the pure\n * {@link evaluateDebugGate} function. All testable logic lives in `./gate.ts`\n * and `./attach.ts`, not here.\n *\n * Layer A of the activation gate (build-time) is NOT enforced in this module.\n * It is the consumer's responsibility: the consumer wraps its\n * `import('@ait-co/devtools/in-app')` call site in `if (__DEBUG_BUILD__) { … }`\n * (see sdk-example `src/main.tsx`), where `__DEBUG_BUILD__` is a\n * consumer-build-time constant. A release consumer build folds that constant\n * to `false` and dead-code-eliminates this whole module. This package is\n * pre-built and ships with `__DEBUG_BUILD__` already resolved at devtools'\n * publish time, so it could never re-evaluate the consumer's build channel —\n * which is exactly why Layer A lives at the consumer guard, not here.\n */\n\nimport { evaluateDebugGate, type GateResult } from './gate.js';\n\nexport { deriveTargetScriptUrl, maybeAttach } from './attach.js';\nexport type { GateInput, GateResult, GateResultAttach, GateResultBlocked } from './gate.js';\nexport { evaluateDebugGate, isPrivateAppsHost, isTrycloudflareHost } from './gate.js';\n\n/**\n * Evaluates the runtime debug activation layers (B and C) against the current\n * page URL.\n *\n * Returns the gate result. Callers can check `result.attach` to decide whether\n * to proceed with debug surface attachment.\n *\n * This function reads `window.location` only — both the hostname (Layer B1\n * host allowlist) and the search params (Layers B2 and C). Layer A\n * (build-time) is enforced by the consumer's `if (__DEBUG_BUILD__)` guard\n * around the import site, not here — see the file-level comment. Consumers\n * call this with no arguments, so the Layer B1 host check is picked up with\n * no change at the call site.\n */\nexport function checkDebugGate(): GateResult {\n  return evaluateDebugGate({\n    hostname: window.location.hostname,\n    searchParams: new URLSearchParams(window.location.search),\n  });\n}\n"],"mappings":"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"}