Scope parsing, classification & policy config

[stevenvegt]

Parent PRD

#4144

Summary

Foundation layer for mixed OAuth2 scope support. Renames PDPBackend.PresentationDefinitions() to FindCredentialProfile() and enriches its return type to include the credential profile scope, its policy, and any remaining ("other") scopes. Extends the policy JSON format with a scope_policy field and adds a policy.authzen.endpoint CLI flag validated at startup.

What changed

Policy interface (policy/interface.go, policy/local.go):

• Method renamed PresentationDefinitions → FindCredentialProfile, returning *CredentialProfileMatch (scope, WalletOwnerMapping, scope policy, other scopes) instead of just pe.WalletOwnerMapping.
• Multi-scope parsing via strings.Fields (tolerant of tabs, newlines, consecutive spaces).
• New errors: ErrAmbiguousScope (multiple profile scopes in one request), distinct from ErrNotFound.

Policy JSON format (policy/local.go, policy/test/scope_policy/):

• Added scope_policy field per credential profile: "profile-only" (default), "passthrough", or "dynamic".
• Existing policy files without scope_policy continue to work (defaults to profile-only).
• Internal credentialProfileConfig replaces the map-based validatingWalletOwnerMapping with an explicit struct (organization/user fields + scope_policy).
• PD schema validation preserved via validatingPresentationDefinition — moved from mapping-level to per-PD level.

Config & validation (policy/config.go, policy/cmd.go, policy/local.go):

• New policy.authzen.endpoint CLI flag.
• Startup fails when any credential profile uses dynamic without an AuthZen endpoint configured.
• passthrough and profile-only continue to work without an endpoint.

Callers updated (auth/api/iam/):

• validation.go and api.go updated for the new return type, with ErrAmbiguousScope mapped to invalid_scope.
• Mock regenerated; existing test expectations updated to use *CredentialProfileMatch.

How to review

Start with policy/interface.go — understand the new types (CredentialProfileMatch, ScopePolicy) and the renamed interface method.

Then policy/local.go — the core logic:

• FindCredentialProfile (scope parsing + classification)
• credentialProfileConfig.UnmarshalJSON (JSON format handling)
• Configure (startup validation for AuthZen endpoint)

Tests to focus on (policy/local_test.go):

• TestLocalPDP_FindCredentialProfile — multi-scope parsing edge cases (consecutive whitespace, empty strings, multiple profile scopes, zero profile scopes)
• TestLocalPDP_ScopePolicyConfig — JSON parsing, invalid value rejection
• TestLocalPDP_Configure — startup validation behavior

Callers (auth/api/iam/) are mechanical updates — they extract .WalletOwnerMapping from the result to preserve existing behavior.

Deviations from spec

• credentialProfileConfig uses an explicit struct with Organization/User fields, not the map-based approach suggested in the spec. This avoided custom JSON parsing of the scope_policy field while preserving the existing flat JSON format. PD validation moved to per-PD level (still uses the v2 schema).
• Added ErrAmbiguousScope as a distinct error (not in spec). Wrapping ErrNotFound for "too many profile scopes" was semantically wrong.
• Added nil-check that credential profile JSON must define at least one of organization / user — catches typos like organisations that standard struct unmarshaling would silently accept.
• Used strings.Fields instead of strings.Split — handles tabs, newlines, and consecutive spaces robustly.

Dependencies

None — this is the foundation PR. Subsequent PRs #4177–#4180 build on this interface.

Design context

• PRD: Support mixed OAuth2 scopes with configurable scope policy #4144 (mixed OAuth2 scopes with configurable scope policy)
• Scope policy modes discussion: passthrough mode was added in-scope after initial PR split (see PRD comment 4235711103)
• Related issue: Consider circuit breaker for AuthZen PDP client #4175 (circuit breaker for AuthZen client — future enhancement)

Acceptance Criteria

