feat(auth): inject MCP_INSPECTOR_API_TOKEN into served index.html (#1378)

[cliffhall]

Closes #1378.

Problem

Reloading the web client at the bare URL (no ?MCP_INSPECTOR_API_TOKEN=… query string) with an empty sessionStorage made every /api/* request 401 — the browser had no way to recover the backend's auth token. Same failure for bookmarks and hand-typed URLs.

Change (Option 1 from the issue — HTML template injection)

The backend already knows the token at index.html serve time, so it now embeds it into the page on every load:

• New shared helper clients/web/server/inject-auth-token.ts — inserts <script>window.__INSPECTOR_API_TOKEN__ = "…"</script> (before </head>, falling back to </body> then prepend). Escapes </script> so a user-supplied token can't break out of the tag. No-op for an empty token (DANGEROUSLY_OMIT_AUTH).
• Dev (vite-hono-plugin.ts) — injects via Vite's transformIndexHtml hook.
• Prod (server.ts) — injects on the / route.
• App.tsx getAuthToken() — reads window.__INSPECTOR_API_TOKEN__ first, then the ?MCP_INSPECTOR_API_TOKEN=… query string, then sessionStorage. Both fallbacks are preserved, so pasted full URLs keep working.
• Shared global name lives in INSPECTOR_API_TOKEN_GLOBAL (core/mcp/remote/constants.ts).

Acceptance criteria

• Reload at bare URL + empty sessionStorage loads the app and calls /api/* without 401 — verified against a live npm run dev: root injects the global, unauthenticated /api/config → 401, injected token → 200.
• Launcher banner URL still works (query-string path retained as fallback).
• Integration test exercises the real prod server's / → /api/* flow (server-token-injection.test.ts) plus helper unit coverage (inject-auth-token.test.ts).
• AGENTS.md documents the token-recovery order and the new file.

Testing

npm run validate, npm run test:integration (491 passed), and npm run test:storybook (322 passed) all green.

🤖 Generated with Claude Code

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 2m 55s —— View job

---

Code Review

• Read changed files
• Analyze injection helper for security/correctness
• Review dev (Vite plugin) and prod (Hono server) integration
• Review App.tsx token resolution order
• Review test coverage
• Post review

Summary

Clean, well-scoped fix. The XSS hardening (JSON-stringify + </script> escape), the dev/prod symmetry (single shared helper), and the documented three-tier recovery order in App.tsx/AGENTS.md are all solid. Tests cover the helper unit-level plus an end-to-end / → /api/* round-trip against the real Hono server. Nothing here looks blocking.

A few observations worth thinking about before/after merge:

---

1. Latent: prod serveStatic SPA fallback serves an un-injected index.html

clients/web/server/server.ts:64-90 registers app.get("/", …) (injects) ahead of app.use("/*", serveStatic({ rewriteRequestPath: …→ "/index.html" })). The / route is fine, but any other path with no dot and no /api prefix (e.g. /oauth/callback — the browser OAuth landing URL, core/auth/browser/providers.ts:40) falls through to serveStatic, which rewrites to /index.html and serves the raw file straight off disk — bypassing the injection helper entirely.

For the OAuth round-trip specifically it likely still works in practice, because the token was saved to sessionStorage on the original launcher-banner load and the App.tsx:105-109 sessionStorage backstop picks it up. But that means the PR's "bare-URL reload works" property is /-only — a bookmark or hand-typed reload at /oauth/callback (or any future SPA route) with empty sessionStorage would 401 again.

Cheapest fix: read the file once, run it through injectAuthToken, and serve it from a small SPA-fallback handler before serveStatic (or hook a transformIndexHtml-equivalent into the static middleware). Fix this →

2. Minor: getAuthToken() doesn't persist fromGlobal into sessionStorage

clients/web/src/App.tsx:84-110 saves to sessionStorage only on the URL-param branch (lines 96-103). If a user only ever loads through injection (the new common case), sessionStorage stays empty — so the third-tier backstop never gets primed, and any later navigation that loses the global (e.g. point #1 above, or an iframe load that doesn't get the inject) has nothing to fall back to.

One-line fix: after if (typeof fromGlobal === "string" && fromGlobal), do the same best-effort sessionStorage.setItem(STORAGE_KEY, fromGlobal) you do for the URL path, then return. Keeps the comment block accurate ("URL value is persisted… so a later navigation that drops it still authenticates" — that intent applies to the injected global too). Fix this →

3. Minor: no Cache-Control on the injected / response

server.ts:64-77 returns c.html(injectAuthToken(html, resolvedAuthToken)) with no cache headers. The token is regenerated on every server start (randomBytes(32) at line 45 when no env override), so a browser- or proxy-cached page carrying a stale token would 401 after a server restart until the user hard-reloads. Low impact for a local dev tool, but a Cache-Control: no-store on this response would be cheap insurance and matches the "fresh token per page load" intent.

4. Nice catches I want to call out positively

• serializeTokenForScript (inject-auth-token.ts:22-24) is the right combination — JSON.stringify for quote/backslash/control-char safety, plus the < → < escape to defuse </script> early-close. The test at inject-auth-token.test.ts:41-51 is exactly the case I'd worry about and it's exercised.
• apply: "serve" + VITEST early-return in vite-hono-plugin.ts:48-58 keeps the plugin inert during Storybook/component tests. Good guard.
• INSPECTOR_API_TOKEN_GLOBAL centralizes the magic string across helper, constants, App.tsx, and the two test files. No drift risk.
• dangerouslyOmitAuth path correctly produces an empty resolvedAuthToken and injectAuthToken("…", "") is a documented no-op — matches the "no banner URL token" behavior so the global stays absent when auth is off.

---

• Branch: v2/auto-inject-api-token

[cliffhall]

Thanks for the review — addressed all three points in 025f06a.

1. Prod serveStatic SPA fallback served un-injected index.html — Fixed. Refactored server.ts to a shared serveIndexHtml helper and added an app.get("*") SPA fallback after serveStatic: real assets (paths with a dot) still serve verbatim, but any non-/api route that doesn't resolve to a file (e.g. /oauth/callback) now serves the injected HTML. Removed the old rewriteRequestPath that routed SPA paths to the raw file. Added integration tests: /oauth/callback carries the token, real asset.js serves verbatim, and unknown /api/* routes 404 rather than falling through to the shell. (Good catch that this is material for the OAuth landing URL — it's why #1379 stacks on this.)

2. getAuthToken() didn't persist fromGlobal — Fixed. Extracted a persist() helper and call it on both the injected-global and URL-param branches, so the sessionStorage backstop is primed even when the token only ever arrives via injection. Updated the comment to match.

3. No Cache-Control on injected / — Fixed. serveIndexHtml sets Cache-Control: no-store on every injected HTML response (both / and the SPA fallback), so a page carrying a token isn't served stale after a restart regenerates it. Added a test asserting the header on both routes.

Thanks also for the positive callouts on serializeTokenForScript, the VITEST/apply: "serve" guards, and the centralized INSPECTOR_API_TOKEN_GLOBAL — kept all of those as-is.

Note: this is the base of a 4-PR stack (#1383 → #1385 → #1387 build on it). I'll propagate these base changes up the stack when we merge down, or sooner if you'd prefer — let me know.