Credential selection when multiple credential from wallet match

[reinkrul]

Problem

When a wallet contains multiple credentials of the same type, the Nuts node needs a way for the EHR to specify which one to select:

• PatientEnrollmentCredential: one per patient in the wallet
• HealthcareProviderTypeCredential: one per organization type (e.g. pharmacy and hospital)

The current PD matcher picks the first match, which is non-deterministic.

Related: #3993

Solution: credential_selection (named parameters)

A new optional credential_selection parameter on the request-service-access-token endpoint. The EHR provides simple key-value pairs mapping PD field IDs to expected values:

{
  "scope": "medicatieoverdracht-gf",
  "authorization_server": "https://verifier.example.com",
  "credential_selection": {
    "patient_id": "123456789"
  }
}

The PD author controls what is selectable by assigning id values to constraint fields (already done for introspection claims). The EHR only needs to know the field name and value — no JSON paths, no query language.

See the full PRD for design details, trade-offs, and architecture.

Status

Sub-issue	Description	PR	Status
#4088	CredentialSelector extension point in PD matcher	#4098	Open
#4120	Selection CredentialSelector (filter by field ID values)	#4121	Open
#4090	Wire credential_selection through API to presenter	#4122	Open

Dependency graph

#4088 → #4120 → #4090

Closed / superseded

Issue	Reason
#4089	DCQL selector — superseded by #4120 (named params approach)
#4087	DCQL parser — kept open for potential future use, not needed for current approach

Decision trail

The comments below document the evolution from DCQL-based credential queries to the simpler named-parameter approach. Key decisions:

• DCQL approach — initial investigation
• Inject selector into PD matcher — architecture decision
• Drop match_policy — simplification
• PRD changelog (2025-03-25) — pivot to named parameters after user feedback

[stevenvegt]

I was under the assumption DCQL could be used, reading section 6.3, you can provide a claims query which consists of a path of the claim and possible values.

From appendix D, this example shows selecting a person with last name "Doe" living in either 90210 or 90211.

{
  "credentials": [
    {
      "id": "my_credential",
      "format": "dc+sd-jwt",
      "meta": {
        "vct_values": [ "https://credentials.example.com/identity_credential" ]
      },
      "claims": [
          {
            "path": ["last_name"],
            "values": ["Doe"]
          },
          {"path": ["first_name"]},
          {"path": ["address", "street_address"]},
          {
            "path": ["postal_code"],
            "values": ["90210", "90211"]
          }
      ]
    }
  ]
}

[reinkrul]

Nice! I think I didn't read it properly.

[stevenvegt]

PRD: Credential Selection via Named Parameters

Problem Statement

When a wallet contains multiple credentials of the same type (e.g., multiple PatientEnrollmentCredentials for different patients, or multiple HealthcareProviderTypeCredentials for different organization types), the Nuts node has no mechanism for the EHR to specify which credential to select. The current Presentation Definition (PD) matching picks the first match, which is non-deterministic when multiple credentials of the same type exist.

Solution

Add a credential_selection parameter to the request-service-access-token endpoint (auth v2) that allows the EHR to specify which credential to use via simple key-value pairs. Each key maps to a field id already declared in the Presentation Definition's input descriptor constraints. The value narrows the match to credentials where that field equals the given value.

A configurable CredentialSelector is injected into the PD matcher's matchConstraints function. When credential_selection is provided, a parameter-based selector filters the candidates by matching field values. When not provided, the default selector (first match) preserves current behavior. The Match public API and return types remain unchanged — one credential per input descriptor.

The selection must narrow to exactly one credential per input descriptor. Zero matches → error (soft failure if submission requirements allow it, e.g. min: 0). Multiple matches → error. The EHR must provide values specific enough to select one credential.

How It Works

PDs already declare constraint fields with optional id properties. These IDs are used for extracting values into the access token via ResolveConstraintsFields, which builds a flat map[string]any (field ID → value). This flat map is stored in AccessToken.InputDescriptorConstraintIdMap and returned as top-level claims in the introspection response. Field IDs are already validated to be globally unique across all PDs in the WalletOwnerMapping — duplicates cause a ServerError (see resolveInputDescriptorValues in s2s_vptoken.go).

Example PD field:

{
  "id": "patient_id",
  "path": ["$.credentialSubject.hasEnrollment.patient.identifier.value"],
  "filter": { "type": "string" }
}

The credential_selection parameter reuses these field IDs. When the EHR provides { "patient_id": "123456789" }, the selector finds all candidates matching the input descriptor's constraints, then further narrows to those where the patient_id field equals "123456789".

The PD author controls what is selectable by assigning id values to constraint fields. The EHR only needs to know the field name and the value — no JSON paths, no query language syntax.

User Stories

