chore(webview): name a root-absolute request that escapes the proxy

When a web tab's boot module (or any asset it builds at runtime) escapes the
`/webview/<cap>/` prefix, the request reaches Codeman's 404 with nothing to relay
to: the frame's document URL is masked, so its `Referer` carries no capability
and the existing fallback declines. The tab then shows a blank page or a spinner
that never resolves, and the log says nothing — the failure mode that made the
DeepSeek Harness tab un-diagnosable twice.

Classify that shape conservatively on the 404 path (asset-shaped
`Sec-Fetch-Dest`, same-origin `Referer` at the masked landing path, not `/api`,
not one of Codeman's own files) and log the path once per five minutes. Nothing
is relayed or rewritten: this only turns a silent blank tab into one grep.

Also document the boundary in `docs/web-tabs.md` — the root-absolute URLs the
proxy never sees (runtime-built `import()`, imports inside external `.js`, static
imports in inline scripts, service-worker registration, `url()` in external
stylesheets) — so the next occurrence starts from the list instead of from zero.
This commit is contained in:
ArizeSky committed 2026-11-16 10:09:37 +08:00
1 parent 0b3087918f
commit 0ea97d62ec
4 files changed
+209 -4

No files matched your search

+38 -1
View File
@@ -269,7 +269,7 @@ import {
registerCliRegistryRoutes,
registerLocalModelRoutes,
} from './routes/index.js';
import { isLostWebviewFrameNavigation } from './webview-proxy.js';
import { escapedWebviewAssetPath, isLostWebviewFrameNavigation } from './webview-proxy.js';
import { CronService } from '../cron/cron-service.js';
import { caseSessionSettled } from '../case-rename.js';
@@ -361,6 +361,38 @@ function getOrCreateSelfSignedCert(): { key: string; cert: string } {
};
}
/**
* One warn per escaped path per few minutes.
*
* A page whose boot module 404s retries in a loop, so an undeduped warn would
* bury the log it is meant to explain. Capped so a page emitting unbounded
* unique paths cannot grow the map without limit.
*/
const escapedWebviewWarnedAt = new Map<string, number>();
const ESCAPED_WEBVIEW_WARN_TTL_MS = 5 * 60_000;
/**
* Name a root-absolute request that escaped a web tab's proxy prefix.
*
* Nothing is retried or rewritten here — the request genuinely has no capability
* to relay to. This exists because that failure is otherwise silent: the tab
* shows a blank page or a spinner that never resolves, and the log says nothing.
*
* @param path - request path already judged as that shape.
*/
function warnEscapedWebviewAsset(path: string): void {
const now = Date.now();
const last = escapedWebviewWarnedAt.get(path);
if (last !== undefined && now - last < ESCAPED_WEBVIEW_WARN_TTL_MS) return;
if (escapedWebviewWarnedAt.size >= 200) escapedWebviewWarnedAt.clear();
escapedWebviewWarnedAt.set(path, now);
console.warn(
`[Webview] ${path} escaped the proxy: a web tab asked for a root-absolute URL that no Codeman route serves. ` +
`Its URL is masked, so the Referer cannot identify the dashboard. Usual cause: a URL built at runtime ` +
`(dynamic import(), worker, service worker) or an import inside an external script. The tab will look blank or stuck.`
);
}
export class WebServer extends EventEmitter {
private app: FastifyInstance;
private sessions: Map<string, Session> = new Map();
@@ -1294,6 +1326,11 @@ export class WebServer extends EventEmitter {
// and the relay declines unless the Referer carries a live capability, so
// genuinely unknown `/api` paths still get the envelope below.
if (await tryWebviewRefererFallback(req, reply, this.basePath)) return reply;
// No capability in the Referer, so this cannot be relayed — but if it has
// the shape of a dashboard asset, say so once. Silent 404s here are what
// turned a boot-module failure into a "blank tab" mystery more than once.
const escaped = escapedWebviewAssetPath({ method: req.method, url: req.url, headers: req.headers });
if (escaped) warnEscapedWebviewAsset(escaped);
// An authenticated web-tab frame (Basic auth, or trusted mode with a cookie)
// that navigated itself off its proxy prefix: the runtime shim masks the
// prefix so the page's router sees its own path, and a reload of that page
+77 -1
View File
@@ -207,6 +207,73 @@ export function capabilityFromReferer(referer: string | undefined, basePath = ''
}
}
/** `Sec-Fetch-Dest` values that describe a page fetching for itself, not navigating. */
const ASSET_FETCH_DESTS = new Set([
'script',
'style',
'image',
'font',
'manifest',
'worker',
'sharedworker',
'audio',
'video',
'track',
'embed',
'object',
'empty',
]);
/** Codeman's own missing files: a 404 here says nothing about a web tab. */
const CODEMAN_OWN_404 =
/^\/(?:favicon\.ico|manifest\.json|manifest\.webmanifest|robots\.txt|apple-touch-icon[\w.-]*)$/i;
/**
* Whether a 404 looks like a proxied dashboard's root-absolute request that
* escaped the prefix.
*
* This decides NOTHING about the response — the request cannot be relayed (a
* masked frame's `Referer` carries no capability, which is exactly why the
* Referer fallback above declined). It exists so the failure is diagnosable:
* the symptom of an escaped URL is a blank page or a spinner that never
* resolves, with nothing in the log to say why. Naming the path turns that into
* one grep.
*
* Deliberately conservative — a masked landing frame (`Referer` path `/`), an
* asset-shaped `Sec-Fetch-Dest`, same origin, not the API, not one of Codeman's
* own files. A false positive is a log line, never a behaviour change.
*
* @param input - method, request URL and headers of the 404.
* @returns the escaped path (no query), or null when it is not that shape.
*/
export function escapedWebviewAssetPath(input: {
method: string;
url: string;
headers: Record<string, string | string[] | undefined>;
}): string | null {
if (input.method !== 'GET' && input.method !== 'HEAD') return null;
const path = input.url.split('?')[0] ?? '';
if (path.startsWith('/api') || CODEMAN_OWN_404.test(path)) return null;
const single = (value: string | string[] | undefined): string | undefined =>
Array.isArray(value) ? value[0] : value;
const dest = single(input.headers['sec-fetch-dest']);
if (!dest || !ASSET_FETCH_DESTS.has(dest.toLowerCase())) return null;
const host = single(input.headers.host);
const referer = single(input.headers.referer);
if (!host || !referer) return null;
try {
const from = new URL(referer);
// Same origin, and the masked landing path: a real Codeman page's assets all
// resolve, so a 404 from one is not this shape.
if (from.host !== host || from.pathname !== '/') return null;
} catch {
return null;
}
return path;
}
/** Remove the `frame-ancestors` directive from a CSP, preserving the rest. */
export function stripFrameAncestors(csp: string): string {
return csp
@@ -718,7 +785,16 @@ export function rewriteHtml(html: string, capability: string, basePath = ''): st
const rebased = rebaseRelativeBase(
html
.replace(/(\s(?:src|href|action)\s*=\s*")\/(?!\/)/gi, `$1${prefix}`)
.replace(/(\s(?:src|href|action)\s*=\s*')\/(?!\/)/gi, `$1${prefix}`),
.replace(/(\s(?:src|href|action)\s*=\s*')\/(?!\/)/gi, `$1${prefix}`)
// A root-absolute dynamic `import()` is the one URL no other layer can
// reach: it is not an attribute, so `<base>` does not apply to it; it is
// not `fetch()`, so the runtime shim cannot rewrite it; and the browser
// resolves it against the ORIGIN root, not the document. SvelteKit's
// inline bootstrap is exactly this shape (`import("/_app/…")`), and the
// failure mode is silent: the module 404s against Codeman and the app's
// own loading spinner never resolves. Rewriting the specifier here is the
// only layer that can.
.replace(/\bimport\s*\(\s*(["'])\/(?!\/)/g, (_match, quote: string) => `import(${quote}${prefix}`),
prefix
);