@ait-co/devtools 0.1.45 → 0.1.48

package/dist/mcp/cli.js

@@ -848,6 +848,51 @@ var AutoDevtoolsOpener = class {
 	}
 };
 //#endregion
+//#region src/mcp/envelope.ts
+/**
+* Returns `true` when `AIT_MCP_COMPAT=chrome-devtools` is set, which bypasses
+* envelope wrapping and returns raw payloads (0.1.x back-compat).
+*/
+function isCompatMode() {
+	return process.env.AIT_MCP_COMPAT === "chrome-devtools";
+}
+/**
+* Maps `McpEnvironment` to `EnvelopeEnv`. After #307 these are the same
+* union (`mock | relay-dev | relay-live`), so this is identity — kept as a
+* named export for surface stability if envelope env diverges in the future.
+*/
+function toEnvelopeEnv(env) {
+	return env;
+}
+/**
+* Wraps `data` in a `ToolEnvelope<T>` **unless** compat mode is active, in
+* which case `data` is returned as-is.
+*
+* Use this at every tool call-site in `debug-server.ts` and `server.ts`.
+*
+* @example
+* ```ts
+* return jsonResult(wrapEnvelope(listPages(connection, tunnel), {
+*   tool: 'list_pages',
+*   env: resolveEnvironment(),
+*   attached: connection.listTargets().length > 0,
+* }));
+* ```
+*/
+function wrapEnvelope(data, ctx) {
+	if (isCompatMode()) return data;
+	return {
+		ok: true,
+		data,
+		meta: {
+			tool: ctx.tool,
+			env: toEnvelopeEnv(ctx.env),
+			attached: ctx.attached,
+			contentType: ctx.contentType ?? "json"
+		}
+	};
+}
+//#endregion
 //#region src/mcp/environment.ts
 /**
 * Returns `true` when the environment is any relay variant (`relay-dev` or
@@ -2013,6 +2058,83 @@ function warnPassthrough(name) {
 }
 SIGNATURES.map((s) => s.name);
 //#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/tools.ts
 /** Static MCP tool descriptors (name + JSONSchema) for the full debug tool surface. */
 const DEBUG_TOOL_DEFINITIONS = [
@@ -2048,7 +2170,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "build_attach_url",
-		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. If the tunnel is not up, restart the MCP server: `npx @ait-co/devtools devtools-mcp`. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 30 s by default), then returns the attached page info too. On timeout, call build_attach_url again to resume polling. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers). Requires MCP_ENV=relay (set automatically when a relay tunnel is detected).",
+		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. If the tunnel is not up, restart the MCP server: `npx @ait-co/devtools devtools-mcp`. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 30 s by default), then returns the attached page info too. On timeout, call build_attach_url again to resume polling. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers). Requires MCP_ENV=relay-dev or relay-live (set automatically in debug-mode default).\n\nTOTP auth: when AIT_DEBUG_TOTP_SECRET is set on the MCP server, the returned attachUrl automatically includes the current one-time code (at=<code>) — the URL is single-use for that 30-second step. The response includes a `totp` field with `expiresAt` (ISO timestamp). If the phone scan happens after expiresAt, the relay will reject the code — just call build_attach_url again to get a fresh one-time URL. Without AIT_DEBUG_TOTP_SECRET, the attachUrl has no expiry.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2101,7 +2223,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		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. Tier C per RFC #277: the same Runtime.evaluate probe runs in both `mock` (devtools panel page with window.__ait state) and `relay` (real-device WebView with window.__sdk). The result includes a `source: \"mock\" | \"relay\"` field so consumers can identify provenance without inspecting payload values. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires a page to be attached — call list_pages first.",
+		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. Tier C per RFC #277: the same Runtime.evaluate probe runs in both `mock` (devtools panel page with window.__ait state) and `relay` (real-device WebView with window.__sdk). The result includes a `source: \"mock\" | \"relay-dev\" | \"relay-live\"` field so consumers can identify provenance without inspecting payload values. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires a page to be attached — call list_pages first.",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -2143,7 +2265,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "call_sdk",
-		description: "Calls a dogfood SDK method via the window.__sdkCall bridge (exported by @apps-in-toss/web-framework only in __DEBUG_BUILD__ bundles). NOT read-only — SDK calls have side effects (navigation, payments, permissions, etc.). On env 2/3 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. Requires the relay to be attached — call list_pages first. Returns {ok: true, value} on success or {ok: false, error} on failure. If a Runtime.exceptionThrown event was observed within [callStart-50ms, callEnd+200ms], the result also includes `recentException` for crash triage. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle) — redeploy via dogfood channel: `ait build && aitcc app deploy`.\n\nSECURITY: method name, args, and result value are not redacted — never include secrets.\n\nLIVE guard: when running against a live/production relay (relay-live env, MCP_ENV=relay-live), this tool requires `confirm: true` to acknowledge that the SDK call may affect real users. Without it the call is rejected with a structured error. mock and relay-dev sessions are unaffected.\n\nIMPORTANT — 인자 시그니처 (잘못된 인자로 호출하면 토스 앱 crash 위험):\n  setDeviceOrientation:        call_sdk(\"setDeviceOrientation\", [{ type: \"landscape\" }])  // NOT \"landscape\"\n  setIosSwipeGestureEnabled:   call_sdk(\"setIosSwipeGestureEnabled\", [{ isEnabled: false }])\n  setSecureScreen:             call_sdk(\"setSecureScreen\", [{ enabled: true }])\n  setScreenAwakeMode:          call_sdk(\"setScreenAwakeMode\", [{ enabled: true }])\n  getOperationalEnvironment:   call_sdk(\"getOperationalEnvironment\", [])\n  getPlatformOS:               call_sdk(\"getPlatformOS\", [])\n  getDeviceId:                 call_sdk(\"getDeviceId\", [])\n  getLocale:                   call_sdk(\"getLocale\", [])\n  getNetworkStatus:            call_sdk(\"getNetworkStatus\", [])\n  getSchemeUri:                call_sdk(\"getSchemeUri\", [])\n  requestReview:               call_sdk(\"requestReview\", [])\n  closeView:                   call_sdk(\"closeView\", [])",
+		description: "Calls a dogfood SDK method via the window.__sdkCall bridge (exported by @apps-in-toss/web-framework only in __DEBUG_BUILD__ bundles). NOT read-only — SDK calls have side effects (navigation, payments, permissions, etc.). On env 3/4 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. (env 2 PWA does not inject the SDK — call_sdk is not available there.) Requires the relay to be attached — call list_pages first. Returns {ok: true, value} on success or {ok: false, error} on failure. If a Runtime.exceptionThrown event was observed within [callStart-50ms, callEnd+200ms], the result also includes `recentException` for crash triage. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle) — redeploy via dogfood channel: `ait build && aitcc app deploy`.\n\nSECURITY: method name, args, and result value are not redacted — never include secrets.\n\nLIVE guard: when running against a live/production relay (relay-live env, MCP_ENV=relay-live), this tool requires `confirm: true` to acknowledge that the SDK call may affect real users. Without it the call is rejected with a structured error. mock and relay-dev sessions are unaffected.\n\nIMPORTANT — 인자 시그니처 (잘못된 인자로 호출하면 토스 앱 crash 위험):\n  setDeviceOrientation:        call_sdk(\"setDeviceOrientation\", [{ type: \"landscape\" }])  // NOT \"landscape\"\n  setIosSwipeGestureEnabled:   call_sdk(\"setIosSwipeGestureEnabled\", [{ isEnabled: false }])\n  setSecureScreen:             call_sdk(\"setSecureScreen\", [{ enabled: true }])\n  setScreenAwakeMode:          call_sdk(\"setScreenAwakeMode\", [{ enabled: true }])\n  getOperationalEnvironment:   call_sdk(\"getOperationalEnvironment\", [])\n  getPlatformOS:               call_sdk(\"getPlatformOS\", [])\n  getDeviceId:                 call_sdk(\"getDeviceId\", [])\n  getLocale:                   call_sdk(\"getLocale\", [])\n  getNetworkStatus:            call_sdk(\"getNetworkStatus\", [])\n  getSchemeUri:                call_sdk(\"getSchemeUri\", [])\n  requestReview:               call_sdk(\"requestReview\", [])\n  closeView:                   call_sdk(\"closeView\", [])",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2197,7 +2319,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "get_diagnostics",
-		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (kind: mock|relay-dev|relay-live, env: mock|relay backward-compat, reason, liveGuardActive: true when relay-live LIVE guard is active), serverLockHolder (pid + startedAt from the lock file, or null), nextRecommendedAction ({tool, reason} or null — the single next tool to call). All fields are nullable — missing data is null, not an error. debug-mode only — dev-mode (--mode=dev) does not support relay diagnostics. Tier C (both mock and relay). Call this first when debugging session state.",
+		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (kind: mock|relay-dev|relay-live, env: mock|relay backward-compat, reason, liveGuardActive: true when relay-live LIVE guard is active), serverLockHolder (pid + startedAt from the lock file, or null), nextRecommendedAction ({tool, reason} or null — the single next tool to call; in local-target mode tunnel.up=false is normal so \"restart\" is never recommended). All fields are nullable — missing data is null, not an error. debug-mode only — dev-mode (--mode=dev) does not support relay diagnostics. Tier C (both mock and relay). Call this first when debugging session state.",
 		inputSchema: {
 			type: "object",
 			properties: { recent_errors_limit: {
@@ -2364,20 +2486,50 @@ function listPages(connection, tunnel) {
 * URL plus this session's live relay. Throws if the tunnel is not up yet (no
 * relay URL to splice in) — the caller surfaces that as a tool error.
 *
+* When `AIT_DEBUG_TOTP_SECRET` is set, generates the current TOTP code and
+* splices it as `at=<code>` into the attach URL. The code is valid for one
+* 30-second time step (±1 skew accepted by the relay, so the effective window
+* is up to 90 s). If the scan happens after `totp.expiresAt`, call
+* `build_attach_url` again to get a fresh code.
+*
 * Also validates the scheme URL's authority. A suspicious authority (empty,
 * "web", "localhost", etc.) is surfaced as a non-fatal `authorityWarning` on
 * the result so the caller can show a helpful hint without blocking the link
 * generation (the warning is consistent with how other validation in
 * `buildDeepLinkAttachUrl` works — hard errors for relay, soft warning for
 * the scheme authority which is in the caller's input, not ours to own).
+*
+* SECRET-HANDLING: `totpSecret` (if provided) is used only to compute a code
+* and must never appear in any log, error message, or output outside of the
+* spliced `at=` param in `attachUrl`.
+*
+* @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL.
+* @param tunnel - Current tunnel status from the running debug server.
+* @param totpSecret - Optional hex-encoded TOTP secret (from
+*   `AIT_DEBUG_TOTP_SECRET`). When provided, the current code is spliced into
+*   the attach URL as `at=<code>`.
 */
-function buildAttachUrl(schemeUrl, tunnel) {
+function buildAttachUrl(schemeUrl, tunnel, totpSecret) {
 	if (!tunnel.up || tunnel.wssUrl === null) throw new Error("tunnel-down: cloudflared 터널이 안 떠 있습니다. MCP 서버를 재시작하거나 잠시 후 list_pages로 터널 상태를 다시 확인하세요.");
 	const authorityWarning = validateSchemeAuthority(schemeUrl) ?? void 0;
+	let totpCode;
+	let totpMeta;
+	if (totpSecret !== void 0 && totpSecret !== "") {
+		const now = Date.now();
+		totpCode = generateTotp(totpSecret, now);
+		const STEP_SECONDS = 30;
+		const expiresAtMs = (Math.floor(now / 1e3 / STEP_SECONDS) + 1) * STEP_SECONDS * 1e3;
+		totpMeta = {
+			enabled: true,
+			ttlSeconds: STEP_SECONDS,
+			expiresAt: new Date(expiresAtMs).toISOString()
+		};
+	}
 	return {
-		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl),
+		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl, totpCode),
 		relayUrl: tunnel.wssUrl,
-		...authorityWarning !== void 0 ? { authorityWarning } : {}
+		...authorityWarning !== void 0 ? { authorityWarning } : {},
+		...totpMeta !== void 0 ? { totp: totpMeta } : {}
 	};
 }
 /**
@@ -2996,7 +3148,8 @@ function readDevtoolsVersion() {
 * Derives the next recommended action from a completed diagnostics snapshot.
 *
 * Branch rules (evaluated in priority order):
-*   1. tunnel.up === false                        → restart
+*   1. tunnel.up === false AND env is relay       → restart (relay needs a live tunnel)
+*   1b. tunnel.up === false AND env is mock       → wait_for_page (local target: tunnel-less is normal)
 *   2. tunnel.up, pages empty, env === relay      → build_attach_url (start attach)
 *   3. pages has entry + crashDetectedAt non-null → build_attach_url (re-attach after crash)
 *   4. otherwise                                  → null (session looks healthy)
@@ -3004,7 +3157,12 @@ function readDevtoolsVersion() {
 * Pure — does not throw; receives the final assembled snapshot fields.
 */
 function computeNextRecommendedAction(tunnel, pages, env) {
-	if (!tunnel.up) return {
+	if (!tunnel.up) if (!isRelayEnv(env)) {
+		if (pages !== null && pages.pages.length === 0 && !pages.crashDetectedAt) return {
+			tool: "wait_for_page",
+			reason: "local Chromium spawn 직후 — 페이지 로드를 기다리거나 list_pages를 재호출하세요 (local 모드는 tunnel이 없는 게 정상입니다)"
+		};
+	} else return {
 		tool: "restart",
 		reason: "tunnel not up — run `npx @ait-co/devtools devtools-mcp` to restart"
 	};
@@ -3069,83 +3227,6 @@ async function getDiagnostics(input) {
 	};
 }
 //#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.
@@ -3518,7 +3599,7 @@ function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs
 * naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, defaultEnv } = deps;
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, defaultEnv, totpSecret } = deps;
 	const resolveEnvironment = getEnvDep ?? (() => getEnvironment({
 		connection,
 		defaultEnv
@@ -3530,7 +3611,7 @@ function createDebugServer(deps) {
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.45"
+		version: "0.1.48"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const env = resolveEnvironment();
@@ -3574,7 +3655,7 @@ function createDebugServer(deps) {
 		if (name === "get_diagnostics") try {
 			const rawLimit = request.params.arguments?.recent_errors_limit;
 			const recentErrorsLimit = typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 10;
-			return jsonResult$1(await getDiagnostics({
+			const result = await getDiagnostics({
 				tunnel: getTunnelStatus(),
 				connection,
 				env: resolveEnvironment(),
@@ -3582,7 +3663,9 @@ function createDebugServer(deps) {
 				collector,
 				readLock: readServerLock,
 				recentErrorsLimit
-			}));
+			});
+			const attached = connection.listTargets().length > 0;
+			return envelopeResult$1(result, name, resolveEnvironment(), attached);
 		} catch (err) {
 			return errorResult(err, name);
 		}
@@ -3609,7 +3692,7 @@ function createDebugServer(deps) {
 				return `${baseText}\n\nNo page${deploymentId ? ` matching deploymentId=${deploymentId}` : ""} attached within ${timeoutSec}s${observedNote} — call list_pages to retry.`;
 			};
 			try {
-				const { attachUrl, relayUrl, authorityWarning } = buildAttachUrl(schemeUrl, getTunnelStatus());
+				const { attachUrl, relayUrl, authorityWarning, totp } = buildAttachUrl(schemeUrl, getTunnelStatus(), totpSecret);
 				const warningPrefix = authorityWarning ? `⚠️  scheme_url 경고: ${authorityWarning}\n\n` : "";
 				const header = "This tool result is shown to the user directly — do NOT re-print the QR below in your reply (it wastes output tokens). Just tell the user to scan the QR in this output (Ctrl+O to expand if collapsed).";
 				const guiAvailable = canOpenBrowser();
@@ -3618,7 +3701,8 @@ function createDebugServer(deps) {
 					const qrHeadless = await renderQr(attachUrl);
 					const headlessText = `${warningPrefix}${headlessNote}${header}\n${JSON.stringify({
 						attachUrl,
-						relayUrl
+						relayUrl,
+						...totp ? { totp } : {}
 					}, null, 2)}\n\n${qrHeadless}`;
 					if (!waitForAttach) return { content: [{
 						type: "text",
@@ -3654,7 +3738,8 @@ function createDebugServer(deps) {
 						};
 						const shortText = `${warningPrefix}${header}\n${JSON.stringify({
 							relayUrl,
-							openResult
+							openResult,
+							...totp ? { totp } : {}
 						}, null, 2)}\n\n브라우저에서 QR을 열었습니다${retriedNote}. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`;
 						if (!waitForAttach) return { content: [{
 							type: "text",
@@ -3693,7 +3778,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					const baseText = `${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
 						attachUrl,
 						relayUrl,
-						openResult
+						openResult,
+						...totp ? { totp } : {}
 					}, null, 2)}\n\n${qr}`;
 					if (!waitForAttach) return { content: [{
 						type: "text",
@@ -3721,7 +3807,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				const qr = await renderQr(attachUrl);
 				const baseText = `${warningPrefix}${header}\n${JSON.stringify({
 					attachUrl,
-					relayUrl
+					relayUrl,
+					...totp ? { totp } : {}
 				}, null, 2)}\n\n${qr}`;
 				if (!waitForAttach) return { content: [{
 					type: "text",
@@ -3756,7 +3843,9 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				if (connection instanceof ChiiCdpConnection) try {
 					await connection.refreshTargets();
 				} catch {}
-				return jsonResult$1(listPages(connection, getTunnelStatus()));
+				const pagesData = listPages(connection, getTunnelStatus());
+				const attached = connection.listTargets().length > 0;
+				return envelopeResult$1(pagesData, name, resolveEnvironment(), attached);
 			}
 			return classifyEnableDomainError(err, name);
 		}
@@ -3768,11 +3857,14 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					return jsonResult$1({ exceptions: listExceptions(connection, typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 50) });
 				}
 				case "list_network_requests": return jsonResult$1(listNetworkRequests(connection));
-				case "list_pages":
+				case "list_pages": {
 					if (connection instanceof ChiiCdpConnection) try {
 						await connection.refreshTargets();
 					} catch {}
-					return jsonResult$1(listPages(connection, getTunnelStatus()));
+					const listPagesData = listPages(connection, getTunnelStatus());
+					const listPagesAttached = connection.listTargets().length > 0;
+					return envelopeResult$1(listPagesData, name, resolveEnvironment(), listPagesAttached);
+				}
 				case "get_dom_document": return jsonResult$1(await getDomDocument(connection));
 				case "take_snapshot": return jsonResult$1(await takeSnapshot(connection));
 				case "take_screenshot": {
@@ -3783,7 +3875,11 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 						mimeType: shot.mimeType
 					}] };
 				}
-				case "measure_safe_area": return jsonResult$1(await measureSafeArea(connection, resolveEnvironment()));
+				case "measure_safe_area": {
+					const safeAreaData = await measureSafeArea(connection, resolveEnvironment());
+					const safeAreaAttached = connection.listTargets().length > 0;
+					return envelopeResult$1(safeAreaData, name, resolveEnvironment(), safeAreaAttached);
+				}
 				case "evaluate": {
 					const expression = request.params.arguments?.expression;
 					if (typeof expression !== "string" || expression === "") return mcpError("evaluate: expression 인자가 비어 있습니다. 평가할 JavaScript 표현식을 전달하세요.");
@@ -3798,7 +3894,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					if (isLiveRelayEnv(env) && request.params.arguments?.confirm !== true) return liveGuardError("call_sdk");
 					const sdkResult = await callSdk(connection, sdkName, sdkArgs);
 					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk");
-					return jsonResult$1(sdkResult);
+					const callSdkAttached = connection.listTargets().length > 0;
+					return envelopeResult$1(sdkResult, name, resolveEnvironment(), callSdkAttached);
 				}
 				default: return unknownTool(name);
 			}
@@ -3814,6 +3911,22 @@ function jsonResult$1(value) {
 		text: JSON.stringify(value, null, 2)
 	}] };
 }
+/**
+* Wraps `value` in a `ToolEnvelope` (when compat mode is off) and returns it
+* as a text content block. When `AIT_MCP_COMPAT=chrome-devtools` is set the
+* envelope is skipped and the raw value is returned — identical to `jsonResult`.
+*/
+function envelopeResult$1(value, tool, env, attached) {
+	const wrapped = wrapEnvelope(value, {
+		tool,
+		env,
+		attached
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(wrapped, null, 2)
+	}] };
+}
 function unknownTool(name) {
 	return mcpError(`알 수 없는 tool: ${name}`);
 }
@@ -3975,7 +4088,8 @@ async function runDebugServer(options = {}) {
 			return qrServer;
 		},
 		diagnosticsCollector,
-		defaultEnv: "relay-dev"
+		defaultEnv: "relay-dev",
+		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -4311,6 +4425,29 @@ const DEV_TOOL_DEFINITIONS = [
 		},
 		availableIn: "both"
 	},
+	{
+		name: "build_attach_url",
+		description: "Turns an `ait deploy --scheme-only` URL into a self-attaching deep link for a real device. NOT available in dev-mode — requires a live cloudflared relay (Tier B, relay-only). To use this tool: restart the MCP server with `--mode=debug` (or omit --mode) and set MCP_ENV=relay, then call build_attach_url to generate the QR for phone scanning. See: https://docs.aitc.dev/guides/debug-relay",
+		inputSchema: {
+			type: "object",
+			properties: {
+				scheme_url: {
+					type: "string",
+					description: "The intoss-private:// URL from `ait deploy --scheme-only`."
+				},
+				wait_for_attach: {
+					type: "boolean",
+					description: "If true, block until a page attaches."
+				},
+				open_in_browser: {
+					type: "boolean",
+					description: "If true (default), open the QR PNG in the OS browser."
+				}
+			},
+			required: ["scheme_url"]
+		},
+		availableIn: "relay"
+	},
 	{
 		name: "evaluate",
 		description: "Evaluates an arbitrary JavaScript expression via CDP Runtime.evaluate. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug` for CDP access.",
@@ -4401,6 +4538,12 @@ const CDP_ONLY_TOOL_NAMES = new Set([
 	"list_exceptions"
 ]);
 /**
+* Tier B tools — relay-only per RFC #277.
+* Listed in dev-mode tool surface (issue #323) so agents get a hand-off hint
+* toward `--mode=debug` instead of "Unknown tool".
+*/
+const TIER_B_TOOL_NAMES = new Set(["build_attach_url"]);
+/**
 * Builds the `list_pages` dev-mode shim response.
 * Returns the Vite dev URL as a single-entry page list with `devMode: true`.
 */
@@ -4515,13 +4658,14 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.45"
+		version: "0.1.48"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const name = request.params.name;
 		if (!DEV_TOOL_NAMES.has(name)) return mcpError(`알 수 없는 tool: ${name}`);
 		if (CDP_ONLY_TOOL_NAMES.has(name)) return mcpError(`${name}: ${CDP_UNAVAILABLE_IN_DEV_MODE}`);
+		if (TIER_B_TOOL_NAMES.has(name)) return tierRejectionError(name, "relay", "mock", "dev-mode — Vite HTTP endpoint, no CDP/relay connection. `--mode=debug` (または `devtools-mcp` without --mode) + MCP_ENV=relay로 재시작하세요.");
 		try {
 			const effective = name === "devtools_get_mock_state" ? "AIT.getMockState" : name;
 			if (isAitToolName(effective)) switch (effective) {
@@ -4531,13 +4675,13 @@ function createDevServer(deps = {}) {
 				default: return mcpError(`알 수 없는 tool: ${name}`);
 			}
 			switch (name) {
-				case "list_pages": return jsonResult(buildDevListPagesResult(devtoolsUrl));
-				case "get_diagnostics": return jsonResult(await buildDevDiagnostics(devtoolsUrl, stateEndpoint, (url) => fetch(url)));
-				case "measure_safe_area": return jsonResult(await buildDevMeasureSafeArea(aitSource));
+				case "list_pages": return envelopeResult("list_pages", buildDevListPagesResult(devtoolsUrl));
+				case "get_diagnostics": return envelopeResult("get_diagnostics", await buildDevDiagnostics(devtoolsUrl, stateEndpoint, (url) => fetch(url)));
+				case "measure_safe_area": return envelopeResult("measure_safe_area", await buildDevMeasureSafeArea(aitSource));
 				case "call_sdk": {
 					const sdkName = request.params.arguments?.name;
 					if (typeof sdkName !== "string" || sdkName === "") return mcpError("call_sdk: name 인자가 비어 있습니다. 호출할 메서드 이름을 전달하세요.");
-					return jsonResult(await buildDevCallSdk(sdkName, aitSource));
+					return envelopeResult("call_sdk", await buildDevCallSdk(sdkName, aitSource));
 				}
 				default: return mcpError(`알 수 없는 tool: ${name}`);
 			}
@@ -4553,6 +4697,26 @@ function jsonResult(value) {
 		text: JSON.stringify(value, null, 2)
 	}] };
 }
+/**
+* Wraps `value` in a `ToolEnvelope` (when compat mode is off) and returns it
+* as a text content block. In dev-mode `env` is always `'mock'` and
+* `attached` is always `true` (the Vite dev server is the single implicit
+* "attached" page).
+*
+* When `AIT_MCP_COMPAT=chrome-devtools` the envelope is skipped and the raw
+* value is returned — identical to `jsonResult` (0.1.x back-compat).
+*/
+function envelopeResult(tool, value) {
+	const wrapped = wrapEnvelope(value, {
+		tool,
+		env: "mock",
+		attached: true
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(wrapped, null, 2)
+	}] };
+}
 /** Builds the dev-mode server and connects it over stdio. */
 async function runDevServer() {
 	const server = createDevServer();