stack/agents/dewey/work/queue-74/build.md

Row 74 (#1568): WebUI preview behind a sign-in proxy, round 2

Owner: Dewey. Reviewers: Darkwing and Filbert (Filbert re-reviews the delta). Brief: docs/plans/2026-10-11_webui-preview.md, blob 1fe76f32 (rev 487; the change from 59fd510f is the out-of-scope line saying Jason starts the preview, and nothing in the code depends on it). Round 2 scope: Sage's queue notes rev 521 (Filbert's findings, comment 27433) and rev 523 (Darkwing's findings). Base 17ea0dbc. None of the four files changed between bc8e1ee7 (round 1's base) and 17ea0dbc, or between 17ea0dbc and refactor HEAD when the packet was built.

build.patch is git diff --binary 17ea0dbc -- packages/webui, the whole row, not a delta on round 1. Apply it with git apply --index to a detached worktree of the base; candidate-manifest.sha256 then checks 4/4 OK. cli.mjs is unchanged from round 1 (same digest).

Round 2 changes

Round 1 was the packet in ea07e19c, candidate 67515db5…76a0, request comment 27428. Filbert approved it (27433); Darkwing sent findings instead of a verdict. The delta, all in serve.mjs, the README and the tests:

1. A repeated Host is 400 repeated Host refused, before any other check, in preview mode and without it. Node keeps the first of repeated Host headers, so Filbert's Host: 127.0.0.1:PORT then Host: NAME with no auth header landed on the loopback path and got 200 with inbox rows. No edge proxy sends two, and nothing else in the Console has a use for them, so the check is not limited to preview mode. Test: Filbert's case exactly, the reverse order, the same Host twice, each with and without HEADER, with and without the flags.
2. HEADER with any Host but NAME is 403 proxy Host refused, with message: 'the proxy must forward Host unchanged'. nginx's default proxy_set_header Host $proxy_host sends the upstream's Host, which is a loopback Host on the Console's port, so the request skipped the user check. Darkwing's case, Host: 127.0.0.1:PORT with a wrong user, got 200 on /api/config. The operator's browser never sends HEADER, so it still gets through. Test: 127.0.0.1, localhost and [::1] on the port, with a wrong user, the right one, the header in mixed case and an empty value, across a bus read, /api/config, HEAD and a POST; nothing reaches the bus or board. This check runs before the loopback check, so a wrong Host carrying HEADER now gets proxy Host refused rather than non-local Host refused; both are 403.
3. Tests only (the code already did these): HEAD unsigned is 401 and signed is 200; HEAD is refused wherever GET is refused for Host and Origin; x.NAME and xNAME are refused; --auth-header refuses remote_user, _ and -remote-user. The comma-joined value Sage skipped as equivalent is not added. send() now leaves an empty HEAD body unparsed, and a raw-socket helper sends the two Host lines node:http won't.
4. README: the general security line names the repeated-Host 400; the preview bullets name the loopback forms, the proxy-Host 403 and the repeated Host; the proxy contract says Host is forwarded unchanged, names nginx's proxy_set_header Host $host; (Caddy and Traefik keep it by default), says any loopback Host on the port is the operator path, localhost included, so a tunnel whose local end uses the same port number reaches it, and binds every hop on this host that reaches the loopback port, not only the edge.
5. Kept: the NAME:443 refusal (both reviewers). The X-Authentik-Uid mixed-case test stays (Sage, rev 523).

Not in round 2, by Sage's scope: Filbert's N4 (--allow-user has no leading-character check) and the wrong "Delivery may be unknown" text on a 403 Reply, which row 76 fixes before the send route opens.

What ships

serve --public-host NAME --auth-header HEADER --allow-user ID, all three or none. Off by default, and without the flags the Console behaves as before (serve.test.mjs unchanged and green, plus a test that NAME is refused and a POST still reaches the board).

• previewOptions (serve.mjs) validates and lowercases NAME and HEADER. NAME is a DNS name with at least one dot: no scheme, port, path or IP literal, and not localhost. HEADER is a header name, 1 to 64 of [a-z0-9-], not host or origin. ID is 1 to 256 visible ASCII characters without a comma. A partial set throws. startServer revalidates its preview option the same way, so a direct caller can't skip the check, and preview: {} refuses instead of serving without it.
• The CLI collects the three flags and calls previewOptions before any config is read, so a partial or bad set exits 2 with refused: … and prints nothing on stdout. With all three it prints a Preview: line.
• A request is a NAME request when its raw Host, lowercased, equals NAME exactly. Anything else goes through the existing loopback Host check unchanged, so NAME:443 and NAME.evil.example get the existing 403 (round 2: with HEADER they get proxy Host refused, also 403).
• The Origin, when sent, must be https://NAME for a NAME request and the existing http://<Host> for a loopback one.
• A NAME request must carry HEADER exactly once (req.headersDistinct), with a value equal to ID. Otherwise 401 {error: 'sign-in required'}, before routing, so no bus read or board call is made. Node lowercases header names and trims surrounding whitespace from values; the compare is otherwise exact.
• In preview mode every method other than GET and HEAD answers 403 {error: 'read-only', message: 'the Console preview is read-only'}, whatever the Host, after the sign-in check. /api/seen and /api/reply never reach the board.
• Loopback requests need no header and read as before. The GET routes are unchanged.

