@ait-co/devtools 0.1.31 → 0.1.33

package/dist/mcp/cli.js

@@ -8,7 +8,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { EventEmitter } from "node:events";
 import { WebSocket } from "ws";
 import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { Tunnel, bin, install } from "cloudflared";
 import qrcode from "qrcode-terminal";
 //#region src/mcp/ait-chii-source.ts
@@ -239,6 +239,23 @@ var ChiiCdpConnection = class {
 *
 * 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 an HTTP upgrade
+*   listener on the server BEFORE calling `chii.start({server})`. Node's
+*   `http.Server` allows multiple 'upgrade' listeners; the first to call
+*   `socket.destroy()` wins. Invalid auth → 401 + destroy (chii never sees
+*   the connection). Valid auth → return without side-effect (chii handles it).
+*
+* 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() {
@@ -250,7 +267,15 @@ function loadChiiServer() {
 async function startChiiRelay(options = {}) {
 	const port = options.port ?? 9100;
 	const host = options.host ?? "127.0.0.1";
+	const { verifyAuth } = options;
 	const httpServer = createServer();
+	if (verifyAuth) httpServer.on("upgrade", (req, socket) => {
+		if (!verifyAuth(req)) {
+			socket.write("HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n");
+			socket.destroy();
+			return;
+		}
+	});
 	await loadChiiServer().start({
 		server: httpServer,
 		domain: `${host}:${port}`,
@@ -278,21 +303,25 @@ function stripExisting(query, key) {
 	return query.split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== key).join("&");
 }
 /**
-* Splices `debug=1` and `relay=<wssUrl>` into a scheme URL's query string,
-* preserving everything else (scheme, authority, path, hash, and the existing
-* `_deploymentId` param). If `debug` or `relay` is already present it is
-* replaced so the helper is idempotent.
+* Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a
+* scheme URL's query string, preserving everything else (scheme, authority,
+* path, hash, and the existing `_deploymentId` param). If any of the spliced
+* params is already present it is replaced so the helper is idempotent.
 *
 * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed
 *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B
 *   of the gate); this helper does not invent one.
 * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the
 *   running debug MCP server's quick tunnel.
-* @returns The same URL with `debug=1&relay=<encoded wssUrl>` appended.
+* @param totpCode - Optional current TOTP code (6 digits). When provided, it
+*   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates
+*   every 30 s. Pass `undefined` or omit when TOTP is disabled.
+* @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`
+*   appended.
 * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so
 *   producing such a link would be a silent dead end).
 */
-function buildDeepLinkAttachUrl(schemeUrl, wssUrl) {
+function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 	let relay;
 	try {
 		relay = new URL(wssUrl);
@@ -307,6 +336,8 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl) {
 	const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);
 	let query = queryIndex === -1 ? "" : beforeHash.slice(queryIndex + 1);
 	const appended = [["debug", "1"], ["relay", wssUrl]];
+	if (totpCode !== void 0 && totpCode !== "") appended.push(["at", totpCode]);
+	query = stripExisting(query, "at");
 	for (const [key] of appended) query = stripExisting(query, key);
 	for (const [key, value] of appended) {
 		const pair = `${key}=${encodeURIComponent(value)}`;
@@ -384,6 +415,15 @@ const DEBUG_TOOL_DEFINITIONS = [
 			required: []
 		}
 	},
+	{
+		name: "measure_safe_area",
+		description: "Runs a safe-area probe on the attached mini-app page via Runtime.evaluate and returns normalized safe-area insets, viewport geometry, device pixel ratio, and User-Agent. Read-only — does not modify page state. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires the relay to be attached — call list_pages first.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
 	{
 		name: "AIT.getSdkCallHistory",
 		description: "Returns the recent Apps In Toss SDK call trace (method, args, result/error, timestamp) that raw CDP cannot observe. Read-only. Use to confirm an SDK call fired and how it resolved (e.g. a saveBase64Data permission regression).",
@@ -498,6 +538,45 @@ async function takeScreenshot(connection) {
 		mimeType: "image/png"
 	};
 }
+`
+(function() {
+  var el = document.createElement('div');
+  el.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;visibility:hidden;' +
+    'padding-top:env(safe-area-inset-top,0px);' +
+    'padding-right:env(safe-area-inset-right,0px);' +
+    'padding-bottom:env(safe-area-inset-bottom,0px);' +
+    'padding-left:env(safe-area-inset-left,0px)';
+  document.documentElement.appendChild(el);
+  var cs = window.getComputedStyle(el);
+  var cssEnv = {
+    top: parseFloat(cs.paddingTop) || 0,
+    right: parseFloat(cs.paddingRight) || 0,
+    bottom: parseFloat(cs.paddingBottom) || 0,
+    left: parseFloat(cs.paddingLeft) || 0
+  };
+  document.documentElement.removeChild(el);
+  var sdkInsets = null;
+  try {
+    if (typeof SafeAreaInsets !== 'undefined' && SafeAreaInsets && typeof SafeAreaInsets.get === 'function') {
+      sdkInsets = SafeAreaInsets.get();
+    }
+  } catch(_) {}
+  var navBarHeight = null;
+  try {
+    var nb = document.querySelector('.ait-navbar');
+    if (nb) navBarHeight = nb.getBoundingClientRect().height;
+  } catch(_) {}
+  return JSON.stringify({
+    cssEnv: cssEnv,
+    sdkInsets: sdkInsets,
+    navBarHeight: navBarHeight,
+    innerWidth: window.innerWidth,
+    innerHeight: window.innerHeight,
+    devicePixelRatio: window.devicePixelRatio,
+    userAgent: navigator.userAgent
+  });
+})()
+`.trim();
 /** Set of tool names served by the AIT source rather than the CDP connection. */
 const AIT_TOOL_NAMES = new Set([
 	"AIT.getSdkCallHistory",
@@ -521,16 +600,97 @@ function getOperationalEnvironment(source) {
 	return source.get("AIT.getOperationalEnvironment");
 }
 //#endregion
+//#region src/mcp/totp.ts
+/**
+* RFC 6238 TOTP implementation (Node.js, node:crypto only).
+*
+* External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used
+* to keep the dependency surface minimal. This hand-roll is ~30 lines and
+* covers exactly what relay-side auth needs.
+*
+* Algorithm summary (RFC 6238 + RFC 4226):
+*   T  = floor(now / 30)          — 30-second time step counter
+*   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)
+*   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)
+*   offset = MAC[19] & 0x0f
+*   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits
+*
+* Security note (keep this comment accurate):
+*   The baked-in secret in a dogfood build is extractable from the bundle by a
+*   determined reverse engineer. This mechanism raises the bar from
+*   "anyone with the URL" to "URL + bundle extraction + live TOTP calculation".
+*   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are
+*   blocked; deliberate reverse engineering is not. See threat model in
+*   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.
+*
+* SECRET-HANDLING: secret values and computed codes MUST NOT appear in any
+* log, error message, or string visible outside this module. Only boolean
+* pass/fail and reason enum values are safe to surface.
+*/
+/** Time step window in seconds (RFC 6238 default). */
+const TIME_STEP = 30;
+/** Number of digits in the generated code. */
+const DIGITS = 6;
+/**
+* Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-
+* clock time.
+*
+* @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32
+*   bytes). Must be the output of `generateAttachToken()` or compatible.
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @returns A zero-padded 6-digit decimal string, e.g. `"042193"`.
+*/
+function generateTotp(secret, when = Date.now()) {
+	const key = Buffer.from(secret, "hex");
+	const counter = Math.max(0, Math.floor(when / 1e3 / TIME_STEP));
+	const counterBuf = Buffer.alloc(8);
+	const hi = Math.floor(counter / 4294967296);
+	const lo = counter >>> 0;
+	counterBuf.writeUInt32BE(hi, 0);
+	counterBuf.writeUInt32BE(lo, 4);
+	const mac = createHmac("sha1", key).update(counterBuf).digest();
+	const offset = mac[19] & 15;
+	return (((mac[offset] & 127) << 24 | (mac[offset + 1] & 255) << 16 | (mac[offset + 2] & 255) << 8 | mac[offset + 3] & 255) % 10 ** DIGITS).toString().padStart(DIGITS, "0");
+}
+/**
+* Verifies a TOTP code against the secret, accepting ±`skew` time steps to
+* tolerate clock drift between the relay host and the client device.
+*
+* Uses `timingSafeEqual` for constant-time comparison to prevent timing
+* side-channel attacks.
+*
+* @param secret - Hex-encoded shared secret.
+* @param code - The 6-digit code to verify (string or numeric).
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @param skew - Number of adjacent steps to accept on either side. Default 1
+*   (accepts T-1, T, T+1 — a 90-second acceptance window).
+* @returns `true` if the code matches any accepted step, `false` otherwise.
+*/
+function verifyTotp(secret, code, when = Date.now(), skew = 1) {
+	const normalised = String(code).padStart(DIGITS, "0");
+	if (normalised.length !== DIGITS || !/^\d{6}$/.test(normalised)) return false;
+	const candidateBuf = Buffer.from(normalised, "utf8");
+	for (let delta = -skew; delta <= skew; delta++) {
+		const expected = generateTotp(secret, when + delta * TIME_STEP * 1e3);
+		if (timingSafeEqual(Buffer.from(expected, "utf8"), candidateBuf)) return true;
+	}
+	return false;
+}
+//#endregion
 //#region src/mcp/tunnel.ts
 /**
 * cloudflared quick tunnel + attach banner for the debug-mode MCP server.
 *
 * On spawn, the debug server opens an accountless `*.trycloudflare.com` quick
 * tunnel to the local Chii relay so the phone can attach over a public wss URL,
-* then prints that URL + an attach token + an ASCII QR to the terminal. The
-* phone scans the QR (or pastes the URL) to attach; the in-app side passes the
-* token back. The token is generated + displayed as a pairing hint; relay-side
-* validation (ACL enforcement) is a later phase.
+* then prints an ASCII QR + attach instructions. When TOTP auth is enabled
+* (`AIT_DEBUG_TOTP_SECRET` is set), the QR encodes only the base relay URL —
+* the TOTP code (`at=`) is NOT included because it rotates every 30 s and
+* would be stale by the time a human scans. The in-app deep-link builder
+* splices the live code at attach time.
+*
+* SECRET-HANDLING: The TOTP secret and computed code values MUST NOT appear
+* in any output from this module.
 *
 * Node-only: spawns the cloudflared binary and writes to stdout/stderr.
 */
@@ -580,22 +740,31 @@ async function startQuickTunnel(localPort) {
 		}
 	};
 }
-/** Renders the attach banner (URL + token + ASCII QR) as a string. */
+/**
+* Renders the attach banner (relay URL + ASCII QR) as a string.
+*
+* The QR encodes the base `wssUrl` only. When `totpEnabled` is true, a note
+* is added that attach URLs generated by `build_attach_url` will include a
+* live TOTP code (`at=`) appended at call time.
+*
+* SECRET-HANDLING: no secret value, TOTP code, or intermediate value is
+* included in this output.
+*/
 async function renderAttachBanner(input) {
-	const payload = `${input.wssUrl}?token=${input.token}`;
 	const qr = await new Promise((resolve) => {
-		qrcode.generate(payload, { small: true }, (rendered) => resolve(rendered));
+		qrcode.generate(input.wssUrl, { small: true }, (rendered) => resolve(rendered));
 	});
+	const authNote = input.totpEnabled ? "  auth:          TOTP enabled — attach URLs include a rotating code (at=)." : "  auth:          none (set AIT_DEBUG_TOTP_SECRET to enable TOTP).";
 	return [
 		"",
 		"AIT debug — attach a mini-app to this session",
 		"",
 		`  relay (wss):   ${input.wssUrl}`,
-		`  attach token:  ${input.token}`,
-		`  (token is a pairing hint — relay-side validation lands in a later phase)`,
+		authNote,
 		"",
-		"  Open the dogfood mini-app with ?debug=1, then scan the QR",
-		"  (or paste the relay URL + token in the in-app attach form):",
+		"  Use build_attach_url to generate a deep link with the current TOTP code.",
+		"  Scan the QR to locate the relay (open the dogfood URL separately with",
+		"  ?debug=1&relay=<wss>&at=<code> or use the build_attach_url tool):",
 		"",
 		qr
 	].join("\n");
@@ -635,7 +804,7 @@ function createDebugServer(deps) {
 	const { connection, aitSource, getTunnelStatus } = deps;
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.31"
+		version: "0.1.33"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEBUG_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -734,21 +903,49 @@ function errorResult(err, name) {
 	};
 }
 /**
+* Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a
+* `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.
+*
+* The predicate checks the `at` query parameter against the current and
+* adjacent TOTP time steps (±1 skew) using `verifyTotp`.
+*
+* Returns `undefined` when the env var is not set — callers treat that as
+* "auth disabled" (no predicate registered on the relay).
+*
+* SECRET-HANDLING: The secret value read from env is captured in a closure and
+* is NEVER written to any log, error message, or process output.
+*/
+function buildRelayVerifyAuth() {
+	const secret = process.env.AIT_DEBUG_TOTP_SECRET;
+	if (!secret) return void 0;
+	return (req) => {
+		const rawUrl = req.url ?? "";
+		const qIndex = rawUrl.indexOf("?");
+		const queryStr = qIndex === -1 ? "" : rawUrl.slice(qIndex + 1);
+		return verifyTotp(secret, new URLSearchParams(queryStr).get("at") ?? "");
+	};
+}
+/**
 * Boots the live debug stack and serves it over stdio:
-*   1. start the Chii relay,
+*   1. start the Chii relay (with TOTP auth if AIT_DEBUG_TOTP_SECRET is set),
 *   2. open a cloudflared quick tunnel to it,
-*   3. print QR + secret token,
+*   3. print relay URL + attach instructions,
 *   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
 */
 async function runDebugServer(options = {}) {
 	const relayPort = options.relayPort ?? 9100;
-	const relay = await startChiiRelay({ port: relayPort });
+	const verifyAuth = buildRelayVerifyAuth();
+	const totpEnabled = verifyAuth !== void 0;
+	const relay = await startChiiRelay({
+		port: relayPort,
+		verifyAuth
+	});
 	let tunnel = null;
 	let tunnelStatus = {
 		up: false,
 		wssUrl: null
 	};
-	const token = generateAttachToken();
+	generateAttachToken();
 	try {
 		tunnel = await startQuickTunnel(relayPort);
 		tunnelStatus = {
@@ -757,7 +954,7 @@ async function runDebugServer(options = {}) {
 		};
 		await printAttachBanner({
 			wssUrl: tunnel.wssUrl,
-			token
+			totpEnabled
 		});
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
@@ -809,7 +1006,10 @@ var HttpAitSource = class {
 					sdkVersion: typeof state.appVersion === "string" ? state.appVersion : null
 				};
 			}
-			case "AIT.getSdkCallHistory": return { calls: [] };
+			case "AIT.getSdkCallHistory": {
+				const raw = (await this.fetchState()).sdkCallLog;
+				return { calls: Array.isArray(raw) ? raw : [] };
+			}
 			default: throw new Error(`Unknown AIT method: ${String(method)}`);
 		}
 	}
@@ -897,7 +1097,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.31"
+		version: "0.1.33"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {