Attesto.VpToken (Attesto v2.28.0)

Copy Markdown View Source

OID4VP vp_token verification for SD-JWT VC (dc+sd-jwt) and ISO mdoc (mso_mdoc) presentations (OID4VP §7).

The response is a map from credential-query IDs to non-empty arrays of presentations. Verification is conn-free. SD-JWT VC entries delegate issuer signature, disclosure, VC claim, and holder Key Binding JWT checks to Attesto.SdJwtVc and Attesto.SdJwt; mso_mdoc entries delegate Device- Response and device-signature checks to Attesto.Mdoc.verify_device_response/4.

Holder key binding is mandatory for SD-JWT VC: a credential without a cnf.jwk or a valid Key Binding JWT cannot satisfy an OID4VP request. mdoc presentations carry their own device-signature binding instead.

Issuer trust comes from exactly one of :issuer_jwks, :resolve_issuer, or :trusted_certificates. Certificate trust delegates chain validation to the credential verifier and uses the validated leaf key without key lookup or fallback. :certificate_trust adds host policy; :haip defaults to true.

Format dispatch

Each query ID's format is resolved via the optional :formats option — a map of query ID to "dc+sd-jwt" or "mso_mdoc" — falling back to format detection when a query ID is absent from :formats (or the option itself is omitted): a ~-delimited string is SD-JWT VC, a plain base64url string is mso_mdoc. Prefer :formats when the DCQL query is known ahead of time; detection exists for callers that don't thread it through.

mdoc context

An mso_mdoc entry additionally needs :response_uri — the OID4VP response_uri the wallet's DeviceResponse was bound to via its OpenID4VPHandover SessionTranscript. :audience doubles as the handover's client_id and the shared :nonce as its nonce. The optional :response_encryption_jwk binds encrypted responses to the encryption key. SD-JWT-VC-only callers never need :response_uri; it is required only when the vp_token actually contains an mso_mdoc entry.

Set :dc_api_origin to select the mdoc Digital Credentials API flow instead. It takes the exact platform origin, without an origin: prefix; serialized HTTP(S) origins omit paths, trailing slashes and default ports. Platform application URIs are also supported. :response_uri and :audience do not enter the mdoc DC API transcript. :audience remains required and is still used directly for SD-JWT Key Binding JWTs (use "origin:" <> origin for those in a DC API response). Invalid DC API origin/key options raise before response parsing or issuer resolution. Omit :response_encryption_jwk for dc_api; supply the actual response encryption public key for dc_api.jwt.

OpenID4VP 1.0 §B.2.6.2 requires "OpenID4VPDCAPIHandover" for this transcript. The full rules, source quotations and HAIP §5.2 encryption requirement are documented in Attesto.Mdoc. This function verifies presentations after the host has decrypted any response envelope; it does not invoke the browser API. Credential status references are fetched and enforced by default through Attesto.StatusList.fetch/3 and its bounded verified-token cache. Explicit resolve_status: false is for offline inspection; it must not be used to decide whether a credential is acceptable. A custom resolver can replace the transport while retaining signature and status enforcement.

Summary

Functions

Derive per-query-id verification constraints from a DCQL query, for the :query_constraints option of verify/2.

Return whether a DCQL scalar claim value strictly matches at least one entry in allowed (===, so numbers, booleans, and strings never coerce across types). Used by both the verifier and wallet claim-filtering logic.

Traverse root using an OID4VP DCQL claims path pointer ([component | rest]). Returns {:ok, selected_values} or :error when any step fails or selects nothing.

Verify an OID4VP vp_token carrying SD-JWT VC and/or mso_mdoc presentations.

Types

certificate_option()

@type certificate_option() ::
  {:certificate_trust, ([binary()] -> :ok | {:error, term()})}
  | {:haip, boolean()}

issuer_trust()

@type issuer_trust() ::
  {:issuer_jwks, map() | list()}
  | {:resolve_issuer, (String.t() -> term())}
  | {:trusted_certificates, [binary()]}

mdoc_safe_result()

@type mdoc_safe_result() :: %{
  doc_type: String.t(),
  namespaces: map(),
  device_namespaces: map(),
  validity: map()
}

safe_result()

@type safe_result() :: %{
  vct: String.t(),
  iss: String.t(),
  claims: map(),
  cnf: map() | nil
}

verify_result()

@type verify_result() :: {:ok, map()} | {:error, term()}

Functions

constraints_from_dcql(dcql_query)

@spec constraints_from_dcql(map()) :: %{optional(String.t()) => map()}

Derive per-query-id verification constraints from a DCQL query, for the :query_constraints option of verify/2.

