fix(oauth): a dynamic client without a declared scope holds the realm's opted-in scopes

[windischb]

Summary

Reported from the field (amZettel, priority high) — the follow-up to #238, one check deeper. With the loopback port accepted, Claude Code still could not log in against an MCP server behind Modgud: /connect/authorize answered invalid_request — This client application is not allowed to use the specified scope (OpenIddict ID2051) for every scope but openid and offline_access, although all of the server's scopes had AllowDynamicRegistrationClients = true and the API had AllowDynamicRegistration = true.

Cause

A dynamic client held exactly the scopes its CIMD document or DCR registration declared. Claude Code's document — like every static MCP-client document, one file for every server in the world — declares no scope: it cannot know one server's scopes, the client reads them from the server's protected-resource metadata at run time. So the synthesized client had no scope permission at all, and OpenIddict's permission check refused everything before Modgud's per-scope opt-in was ever consulted. The opt-in built for exactly this case was unreachable. DCR had the same gap (RFC 7591 §2: "if omitted, an authorization server MAY register a client with a default set of scopes" — Modgud's default was the empty set).

Fix — one rule, three seams

DynamicClientScopePolicy: a dynamic client (DCR-minted or CIMD-synthesized) may hold every enabled scope with AllowDynamicRegistrationClients — app-scoped or global; the flag is the boundary, the App link never was — plus the standard scopes other than modgud.management. Standard scopes are immutable, so they need a built-in verdict: the identity and claim-gate scopes name no resource privilege of their own; the management selector is exactly the "tenant.admin.*" case the flag exists to keep away from a habit-click consent (the realm seeder already strips the flag from it). A declared scope is an upper bound intersected with that set; none declared means the whole set.

Seam	Behaviour
CimdClientResolver	permissions computed on every resolve from the live set (memoized per request); the document stays cached — ticking the flag takes effect at once, like Cimd.Enabled
OAuthAdminService (DCR create)	the resolved set is stored; /connect/register echoes what was registered (§3.2.1)
DynamicClientScopeHandler	ordered just before OpenIddict's ValidateScopePermissions: a refused scope gets Modgud's own invalid_scope, naming the scope and the flag, instead of the opaque ID2051; the authorize endpoint's own check (still reached from the consent continuation) uses the same policy and wording

Contract changes (pre-1.0), in the release-notes draft

• A custom global scope now needs the flag for dynamic clients, like an app-scoped one (the docs said "global scopes are always reachable" in one paragraph and "the flag controls which scopes a DCR client can ever request" in the next). Existing DCR clients keep their stored permissions; a new registration or a CIMD document sees the rule at once. modgud.management is never available to a dynamic client.
• A refused scope is answered at /connect/authorize the way OpenIddict answers every request-validation failure — an error page for the user — where Modgud used to redirect to the client with error=invalid_scope. (That is also why the field report saw a 400 for ID2051.)

Test plan

• CimdFullFlowTests.A_document_without_scope_holds_the_realms_dynamic_client_scopes — the exact Claude Code document: an opted-in scope and the OIDC scopes reach consent, a scope without the flag and modgud.management are refused with the Modgud message, the flow completes, and a document that declares scope cannot exceed the set. Red with the resolver / service / handler reverted, green with the fix.
• DcrFullFlowTests.Registration_without_scope_gets_the_realms_dynamic_client_scopes — response echoes and store holds the set; a declared list is intersected (unknown and non-opted-in names dropped); authorize on a non-opted-in scope refused with the flag named. The pre-existing negative twin now asserts the validation-page shape.
• DynamicClientScopePolicyTests — 15 unit cases (standard verdicts, flag reading, disabled/deleted, intersection order)
• Full backend suite green: 1708 unit + 839 integration
• CI on this PR

🤖 Generated with Claude Code