• FindCredentialProfile() accepts space-delimited multi-scope strings (uses strings.Fields for robust whitespace handling)
• Returns exactly one credential profile scope or errors (ErrNotFound for zero, ErrAmbiguousScope for multiple)
• scope_policy field parsed from policy config (defaults to "profile-only")
• Invalid scope_policy values rejected at load time
• Credential profile must define at least one of organization or user
• policy.authzen.endpoint config field and CLI flag added
• Startup fails when dynamic scope policy is used without AuthZen endpoint
• passthrough and profile-only work without AuthZen endpoint
• All existing tests pass (callers and mocks updated for new interface)
• New unit tests for scope parsing, config loading, and startup validation
• PD validation preserved via validatingPresentationDefinition (validates against v2 JSON schema)

Original implementation spec (used during AI-assisted development)

Parent PRD

#4144

Implementation Spec

Overview

Foundation layer for mixed OAuth2 scope support. This PR modifies the policy subsystem to:

1. Parse multi-scope strings (space-delimited) and classify each scope as a credential profile scope (has a PD mapping) or an other scope (no mapping).
2. Enforce exactly one credential profile scope per request.
3. Extend the policy configuration format with a scope_policy field per credential profile.
4. Add a global policy.authzen.endpoint configuration field for the AuthZen PDP URL.
5. Validate at startup that scope_policy: "dynamic" requires an AuthZen endpoint.

Key files modified

• policy/interface.go — Renamed PDPBackend.PresentationDefinitions() to FindCredentialProfile(), added CredentialProfileMatch, ScopePolicy, ErrAmbiguousScope types
• policy/local.go — New credentialProfileConfig struct with explicit Organization/User fields, multi-scope parsing via strings.Fields, scope policy defaulting and validation
• policy/config.go — Added AuthZenConfig with endpoint field
• policy/cmd.go — Added policy.authzen.endpoint CLI flag
• auth/api/iam/validation.go — Updated caller to use FindCredentialProfile, handles ErrAmbiguousScope
• auth/api/iam/api.go — Updated caller to use FindCredentialProfile

Design

Interface change

Renamed PresentationDefinitions to FindCredentialProfile to better reflect the method's responsibility: resolving a scope string against the policy configuration to find the matching credential profile.

type PDPBackend interface {
    FindCredentialProfile(ctx context.Context, scope string) (*CredentialProfileMatch, error)
}

type CredentialProfileMatch struct {
    CredentialProfileScope string
    WalletOwnerMapping     pe.WalletOwnerMapping
    ScopePolicy            ScopePolicy
    OtherScopes            []string
}

Policy configuration format

The per-scope JSON structure now supports scope_policy alongside the existing organization/user keys:

{
  "urn:nuts:medication-overview": {
    "organization": { /* PD */ },
    "scope_policy": "profile-only"
  }
}

Internally, credentialProfileConfig uses a struct with explicit fields (instead of the old map-based validatingWalletOwnerMapping), allowing standard JSON unmarshaling. Individual PDs are validated against the v2 JSON schema via validatingPresentationDefinition.

Error handling

• ErrNotFound — no credential profile scope matched
• ErrAmbiguousScope — multiple credential profile scopes found in the request

Acceptance Criteria

• FindCredentialProfile() accepts space-delimited multi-scope strings (uses strings.Fields for robust whitespace handling)
• Returns exactly one credential profile scope or errors (ErrNotFound for zero, ErrAmbiguousScope for multiple)
• scope_policy field parsed from policy config (defaults to "profile-only")
• Invalid scope_policy values rejected at load time
• Credential profile must define at least one of organization or user
• policy.authzen.endpoint config field and CLI flag added
• Startup fails when dynamic scope policy is used without AuthZen endpoint
• passthrough and profile-only work without AuthZen endpoint
• All existing tests pass (callers and mocks updated for new interface)
• New unit tests for scope parsing, config loading, and startup validation
• PD validation preserved via validatingPresentationDefinition (validates against v2 JSON schema)

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on feature/4144-mixed-scopes by 0.02%.

Modified Files with Diff Coverage (4)

Rating	File	% Diff	Uncovered Line #s
	policy/local.go	93.3%	177-178, 200-201
	policy/cmd.go	0.0%	30
	auth/api/iam/api.go	100.0%
	auth/api/iam/validation.go	100.0%
	Total	92.4%

🤖 Increase coverage with AI coding...

In the `4144-1-scope-parsing-and-config` branch, add test coverage for this new code:

- `policy/cmd.go` -- Line 30
- `policy/local.go` -- Lines 177-178 and 200-201

🚦 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.