Client-side multi-scope token flow

[stevenvegt]

Parent PRD

#4144

Implementation Spec

Overview

Modify the client-side token request flow to support mixed OAuth2 scopes. Introduces a PresentationDefinitionResolver that abstracts the decision of whether to fetch a PD from the remote AS or fall back to local policy resolution. When using local resolution, scope policy is enforced.

Design decisions

• PresentationDefinitionResolver abstraction: The client (RequestRFC021AccessToken) should not decide where the PD comes from. A resolver encapsulates the remote-vs-local decision and scope policy enforcement, keeping the client focused on the OAuth flow.
• Remote PD endpoint → trust remote AS: When the remote AS metadata advertises a PD endpoint, the resolver fetches the PD from there and returns the full scope string. The remote server enforces scope policy (covered by PR Server-side multi-scope flow & scope policy evaluation #4179).
• No remote PD endpoint → local fallback: When no PD endpoint exists, the resolver calls FindCredentialProfile locally to get the PD and scope classification. Scope policy is enforced locally: profile-only rejects extra scopes, passthrough/dynamic forward all scopes.
• Dynamic same as passthrough on client side: The client does not call the AuthZen PDP — the server handles dynamic scope evaluation at token-grant time (PR Server-side multi-scope flow & scope policy evaluation #4179).
• Resolver on OpenID4VPClient: The resolver is a struct dependency, wired through Auth → NewClient. Policy backend passed through Auth to enable local PD fallback.

Deviations from original spec

• Spec assumed presentationDefinitionForScope was the modification point: That helper is server-side only. The actual client-side flow goes through RequestRFC021AccessToken → remote PD endpoint. The resolver replaces the direct PD fetch.
• Spec didn't account for remote-vs-local PD resolution: The client fetches PDs from the remote AS when possible, falling back to local only when no PD endpoint exists. This enables integration with external (non-Nuts) authorization servers.
• Policy backend wired through Auth struct: Added policyBackend parameter to NewAuthInstance and iam.NewClient to propagate the policy backend to the resolver.

Modified flow

RequestRFC021AccessToken(ctx, ..., scope, ...)
    1. Fetch remote AS metadata
    2. resolved, err := c.pdResolver.Resolve(ctx, scope, metadata)
       Internally:
       a. If metadata has PD endpoint → fetch from remote, return full scope
       b. If no PD endpoint → FindCredentialProfile locally, enforce scope policy
    3. Build VP using resolved.PresentationDefinition
    4. Send token request with resolved.Scope

Acceptance Criteria

• PresentationDefinitionResolver resolves PD from remote when PD endpoint exists
• Resolver falls back to local PD via FindCredentialProfile when no remote PD endpoint
• Local fallback: profile-only rejects extra scopes
• Local fallback: passthrough and dynamic forward all scopes
• Remote path: all scopes forwarded, scope policy not enforced locally
• RequestRFC021AccessToken uses resolver instead of direct PD fetch
• Single-scope requests work unchanged (backwards compatible)
• Unit tests cover both resolver paths with all scope policies
• Nil policy backend guard (added during self-review)
• Profile-only returns canonical scope, not raw input (added during self-review)

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (4)

Rating	File	% Diff	Uncovered Line #s
	auth/auth.go	100.0%
	cmd/root.go	100.0%
	auth/client/iam/openid4vp.go	20.0%	69-87
	auth/client/iam/pd_resolver.go	95.7%	63-64
	Total	79.1%

🤖 Increase coverage with AI coding...

In the `4144-3-client-side-flow` branch, add test coverage for this new code:

- `auth/client/iam/openid4vp.go` -- Line 69-87
- `auth/client/iam/pd_resolver.go` -- Line 63-64

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.