@ait-co/devtools 0.1.77 → 0.1.79

package/README.en.md

@@ -126,7 +126,7 @@ When `call_sdk` returns `ok: false, error: "window.__sdkCall is not available"`,
 
 **"QR scanned but auth rejected" — TOTP code expired**
 
-When `AIT_DEBUG_TOTP_SECRET` is set, `build_attach_url` automatically splices the current one-time TOTP code (`at=`) into the returned `attachUrl`. The code is valid for a 30-second step. Scanning after `totp.expiresAt` causes the relay to reject the request. Fix: call `build_attach_url` again to get a fresh URL and QR, then scan within 30 seconds.
+When `AIT_DEBUG_TOTP_SECRET` is set, `build_attach_url` automatically splices the current one-time TOTP code (`at=`) into the returned `attachUrl`. Each code covers a 30-second step, and the relay accepts ±6 steps (~3 min) of backwards skew. Scanning more than ~3 minutes after `totp.expiresAt` causes the relay to reject the request. Fix: call `build_attach_url` again to get a fresh URL and QR.
 
 ---
 
@@ -541,7 +541,7 @@ Each preset includes:
 - **CSS viewport** (portrait `width × height`)
 - **DPR** (devicePixelRatio: 2, 3, 3.5, etc.)
 - **Notch** type (`none` / `notch` / `dynamic-island` / `punch-hole-center`)
-- **Notch inset** — the OS notch / Dynamic Island offset. Device-specific. In portrait this does *not* reach the miniapp's top inset (it's only used for the landscape side inset and to position the visual notch overlay).
+- **Notch inset** — the OS notch / Dynamic Island offset. Device-specific. In portrait this does *not* reach the mini-app's top inset (it's only used for the landscape side inset and to position the visual notch overlay).
 - **Nav bar height** — the Toss host's top nav bar. Device-independent (`54px` for a `partner` WebView). For a `partner` app this height *is* `SafeAreaInsets.get().top`.
 - **Home-indicator inset** — the bottom safe-area inset (home indicator), device-specific.
 

package/README.md

@@ -98,7 +98,7 @@ import '@ait-co/devtools/in-app/auto';
 - **SDK 브리지**: `window.__sdk` / `window.__sdkCall`을 설치해 에이전트가 CDP relay의 `Runtime.evaluate`로 SDK API를 직접 구동할 수 있게 합니다. `@apps-in-toss/web-framework`가 없으면 조용히 skip합니다.
 - **타입**: `Window.__sdk` / `__sdkCall` 글로벌 타입을 자동으로 제공합니다 — 별도 `globals.d.ts` 불필요.
 
-환경 3·4(intoss-private relay) 빌드는 relay QR 딥링크가 `?debug=1&relay=<wss>` 파라미터를 실어 보내므로, 이 한 줄만 있으면 별도 게이트 코드가 필요 없습니다. 환경 2(PWA, `tunnel: { cdp: true }`)도 동일하게 동작합니다.
+환경 3·4(intoss-private relay) 빌드는 relay QR deep-link가 `?debug=1&relay=<wss>` 파라미터를 실어 보내므로, 이 한 줄만 있으면 별도 게이트 코드가 필요 없습니다. 환경 2(PWA, `tunnel: { cdp: true }`)도 동일하게 동작합니다.
 
 > TOTP 인증이 필요한 dogfood 빌드는 빌드 define으로 `__DEBUG_TOTP_SECRET__`을 주입하고 `@ait-co/devtools/in-app`을 직접 import해 `evaluateDebugGate({ verifyTotpCode })` + `maybeAttach()`를 사용하세요. `in-app/auto`는 TOTP verifier를 주입하지 않으므로 C3 레이어가 비활성화됩니다.
 
@@ -126,7 +126,7 @@ cloudflared quick tunnel은 수 시간 후 drop될 수 있습니다. `devtools-m
 
 **"QR 스캔했는데 인증 실패" — TOTP 만료**
 
-`AIT_DEBUG_TOTP_SECRET` 설정 시 `build_attach_url`이 반환하는 attachUrl에는 30초 유효 TOTP 코드(`at=`)가 자동으로 포함됩니다. 응답의 `totp.expiresAt` 이후 스캔하면 relay가 인증을 거부합니다. 해결: `build_attach_url`을 재호출해 새 URL과 QR을 발급받은 뒤 30초 이내에 스캔하세요.
+`AIT_DEBUG_TOTP_SECRET` 설정 시 `build_attach_url`이 반환하는 attachUrl에는 TOTP 코드(`at=`)가 자동으로 포함됩니다. 코드 1개는 30초 창이고, relay는 만료 후 ~3분(±6 step) 이내 소급을 허용합니다. 응답의 `totp.expiresAt`로부터 ~3분 이상 지난 뒤 스캔하면 relay가 인증을 거부합니다. 해결: `build_attach_url`을 재호출해 새 URL과 QR을 발급받으세요.
 
 ---
 
@@ -393,7 +393,7 @@ launcher는 **PWA(홈 화면 앱)로 실행할 때만 동작**합니다. 일반
 ### 3. 매 세션
 
 1. 데스크톱에서 `pnpm dev:phone`을 실행합니다 (1-(c) 스크립트를 추가하지 않았다면 `AIT_TUNNEL=1 pnpm dev`). 터미널에 `https://*.trycloudflare.com` URL + ASCII QR이 출력됩니다.
