feat(web-tabs): open dashboard URLs as tabs beside agent sessions

Adds a "Web / URL" section to the Run dropdown. A saved URL renders as a tab in
the same strip as Claude/Codex/Gemini sessions, with the same Alt+1..9 numbering,
so Codeman is one mission control instead of Codeman plus a pile of browser tabs.

A webview is NOT a sixth SessionMode: no PTY, no tmux, no respawn, no idle
detection. It is a separate resource sharing only the tab strip and the main
content area, the same call that keeps Docker and remote-SSH as case overlays.

Dashboards are proxied through Codeman's own origin, because a direct iframe
fails three ways at once in the shipped deployment: prod serves HTTPS behind
tailscale serve, so http:// targets are hard-blocked as mixed content (with no
override at all on iOS Safari); Grafana/Portainer-class dashboards send
X-Frame-Options: DENY; and our own default-src 'self' CSP blocks cross-origin
frames. Proxying dissolves all three and leaves the production CSP byte-for-byte
unchanged, since /webview/... is already covered by 'self'. A useful side effect:
the fetch happens server-side, so a tailnet-only dashboard is reachable from a
phone that is not on the tailnet.

The proxy is not an API surface. It authenticates on a 192-bit capability in the
path (memory-only, rolling TTL, bound to the minting user, revoked on edit or
delete) and is correspondingly exempt from the cookie and Origin checks, because
a sandboxed iframe is opaque-origin: it sends no SameSite=lax cookie and its
writes arrive with Origin: null. The Host allowlist is never bypassed. A second
Referer-keyed form of the exemption exists for root-absolute assets and is fenced
to safe methods on non-/api, non-/ws, non-/q paths.

Iframes omit allow-same-origin unless a URL is explicitly marked trusted, since a
proxied page is served from Codeman's own origin and could otherwise read this
document and drive the agent-spawning API. Authorization and codeman_session are
stripped upstream in BOTH modes, so CODEMAN_PASSWORD cannot leak into a dashboard.

Two things only a real browser reveals, both presenting as the dashboard's own
"Failed to fetch" while the page itself renders fine:

- Runtime-built root-absolute URLs (fetch('/api/data')) escape <base href> and
  land on Codeman's root. Widening the Referer fallback into /api would trade
  security for it, so an injected shim patches fetch/XHR/WebSocket/EventSource
  inside the frame instead, removing the class rather than the guard.
- An opaque-origin document CORS-checks every request, including to the host it
  was served from. Script/css/img loads are not CORS-checked, which is why the
  page renders while its API calls die. The proxy now emits CORS headers and
  answers preflights itself. registerSecurityHeaders answered every OPTIONS with
  a bare 204 before routing, carrying no ACAO for Origin: null, so that
  short-circuit now exempts a valid capability.

Neither is reproducible with curl, which does not enforce CORS.

Also fixes a pre-existing bug found on the way: .toolbar has backdrop-filter,
making it a stacking context that trapped .run-mode-menu's z-index:1000, so
.welcome-overlay painted over the whole Run menu. With no session open, every
item in it (Claude Code included) was unclickable.

Verified end to end against a real tailnet dashboard: live data, WebSocket push,
no failed requests, and switching tabs does not reload the frame. 98 new tests
cover the pure rewrite helpers, the CORS helper, the shim's rewrite logic, route
CRUD, and every edge of the auth exemption.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer
2026-07-27 17:06:36 +02:00
parent ea4c935d51
commit b34fcaf928
26 changed files with 3316 additions and 18 deletions
+1
View File
@@ -70,3 +70,4 @@ export * from './update.js';
export * from './workflow-run.js';
export * from './search.js';
export * from './user.js';
export * from './webview.js';
+87
View File
@@ -0,0 +1,87 @@
/**
* @fileoverview Web tab (dashboard) types.
*
* A "webview" is a saved URL that Codeman renders as a tab alongside agent
* sessions: Grafana on :3000, a Uptime-Kuma on :4000, an internal status page.
* It is deliberately NOT a sixth `SessionMode`, it has no PTY, no tmux, no
* respawn and no idle detection. Same reasoning that keeps Docker and remote-SSH
* as case overlays rather than modes.
*
* Key exports:
* - Webview, the persisted record (`~/.codeman/webviews.json`).
* - WebviewEmbedMode, 'proxy' (served through Codeman's origin) or 'direct'
* (a plain cross-origin iframe, only viable for HTTPS targets that allow framing).
* - WebviewProbe, the result of the server-side reachability/framing probe.
* - WebviewOpenData, what `POST /api/webviews/:id/open` hands the browser.
*
* No I/O here. Persistence lives in `src/webview-store.ts`, capability minting in
* `src/webview-capabilities.ts`, the proxy helpers in `src/web/webview-proxy.ts`.
*/
/**
* How the browser should embed a webview.
*
* - `proxy`: the iframe points at `/webview/<capability>/` on Codeman's own
* origin and the server relays to the target. Required whenever the target is
* plain HTTP (an HTTPS Codeman page cannot embed it: mixed content) or refuses
* framing via `X-Frame-Options` / `frame-ancestors`.
* - `direct`: the iframe points at the target URL itself. Cheaper, but only works
* for HTTPS targets that permit framing, and needs the target origin added to
* the page CSP's `frame-src`.
*/
export type WebviewEmbedMode = 'proxy' | 'direct';
/** A saved dashboard, persisted to `~/.codeman/webviews.json`. */
export interface Webview {
id: string;
/** Display name shown on the tab. */
name: string;
/** Absolute target URL. `http:` / `https:` only, never with embedded credentials. */
url: string;
/** Optional single-glyph tab icon (emoji or letter). */
icon?: string;
/** Default embed strategy for this dashboard. */
embedMode: WebviewEmbedMode;
/**
* When false (the default) the iframe is sandboxed WITHOUT `allow-same-origin`,
* so a proxied page runs in an opaque origin and cannot read the Codeman page or
* call its API. Setting this to true trades that isolation for the page's own
* cookies/localStorage, only for dashboards the user fully trusts.
*/
trusted: boolean;
/** Multi-user owner (username). Undefined in single-user mode. */
owner?: string;
createdAt: number;
lastOpenedAt?: number;
}
/** Result of the server-side probe used by the "Test" button in the editor. */
export interface WebviewProbe {
/** True when the server could complete an HTTP request to the target. */
reachable: boolean;
/** Upstream status code, when a response came back. */
status?: number;
/** Raw `X-Frame-Options` value, if the target sent one. */
xFrameOptions?: string;
/** The `frame-ancestors` directive extracted from the target's CSP, if any. */
frameAncestors?: string;
/** True when the target permits being framed cross-origin by this Codeman. */
framable: boolean;
/** Strategy the UI should default to for this URL. */
recommendedMode: WebviewEmbedMode;
/** Human-readable explanation of the recommendation (or the failure). */
reason: string;
}
/** Payload of `POST /api/webviews/:id/open`. */
export interface WebviewOpenData {
/** The webview being opened (echoed so the client can refresh its copy). */
webview: Webview;
/**
* Same-origin path the iframe should load. Present for `proxy` mode only;
* `direct` mode uses `webview.url` instead.
*/
embedUrl?: string;
/** Epoch ms at which the capability behind `embedUrl` stops working. */
expiresAt?: number;
}