security(config): require --url, closing header-derived host takeover

[lakhansamani]

Fixes GHSA-m82j-rq33-qjx2 — the last of the four live vulnerabilities found while triaging the advisory backlog. Also does the process work (items 3 and 4 of the triage plan).

The vulnerability

With --url unset — the default — every self-referential URL this server emits is derived from request headers (X-Authorizer-URL, then X-Forwarded-Host, then Host): password-reset links, email-verification links, magic links, the JWT iss claim, and the OIDC discovery/JWKS URLs.

The attack needs no prior access and no mailbox compromise:

1. Attacker sends forgot_password for the victim, carrying Host: evil.example.
2. Victim receives a genuine reset email from the real service, pointing at evil.example.
3. Victim clicks; the token lands on the attacker's server.
4. Attacker redeems it — iss is validated against the same header-derived host, so replaying the spoofed Host satisfies the check.

Full account takeover (CWE-640).

Why require --url rather than patch around it

The obvious lighter fix — validate the header-derived host against the origin allowlist — helps only deployments that configured an explicit list and does nothing on the default *, which is the configuration the attack targets. It would leave the vulnerable setup vulnerable.

Requiring --url closes the class, and costs no supported capability:

• Setting --url already collapses an instance to a single canonical host (GetHostFromRequest returns it and ignores every header, parsers/url.go:58). Multi-host operation only ever worked on the vulnerable path.
• Verified org domains are email-domain→organization routing for home realm discovery, not HTTP virtual hosting. Unaffected.
• --mcp-enabled already required --url; this follows the same precedent and sits next to it in runRoot.

Timing is the argument. Pre-GA this is a release note. Post-GA it is a breaking change that needs a major. rc.19 is the last cheap moment.

The subtle half

An unusable --url is rejected, not just an empty one. SetTrustedURL discards anything sanitizeAuthorizerURL can't normalize and silently resumes header derivation — so --url=auth.example.com (no scheme) or --url=https://user:pw@host would have looked configured while staying fully vulnerable. Checking only for "" would have shipped a gate with a hole in it.

--url vs --allowed-origins

These get conflated constantly, and now that one is mandatory the confusion surfaces at boot. Both config fields now document each other, and the startup error says it outright:

--url is required (e.g. --url=https://auth.example.com)

  Why: without it the password-reset, email-verification and magic-link URLs, and the
  JWT `iss` claim, are derived from request headers — so an attacker can have a victim
  emailed a genuine reset link pointing at a domain the attacker controls.

  Note --url is NOT --allowed-origins; you need both:
    --url             this server's own address, e.g. https://auth.example.com
    --allowed-origins your apps this server may redirect to, e.g. https://app.example.com

One real interaction is documented too: when --allowed-origins is empty or *, IsValidRedirectURI restricts redirects to the server's own host — which is derived from --url. So --url also decides where the wildcard default may redirect.

Process changes

• SECURITY.md — states the three outcomes every report reaches: confirmed (reproduced with a failing test that ships with the fix), not accepted (closed with a written reason, original preserved, reopen if we're wrong), or needs-info. "Cannot reproduce" and "we think you're wrong" are now distinguished explicitly.
• AGENTS.md — the triage runbook, with the incident that motivated it: twelve advisories sat from April to August 2026, four were live, one was reported twice and flagged as an incomplete fix of a published CVE, and nineteen RCs shipped with it. Core rule: write a probe before forming an opinion, verify affected/patched ranges yourself (three of six published on 2026-08-13 had stale or missing ones), and fix live high-severity issues in a private fork, not a public PR.

Tests

cmd/authorizer_url_config_test.go:

• Empty and whitespace-only --url refused
• Seven unusable values refused, each asserted to be one SetTrustedURL would have discarded — the precondition is checked, so the test can't pass vacuously
• Five usable forms accepted, including trailing slash and surrounding whitespace
• --url beats X-Authorizer-URL + X-Forwarded-Host + Host set simultaneously
• Header derivation still works when unset, so the fallback library embedders rely on doesn't rot

Verification

• go build ./..., go vet ./..., make lint — 0 issues
• make test — pass
• make smoke — caught a real break. org_admin_smoke_test.go boots a second server without --url; it failed with the new gate, which is the gate working. Fixed, re-run green. I then checked every other startServer call site and all nine Authorizer services in e2e-playground/docker-compose.yml — all already pass --url.
• make dev updated (it didn't pass --url)

Upgrade note for rc.20

Every deployment must now set --url. Existing installs that omitted it will refuse to start with the message above. This is deliberate: the configurations that break are exactly the ones vulnerable to account takeover.