-2. 폰의 카메라(또는 launcher 아이콘 안의 "Scan QR")로 QR을 스캔합니다. QR은 `https://devtools.aitc.dev/launcher/?url=<tunnel>` 딥링크라 launcher PWA가 자동으로 열리고 그날의 dev 앱이 풀스크린으로 뜹니다 — URL 붙여넣기 단계가 필요 없습니다.
+2. 폰의 카메라(또는 launcher 아이콘 안의 "Scan QR")로 QR을 스캔합니다. QR은 `https://devtools.aitc.dev/launcher/?url=<tunnel>` deep-link라 launcher PWA가 자동으로 열리고 그날의 dev 앱이 풀스크린으로 뜹니다 — URL 붙여넣기 단계가 필요 없습니다.
 3. 다음 세션엔 새 QR을 스캔만 하면 됩니다. launcher는 마지막 URL을 기억하고, "Rescan" 버튼으로 언제든 교체할 수 있습니다.
 
 > QR을 일반 카메라 앱으로 찍었을 때 Safari/Chrome이 일반 탭이 아닌 설치된 launcher PWA로 곧장 라우팅하는 동작은 Android Chrome에서 가장 안정적이고, iOS Safari는 버전에 따라 일반 탭으로 폴백할 수 있습니다. 그 경우 launcher 홈 화면 아이콘에서 한 번 열어주면 그 안의 QR 스캐너로 다시 시도할 수 있습니다.
@@ -1017,7 +1017,7 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 
 #### 환경 2 (실기기 PWA CDP) — `--target=mobile`
 
-토스 검수 없이 실기기 WebKit 엔진에서 CDP 디버깅이 가능한 모드입니다. [`tunnel:{cdp:true}`](#tunnel-옵션)를 켠 Vite dev server가 앱 HTTP 터널과 Chii relay 터널을 두 개 띄우고, MCP는 그 relay에 붙어 `build_attach_url` → 런처 QR을 제공합니다.
+토스 검수 없이 실기기 WebKit 엔진에서 CDP 디버깅이 가능한 모드입니다. [`tunnel:{cdp:true}`](#tunnel-옵션)를 켠 Vite dev server가 앱 HTTP 터널과 Chii relay 터널을 두 개 띄우고, MCP는 그 relay에 붙어 `build_attach_url` → launcher QR을 제공합니다.
 
 **진입 절차:**
 
@@ -1050,7 +1050,7 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
    start_debug({mode: 'relay-sandbox'})
    build_attach_url()
    ```
-   QR을 폰 카메라로 스캔하면 런처 PWA가 앱을 프레임에 열고 Chii target.js를 주입합니다.
+   QR을 폰 카메라로 스캔하면 launcher PWA가 앱을 프레임에 열고 Chii target.js를 주입합니다.
 
 4. `list_pages()` → 페이지 1개 확인. `take_screenshot()` 등 CDP tool을 사용합니다.
 
@@ -1097,7 +1097,7 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
 | `list_console_messages` | `Runtime.consoleAPICalled` | 최근 console.log/warn/error 메시지 (level, text, timestamp, args) |
 | `list_network_requests` | `Network.requestWillBeSent` + `responseReceived` | 최근 XHR/fetch 요청 (url, method, status, timing) |
 | `list_pages` | Chii 릴레이 target 목록 | attach된 페이지 + tunnel 상태 + wss URL |
-| `build_attach_url` | (순수 합성) | `ait deploy --scheme-only` URL에 `debug=1`+릴레이 URL을 끼워 self-attach 딥링크 합성 → QR을 터미널 출력. QR을 폰 카메라로 스캔하는 것이 환경 2·3의 단일 진입 경로 (`list_pages` 먼저 필요) |
+| `build_attach_url` | (순수 합성) | `ait deploy --scheme-only` URL에 `debug=1`+릴레이 URL을 끼워 self-attach deep-link 합성 → QR을 터미널 출력. QR을 폰 카메라로 스캔하는 것이 환경 2·3의 단일 진입 경로 (`list_pages` 먼저 필요) |
 | `get_dom_document` | `DOM.getDocument` | DOM 트리 read (구조/레이아웃 회귀 진단) |
 | `take_snapshot` | `DOMSnapshot.captureSnapshot` | 페이지 스냅샷 (documents + interned strings, 시각 회귀 진단) |
 | `take_screenshot` | `Page.captureScreenshot` | 페이지 PNG 스크린샷 (MCP image content block 반환) |

package/dist/deeplink-B-94XmWA.js.map

@@ -1 +1 @@
-{"version":3,"file":"deeplink-B-94XmWA.js","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}
+{"version":3,"file":"deeplink-B-94XmWA.js","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dog-food deep-link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dog-food bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}

package/dist/deeplink-BLU2_hg6.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"deeplink-BLU2_hg6.cjs","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}
+{"version":3,"file":"deeplink-BLU2_hg6.cjs","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dog-food deep-link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dog-food bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}

package/dist/deeplink-CU6opogq.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"deeplink-CU6opogq.cjs","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}
+{"version":3,"file":"deeplink-CU6opogq.cjs","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dog-food deep-link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dog-food bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}

package/dist/deeplink-CYqDwVYs.js.map

@@ -1 +1 @@
-{"version":3,"file":"deeplink-CYqDwVYs.js","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}
+{"version":3,"file":"deeplink-CYqDwVYs.js","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dog-food deep-link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dog-food bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}