The query is first normalized with Attesto.PresentationRequest.dcql_query/1, so malformed empty constraints raise ArgumentError instead of being weakened. For each credential query this function extracts the requested format, cardinality, accepted credential type (vct_values for dc+sd-jwt, doctype_value/doctype_values for mso_mdoc), claims, and claim_sets. It also embeds the query's required credential-set options in every entry so the returned map is sufficient to enforce the complete DCQL response plan. verify/2 enforces these after signature and holder binding. Query IDs absent from the returned map are unconstrained.

dcql_value_matches?(value, allowed)

@spec dcql_value_matches?(term(), [term()]) :: boolean()

Return whether a DCQL scalar claim value strictly matches at least one entry in allowed (===, so numbers, booleans, and strings never coerce across types). Used by both the verifier and wallet claim-filtering logic.

resolve_json_path(root, path)

@spec resolve_json_path(map() | [term()], [term()]) :: {:ok, [term()]} | :error

Traverse root using an OID4VP DCQL claims path pointer ([component | rest]). Returns {:ok, selected_values} or :error when any step fails or selects nothing.

verify(vp_token, opts \\ [])

@spec verify(
  term(),
  keyword()
) :: verify_result()

Verify an OID4VP vp_token carrying SD-JWT VC and/or mso_mdoc presentations.

Required options are :nonce, :audience, and exactly one issuer trust source: :issuer_jwks for static issuer keys, :resolve_issuer for a callback receiving the presentation's (unverified) issuer identity, or :trusted_certificates for a non-empty list of DER trust-anchor binaries. Certificate trust verifies each SD-JWT VC's x5c or mdoc's x5chain and uses only the validated leaf key, with no issuer-key lookup or fallback. :certificate_trust is an optional additional chain-policy callback (see Attesto.X509.verify/2); :haip is a boolean, defaulting to true, which refuses self-signed leaves and chains containing a configured anchor. SD-JWT VC also binds the leaf to iss; mdoc does not bind certificates to docType (see Attesto.Mdoc). Certificate validity uses the system clock. The optional :now value is passed to both the VC/mdoc and holder-binding verifiers. See the moduledoc for :formats and :response_uri. :accepted_algs is forwarded to SD-JWT and mdoc issuer verification, independently of holder authentication. For mdoc it defaults to ["ES256"] and can include "ES384" and "ES512", with strict EC curve pairing. :enforce_fapi_alg_policy applies only to SD-JWT issuer verification. :expected_query_ids identifies individually required entries; :permitted_query_ids can include optional requested entries. :required_credential_sets carries DCQL's AND-of-ORs response rule as a list of required sets, each containing one or more complete credential-ID options. For example, [[["pid"], ["mdl"]], [["address"]]] requires either pid or mdl, and also requires address. An explicit empty list represents a DCQL query whose credential sets are all optional and is the only policy that permits an empty VP Token. constraints_from_dcql/1 embeds this policy in its result, so callers already storing that result as :query_constraints do not need to pass a second option. When omitted, the permitted set is derived from expected IDs, constraint keys, and required-set IDs. Entries outside that set are rejected before format detection or issuer lookup. Only low-level calls omitting all query-policy options accept arbitrary non-empty query IDs. Constraints remain enforced on optional entries when they are present. A query constraint permits multiple presentations only when its :multiple or "multiple" member is explicitly true; omission applies DCQL's default of one presentation. Malformed response maps and values return {:error, :invalid_vp_token}; malformed trusted options still raise ArgumentError.

:resolve_issuer receives UNVERIFIED issuer material

For SD-JWT VC, the callback is handed the iss peeked from the still- unverified issuer JWT (verifying the signature requires the key, which requires iss — so the lookup is unavoidably ahead of verification). For mso_mdoc, it is handed the docType peeked from the still-unverified DeviceResponse in the same way. The signature is then checked against whatever keys the callback returns, so forged issuer material cannot forge a credential — it only misdirects the key lookup. But the callback MUST NOT make a network request derived from this value without an allow-list: the presenter controls it, so a naive fetch is an SSRF sink. Resolve from a trusted issuer registry, not by dereferencing the peeked value.

Each query ID must contain a non-empty list of presentation strings and produces a list of safe results, as required by OID4VP 1.0. The explicit :legacy_scalar_values option (default false) also accepts a non-empty presentation string and returns one safe result for that legacy entry. Raw JWTs and raw DeviceResponse bytes are never returned.

:max_presentations_per_query bounds verification work for every query ID, including low-level calls without DCQL constraints. It defaults to 16 and must be a positive integer. This cap still applies when DCQL multiple is explicitly true.