fix: CIMD redirect policy — loopback callbacks proceed, allowed_domains vets remote ones; docs: name both ways to supply the browser leg

[rsharath]

Follow-up to #278 (merged), correcting a docs gap it left — and, since #285 landed mid-review, fixing a promise that PR's docs make and its code does not keep.

1. Two ways to supply the browser leg (the original change)

docs/cimd.md said the browser leg "needs a GET-capable PrincipalResolver, which ZeroID does not ship" and that the deployer "must register one that reads a session cookie." True of one shape and not the only one, and it describes the opposite of what Highflame actually runs.

There are two routes, and the second needs no GET-capable resolver at all:

1. Register a cookie-reading resolver and own the login and consent screens behind it. /oauth2/authorize becomes the browser-facing endpoint, with the CSRF obligations that brings.
2. Front the browser leg above ZeroID and hand off over POST. Your surface owns the redirect, authenticates the human, and POSTs an RFC 7523 assertion a form-based resolver reads. The browser never reaches the endpoint.

Route 2 does not remove authorization-request CSRF — it moves it to the fronting surface, which is where the explicit consent gesture has to happen. Documented as such rather than left implied.

Highflame takes route 2 (Studio authenticates, mints, POSTs). Route 1 exists for deployers with no such surface. The SetAuthorizationCodeAvailable guidance is corrected to match: a route-2 deployment is fine with only form-based resolvers.

2. cimd.allowed_domains now actually restores redirects

This is a behaviour change, and the reason this PR is no longer docs-only.

#285 added the §4.1.2.1 self-asserted carve-out: a CIMD client gets a §5.2 JSON body instead of an error redirect, and redirectToInteractiveLogin refuses it too. It documented an escape hatch in three places — failAuthorize's godoc, redirectToInteractiveLogin's godoc, and docs/cimd.md §12.5 — all saying that setting cimd.allowed_domains restores the redirect, because vetting which hosts may publish restores the assumption the rule is built on.

No code implemented it. Both gates read client.SelfAsserted() alone, which is RegistrationSource == "cimd", set unconditionally at synthesis (internal/service/cimd.go:548) whether or not an allow-list is in force. The handler never received the allow-list at all — API carried only cimdEnabled. Setting the config did nothing.

The fix is small and deliberately shaped so it cannot rot again:

• API.cimdPublishersVetted, set by Server.NewServer from cimdSvc.AllowedDomainCount() > 0 — the effective count, for the same reason the startup log uses it: allowed_domains: [""] has length 1 and vets nothing.
• One predicate, refusesRedirectTo, behind both gates. They were two copies of the same condition; now they are one, so the error redirect and the login redirect cannot drift apart.
• The empty-allowlist startup warning names the new consequence: without a list, a browser-driven CIMD client cannot sign a user in.

3. A loopback callback is redirected to — the carve-out is about reach

The carve-out refuses a self-asserted client because its redirect_uris are attacker-chosen, making the endpoint "an unauthenticated redirector with the AS's own origin as the first hop." That is a claim about a remote destination. It was being applied to every destination.

A 302 to 127.0.0.1 has no remote hop. The code lands on the machine the user is sitting at, and an attacker able to listen there already has local code execution — the same reasoning RFC 8252 §7.3 uses to accept loopback callbacks from clients nobody registered.

This is not a corner case, it is the MCP case. A CIMD client_id names the client vendor's domain, and the canonical document at the top of docs/cimd.md — an ordinary desktop/CLI MCP client — lists loopback callbacks and nothing else. The carve-out was costing the whole browser leg for the dominant client shape while preventing nothing, and allowed_domains was being asked to buy back something loopback already gives for free.

refusesRedirectTo now asks whether the destination can reach a third party the client chose:

Destination	Redirected?
loopback http://, private-use scheme	yes — delivers to the caller's own device
remote https://, self-asserted, unvetted host	no
remote https://, self-asserted, allow-listed host	yes (§2)
registered / RFC 7591 client	yes, unchanged

service.RedirectDeliversLocally holds the judgement, next to the URI rules it belongs with. Loopback matching is exact, so 127.0.0.1.evil.com is remote — tested.

Consequence: a desktop MCP client completes the browser leg with no allowlist configured at all. Only clients with real https:// callbacks need cimd.allowed_domains, and the config godoc, zeroid.yaml, docs/cimd.md and spec §12.5 now say that rather than the blanket MUST an earlier revision of this PR carried.

Why this matters beyond conformance

It is the difference between MCP CIMD working end to end and not working at all.

An MCP client sends the user's browser to GET /oauth2/authorize with an https:// client_id. Discovery, document resolution, redirect_uri validation and code redemption all work. Principal resolution is the whole gap: a browser presents no credential, so the resolver chain must be able to say "send this person to log in." For a CIMD client that redirect was refused unconditionally — meaning a user with no existing session could never establish one, and the flow could not complete on any deployment, at any configuration. The allow-list was described as the switch and was wired to nothing.

§3 then removes the need for that switch entirely for native clients, which is where MCP actually lives. §2 remains what makes the allow-list trustworthy for the hosted-client case.

allowed_domains remains deployment-wide, so this re-enablement is meaningful only on a single-tenant deployment — unchanged from #285, still tracked in #286.

Tests

TestVettedPublishers_RestoresRedirects covers both halves — the error redirect (status, error, state echoed) and the interactive-login redirect — plus that vetting does not bypass the nil-client or non-GET refusals, so "vetted" never becomes a blanket exemption. #285's existing TestSelfAsserted_* tests pin the default-off behaviour and still pass unchanged.

Docs and spec §12.5 updated to describe the refusal as conditional, which is what it now is.

[Copilot]

Pull request overview

Documents two ways to connect CIMD’s browser authorization leg to ZeroID.

Changes:

• Describes cookie-based GET resolution.
• Adds a fronted server-to-server POST pattern using signed assertions.
• Documents Highflame’s deployment approach.

Suppressed comments (1)

docs/cimd.md:82

• This form-based resolver route conflicts with the public API documentation: RegisterPrincipalResolver tells every form-only deployment to disable the grant (server.go:759-765), and SetAuthorizationCodeAvailable repeats that instruction (server.go:905-915). Following that guidance makes this POST handoff return 503. Update those Go docs to distinguish direct browser GETs from a fronted server POST so deployers do not receive opposite instructions.

   and then POSTs to `/oauth2/authorize` with a credential a form-based resolver
   reads — an RFC 7523 assertion signed by that surface, say, verified against

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.