A missing asset is a 404, only a read serves a file, and web-root containment is a boundary (#1311) #1312

Merged
jaylouisw merged 1 commit from fix/static-surface into main 2026-11-10 01:25:45 +00:00
Owner

A missing asset is a 404, only a read serves a file, and web-root containment is a boundary.

Fixes #1311.

Pointing at the static server with the request-level lens used for #1307 and #1309. Three defects — and one of them
was pinned by a test that asserted the wrong thing.

1. A missing file was answered with the app

GET /nope.js   -> 200  text/html; charset=utf-8   <!DOCTYPE html> ...
GET /nope.png  -> 200  text/html

serveStatic() fell back to index.html for anything it could not read. This app has no client-side routes — one
page with tabs — so the fallback served no deep link that matters and instead hid every wrong filename: the
browser's only report is Uncaught SyntaxError: Unexpected token '<', in a file the reader can no longer identify.

2. The method was ignored

POST /index.html    -> 200 (the document)
DELETE /index.html  -> 200

A client that POSTs could conclude its write landed. HEAD returned a body too, including on the gzip branch.

3. Containment was a string prefix, not a path boundary

if (filePath.indexOf(WEB_DIR) !== 0) { 403 }

indexOf(WEB_DIR) === 0 also accepts …/web-backup/…, a sibling whose name merely starts with web. Nothing
exploits it today — the URL parser collapses .. before the path is joined — but a check that is only safe because
another component happens to clean up first is not a check, and the next directory added beside web/ inherits it.

A test was pinning the defect

test/server-static-cache.test.js asserted:

ok(missing.status === 200, 'a missing asset falls back to the app rather than 404');
ok(contentType.indexOf('text/html') === 0, 'and is served as HTML');

The behaviour was not merely untested, it was specified in the wrong direction — which is why it survived. Those
two assertions are corrected rather than deleted, so the change of intent is visible in the diff.

Fixes

A path with an extension that does not exist → 404 text/plain; a path with no extension → still opens the app;
POST/PUT/DELETE/PATCH → 405 with Allow: GET, HEAD; HEAD → no body on every branch including gzip;
containment → filePath === WEB_DIR || filePath.startsWith(WEB_DIR + path.sep).

Evidence

test/static-surface.test.js — 19 checks over real HTTP:

  • the app is served, with correct content types for .js and .css;
  • five file-shaped misses are 404s and none of them is the document;
  • twelve escape attempts (.., %2e%2e, ..%2f, //, mixed separators, package.json, engine source) all
    fail to return server or engine source;
  • four write methods are 405 with Allow;
  • HEAD has no body and the length a GET would send, including with Accept-Encoding: gzip;
  • ETag and If-Modified-Since still revalidate to an empty 304, while a stale tag still gets the bytes;
  • the boundary property is pinned in the source too, because HTTP cannot reach the difference.

With server/index.js reverted, 4 of the 19 fail — /nope.js → 200 text/html, both boundary checks, and
POST → 200 with no Allow header.

docs/ARCHITECTURE.md: "What the static server answers" — the table, and why the second row mattered.

Suite: 171 suites, 6,897 assertions, 0 failed.

A missing asset is a 404, only a read serves a file, and web-root containment is a boundary. Fixes #1311. Pointing at the static server with the request-level lens used for #1307 and #1309. Three defects — and one of them was pinned by a test that asserted the wrong thing. ## 1. A missing file was answered with the app ``` GET /nope.js -> 200 text/html; charset=utf-8 <!DOCTYPE html> ... GET /nope.png -> 200 text/html ``` `serveStatic()` fell back to `index.html` for anything it could not read. This app has **no client-side routes** — one page with tabs — so the fallback served no deep link that matters and instead hid every wrong filename: the browser's only report is `Uncaught SyntaxError: Unexpected token '<'`, in a file the reader can no longer identify. ## 2. The method was ignored ``` POST /index.html -> 200 (the document) DELETE /index.html -> 200 ``` A client that POSTs could conclude its write landed. `HEAD` returned a body too, including on the gzip branch. ## 3. Containment was a string prefix, not a path boundary ```js if (filePath.indexOf(WEB_DIR) !== 0) { 403 } ``` `indexOf(WEB_DIR) === 0` also accepts `…/web-backup/…`, a sibling whose name merely starts with `web`. Nothing exploits it today — the URL parser collapses `..` before the path is joined — but a check that is only safe because another component happens to clean up first is not a check, and the next directory added beside `web/` inherits it. ## A test was pinning the defect `test/server-static-cache.test.js` asserted: ```js ok(missing.status === 200, 'a missing asset falls back to the app rather than 404'); ok(contentType.indexOf('text/html') === 0, 'and is served as HTML'); ``` The behaviour was not merely untested, it was **specified in the wrong direction** — which is why it survived. Those two assertions are corrected rather than deleted, so the change of intent is visible in the diff. ## Fixes A path with an extension that does not exist → `404 text/plain`; a path with no extension → still opens the app; `POST`/`PUT`/`DELETE`/`PATCH` → `405` with `Allow: GET, HEAD`; `HEAD` → no body on every branch including gzip; containment → `filePath === WEB_DIR || filePath.startsWith(WEB_DIR + path.sep)`. ## Evidence `test/static-surface.test.js` — **19 checks** over real HTTP: * the app is served, with correct content types for `.js` and `.css`; * five file-shaped misses are 404s and **none of them is the document**; * **twelve** escape attempts (`..`, `%2e%2e`, `..%2f`, `//`, mixed separators, `package.json`, engine source) all fail to return server or engine source; * four write methods are `405` with `Allow`; * `HEAD` has no body and the length a `GET` would send, including with `Accept-Encoding: gzip`; * ETag and `If-Modified-Since` still revalidate to an empty `304`, while a stale tag still gets the bytes; * the boundary property is pinned in the source too, because HTTP cannot reach the difference. With `server/index.js` reverted, **4 of the 19 fail** — `/nope.js → 200 text/html`, both boundary checks, and `POST → 200` with no `Allow` header. `docs/ARCHITECTURE.md`: "What the static server answers" — the table, and why the second row mattered. Suite: 171 suites, 6,897 assertions, 0 failed.
A missing asset is a 404, only a read serves a file, and web-root containment is a boundary (#1311)
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Test (Node 20) (pull_request) Successful in 2m32s
CI / Test (Node 18) (pull_request) Successful in 2m41s
CI / Server smoke test (pull_request) Successful in 34s
CI / Docker build (pull_request) Successful in 42s
CI / Test (Node 22) (pull_request) Successful in 2m10s
5f5e7046de
Pointing at the static server with the request-level lens used for #1307 and #1309. Three defects, and one of them
was pinned by a test that asserted the wrong thing.

1. A missing file was answered with the app

  GET /nope.js   -> 200  text/html; charset=utf-8   <!DOCTYPE html> ...
  GET /nope.png  -> 200  text/html

serveStatic() fell back to index.html for anything it could not read. This app has no client-side routes - it is
one page with tabs - so the fallback served no deep link that matters and instead hid every wrong filename: the
browser's only report is "Uncaught SyntaxError: Unexpected token '<'", in a file the reader can no longer identify.

2. The method was ignored

  POST /index.html    -> 200 (the document)
  DELETE /index.html  -> 200

A client that POSTs could conclude its write landed. HEAD returned a body too, including on the gzip branch.

3. Containment was a string prefix, not a path boundary

  if (filePath.indexOf(WEB_DIR) !== 0) { 403 }

indexOf(WEB_DIR) === 0 also accepts ../web-backup/..., a sibling whose name merely starts with "web". Nothing
exploits it today - the URL parser collapses .. before the path is joined - but a check that is only safe because
another component happens to clean up first is not a check, and the next directory added beside web/ inherits it.

Fixes: a path with an extension that does not exist is 404 text/plain; a path with no extension still opens the app;
POST/PUT/DELETE/PATCH is 405 with Allow: GET, HEAD; HEAD carries no body on every branch including gzip; and
containment is filePath === WEB_DIR || filePath.startsWith(WEB_DIR + path.sep).

A test was pinning the defect: test/server-static-cache.test.js asserted "a missing asset falls back to the app
rather than 404" and "and is served as HTML". The behaviour was not merely untested, it was specified in the wrong
direction - which is why it survived. Those two assertions are corrected rather than deleted, so the change of
intent is visible in the diff.

test/static-surface.test.js: 19 checks over real HTTP - the app is served with correct content types; five
file-shaped misses are 404s and none of them is the document; twelve escape attempts (.., %2e%2e, ..%2f, //, mixed
separators, package.json, engine source) all fail to return server or engine source; four write methods are 405 with
Allow; HEAD has no body and the length a GET would send, including with Accept-Encoding: gzip; ETag and
If-Modified-Since still revalidate to an empty 304 while a stale tag still gets the bytes. The boundary property is
pinned in the source too, because HTTP cannot reach the difference.

With server/index.js reverted, 4 of the 19 fail - /nope.js -> 200 text/html, both boundary checks, and POST -> 200
with no Allow header.

docs/ARCHITECTURE.md: "What the static server answers" - the table, and why the second row mattered.

Suite: 171 suites, 6,897 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 01:25:41 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1312
No description provided.