mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-20 04:59:34 +01:00
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:
1 parent
0b3087918f
commit
0ea97d62ec
4 files changed
+209
-4
No files matched your search
+20
-2
@@ -144,9 +144,17 @@ per-device (`localStorage`), since that is workspace layout rather than config.
|
||||
Worth knowing, because it is where this feature does its least obvious work. Three
|
||||
layers cooperate so a dashboard talking to its own backend just works:
|
||||
|
||||
1. `<base href>` handles relative URLs in the markup.
|
||||
1. `<base href>` handles relative URLs in the markup. A page that ships its own
|
||||
**relative** base (`<base href="./">`, what a Vite build emits) has it resolved
|
||||
against the proxy prefix first: the page's URL is masked a few paragraphs below,
|
||||
a base is resolved against that URL, so `./` would otherwise point at Codeman's
|
||||
root and 404 every module script behind an otherwise-painted page.
|
||||
2. Attribute rewriting handles root-absolute `src`/`href`/`action` in the page the
|
||||
proxy serves.
|
||||
proxy serves — and root-absolute dynamic `import("/...")` specifiers in the
|
||||
initial HTML. The import is the one URL no other layer can reach: `<base>` does
|
||||
not apply to a `/`-rooted specifier and it is not a `fetch()`. SvelteKit's inline
|
||||
bootstrap is exactly this shape; without the rewrite the module loads from
|
||||
Codeman's root, 404s, and the app sits on its own loading spinner forever.
|
||||
3. A small injected script rebases URLs built at **runtime**, which the first two
|
||||
cannot see: `fetch('/api/data')` and `new WebSocket('/live')`, but equally
|
||||
`card.innerHTML = '<img src="/api/hero">'`, `img.src = '/api/slide'`, and
|
||||
@@ -190,6 +198,16 @@ then every API call fails, which looks like the dashboard being broken.
|
||||
EventSource, normal markup, the DOM sinks a page uses to build markup at runtime,
|
||||
and `url()` inside stylesheets. Something that constructs requests by an unusual
|
||||
route can still slip through. Symptom: the page renders but a panel stays empty.
|
||||
- **Root-absolute URLs the proxy never sees.** Only the HTML is rewritten, and only
|
||||
literal `/`-rooted specifiers in it. Still escape: an `import()` built at runtime
|
||||
(`import('/' + name)`), an import written inside an external `.js`, a static
|
||||
`import x from "/x"` in an inline script, `navigator.serviceWorker.register("/sw.js")`,
|
||||
and `url(/img.png)` inside an external stylesheet. They cannot be relayed either —
|
||||
the masked frame's `Referer` carries no capability — so the failure is quiet: a
|
||||
blank page, or a spinner that never resolves. Codeman now logs
|
||||
`[Webview] <path> escaped the proxy` (once per path per five minutes) when such a
|
||||
request reaches its 404, which is the fastest way to tell this class apart from a
|
||||
dashboard that is genuinely broken.
|
||||
- **A root-absolute `url()` inside an inline `<style>` is not rescued.** Masking the
|
||||
page's URL (layer 5) trades away the `Referer` safety net of layer 4 for
|
||||
requests the shim cannot see, and only HTML is rewritten server-side. An
|
||||
|
||||
+38
-1
@@ -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
|
||||
|
||||
@@ -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
|
||||
);
|
||||
|
||||
|
||||
@@ -13,6 +13,7 @@ import {
|
||||
buildUpstreamRequestHeaders,
|
||||
capabilityFromProxyPath,
|
||||
capabilityFromReferer,
|
||||
escapedWebviewAssetPath,
|
||||
extractFrameAncestors,
|
||||
filterCookieHeader,
|
||||
isFramableCrossOrigin,
|
||||
@@ -398,6 +399,27 @@ describe('rewriteHtml', () => {
|
||||
expect(rewriteHtml('just text', CAP)).toContain('<script>');
|
||||
});
|
||||
|
||||
// SvelteKit's inline bootstrap does `import("/_app/…")`. A dynamic import is
|
||||
// neither an attribute nor a fetch(), so `<base>` and the runtime shim both
|
||||
// miss it and the module loads from Codeman's root — the app then sits on its
|
||||
// own spinner forever.
|
||||
it('rewrites root-absolute dynamic import() specifiers', () => {
|
||||
const dq = rewriteHtml('<head><script>import("/_app/entry.js")</script></head>', CAP);
|
||||
expect(dq).toContain(`import("${PREFIX}_app/entry.js")`);
|
||||
const sq = rewriteHtml("<head><script>import( '/x.js' )</script></head>", CAP);
|
||||
expect(sq).toContain(`import('${PREFIX}x.js' )`);
|
||||
});
|
||||
|
||||
it('leaves relative and cross-origin import() specifiers alone', () => {
|
||||
const out = rewriteHtml(
|
||||
`<head><script>import("./a.js");import("//cdn.example/b.js");import("https://cdn.example/c.js")</script></head>`,
|
||||
CAP
|
||||
);
|
||||
expect(out).toContain('import("./a.js")');
|
||||
expect(out).toContain('import("//cdn.example/b.js")');
|
||||
expect(out).toContain('import("https://cdn.example/c.js")');
|
||||
});
|
||||
|
||||
it('rebases root-absolute src/href/action, which <base> cannot fix', () => {
|
||||
const out = rewriteHtml(
|
||||
`<head></head><body><script src="/static/app.js"></script><link href='/s.css'><form action="/login"></form></body>`,
|
||||
@@ -898,3 +920,55 @@ describe('lost-frame recovery', () => {
|
||||
expect(has({ authorization: 'Basic YWRtaW46eA==' })).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('escapedWebviewAssetPath: naming a 404 a web tab caused', () => {
|
||||
const req = (over: Record<string, unknown> = {}) => ({
|
||||
method: 'GET',
|
||||
url: '/_app/immutable/entry/start.js',
|
||||
...over,
|
||||
headers: {
|
||||
host: 'codeman.example:3001',
|
||||
referer: 'http://codeman.example:3001/',
|
||||
'sec-fetch-dest': 'script',
|
||||
...((over.headers as Record<string, string | string[] | undefined> | undefined) ?? {}),
|
||||
},
|
||||
});
|
||||
|
||||
it('recognises a root-absolute module a masked frame asked for', () => {
|
||||
expect(escapedWebviewAssetPath(req())).toBe('/_app/immutable/entry/start.js');
|
||||
});
|
||||
|
||||
it('drops the query string, which carries no diagnostic value', () => {
|
||||
expect(escapedWebviewAssetPath(req({ url: '/_app/x.js?v=17' }))).toBe('/_app/x.js');
|
||||
});
|
||||
|
||||
it('ignores every shape that is not a dashboard asset', () => {
|
||||
// A navigation is the lost-frame recovery's job, not this one's.
|
||||
expect(
|
||||
escapedWebviewAssetPath(req({ headers: { host: 'h', referer: 'http://h/', 'sec-fetch-dest': 'document' } }))
|
||||
).toBeNull();
|
||||
// Codeman's own missing files say nothing about a web tab.
|
||||
expect(
|
||||
escapedWebviewAssetPath(
|
||||
req({ url: '/favicon.ico', headers: { host: 'h', referer: 'http://h/', 'sec-fetch-dest': 'image' } })
|
||||
)
|
||||
).toBeNull();
|
||||
// A real Codeman page's assets resolve; only a masked landing (`/`) is this shape.
|
||||
expect(
|
||||
escapedWebviewAssetPath(req({ headers: { host: 'h', referer: 'http://h/settings', 'sec-fetch-dest': 'script' } }))
|
||||
).toBeNull();
|
||||
// Cross-origin referer, API paths, writes, and no referer at all.
|
||||
expect(
|
||||
escapedWebviewAssetPath(req({ headers: { host: 'h', referer: 'http://other/', 'sec-fetch-dest': 'script' } }))
|
||||
).toBeNull();
|
||||
expect(escapedWebviewAssetPath(req({ url: '/api/thing' }))).toBeNull();
|
||||
expect(escapedWebviewAssetPath(req({ method: 'POST' }))).toBeNull();
|
||||
expect(escapedWebviewAssetPath(req({ headers: { host: 'h' } }))).toBeNull();
|
||||
});
|
||||
|
||||
it('accepts the array headers a proxy front end can produce', () => {
|
||||
expect(
|
||||
escapedWebviewAssetPath(req({ headers: { host: ['h'], referer: ['http://h/'], 'sec-fetch-dest': ['image'] } }))
|
||||
).toBe('/_app/immutable/entry/start.js');
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user