Order of checks for a NAME request: Host, Origin, header (401), method (403). Round 2 puts two checks ahead of all of these, for every request: a repeated Host (400), then HEADER with a Host other than NAME (403). An unsigned write gets 401, not 403, so nothing about the routes is answered before sign-in.

Decisions and tradeoffs

1. Every non-GET/HEAD method gets 403, not only POST. The brief says "every POST". The Console's only write routes are POST today, and every other non-GET/HEAD method already gets 404 or 405 on the base, so the superset changes no allowed request. It means a write route added later is refused in preview mode until someone opens it on purpose (row 76 does, under --send).
2. A port on NAME is refused. The README tells the proxy to preserve Host: NAME. A proxy that sends NAME:443 fails closed with a 403 rather than being matched loosely. If ops-01's proxy adds the port, the fix is in the proxy config, not here.
3. Repeated header is 401. Two values could come from a client copy the proxy failed to strip plus the proxy's own. Refusing is the safe reading. A comma is refused in ID for the same reason: a proxy that joins values with a comma would make ID,ID look like one value.
4. HEAD is allowed with GET. It reads nothing GET doesn't.
5. Provider-neutral. No identity provider is named in the code or the README; the README example uses X-Example-Uid. The tests use remote-user/jason and, for the first deployment's shape as the brief asks, X-authentik-uid with a 64-hex stand-in id, so a provider's header name does appear in the tests and the demo. (Round 1 said "code, tests or README", which overstated it; Filbert's N3.)

Where the brief and the code differ (for Sage)

• The superset in decision 1.
• With row 60 landed, /api/bus/credentials is also readable through the preview by the signed-in user: credential states and dates, no tokens. /api/bus/decisions is readable today. Both are GET routes that "stay as they are"; I mention them because the brief lists inbox, tasks, agents and trails as the minimum.
• Overlap with row 60: both change packages/webui/src/serve.mjs (row 60 only the BUS_VERBS line) and packages/webui/README.md. The two patches apply on top of each other in either order without conflict, but whichever lands second has different digests for those files, so its manifest needs a new round.
• A refused Reply in the page shows read-only Delivery may be unknown; check the seat before sending again. The second sentence is wrong for a 403. It comes from src/public/app.js, which isn't in this row's files, and row 76 changes that path.
• The brief's line references (serve.mjs 82, 92, 96) match the base.

Files

File	Change
packages/webui/src/serve.mjs	previewOptions, the preview option, the repeated-Host, proxy-Host, NAME, Origin, header and read-only checks
packages/webui/src/cli.mjs	the three flags, checked before config; the Preview: line
packages/webui/README.md	the preview section, the proxy contract, the local exposure; two lines of the old "do not expose" text replaced; the repeated Host in the general security line
packages/webui/tests/preview.test.mjs	new, 11 tests

The README's bus-reads exposure paragraph is untouched, to keep the overlap with row 60 small.

Tests (preview.test.mjs)

1. Options are all three or none, and each is checked (hosts, headers, users; startServer with a partial set or {}). Round 2 adds remote_user, _ and -remote-user to the refused headers.
2. The CLI refuses a partial or invalid flag set at start: exit 2, refused:, empty stdout.
3. The CLI with all three flags serves preview mode: the Preview: line, 401 unsigned, 200 signed in, 403 for a loopback POST.
4. 401 with nothing read: no header, another user, a suffix, a different header, two values, across a bus read, a trail, the board and /, and a HEAD for each case (round 2).
5. Header name case and exact value: X-authentik-uid on the flag with a 64-hex id; lower, mixed and upper names pass; an uppercased value, a truncated value, a suffix, or ID,ID gets 401.
6. Signed-in reads of inbox, tasks, agents, a trail, the board and /; NAME in mixed case; a signed HEAD of / is 200. Wrong Host, NAME:443, NAME.evil.example, x.NAME and xNAME get 403 for GET and HEAD: non-local Host refused without HEADER, proxy Host refused with it. Wrong Origins get 403 for GET and HEAD.
7. Every write gets 403 read-only from NAME and from loopback, with and without Origin, for both write routes, a bus route and /; PUT, DELETE, PATCH and OPTIONS too; an unsigned write gets 401; nothing reaches the board or bus.
8. Loopback is unchanged in preview mode, and with the board down its route answers the existing 502 while the bus views answer.
9. A proxy that rewrites Host to the loopback port gets 403 proxy Host refused (round 2, Darkwing's case and its variants, listed above).
10. A repeated Host is 400 before any other check, with and without the flags (round 2, Filbert's case and its variants).
11. Without the flags NAME is refused and a POST still reaches the board.

Without the round 2 serve.mjs change, tests 6, 9 and 10 fail and the other eight pass.

Mutants

Round 2: 34 single-site mutants in a separate worktree (17ea0dbc plus build.patch), run against preview.test.mjs and serve.test.mjs (mutants.py, output in mutants.txt). 34 of 34 killed; the worktree was clean after the run. They are round 1's 22 (one site pinned more narrowly, since the header lookup now appears twice) and 12 new:

Mutant	Edit
repeated-host-allowed	two Hosts pass; only three are refused
repeated-host-preview-only	the repeated-Host check only with the flags
proxy-host-skipped	the proxy-Host check removed
proxy-host-wrong-user-only	refused only when the value isn't ID
proxy-host-nonempty-only	an empty HEADER value passes
proxy-host-get-only	the proxy-Host check only for GET
proxy-host-loopback-only	the check only for a loopback-looking Host
proxy-host-raw-name	the check looks HEADER up by the raw flag
header-check-skips-head	Darkwing's: HEAD skips the sign-in check
head-refused	Darkwing's: HEAD gets 403 read-only
header-leading-dash	--auth-header accepts a leading -
header-underscore	--auth-header accepts _

The last four edit code round 1 already had. Against round 1's tests all four survive (mutants-round1-tests.txt, mutants.py pointed at a worktree of bc8e1ee7 with round 1's patch); round 2's tests kill them.

Round 1's 22, for reference:

Partial set allowed; NAME not lowercased; HEADER not lowercased; IP allowed; host allowed as HEADER; comma allowed in ID; preview: {} served; NAME compared case-sensitively; NAME as a prefix; NAME with any port; http://NAME Origin allowed; https://NAME Origin allowed on loopback; header check skipped; any of several values accepted; value as a prefix; value compared without case; header looked up by the raw flag; read-only only for NAME; read-only only for POST; read-only without the flags; CLI drops the option; CLI never validates.

The first run found two faults in the tests, not the code, both fixed before the gate. setup() registered the fake board's cleanup after startServer, so a mutant that made startServer throw left the board open and the run hung instead of failing. And test 1 left open any server a mutant let start. Both now close what they open, and the mutants that had hung fail in about a second. Test 3 was added because no test started the CLI with all three flags, so a CLI that dropped the option would have passed.

Demonstration

Round 2 adds four refusals to demo.sh: a wrong Host without and with HEADER, a Host rewritten to 127.0.0.1:PORT with a wrong user and to localhost:PORT with the right one, and the two Hosts (over a raw socket, since curl sends one Host however many are given). demo.txt was run on the build worktree, whose four files match the manifest.

demo.sh starts the CLI in preview mode on loopback port 0 with no system config and a closed board port, then drives it with curl, showing each refusal and the allowed reads. demo.txt is its output, run on the gate worktree, with the server's start lines. Nothing leaves the host. With no bus configured the inbox read answers 503 not-configured, which shows it got past the sign-in check; tests 6 and 8 show the bus reads themselves.

Gate (my run on the candidate)

Round 2: all suites ran one after another in a detached worktree of 17ea0dbc with build.patch applied, TMPDIR in my scratch and Docker on, from 2026-10-11T23:15:06Z to 23:22:54Z. The manifest checked 4/4 OK before the run, and core.hooksPath stayed unset. No flake, no rerun.

Suite	Result
packages/webui	61 pass, 0 fail (11 in preview.test.mjs), the browser tests included
packages/control-board	124 pass, 0 fail
packages/cli	112 pass, 0 fail
bus, business, conversation, discord, harness, ledger, mosaic, queue, runs, seat, tasks	all 0 fail (80, 60, 182, 178, 57, 78, 69, 150, 41, 27, 71 pass)
build-tokens --check	exit 0
test-auth, test-conductor, test-config, test-discord, test-extension-package, test-foundation, test-queue	exit 0 (15, 17, 24, 66, 18, 44, 27 passed)
test-release	14 passed, 0 failed (Docker, nothing skipped)
test-task	98 passed, 0 failed (Docker, nothing skipped)

Round 1's gate ran on bc8e1ee7 from 22:26:06Z to 22:35:49Z, also all green (webui 49 then).

Questions for reviewers

Round 1's two are answered: keep refusing NAME:443, and the contract lines are added. One for round 2:

1. The repeated-Host 400 applies without the flags too. Without them only the first Host is ever read, and it must pass the loopback check by itself, so the 400 closes nothing there. I kept it unconditional because a repeated Host has no legitimate sender and one rule is simpler to state. Would you rather it be preview-only?