DCQL credential query parser with claims/values matching

[stevenvegt]

Parent PRD

#4067 (see PRD comment)

What to build

Standalone DCQL credential query parser that evaluates DCQL credential queries (OpenID4VP sections 6.1/6.3/7) against a list of Verifiable Credentials and returns matching VCs.

Interface: takes a DCQL credential query object and a list of VCs, returns the subset that matches (or an error for invalid queries).

Spec compliance

This implements a subset of the DCQL specification (OpenID4VP 1.0 sections 6 and 7). The supported and unsupported features are documented in the package.

Credential Query (section 6.1) — supported fields:

• id (REQUIRED): validated per spec (non-empty, alphanumeric/underscore/hyphen only)
• claims (OPTIONAL): array of claims queries

Credential Query — not supported (not needed for our use case):

• format: credential format selection is handled by PD matching
• meta: credential metadata constraints are handled by PD matching
• multiple: we use match_policy in the filter chain instead
• claim_sets: not needed for our value-matching use case
• trusted_authorities: trust is handled by PD matching and DID resolution
• require_cryptographic_holder_binding: handled by VP verification

Claims Query (section 6.3) — supported fields:

• path (REQUIRED): Claims Path Pointer per section 7 (strings, integers, null)
• values (OPTIONAL): exact value matching with OR semantics

Claims Query — not supported:

• id: only needed when claim_sets is used
• claim_sets on the credential query: not needed

Claims Path Pointer (section 7) — supported:

• String elements: key lookup in JSON objects
• Non-negative integer elements: array index lookup
• Null elements: wildcard, selects all elements of an array
• Path starts at the credential root (not scoped to credentialSubject)

Implementation details

• Exact value matching via values parameter (strings, integers, booleans)
• OR semantics when multiple values are specified (match if any value matches)
• Multiple claims entries in a single query (AND semantics — all must match)
• Path resolution supports the full credential JSON (root-level fields like type, issuer, as well as nested credentialSubject fields)
• credentialSubject is unwrapped from its Go array representation to a single object for ergonomic path access

No integration with PD matching, wallet, or API yet — this is purely the matching engine.

See "DCQL Support" and "DCQL credential query parser" in the PRD for full context.

Acceptance criteria

• Parses DCQL credential query objects with id and claims array
• Validates id per spec: non-empty, alphanumeric/underscore/hyphen characters only
• Returns error for invalid credential query (empty or invalid id)
• Path resolution starts at the credential root, supporting top-level fields (type, issuer, etc.)
• Path supports string elements (key lookup in objects)
• Path supports non-negative integer elements (array index lookup)
• Path supports null elements (wildcard: select all array elements)
• Matches values with exact equality for strings, integers, and booleans
• Multiple values in a single claim query use OR semantics
• Multiple claims entries use AND semantics
• Returns all matching VCs from the input list
• Returns empty list (not error) when no VCs match
• Handles edge cases: missing fields in credential, empty claims array, deeply nested paths
• Supported DCQL subset is documented in the package
• Unit tests covering all of the above
• Benchmark: ~14ms worst case for 2000 credentials

Blocked by

None.

User stories addressed

• User story 7: standard DCQL syntax
• User story 10: exact value matching on claim fields
• User story 11: multiple values with OR semantics