@ait-co/devtools 0.1.54 → 0.1.56

package/dist/totp-BkKP4m8H.cjs

@@ -0,0 +1,185 @@
+let node_crypto = require("node:crypto");
+//#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 = (0, node_crypto.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 ((0, node_crypto.timingSafeEqual)(Buffer.from(expected, "utf8"), candidateBuf)) return true;
+	}
+	return false;
+}
+/**
+* Minimum length (in hex characters) accepted for `AIT_DEBUG_TOTP_SECRET`.
+*
+* The secret is hex-encoded (see {@link generateTotp} — `Buffer.from(secret,
+* 'hex')`). 32 hex chars = 16 bytes = 128 bits, the floor for an HMAC-SHA1 key
+* we are willing to gate a public relay behind. `generateAttachToken()` emits
+* 64 hex chars (32 bytes), comfortably above this bar.
+*/
+const MIN_SECRET_HEX_CHARS = 32;
+/** Hex string: one or more hex digits, case-insensitive (RFC 4648 base16). */
+const HEX_RE = /^[0-9a-fA-F]+$/;
+/**
+* Human-facing guidance printed when {@link assertRelayAuthConfigured} fails.
+*
+* SECRET-HANDLING: this message states only the REQUIREMENT (≥32 hex chars) and
+* how to mint one. It NEVER echoes the configured value, its length, or any
+* fragment derived from it — see {@link assertRelayAuthConfigured}.
+*
+* Note on encoding: the secret is hex (base16), not base32 — `generateTotp`
+* decodes it with `Buffer.from(secret, 'hex')`. A base32 string would be
+* silently mis-decoded and every TOTP code would fail to match, so the minting
+* command emits hex.
+*/
+const RELAY_AUTH_SECRET_MISSING_MESSAGE = [
+	"[ait-debug] AIT_DEBUG_TOTP_SECRET이 필수입니다. 32자 이상 16진수(hex) 문자열을 설정하세요.",
+	"발급: openssl rand -hex 32",
+	"자세히: https://docs.aitc.dev/guides/relay-auth-totp"
+].join("\n");
+/**
+* Whether `secret` is a well-formed relay-auth TOTP secret: a hex string of at
+* least {@link MIN_SECRET_HEX_CHARS} characters with an even length (an odd
+* length would have its trailing nibble silently dropped by `Buffer.from(...,
+* 'hex')`, weakening the key without warning).
+*
+* Pure predicate so callers can test the validation independently of the
+* fail-fast side effect in {@link assertRelayAuthConfigured}.
+*
+* SECRET-HANDLING: returns only a boolean — the input value is never returned,
+* logged, or echoed.
+*/
+function isValidRelayAuthSecret(secret) {
+	if (secret === void 0 || secret === "") return false;
+	if (secret.length < MIN_SECRET_HEX_CHARS) return false;
+	if (secret.length % 2 !== 0) return false;
+	return HEX_RE.test(secret);
+}
+/**
+* Fail-fast guard enforcing that a relay-auth TOTP secret is configured before
+* a public-internet-exposed relay is booted (issue #250).
+*
+* Relay-auth (the §4 Layer C TOTP gate) is the only fail-fast layer that closes
+* the real gap: a leaked `wss://…trycloudflare.com` URL otherwise lets a third
+* party attach a debugger to a dogfood/live mini-app. Without a secret the relay
+* comes up unauthenticated, so this guard is called at every relay-boot site —
+* `bootRelayFamily` (intoss env 3/4) and `bootExternalRelayFamily` (env-2 PWA),
+* both eager and lazy. Local-only sessions never boot a relay and so never reach
+* this guard, matching the issue's exemption for non-relay debugging.
+*
+* Throws when the secret is unset, empty, too short, or not a valid hex string.
+* The thrown message is the bin entry's fatal stderr (see `cli.ts` `main().catch`)
+* — the same fatal model as the missing-`AIT_RELAY_BASE_URL` path.
+*
+* SECRET-HANDLING: the env value is read once, passed ONLY to the boolean
+* predicate, and never logged. The thrown message names the requirement, never
+* the value, its length, or any derived fragment.
+*
+* @param env - Environment to read from. Defaults to `process.env`; injectable
+*   for tests so they never mutate the real process environment.
+*/
+function assertRelayAuthConfigured(env = process.env) {
+	if (!isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) throw new Error(RELAY_AUTH_SECRET_MISSING_MESSAGE);
+}
+/**
+* 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 {@link verifyTotp}.
+*
+* Returns `undefined` when the env var is not set — callers treat that as
+* "auth disabled" (no predicate registered on the relay). Note that since
+* issue #250 the secret is MANDATORY at every relay-boot site (enforced by
+* {@link assertRelayAuthConfigured} BEFORE the relay starts), so in production
+* this never returns `undefined` for a relay that actually boots; the
+* `undefined` branch only matters for the no-relay local path and tests.
+*
+* Lives here (not in the MCP server) so the unplugin's env-2 relay can wire the
+* same gate without importing the heavy MCP server module graph. Re-exported
+* from `debug-server.ts` for back-compat.
+*
+* 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(env = process.env) {
+	const secret = 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") ?? "");
+	};
+}
+//#endregion
+exports.assertRelayAuthConfigured = assertRelayAuthConfigured;
+exports.buildRelayVerifyAuth = buildRelayVerifyAuth;
+
+//# sourceMappingURL=totp-BkKP4m8H.cjs.map

package/dist/totp-BkKP4m8H.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-BkKP4m8H.cjs","names":[],"sources":["../src/mcp/totp.ts"],"sourcesContent":["/**\n * RFC 6238 TOTP implementation (Node.js, node:crypto only).\n *\n * External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used\n * to keep the dependency surface minimal. This hand-roll is ~30 lines and\n * covers exactly what relay-side auth needs.\n *\n * Algorithm summary (RFC 6238 + RFC 4226):\n *   T  = floor(now / 30)          — 30-second time step counter\n *   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)\n *   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)\n *   offset = MAC[19] & 0x0f\n *   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits\n *\n * Security note (keep this comment accurate):\n *   The baked-in secret in a dogfood build is extractable from the bundle by a\n *   determined reverse engineer. This mechanism raises the bar from\n *   \"anyone with the URL\" to \"URL + bundle extraction + live TOTP calculation\".\n *   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are\n *   blocked; deliberate reverse engineering is not. See threat model in\n *   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.\n *\n * SECRET-HANDLING: secret values and computed codes MUST NOT appear in any\n * log, error message, or string visible outside this module. Only boolean\n * pass/fail and reason enum values are safe to surface.\n */\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\n\n/** Time step window in seconds (RFC 6238 default). */\nconst TIME_STEP = 30;\n\n/** Number of digits in the generated code. */\nconst DIGITS = 6;\n\n/**\n * Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-\n * clock time.\n *\n * @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32\n *   bytes). Must be the output of `generateAttachToken()` or compatible.\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @returns A zero-padded 6-digit decimal string, e.g. `\"042193\"`.\n */\nexport function generateTotp(secret: string, when: number = Date.now()): string {\n  const key = Buffer.from(secret, 'hex');\n  // Clamp to 0 so negative timestamps (e.g. in ±skew checks near epoch) do not\n  // produce a negative counter, which would cause writeUInt32BE to throw.\n  const counter = Math.max(0, Math.floor(when / 1000 / TIME_STEP));\n\n  // Encode counter as 8-byte big-endian unsigned integer.\n  const counterBuf = Buffer.alloc(8);\n  // JavaScript numbers are safe integers up to 2^53; counter is ~7.5×10^10 at\n  // year 9999 — well within safe range so standard bitwise ops are fine.\n  const hi = Math.floor(counter / 0x100000000);\n  const lo = counter >>> 0;\n  counterBuf.writeUInt32BE(hi, 0);\n  counterBuf.writeUInt32BE(lo, 4);\n\n  const mac = createHmac('sha1', key).update(counterBuf).digest();\n\n  // Dynamic truncation (RFC 4226 §5.4).\n  const offset = mac[19] & 0x0f;\n  const binCode =\n    ((mac[offset] & 0x7f) << 24) |\n    ((mac[offset + 1] & 0xff) << 16) |\n    ((mac[offset + 2] & 0xff) << 8) |\n    (mac[offset + 3] & 0xff);\n\n  const otp = binCode % 10 ** DIGITS;\n  return otp.toString().padStart(DIGITS, '0');\n}\n\n/**\n * Verifies a TOTP code against the secret, accepting ±`skew` time steps to\n * tolerate clock drift between the relay host and the client device.\n *\n * Uses `timingSafeEqual` for constant-time comparison to prevent timing\n * side-channel attacks.\n *\n * @param secret - Hex-encoded shared secret.\n * @param code - The 6-digit code to verify (string or numeric).\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @param skew - Number of adjacent steps to accept on either side. Default 1\n *   (accepts T-1, T, T+1 — a 90-second acceptance window).\n * @returns `true` if the code matches any accepted step, `false` otherwise.\n */\nexport function verifyTotp(\n  secret: string,\n  code: string,\n  when: number = Date.now(),\n  skew: number = 1,\n): boolean {\n  const normalised = String(code).padStart(DIGITS, '0');\n  if (normalised.length !== DIGITS || !/^\\d{6}$/.test(normalised)) {\n    return false;\n  }\n\n  const candidateBuf = Buffer.from(normalised, 'utf8');\n\n  for (let delta = -skew; delta <= skew; delta++) {\n    const stepWhen = when + delta * TIME_STEP * 1000;\n    const expected = generateTotp(secret, stepWhen);\n    const expectedBuf = Buffer.from(expected, 'utf8');\n    if (timingSafeEqual(expectedBuf, candidateBuf)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Minimum length (in hex characters) accepted for `AIT_DEBUG_TOTP_SECRET`.\n *\n * The secret is hex-encoded (see {@link generateTotp} — `Buffer.from(secret,\n * 'hex')`). 32 hex chars = 16 bytes = 128 bits, the floor for an HMAC-SHA1 key\n * we are willing to gate a public relay behind. `generateAttachToken()` emits\n * 64 hex chars (32 bytes), comfortably above this bar.\n */\nconst MIN_SECRET_HEX_CHARS = 32;\n\n/** Hex string: one or more hex digits, case-insensitive (RFC 4648 base16). */\nconst HEX_RE = /^[0-9a-fA-F]+$/;\n\n/**\n * Human-facing guidance printed when {@link assertRelayAuthConfigured} fails.\n *\n * SECRET-HANDLING: this message states only the REQUIREMENT (≥32 hex chars) and\n * how to mint one. It NEVER echoes the configured value, its length, or any\n * fragment derived from it — see {@link assertRelayAuthConfigured}.\n *\n * Note on encoding: the secret is hex (base16), not base32 — `generateTotp`\n * decodes it with `Buffer.from(secret, 'hex')`. A base32 string would be\n * silently mis-decoded and every TOTP code would fail to match, so the minting\n * command emits hex.\n */\nexport const RELAY_AUTH_SECRET_MISSING_MESSAGE = [\n  '[ait-debug] AIT_DEBUG_TOTP_SECRET이 필수입니다. 32자 이상 16진수(hex) 문자열을 설정하세요.',\n  '발급: openssl rand -hex 32',\n  '자세히: https://docs.aitc.dev/guides/relay-auth-totp',\n].join('\\n');\n\n/**\n * Whether `secret` is a well-formed relay-auth TOTP secret: a hex string of at\n * least {@link MIN_SECRET_HEX_CHARS} characters with an even length (an odd\n * length would have its trailing nibble silently dropped by `Buffer.from(...,\n * 'hex')`, weakening the key without warning).\n *\n * Pure predicate so callers can test the validation independently of the\n * fail-fast side effect in {@link assertRelayAuthConfigured}.\n *\n * SECRET-HANDLING: returns only a boolean — the input value is never returned,\n * logged, or echoed.\n */\nexport function isValidRelayAuthSecret(secret: string | undefined): secret is string {\n  if (secret === undefined || secret === '') return false;\n  if (secret.length < MIN_SECRET_HEX_CHARS) return false;\n  if (secret.length % 2 !== 0) return false;\n  return HEX_RE.test(secret);\n}\n\n/**\n * Fail-fast guard enforcing that a relay-auth TOTP secret is configured before\n * a public-internet-exposed relay is booted (issue #250).\n *\n * Relay-auth (the §4 Layer C TOTP gate) is the only fail-fast layer that closes\n * the real gap: a leaked `wss://…trycloudflare.com` URL otherwise lets a third\n * party attach a debugger to a dogfood/live mini-app. Without a secret the relay\n * comes up unauthenticated, so this guard is called at every relay-boot site —\n * `bootRelayFamily` (intoss env 3/4) and `bootExternalRelayFamily` (env-2 PWA),\n * both eager and lazy. Local-only sessions never boot a relay and so never reach\n * this guard, matching the issue's exemption for non-relay debugging.\n *\n * Throws when the secret is unset, empty, too short, or not a valid hex string.\n * The thrown message is the bin entry's fatal stderr (see `cli.ts` `main().catch`)\n * — the same fatal model as the missing-`AIT_RELAY_BASE_URL` path.\n *\n * SECRET-HANDLING: the env value is read once, passed ONLY to the boolean\n * predicate, and never logged. The thrown message names the requirement, never\n * the value, its length, or any derived fragment.\n *\n * @param env - Environment to read from. Defaults to `process.env`; injectable\n *   for tests so they never mutate the real process environment.\n */\nexport function assertRelayAuthConfigured(env: NodeJS.ProcessEnv = process.env): void {\n  if (!isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) {\n    throw new Error(RELAY_AUTH_SECRET_MISSING_MESSAGE);\n  }\n}\n\n/**\n * Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a\n * `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.\n *\n * The predicate checks the `at` query parameter against the current and\n * adjacent TOTP time steps (±1 skew) using {@link verifyTotp}.\n *\n * Returns `undefined` when the env var is not set — callers treat that as\n * \"auth disabled\" (no predicate registered on the relay). Note that since\n * issue #250 the secret is MANDATORY at every relay-boot site (enforced by\n * {@link assertRelayAuthConfigured} BEFORE the relay starts), so in production\n * this never returns `undefined` for a relay that actually boots; the\n * `undefined` branch only matters for the no-relay local path and tests.\n *\n * Lives here (not in the MCP server) so the unplugin's env-2 relay can wire the\n * same gate without importing the heavy MCP server module graph. Re-exported\n * from `debug-server.ts` for back-compat.\n *\n * SECRET-HANDLING: The secret value read from env is captured in a closure and\n * is NEVER written to any log, error message, or process output.\n */\nexport function buildRelayVerifyAuth(\n  env: NodeJS.ProcessEnv = process.env,\n): ((req: import('node:http').IncomingMessage) => boolean) | undefined {\n  const secret = env.AIT_DEBUG_TOTP_SECRET;\n  if (!secret) return undefined;\n\n  return (req) => {\n    // Parse the `at` query param from the upgrade request URL.\n    // req.url is the raw request path + query, e.g. `/client/id?target=…&at=123456`\n    const rawUrl = req.url ?? '';\n    const qIndex = rawUrl.indexOf('?');\n    const queryStr = qIndex === -1 ? '' : rawUrl.slice(qIndex + 1);\n    const params = new URLSearchParams(queryStr);\n    const code = params.get('at') ?? '';\n\n    // Do NOT log `code`, `secret`, or any derived value here.\n    return verifyTotp(secret, code);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAM,YAAY;;AAGlB,MAAM,SAAS;;;;;;;;;;AAWf,SAAgB,aAAa,QAAgB,OAAe,KAAK,KAAK,EAAU;CAC9E,MAAM,MAAM,OAAO,KAAK,QAAQ,MAAM;CAGtC,MAAM,UAAU,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,MAAO,UAAU,CAAC;CAGhE,MAAM,aAAa,OAAO,MAAM,EAAE;CAGlC,MAAM,KAAK,KAAK,MAAM,UAAU,WAAY;CAC5C,MAAM,KAAK,YAAY;AACvB,YAAW,cAAc,IAAI,EAAE;AAC/B,YAAW,cAAc,IAAI,EAAE;CAE/B,MAAM,OAAA,GAAA,YAAA,YAAiB,QAAQ,IAAI,CAAC,OAAO,WAAW,CAAC,QAAQ;CAG/D,MAAM,SAAS,IAAI,MAAM;AAQzB,WANI,IAAI,UAAU,QAAS,MACvB,IAAI,SAAS,KAAK,QAAS,MAC3B,IAAI,SAAS,KAAK,QAAS,IAC5B,IAAI,SAAS,KAAK,OAEC,MAAM,QACjB,UAAU,CAAC,SAAS,QAAQ,IAAI;;;;;;;;;;;;;;;;AAiB7C,SAAgB,WACd,QACA,MACA,OAAe,KAAK,KAAK,EACzB,OAAe,GACN;CACT,MAAM,aAAa,OAAO,KAAK,CAAC,SAAS,QAAQ,IAAI;AACrD,KAAI,WAAW,WAAW,UAAU,CAAC,UAAU,KAAK,WAAW,CAC7D,QAAO;CAGT,MAAM,eAAe,OAAO,KAAK,YAAY,OAAO;AAEpD,MAAK,IAAI,QAAQ,CAAC,MAAM,SAAS,MAAM,SAAS;EAE9C,MAAM,WAAW,aAAa,QADb,OAAO,QAAQ,YAAY,IACG;AAE/C,OAAA,GAAA,YAAA,iBADoB,OAAO,KAAK,UAAU,OAAO,EAChB,aAAa,CAC5C,QAAO;;AAIX,QAAO;;;;;;;;;;AAWT,MAAM,uBAAuB;;AAG7B,MAAM,SAAS;;;;;;;;;;;;;AAcf,MAAa,oCAAoC;CAC/C;CACA;CACA;CACD,CAAC,KAAK,KAAK;;;;;;;;;;;;;AAcZ,SAAgB,uBAAuB,QAA8C;AACnF,KAAI,WAAW,KAAA,KAAa,WAAW,GAAI,QAAO;AAClD,KAAI,OAAO,SAAS,qBAAsB,QAAO;AACjD,KAAI,OAAO,SAAS,MAAM,EAAG,QAAO;AACpC,QAAO,OAAO,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA0B5B,SAAgB,0BAA0B,MAAyB,QAAQ,KAAW;AACpF,KAAI,CAAC,uBAAuB,IAAI,sBAAsB,CACpD,OAAM,IAAI,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;AAyBtD,SAAgB,qBACd,MAAyB,QAAQ,KACoC;CACrE,MAAM,SAAS,IAAI;AACnB,KAAI,CAAC,OAAQ,QAAO,KAAA;AAEpB,SAAQ,QAAQ;EAGd,MAAM,SAAS,IAAI,OAAO;EAC1B,MAAM,SAAS,OAAO,QAAQ,IAAI;EAClC,MAAM,WAAW,WAAW,KAAK,KAAK,OAAO,MAAM,SAAS,EAAE;AAK9D,SAAO,WAAW,QAJH,IAAI,gBAAgB,SAAS,CACxB,IAAI,KAAK,IAAI,GAGF"}

package/dist/totp-CxHsagqY.js

@@ -0,0 +1,184 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#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;
+}
+/**
+* Minimum length (in hex characters) accepted for `AIT_DEBUG_TOTP_SECRET`.
+*
+* The secret is hex-encoded (see {@link generateTotp} — `Buffer.from(secret,
+* 'hex')`). 32 hex chars = 16 bytes = 128 bits, the floor for an HMAC-SHA1 key
+* we are willing to gate a public relay behind. `generateAttachToken()` emits
+* 64 hex chars (32 bytes), comfortably above this bar.
+*/
+const MIN_SECRET_HEX_CHARS = 32;
+/** Hex string: one or more hex digits, case-insensitive (RFC 4648 base16). */
+const HEX_RE = /^[0-9a-fA-F]+$/;
+/**
+* Human-facing guidance printed when {@link assertRelayAuthConfigured} fails.
+*
+* SECRET-HANDLING: this message states only the REQUIREMENT (≥32 hex chars) and
+* how to mint one. It NEVER echoes the configured value, its length, or any
+* fragment derived from it — see {@link assertRelayAuthConfigured}.
+*
+* Note on encoding: the secret is hex (base16), not base32 — `generateTotp`
+* decodes it with `Buffer.from(secret, 'hex')`. A base32 string would be
+* silently mis-decoded and every TOTP code would fail to match, so the minting
+* command emits hex.
+*/
+const RELAY_AUTH_SECRET_MISSING_MESSAGE = [
+	"[ait-debug] AIT_DEBUG_TOTP_SECRET이 필수입니다. 32자 이상 16진수(hex) 문자열을 설정하세요.",
+	"발급: openssl rand -hex 32",
+	"자세히: https://docs.aitc.dev/guides/relay-auth-totp"
+].join("\n");
+/**
+* Whether `secret` is a well-formed relay-auth TOTP secret: a hex string of at
+* least {@link MIN_SECRET_HEX_CHARS} characters with an even length (an odd
+* length would have its trailing nibble silently dropped by `Buffer.from(...,
+* 'hex')`, weakening the key without warning).
+*
+* Pure predicate so callers can test the validation independently of the
+* fail-fast side effect in {@link assertRelayAuthConfigured}.
+*
+* SECRET-HANDLING: returns only a boolean — the input value is never returned,
+* logged, or echoed.
+*/
+function isValidRelayAuthSecret(secret) {
+	if (secret === void 0 || secret === "") return false;
+	if (secret.length < MIN_SECRET_HEX_CHARS) return false;
+	if (secret.length % 2 !== 0) return false;
+	return HEX_RE.test(secret);
+}
+/**
+* Fail-fast guard enforcing that a relay-auth TOTP secret is configured before
+* a public-internet-exposed relay is booted (issue #250).
+*
+* Relay-auth (the §4 Layer C TOTP gate) is the only fail-fast layer that closes
+* the real gap: a leaked `wss://…trycloudflare.com` URL otherwise lets a third
+* party attach a debugger to a dogfood/live mini-app. Without a secret the relay
+* comes up unauthenticated, so this guard is called at every relay-boot site —
+* `bootRelayFamily` (intoss env 3/4) and `bootExternalRelayFamily` (env-2 PWA),
+* both eager and lazy. Local-only sessions never boot a relay and so never reach
+* this guard, matching the issue's exemption for non-relay debugging.
+*
+* Throws when the secret is unset, empty, too short, or not a valid hex string.
+* The thrown message is the bin entry's fatal stderr (see `cli.ts` `main().catch`)
+* — the same fatal model as the missing-`AIT_RELAY_BASE_URL` path.
+*
+* SECRET-HANDLING: the env value is read once, passed ONLY to the boolean
+* predicate, and never logged. The thrown message names the requirement, never
+* the value, its length, or any derived fragment.
+*
+* @param env - Environment to read from. Defaults to `process.env`; injectable
+*   for tests so they never mutate the real process environment.
+*/
+function assertRelayAuthConfigured(env = process.env) {
+	if (!isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) throw new Error(RELAY_AUTH_SECRET_MISSING_MESSAGE);
+}
+/**
+* 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 {@link verifyTotp}.
+*
+* Returns `undefined` when the env var is not set — callers treat that as
+* "auth disabled" (no predicate registered on the relay). Note that since
+* issue #250 the secret is MANDATORY at every relay-boot site (enforced by
+* {@link assertRelayAuthConfigured} BEFORE the relay starts), so in production
+* this never returns `undefined` for a relay that actually boots; the
+* `undefined` branch only matters for the no-relay local path and tests.
+*
+* Lives here (not in the MCP server) so the unplugin's env-2 relay can wire the
+* same gate without importing the heavy MCP server module graph. Re-exported
+* from `debug-server.ts` for back-compat.
+*
+* 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(env = process.env) {
+	const secret = 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") ?? "");
+	};
+}
+//#endregion
+export { assertRelayAuthConfigured, buildRelayVerifyAuth };
+
+//# sourceMappingURL=totp-CxHsagqY.js.map

package/dist/totp-CxHsagqY.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-CxHsagqY.js","names":[],"sources":["../src/mcp/totp.ts"],"sourcesContent":["/**\n * RFC 6238 TOTP implementation (Node.js, node:crypto only).\n *\n * External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used\n * to keep the dependency surface minimal. This hand-roll is ~30 lines and\n * covers exactly what relay-side auth needs.\n *\n * Algorithm summary (RFC 6238 + RFC 4226):\n *   T  = floor(now / 30)          — 30-second time step counter\n *   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)\n *   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)\n *   offset = MAC[19] & 0x0f\n *   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits\n *\n * Security note (keep this comment accurate):\n *   The baked-in secret in a dogfood build is extractable from the bundle by a\n *   determined reverse engineer. This mechanism raises the bar from\n *   \"anyone with the URL\" to \"URL + bundle extraction + live TOTP calculation\".\n *   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are\n *   blocked; deliberate reverse engineering is not. See threat model in\n *   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.\n *\n * SECRET-HANDLING: secret values and computed codes MUST NOT appear in any\n * log, error message, or string visible outside this module. Only boolean\n * pass/fail and reason enum values are safe to surface.\n */\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\n\n/** Time step window in seconds (RFC 6238 default). */\nconst TIME_STEP = 30;\n\n/** Number of digits in the generated code. */\nconst DIGITS = 6;\n\n/**\n * Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-\n * clock time.\n *\n * @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32\n *   bytes). Must be the output of `generateAttachToken()` or compatible.\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @returns A zero-padded 6-digit decimal string, e.g. `\"042193\"`.\n */\nexport function generateTotp(secret: string, when: number = Date.now()): string {\n  const key = Buffer.from(secret, 'hex');\n  // Clamp to 0 so negative timestamps (e.g. in ±skew checks near epoch) do not\n  // produce a negative counter, which would cause writeUInt32BE to throw.\n  const counter = Math.max(0, Math.floor(when / 1000 / TIME_STEP));\n\n  // Encode counter as 8-byte big-endian unsigned integer.\n  const counterBuf = Buffer.alloc(8);\n  // JavaScript numbers are safe integers up to 2^53; counter is ~7.5×10^10 at\n  // year 9999 — well within safe range so standard bitwise ops are fine.\n  const hi = Math.floor(counter / 0x100000000);\n  const lo = counter >>> 0;\n  counterBuf.writeUInt32BE(hi, 0);\n  counterBuf.writeUInt32BE(lo, 4);\n\n  const mac = createHmac('sha1', key).update(counterBuf).digest();\n\n  // Dynamic truncation (RFC 4226 §5.4).\n  const offset = mac[19] & 0x0f;\n  const binCode =\n    ((mac[offset] & 0x7f) << 24) |\n    ((mac[offset + 1] & 0xff) << 16) |\n    ((mac[offset + 2] & 0xff) << 8) |\n    (mac[offset + 3] & 0xff);\n\n  const otp = binCode % 10 ** DIGITS;\n  return otp.toString().padStart(DIGITS, '0');\n}\n\n/**\n * Verifies a TOTP code against the secret, accepting ±`skew` time steps to\n * tolerate clock drift between the relay host and the client device.\n *\n * Uses `timingSafeEqual` for constant-time comparison to prevent timing\n * side-channel attacks.\n *\n * @param secret - Hex-encoded shared secret.\n * @param code - The 6-digit code to verify (string or numeric).\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @param skew - Number of adjacent steps to accept on either side. Default 1\n *   (accepts T-1, T, T+1 — a 90-second acceptance window).\n * @returns `true` if the code matches any accepted step, `false` otherwise.\n */\nexport function verifyTotp(\n  secret: string,\n  code: string,\n  when: number = Date.now(),\n  skew: number = 1,\n): boolean {\n  const normalised = String(code).padStart(DIGITS, '0');\n  if (normalised.length !== DIGITS || !/^\\d{6}$/.test(normalised)) {\n    return false;\n  }\n\n  const candidateBuf = Buffer.from(normalised, 'utf8');\n\n  for (let delta = -skew; delta <= skew; delta++) {\n    const stepWhen = when + delta * TIME_STEP * 1000;\n    const expected = generateTotp(secret, stepWhen);\n    const expectedBuf = Buffer.from(expected, 'utf8');\n    if (timingSafeEqual(expectedBuf, candidateBuf)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Minimum length (in hex characters) accepted for `AIT_DEBUG_TOTP_SECRET`.\n *\n * The secret is hex-encoded (see {@link generateTotp} — `Buffer.from(secret,\n * 'hex')`). 32 hex chars = 16 bytes = 128 bits, the floor for an HMAC-SHA1 key\n * we are willing to gate a public relay behind. `generateAttachToken()` emits\n * 64 hex chars (32 bytes), comfortably above this bar.\n */\nconst MIN_SECRET_HEX_CHARS = 32;\n\n/** Hex string: one or more hex digits, case-insensitive (RFC 4648 base16). */\nconst HEX_RE = /^[0-9a-fA-F]+$/;\n\n/**\n * Human-facing guidance printed when {@link assertRelayAuthConfigured} fails.\n *\n * SECRET-HANDLING: this message states only the REQUIREMENT (≥32 hex chars) and\n * how to mint one. It NEVER echoes the configured value, its length, or any\n * fragment derived from it — see {@link assertRelayAuthConfigured}.\n *\n * Note on encoding: the secret is hex (base16), not base32 — `generateTotp`\n * decodes it with `Buffer.from(secret, 'hex')`. A base32 string would be\n * silently mis-decoded and every TOTP code would fail to match, so the minting\n * command emits hex.\n */\nexport const RELAY_AUTH_SECRET_MISSING_MESSAGE = [\n  '[ait-debug] AIT_DEBUG_TOTP_SECRET이 필수입니다. 32자 이상 16진수(hex) 문자열을 설정하세요.',\n  '발급: openssl rand -hex 32',\n  '자세히: https://docs.aitc.dev/guides/relay-auth-totp',\n].join('\\n');\n\n/**\n * Whether `secret` is a well-formed relay-auth TOTP secret: a hex string of at\n * least {@link MIN_SECRET_HEX_CHARS} characters with an even length (an odd\n * length would have its trailing nibble silently dropped by `Buffer.from(...,\n * 'hex')`, weakening the key without warning).\n *\n * Pure predicate so callers can test the validation independently of the\n * fail-fast side effect in {@link assertRelayAuthConfigured}.\n *\n * SECRET-HANDLING: returns only a boolean — the input value is never returned,\n * logged, or echoed.\n */\nexport function isValidRelayAuthSecret(secret: string | undefined): secret is string {\n  if (secret === undefined || secret === '') return false;\n  if (secret.length < MIN_SECRET_HEX_CHARS) return false;\n  if (secret.length % 2 !== 0) return false;\n  return HEX_RE.test(secret);\n}\n\n/**\n * Fail-fast guard enforcing that a relay-auth TOTP secret is configured before\n * a public-internet-exposed relay is booted (issue #250).\n *\n * Relay-auth (the §4 Layer C TOTP gate) is the only fail-fast layer that closes\n * the real gap: a leaked `wss://…trycloudflare.com` URL otherwise lets a third\n * party attach a debugger to a dogfood/live mini-app. Without a secret the relay\n * comes up unauthenticated, so this guard is called at every relay-boot site —\n * `bootRelayFamily` (intoss env 3/4) and `bootExternalRelayFamily` (env-2 PWA),\n * both eager and lazy. Local-only sessions never boot a relay and so never reach\n * this guard, matching the issue's exemption for non-relay debugging.\n *\n * Throws when the secret is unset, empty, too short, or not a valid hex string.\n * The thrown message is the bin entry's fatal stderr (see `cli.ts` `main().catch`)\n * — the same fatal model as the missing-`AIT_RELAY_BASE_URL` path.\n *\n * SECRET-HANDLING: the env value is read once, passed ONLY to the boolean\n * predicate, and never logged. The thrown message names the requirement, never\n * the value, its length, or any derived fragment.\n *\n * @param env - Environment to read from. Defaults to `process.env`; injectable\n *   for tests so they never mutate the real process environment.\n */\nexport function assertRelayAuthConfigured(env: NodeJS.ProcessEnv = process.env): void {\n  if (!isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) {\n    throw new Error(RELAY_AUTH_SECRET_MISSING_MESSAGE);\n  }\n}\n\n/**\n * Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a\n * `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.\n *\n * The predicate checks the `at` query parameter against the current and\n * adjacent TOTP time steps (±1 skew) using {@link verifyTotp}.\n *\n * Returns `undefined` when the env var is not set — callers treat that as\n * \"auth disabled\" (no predicate registered on the relay). Note that since\n * issue #250 the secret is MANDATORY at every relay-boot site (enforced by\n * {@link assertRelayAuthConfigured} BEFORE the relay starts), so in production\n * this never returns `undefined` for a relay that actually boots; the\n * `undefined` branch only matters for the no-relay local path and tests.\n *\n * Lives here (not in the MCP server) so the unplugin's env-2 relay can wire the\n * same gate without importing the heavy MCP server module graph. Re-exported\n * from `debug-server.ts` for back-compat.\n *\n * SECRET-HANDLING: The secret value read from env is captured in a closure and\n * is NEVER written to any log, error message, or process output.\n */\nexport function buildRelayVerifyAuth(\n  env: NodeJS.ProcessEnv = process.env,\n): ((req: import('node:http').IncomingMessage) => boolean) | undefined {\n  const secret = env.AIT_DEBUG_TOTP_SECRET;\n  if (!secret) return undefined;\n\n  return (req) => {\n    // Parse the `at` query param from the upgrade request URL.\n    // req.url is the raw request path + query, e.g. `/client/id?target=…&at=123456`\n    const rawUrl = req.url ?? '';\n    const qIndex = rawUrl.indexOf('?');\n    const queryStr = qIndex === -1 ? '' : rawUrl.slice(qIndex + 1);\n    const params = new URLSearchParams(queryStr);\n    const code = params.get('at') ?? '';\n\n    // Do NOT log `code`, `secret`, or any derived value here.\n    return verifyTotp(secret, code);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAM,YAAY;;AAGlB,MAAM,SAAS;;;;;;;;;;AAWf,SAAgB,aAAa,QAAgB,OAAe,KAAK,KAAK,EAAU;CAC9E,MAAM,MAAM,OAAO,KAAK,QAAQ,MAAM;CAGtC,MAAM,UAAU,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,MAAO,UAAU,CAAC;CAGhE,MAAM,aAAa,OAAO,MAAM,EAAE;CAGlC,MAAM,KAAK,KAAK,MAAM,UAAU,WAAY;CAC5C,MAAM,KAAK,YAAY;AACvB,YAAW,cAAc,IAAI,EAAE;AAC/B,YAAW,cAAc,IAAI,EAAE;CAE/B,MAAM,MAAM,WAAW,QAAQ,IAAI,CAAC,OAAO,WAAW,CAAC,QAAQ;CAG/D,MAAM,SAAS,IAAI,MAAM;AAQzB,WANI,IAAI,UAAU,QAAS,MACvB,IAAI,SAAS,KAAK,QAAS,MAC3B,IAAI,SAAS,KAAK,QAAS,IAC5B,IAAI,SAAS,KAAK,OAEC,MAAM,QACjB,UAAU,CAAC,SAAS,QAAQ,IAAI;;;;;;;;;;;;;;;;AAiB7C,SAAgB,WACd,QACA,MACA,OAAe,KAAK,KAAK,EACzB,OAAe,GACN;CACT,MAAM,aAAa,OAAO,KAAK,CAAC,SAAS,QAAQ,IAAI;AACrD,KAAI,WAAW,WAAW,UAAU,CAAC,UAAU,KAAK,WAAW,CAC7D,QAAO;CAGT,MAAM,eAAe,OAAO,KAAK,YAAY,OAAO;AAEpD,MAAK,IAAI,QAAQ,CAAC,MAAM,SAAS,MAAM,SAAS;EAE9C,MAAM,WAAW,aAAa,QADb,OAAO,QAAQ,YAAY,IACG;AAE/C,MAAI,gBADgB,OAAO,KAAK,UAAU,OAAO,EAChB,aAAa,CAC5C,QAAO;;AAIX,QAAO;;;;;;;;;;AAWT,MAAM,uBAAuB;;AAG7B,MAAM,SAAS;;;;;;;;;;;;;AAcf,MAAa,oCAAoC;CAC/C;CACA;CACA;CACD,CAAC,KAAK,KAAK;;;;;;;;;;;;;AAcZ,SAAgB,uBAAuB,QAA8C;AACnF,KAAI,WAAW,KAAA,KAAa,WAAW,GAAI,QAAO;AAClD,KAAI,OAAO,SAAS,qBAAsB,QAAO;AACjD,KAAI,OAAO,SAAS,MAAM,EAAG,QAAO;AACpC,QAAO,OAAO,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA0B5B,SAAgB,0BAA0B,MAAyB,QAAQ,KAAW;AACpF,KAAI,CAAC,uBAAuB,IAAI,sBAAsB,CACpD,OAAM,IAAI,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;AAyBtD,SAAgB,qBACd,MAAyB,QAAQ,KACoC;CACrE,MAAM,SAAS,IAAI;AACnB,KAAI,CAAC,OAAQ,QAAO,KAAA;AAEpB,SAAQ,QAAQ;EAGd,MAAM,SAAS,IAAI,OAAO;EAC1B,MAAM,SAAS,OAAO,QAAQ,IAAI;EAClC,MAAM,WAAW,WAAW,KAAK,KAAK,OAAO,MAAM,SAAS,EAAE;AAK9D,SAAO,WAAW,QAJH,IAAI,gBAAgB,SAAS,CACxB,IAAI,KAAK,IAAI,GAGF"}

package/dist/{tunnel-D0_TwDNE.js → tunnel-Cj8g1LIL.js}

@@ -32,9 +32,16 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * Plain-text raw URL is no longer enough — the launcher gates its setup UI to
 * the installed PWA, so a raw tunnel URL opened in a normal browser tab would
 * land on a "please install" screen.
+*
+* When `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries
+* `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so
+* the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and
+* a Chii target.js is injected into the live view.
 */
-function buildLauncherDeepLink(tunnelUrl) {
-	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+function buildLauncherDeepLink(tunnelUrl, relayWssUrl) {
+	const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+	if (!relayWssUrl) return base;
+	return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;
 }
 /**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
@@ -44,7 +51,7 @@ function buildLauncherDeepLink(tunnelUrl) {
 */
 async function printTunnelBanner(url, opts = {}) {
 	const log = opts.log ?? ((m) => console.log(m));
-	const deepLink = buildLauncherDeepLink(url);
+	const deepLink = buildLauncherDeepLink(url, opts.relayWssUrl);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
@@ -53,6 +60,7 @@ async function printTunnelBanner(url, opts = {}) {
 		`  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,
 		"  │  Then scan the QR below — it opens the launcher directly",
 		"  │  into this tunnel URL (no manual paste needed).",
+		...opts.relayWssUrl ? ["  │  The same scan also attaches CDP — connect your AI host", "  │  to the relay and debug the live view on-device."] : [],
 		"  │  Quick tunnels are unauthenticated, change every run, and are",
 		"  │  not for production use.",
 		"  └──────────────────────────────────────────────────────────────",
@@ -130,4 +138,4 @@ async function startQuickTunnel(port) {
 //#endregion
 export { printTunnelBanner, startQuickTunnel };
 
-//# sourceMappingURL=tunnel-D0_TwDNE.js.map
+//# sourceMappingURL=tunnel-Cj8g1LIL.js.map

package/dist/tunnel-Cj8g1LIL.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-Cj8g1LIL.js","names":[],"sources":["../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n  /**\n   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When\n   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the\n   * framed PWA passes the in-app debug gate and attaches a Chii target — the\n   * same single scan opens screen preview *and* CDP debugging.\n   */\n  relayWssUrl?: string;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n *\n * When `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries\n * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so\n * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and\n * a Chii target.js is injected into the live view.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string, relayWssUrl?: string): string {\n  const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n  if (!relayWssUrl) return base;\n  return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url, opts.relayWssUrl);\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    ...(opts.relayWssUrl\n      ? [\n          '  │  The same scan also attaches CDP — connect your AI host',\n          '  │  to the relay and debug the live view on-device.',\n        ]\n      : []),\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      cleanup();\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAiBpB,MAAM,eAAe;;;;;;;;;;;;;;AAerB,SAAgB,sBAAsB,WAAmB,aAA8B;CACrF,MAAM,OAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;AACjE,KAAI,CAAC,YAAa,QAAO;AACzB,QAAO,GAAG,KAAK,iBAAiB,mBAAmB,YAAY;;;;;;;;AASjE,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,KAAK,KAAK,YAAY;AAoB7D,KAnBwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA,GAAI,KAAK,cACL,CACE,+DACA,uDACD,GACD,EAAE;EACN;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,UAAU,EAAE,OAAO,MAAM,GAAG,QAAQ;AAClD,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,CAAC,WAAW,IAAI,EAAE;AACpB,QAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,YAAS;AACT,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/{tunnel-BYP0yRBN.cjs → tunnel-p-q6eVWT.cjs}

@@ -32,9 +32,16 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * Plain-text raw URL is no longer enough — the launcher gates its setup UI to
 * the installed PWA, so a raw tunnel URL opened in a normal browser tab would
 * land on a "please install" screen.
+*
+* When `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries
+* `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so
+* the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and
+* a Chii target.js is injected into the live view.
 */
-function buildLauncherDeepLink(tunnelUrl) {
-	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+function buildLauncherDeepLink(tunnelUrl, relayWssUrl) {
+	const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+	if (!relayWssUrl) return base;
+	return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;
 }
 /**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
@@ -44,7 +51,7 @@ function buildLauncherDeepLink(tunnelUrl) {
 */
 async function printTunnelBanner(url, opts = {}) {
 	const log = opts.log ?? ((m) => console.log(m));
-	const deepLink = buildLauncherDeepLink(url);
+	const deepLink = buildLauncherDeepLink(url, opts.relayWssUrl);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
@@ -53,6 +60,7 @@ async function printTunnelBanner(url, opts = {}) {
 		`  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,
 		"  │  Then scan the QR below — it opens the launcher directly",
 		"  │  into this tunnel URL (no manual paste needed).",
+		...opts.relayWssUrl ? ["  │  The same scan also attaches CDP — connect your AI host", "  │  to the relay and debug the live view on-device."] : [],
 		"  │  Quick tunnels are unauthenticated, change every run, and are",
 		"  │  not for production use.",
 		"  └──────────────────────────────────────────────────────────────",
@@ -131,4 +139,4 @@ async function startQuickTunnel(port) {
 exports.printTunnelBanner = printTunnelBanner;
 exports.startQuickTunnel = startQuickTunnel;
 
-//# sourceMappingURL=tunnel-BYP0yRBN.cjs.map
+//# sourceMappingURL=tunnel-p-q6eVWT.cjs.map

package/dist/tunnel-p-q6eVWT.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-p-q6eVWT.cjs","names":[],"sources":["../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n  /**\n   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When\n   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the\n   * framed PWA passes the in-app debug gate and attaches a Chii target — the\n   * same single scan opens screen preview *and* CDP debugging.\n   */\n  relayWssUrl?: string;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n *\n * When `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries\n * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so\n * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and\n * a Chii target.js is injected into the live view.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string, relayWssUrl?: string): string {\n  const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n  if (!relayWssUrl) return base;\n  return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url, opts.relayWssUrl);\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    ...(opts.relayWssUrl\n      ? [\n          '  │  The same scan also attaches CDP — connect your AI host',\n          '  │  to the relay and debug the live view on-device.',\n        ]\n      : []),\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      cleanup();\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAiBpB,MAAM,eAAe;;;;;;;;;;;;;;AAerB,SAAgB,sBAAsB,WAAmB,aAA8B;CACrF,MAAM,OAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;AACjE,KAAI,CAAC,YAAa,QAAO;AACzB,QAAO,GAAG,KAAK,iBAAiB,mBAAmB,YAAY;;;;;;;;AASjE,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,KAAK,KAAK,YAAY;AAoB7D,KAnBwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA,GAAI,KAAK,cACL,CACE,+DACA,uDACD,GACD,EAAE;EACN;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,UAAU,EAAE,OAAO,MAAM,GAAG,QAAQ;AAClD,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,EAAA,GAAA,QAAA,YAAY,IAAI,EAAE;AACpB,SAAA,GAAA,iBAAA,QAAA,GAAA,UAAA,SAAoB,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,YAAS;AACT,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/unplugin/index.cjs

@@ -125,6 +125,8 @@ const aitDevtoolsPlugin = (0, unplugin.createUnplugin)((options) => {
 				});
 				if (shouldTunnel) {
 					let tunnel = null;
+					let relayTunnel = null;
+					let relay = null;
 					const httpServer = server.httpServer;
 					httpServer?.once("listening", () => {
 						const address = httpServer?.address();
@@ -133,15 +135,39 @@ const aitDevtoolsPlugin = (0, unplugin.createUnplugin)((options) => {
 							console.warn("[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.");
 							return;
 						}
-						Promise.resolve().then(() => require("../tunnel-BYP0yRBN.cjs")).then(async ({ startQuickTunnel, printTunnelBanner }) => {
+						Promise.resolve().then(() => require("../tunnel-p-q6eVWT.cjs")).then(async ({ startQuickTunnel, printTunnelBanner }) => {
 							const t = await startQuickTunnel(port);
 							tunnel = t;
-							await printTunnelBanner(t.url, { qr: tunnelConfig.qr });
+							let relayWssUrl;
+							if (tunnelConfig.cdp) try {
+								const { assertRelayAuthConfigured, buildRelayVerifyAuth } = await Promise.resolve().then(() => require("../totp-BkKP4m8H.cjs"));
+								assertRelayAuthConfigured();
+								const verifyAuth = buildRelayVerifyAuth();
+								const { startChiiRelay } = await Promise.resolve().then(() => require("../chii-relay-57BfqF_5.cjs"));
+								const r = await startChiiRelay({
+									port: 0,
+									verifyAuth
+								});
+								relay = r;
+								const rt = await startQuickTunnel(r.port);
+								relayTunnel = rt;
+								relayWssUrl = rt.url.replace(/^https:/, "wss:");
+							} catch (err) {
+								console.warn(`[@ait-co/devtools] tunnel: CDP relay not started — screen preview works without on-device debugging: ${err instanceof Error ? err.message : String(err)}`);
+							}
+							await printTunnelBanner(t.url, {
+								qr: tunnelConfig.qr,
+								relayWssUrl
+							});
 						}).catch((err) => {
 							console.warn(`[@ait-co/devtools] tunnel failed to start: ${err instanceof Error ? err.message : String(err)}`);
 						});
 					});
-					const cleanup = () => tunnel?.stop();
+					const cleanup = () => {
+						tunnel?.stop();
+						relayTunnel?.stop();
+						relay?.close();
+					};
 					httpServer?.once("close", cleanup);
 					process.once("SIGINT", cleanup);
 					process.once("SIGTERM", cleanup);