1. As an EHR developer, I want to specify which patient's PatientEnrollmentCredential to present, so that the correct patient context is established in the access token request.
2. As an EHR developer, I want to specify which HealthcareProviderTypeCredential to present, so that the correct organization type is used when my organization has multiple classifications.
3. As an EHR developer, I want to only provide credential_selection for ambiguous credential types, so that I don't need to specify selection criteria for credentials that are already unambiguous.
4. As an EHR developer, I want a clear error when my selection criteria match zero credentials in the wallet, so that I can diagnose misconfiguration or missing credentials.
5. As an EHR developer, I want a clear error when my selection criteria still match multiple credentials, so that I know my values are not specific enough.
6. As an EHR developer, I want a simple key-value interface for credential selection, so that I don't need to learn a query language or know internal credential JSON paths.
7. As an EHR developer, I want to continue providing self-attested credentials via the existing credentials array alongside credential_selection, so that both mechanisms work together.
8. As an EHR developer, I want the existing behavior (PD picks first match) to be preserved for input descriptors where I don't provide selection criteria, so that this change is backward compatible.
9. As a Nuts node operator, I want credential selection errors to be descriptive, so that I can help EHR vendors troubleshoot integration issues.

Implementation Decisions

API Design

The ServiceAccessTokenRequest gains one new optional field:

• credential_selection: An object mapping PD field ids to expected values. Each key MUST match a field id declared in a PD input descriptor's constraints. Field IDs are already guaranteed unique across PDs (enforced by resolveInputDescriptorValues duplicate detection).

Example request:

{
  "scope": "medicatieoverdracht-gf",
  "authorization_server": "https://verifier.example.com",
  "credential_selection": {
    "patient_id": "123456789"
  }
}

Compare to the previous DCQL approach (now superseded):

{
  "credential_query": [
    {
      "id": "id_patient_enrollment",
      "claims": [
        {
          "path": ["credentialSubject", "hasEnrollment", "patient", "identifier", "value"],
          "values": ["123456789"]
        }
      ]
    }
  ]
}

CredentialSelector Architecture

A CredentialSelector strategy is injected into the PD matcher's matchConstraints function. This is the same injection point used by the DCQL selector (#4089). See approach comment.

matchConstraints collects all matching VCs per input descriptor (removes the break on first match), then calls the CredentialSelector to pick one. The Match return type and Candidate struct remain unchanged.

type CredentialSelector func(inputDescriptor InputDescriptor, candidates []vc.VerifiableCredential) (*vc.VerifiableCredential, error)

• Default selector: picks the first match (preserves current behavior)
• Selection selector: for each candidate, resolves the PD fields referenced by credential_selection keys, keeps only candidates where all field values match the given values, errors on zero or multiple remaining candidates

The selection selector follows the same factory pattern as NewDCQLSelector in vcr/pe/selector.go (branch feature/4089-dcql-selector): validate selection keys against PD field IDs at construction time, return a CredentialSelector closure. The wiring through buildSubmission in presenter.go (branch feature/4090-api-credential-query) is also directly reusable — replace credentialQueries []dcql.CredentialQuery with credentialSelection map[string]string.

Error handling in matchConstraints:

• ErrNoCredentials from the selector is treated as a soft failure (nil selection), allowing submission requirements (e.g., pick rules with min: 0) to evaluate whether zero fulfilled descriptors is acceptable.
• ErrMultipleCredentials and other errors are hard failures.

Trade-offs

This approach is simpler but more constrained than a full query language:

	credential_selection (chosen)	credential_query (DCQL, superseded)
Caller complexity	Key-value pairs, no paths needed	Must know JSON paths and DCQL syntax
Query expressiveness	Equality only, pre-declared fields	Arbitrary paths, OR semantics
PD author effort	Add id to selectable fields (often already done for introspection)	None (queries are self-contained)
Error surface	Wrong key name	Wrong path, wrong ID, wrong structure

Why the simpler approach is sufficient:

• Real-world use cases are equality matches on known fields (which patient, which organization type).
• The PD already declares relevant fields with ids for access token value extraction — reusing these avoids duplication.
• Field IDs are already guaranteed unique across PDs and surfaced as flat claims in introspection — the namespace is consistent.
• If a richer query language is needed in the future, it can be added as a separate parameter without breaking credential_selection.

Modules

