fix(security): validate the upstream base URL, and integrate the review into the docs

[ojassug]

Closes the last substantive item from the security review, and puts the review where later sessions will actually find it.

Stacked on #54 (docs/security-review-reconciliation), so it includes that commit. Merge #54 first, or merge this one and #54 becomes empty.

SSRF — §6.3's unvalidated upstream base URL

buildUpstreamUrl trimmed a trailing slash and concatenated, with no validation of any kind, while buildForwardHeaders delivers the caller's Authorization / x-api-key to whatever came out. R-06 demonstrated a one-line config change putting a live-looking bearer token on an arbitrary listener; 169.254.169.254 is what makes that worth doing.

start() now refuses a base URL that is not https: or that names a literal private, loopback or link-local address. allowInsecureUpstream is the named opt-in — the same shape as OX-M8's allowUnauthenticatedNonLoopback — and its honest use is a local test stub. This repo's own gateway tests are exactly that case, which is why the escape hatch exists rather than the rule being quietly weakened to let them pass.

Placement at start() follows M8's reasoning: a misconfiguration that would leak a credential is named once, where it can still be fixed, rather than surfacing as an opaque 502 on every call.

Two limits, stated rather than glossed

• Literal addresses only. A hostname resolving into a private range is not caught, because this reads the configured string rather than the address the socket connects to. Resolving at startup would still leave a TOCTOU window, so the honest fix is a connect-time hook that does not exist yet.
• The guard is on GatewayServer.start(), so a library caller invoking handleProxyRequest directly bypasses it.

One bypass caught by its own test

URL normalises [::ffff:169.254.169.254] to [::ffff:a9fe:a9fe]. A validator understanding only dotted IPv4-mapped notation passes the metadata service itself. Both spellings are handled now — found by the test, not by reading.

Why this was never in §3

It sat in §6.3 as a "library hazard, no shipping caller". That reasoning was inconsistent: F-02 was library-only on identical terms, was filed as a Medium, and was fixed in #53. Fixing this closes the asymmetry from the other side, which is one of the two dispositions §8.2 asked for.

F-01's residual — a fix investigated and refused

§9.1 listed "session state mutates before any credential check" as fixable. Measured before writing it, hoisting the check stops nothing:

session created with NO auth header  : true
session created with junk auth header: true

hasAuthHeaders tests presence, not validity, so an attacker passes it with Bearer literally-anything. The gate would read as a credential check in the source and in the changelog while being a formality an adversary steps around by typing a word.

Recorded in §3.1 with the measurement instead. A control that only stops an attacker who declines to bypass it is the vacuity the protocol exists to prevent, and shipping one is worse than the honest gap, because the next reader stops looking.

Documentation integration

Two gaps found by sweeping all four audit documents:

• CLAUDE.md had zero mentions of the security review. The file every session reads first had no record that four sessions ran, found eight findings and fixed seven. It now carries the parts that change how the rest of that file is read — including that driftScore: 0, measured: true, fallbackUsed: false is not a semantic-safety attestation.
• docs/audit-remediation-status.md also had zero mentions, despite CLAUDE.md designating it the current index — and its own heading said oxaudit.md "is open" while line 7 said §70 closes it in full. Heading corrected; both later audits added with their remaining items named.

Checks

905 tests pass (2 skipped, POSIX-only), typecheck and lint clean. The new guard has 16 cases including every private range, both IPv4-mapped spellings, and negative cases (https://api.openai.com and public 8.8.8.8 must still be allowed — a rule rejecting every literal IP would be easy to write and wrong).

🤖 Generated with Claude Code