1. CredentialSelector in PD matcher (Refactor PD matching to return all candidates per input descriptor #4088, modify vcr/pe): Inject CredentialSelector into matchConstraints. Collect all candidates per input descriptor, then call selector. Default selector picks first match. Soft-fail for ErrNoCredentials. Status: PR #4088: CredentialSelector extension point in PD matcher #4098 open.
2. Selection CredentialSelector (new issue, reuses code from feature/4089-dcql-selector): Implementation that resolves PD field ids against candidates and filters by the credential_selection values. Same factory pattern as NewDCQLSelector — validate keys at construction, return selector closure. Errors on zero or multiple matches.
3. API layer + OpenAPI spec (Add credential_selection to access token request API #4090, modify auth/api/iam, reuses wiring from feature/4090-api-credential-query): Add credential_selection to ServiceAccessTokenRequest, propagate through RequestRFC021AccessToken → BuildSubmission → presenter.buildSubmission → builder.SetCredentialSelector. Same call chain as the DCQL approach, with map[string]string instead of []dcql.CredentialQuery.

Superseded modules:

• Credential filter chain with DCQL and default selector #4089 — DCQL CredentialSelector (replaced by selection selector; code in feature/4089-dcql-selector branch reusable for structure/tests)

Modules kept open for future consideration:

• DCQL credential query parser with claims/values matching #4087 — DCQL credential query parser (may be useful if richer query support is needed later)

Reusable Code

Branches feature/4089-dcql-selector and feature/4090-api-credential-query contain implementation that maps closely to the new approach:

Branch	File	What to reuse
4089	vcr/pe/selector.go	Factory pattern: validate IDs at construction, return CredentialSelector closure. Replace dcql.Match with field-value matching.
4089	vcr/pe/selector_test.go	Test structure: fallback, single match, zero matches, multiple matches, ID validation, multi-descriptor. Adapt assertions.
4090	vcr/holder/presenter.go	buildSubmission wiring: create selector if selection provided, call builder.SetCredentialSelector. Replace []dcql.CredentialQuery param with map[string]string.
4090	vcr/holder/interface.go	BuildSubmission signature change. Replace credentialQueries param with credentialSelection.
4090	auth/api/iam/api.go	API handler: parse selection from request, propagate to client. Simpler than DCQL parsing.
4090	docs/_static/auth/v2.yaml	OpenAPI spec structure. Replace credential_query schema with credential_selection object.

Testing Decisions

• CredentialSelector (Refactor PD matching to return all candidates per input descriptor #4088): Unit tests for default selector (first match), selector called with all candidates, soft-fail for ErrNoCredentials with min: 0 submission requirements. Existing PD matching tests pass unchanged. Done in PR #4088: CredentialSelector extension point in PD matcher #4098.
• Selection CredentialSelector (new): Adapt test structure from feature/4089-dcql-selector branch. Unit tests for: single match success, zero matches error (ErrNoCredentials), multiple matches error (ErrMultipleCredentials), selection key not matching any PD field ID errors, multiple selection keys (AND semantics), fallback to default selector for descriptors without matching selection keys, interaction with submission requirements.
• API layer (Add credential_selection to access token request API #4090): End-to-end tests for the full request flow with and without credential_selection. Adapt from feature/4090-api-credential-query e2e test.

Out of Scope

• Replacing PD with DCQL entirely: Longer-term goal. DCQL currently lacks some PD features we depend on, notably regex-based value extraction for token introspection.
• Verifier-side changes: The verifier's PD and token validation are unchanged. credential_selection is purely a requestor-side wallet selection mechanism.
• Complex query support: Range queries, OR semantics, pattern matching on selection values. Can be added later if needed.
• Migration of existing PD configurations: Existing PDs continue to work unchanged.

Sub-issues

• Refactor PD matching to return all candidates per input descriptor #4088 — CredentialSelector extension point in PD matcher (PR #4088: CredentialSelector extension point in PD matcher #4098, open)
• Selection CredentialSelector: filter candidates by PD field ID values #4120 — Selection CredentialSelector: filter candidates by PD field ID values (replaces Credential filter chain with DCQL and default selector #4089)
• Add credential_selection to access token request API #4090 — Add credential_selection to access token request API (scope updated from credential_query)

Dependency graph

#4088 ──> #4120  ──> #4090

Changelog

• 2025-03-25: Replaced credential_query (DCQL) approach with credential_selection (named parameters). Motivation: user feedback indicated DCQL queries are complex to implement for EHR developers and the actual use cases are simple equality matches on known fields. The named parameter approach reuses existing PD field ids (already guaranteed unique and used for introspection claims), is dramatically simpler for callers, and sufficient for current requirements. DCQL parser (DCQL credential query parser with claims/values matching #4087) kept open for potential future use. DCQL selector (Credential filter chain with DCQL and default selector #4089) superseded; code in local branch reusable for structure. Added soft-fail semantics for ErrNoCredentials in matchConstraints (discovered during PR #4088: CredentialSelector extension point in PD matcher #4098 review). Added ErrNoCredentials soft-fail handling and test in PR #4088: CredentialSelector extension point in PD matcher #4098. See original DCQL-based PRD in edit history for the previous approach.