@openeudi/openid4vp 0.11.1 → 0.12.0

package/README.md

@@ -119,6 +119,73 @@ Supported formats: `dc+sd-jwt` and `mso_mdoc`. Other formats (e.g., `jwt_vc_json
 
 Known EUDI doctypes auto-namespace their claim paths (e.g., `org.iso.18013.5.1.mDL` → claims under `org.iso.18013.5.1`). Unknown doctypes use the full doctype string as the namespace.
 
+### Offering the wallet a choice (`credential_sets`)
+
+Some questions can be answered by more than one credential. The clearest case is
+proof of age: a wallet may hold a **Proof-of-Age attestation** (`mso_mdoc`, with
+`age_over_18` in namespace `eu.europa.ec.av.1`) or only a **PID** (`dc+sd-jwt`,
+carrying `birth_date` — the PID has no age attribute, so the verifier computes the
+threshold). Asking for both in one request avoids a second wallet interaction:
+
+```ts
+import { buildCredentialSetQuery } from "@openeudi/openid4vp";
+
+const query = buildCredentialSetQuery({
+  options: [
+    // Most-preferred first — discloses only a boolean.
+    {
+      credentialId: "age-attestation",
+      format: "mso_mdoc",
+      doctypeValue: "eu.europa.ec.av.1",
+      claims: ["age_over_18"],
+    },
+    // Fallback — the verifier computes the threshold from birth_date.
+    {
+      credentialId: "pid",
+      format: "dc+sd-jwt",
+      vctValues: ["urn:eu.europa.ec.eudi:pid:1"],
+      claims: ["birth_date"],
+    },
+  ],
+});
+```
+
+The wallet satisfies **one** option and returns **one** presentation;
+`verifyAuthorizationResponse` resolves it by the id the wallet keyed `vp_token`
+with. Option order is a privacy preference signal, not a constraint — wallets are
+not obliged to honour it.
+
+Validate a hand-built disjunction with `validateCredentialSetQuery`. Note this is
+deliberately **not** HAIP-minimal: `validateHaipQuery` rejects `credential_sets`
+and `isHaipQuery` returns `false` for these queries.
+
+> **`match.unmatched` is non-empty on success here.** A disjunction is satisfied
+> when the wallet takes **one** option, so the option it did *not* take is
+> reported as unmatched — typically with `format_mismatch` or `vct_mismatch`
+> against the credential the wallet never held. That is the expected result, not
+> a failure:
+>
+> ```ts
+> // Wallet presented the PID; the attestation option was not taken.
+> result.valid                  // true
+> result.match.satisfied        // true
+> result.match.matches          // [{ queryId: "pid", ... }]
+> result.match.unmatched        // [{ queryId: "age-attestation", reason: "format_mismatch" }]
+> ```
+>
+> Gate on `result.valid` (or `match.satisfied`), **never** on
+> `match.unmatched.length === 0`. The latter is the correct test only for a query
+> without `credential_sets`, and silently rejects every valid disjunction
+> response. If you log `unmatched` as "mismatch reasons" (as the verification
+> example below does), expect a benign entry per successful disjunction and
+> filter accordingly so it does not trip alerting.
+
+> **Not ZKP.** This is the plain `mso_mdoc` attestation path. The AV technical
+> specification's preferred mechanism — a Zero-Knowledge Proof — is not supported
+> over OpenID4VP (no standardised DCQL query for it exists); it rides only the W3C
+> Digital Credentials API. Plain mDoc is the profile's designated fallback for this
+> transport.
+
 ## Verifying presentations against a query
 
 Use `verifyPresentation` to combine crypto/structural verification with DCQL matching in a single call:
@@ -143,6 +210,11 @@ if (result.valid) {
 
 Mismatches return `valid: false` — they do not throw. Only crypto/structural failures (malformed VP tokens, invalid signatures, expired credentials) and malformed DCQL queries throw exceptions.
 
+The `else` branch above is the right place to read `unmatched` for an ordinary
+query. For a **`credential_sets` disjunction** it is not the whole story: the
+option the wallet did not take is reported as unmatched even when `valid` is
+`true`. See [Offering the wallet a choice](#offering-the-wallet-a-choice-credential_sets).
+
 > **Privacy — diagnostics are verifier-internal.** `match.unmatched[].reason` and `detail` (including `value_mismatch`) are intended for verifier-side logging, debugging, and admin UIs. OpenID4VP §11 warns that per-claim verification outcomes can reveal wallet contents to observers. Do NOT echo these diagnostics into the OpenID4VP wire response sent back to the wallet, into end-user-visible error messages that another party could correlate, or into public analytics/third-party logs. The protocol's own error codes are the public interface; these fields are your internal instrumentation.
 
 ## Signed authorization requests (x509_san_dns, x509_hash)
@@ -318,6 +390,21 @@ Both `parsePresentation` and `verifyPresentation` accept:
 - `verifierEncryptionJwk?` — *(`VerifyAuthorizationResponseOptions` only)* the verifier's response-encryption public JWK. Required on the encrypted path when `sessionTranscriptProfile: 'openid4vp-1.0'` is used, to derive the handover's JWK thumbprint; ignored for the `'iso-18013-7'` profile.
 - `trustedCertificates` (required when `trustStore` is unset) — DER-encoded issuer leaf certificates for the 0.4.x byte-equality trust check. Deprecated since 0.5.0 — pass an empty array and supply `trustStore` for production deployments.
 - `trustStore?` — `TrustStore` instance for full RFC 5280 chain validation (e.g. `LotlTrustStore`, `StaticTrustStore`, or `CompositeTrustStore`). When set, takes precedence over `trustedCertificates`.
+
+  > **`LotlTrustStore` requires an `xmldsigjs` crypto engine.** Trusted lists are
+  > verified as signed XML, and this library does not pick a WebCrypto provider on
+  > your behalf. Register one **once at startup**, before any trusted-list fetch:
+  >
+  > ```ts
+  > import * as xmldsig from "xmldsigjs";
+  > import { Crypto } from "@peculiar/webcrypto";
+  >
+  > xmldsig.Application.setEngine("NodeJS", new Crypto());
+  > ```
+  >
+  > Omit it and `LotlTrustStore` throws `LotlConfigurationError` on first use,
+  > naming this as the cause. `StaticTrustStore` is unaffected.
+
 - `revocationPolicy?` — `'skip'` (default) | `'prefer'` | `'require'`. Controls whether the chain validator consults OCSP / CRL.
 - `fetcher?` — HTTP transport for CRL/OCSP/LOTL fetches. Defaults to `globalThis.fetch`.
 - `cache?` — cache for CRL/OCSP/LOTL artefacts. Defaults to `new InMemoryCache()`.
@@ -405,6 +492,7 @@ class MyCustomParser implements ICredentialParser {
 | `MalformedCredentialError` | Credential structure is malformed         | Token cannot be decoded or is structurally invalid |
 | `NonceValidationError`     | Nonce does not match expected value       | Key binding JWT nonce does not match               |
 | `HaipValidationError`      | HAIP query constraint violated            | DCQL query fails `validateHaipQuery`               |
+| `LotlConfigurationError`   | No xmldsigjs crypto engine registered     | `LotlTrustStore` used without `Application.setEngine` |
 
 ```ts
 import { MalformedCredentialError, ExpiredCredentialError } from "@openeudi/openid4vp";
@@ -427,7 +515,7 @@ This library implements the **verifier side** of OpenID4VP for SD-JWT VC and mDO
 - **SD-JWT VC** — full cryptographic verification (issuer JWT signature via `x5c`, transitive disclosure-hash check, key binding JWT signature + `sd_hash`, nonce check). Holder binding (KB-JWT) is **mandatory and fails closed** whenever the issuer JWT carries a `cnf` claim; `requireKeyBinding` extends the requirement to credentials without `cnf`. Optional `trustedIssuerJwks` alternate trust path for VCs without `x5c`.
 - **mDOC / ISO 18013-5** `mso_mdoc` format — CBOR decoding, claim extraction, COSE_Sign1 signature verification, MobileSecurityObject validity enforcement, IssuerSignedItem digest verification. Device authentication (ISO 18013-5 §9.1.3) is **mandatory and fails closed**: the `DeviceSignature` (COSE_Sign1) over `DeviceAuthentication`/`SessionTranscript` is verified against the MSO-committed device key. `DeviceMac` (COSE_Mac0) is **not supported and is rejected**.
 - **DCQL** — authorization request builder with DCQL query, matching via [@openeudi/dcql](https://www.npmjs.com/package/@openeudi/dcql), `verifyPresentation` for combined crypto + match.
-- **HAIP** — `buildHaipQuery` / `validateHaipQuery` helpers for the High Assurance Interoperability Profile.
+- **HAIP** — `buildHaipQuery` / `validateHaipQuery` helpers for the High Assurance Interoperability Profile, plus `buildCredentialSetQuery` / `validateCredentialSetQuery` for `credential_sets` disjunctions.
 - **Signed authorization requests (JAR)** — `createSignedAuthorizationRequest` per RFC 9101 / OpenID4VP 1.0 §5.10 with `x509_san_dns` or `x509_hash` client-id binding. Emits the OpenID4VP 1.0 Final `client_metadata` shape. Self-signed verifier leaf certificates are rejected by default per HAIP 1.0 Final.
 - **Encrypted responses** — `decryptAuthorizationResponse` for `direct_post.jwt` (ECDH-ES + A128GCM/A256GCM), `verifyAuthorizationResponse` for the 1.0 §8.1 object-keyed `vp_token` envelope.
 - **X.509 chain validation** — RFC 5280 chain building including `nameConstraints`, `StaticTrustStore`, `CompositeTrustStore`.

package/dist/index.cjs

@@ -45,7 +45,7 @@ var init_reflect_polyfill = __esm({
 });
 
 // src/errors.ts
-exports.InvalidSignatureError = void 0; exports.ExpiredCredentialError = void 0; exports.UnsupportedFormatError = void 0; exports.MalformedCredentialError = void 0; exports.NonceValidationError = void 0; exports.HaipValidationError = void 0; exports.OpenID4VPError = void 0; exports.TrustAnchorNotFoundError = void 0; exports.CertificateChainError = void 0; exports.RevokedCertificateError = void 0; exports.RevocationCheckFailedError = void 0; exports.LotlFetchError = void 0; exports.LotlSignatureError = void 0; exports.SignedRequestBuildError = void 0; exports.UnsupportedJweError = void 0; exports.DecryptionFailedError = void 0; exports.MissingDecryptionKeyError = void 0; exports.MissingVerifierEncryptionKeyError = void 0; exports.MultipleCredentialsNotSupportedError = void 0;
+exports.InvalidSignatureError = void 0; exports.ExpiredCredentialError = void 0; exports.UnsupportedFormatError = void 0; exports.MalformedCredentialError = void 0; exports.NonceValidationError = void 0; exports.HaipValidationError = void 0; exports.OpenID4VPError = void 0; exports.TrustAnchorNotFoundError = void 0; exports.CertificateChainError = void 0; exports.RevokedCertificateError = void 0; exports.RevocationCheckFailedError = void 0; exports.LotlFetchError = void 0; exports.LotlSignatureError = void 0; exports.LotlConfigurationError = void 0; exports.SignedRequestBuildError = void 0; exports.UnsupportedJweError = void 0; exports.DecryptionFailedError = void 0; exports.MissingDecryptionKeyError = void 0; exports.MissingVerifierEncryptionKeyError = void 0; exports.MultipleCredentialsNotSupportedError = void 0;
 var init_errors = __esm({
   "src/errors.ts"() {
     init_reflect_polyfill();
@@ -142,6 +142,9 @@ var init_errors = __esm({
     exports.LotlSignatureError = class extends exports.OpenID4VPError {
       code = "lotl_signature_invalid";
     };
+    exports.LotlConfigurationError = class extends exports.OpenID4VPError {
+      code = "lotl_configuration_invalid";
+    };
     exports.SignedRequestBuildError = class extends exports.OpenID4VPError {
       code;
       constructor(code, message) {
@@ -8443,6 +8446,33 @@ function buildHaipQuery(input) {
   }
   return { credentials: [credential] };
 }
+function buildCredentialSetQuery(input) {
+  if (input.options.length === 0) {
+    throw new exports.HaipValidationError(
+      "EMPTY_OPTIONS",
+      "a credential set must offer at least one option"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const option of input.options) {
+    if (seen.has(option.credentialId)) {
+      throw new exports.HaipValidationError(
+        "DUPLICATE_CREDENTIAL_ID",
+        `credential '${option.credentialId}' is declared by more than one option; credential ids must be unique for credential_sets to reference them`,
+        option.credentialId
+      );
+    }
+    seen.add(option.credentialId);
+  }
+  const credentials = input.options.map((option) => buildHaipQuery(option).credentials[0]);
+  const credentialSet = {
+    options: input.options.map((option) => [option.credentialId])
+  };
+  if (input.required === false) {
+    credentialSet.required = false;
+  }
+  return { credentials, credential_sets: [credentialSet] };
+}
 var HAIP_FORMATS = /* @__PURE__ */ new Set(["dc+sd-jwt", "mso_mdoc"]);
 function validateHaipQuery(query) {
   if (!query.credentials || query.credentials.length === 0) {
@@ -8458,46 +8488,86 @@ function validateHaipQuery(query) {
     );
   }
   for (const credential of query.credentials) {
-    if (!HAIP_FORMATS.has(credential.format)) {
+    validateCredential(credential);
+  }
+}
+function validateCredential(credential) {
+  if (!HAIP_FORMATS.has(credential.format)) {
+    throw new exports.HaipValidationError(
+      "UNSUPPORTED_FORMAT",
+      `credential '${credential.id}' uses unsupported format '${credential.format}' (allowed: dc+sd-jwt, mso_mdoc)`,
+      credential.id
+    );
+  }
+  if (credential.format === "dc+sd-jwt") {
+    const vctValues = credential.meta?.vct_values;
+    if (!vctValues || vctValues.length === 0) {
       throw new exports.HaipValidationError(
-        "UNSUPPORTED_FORMAT",
-        `credential '${credential.id}' uses unsupported format '${credential.format}' (allowed: dc+sd-jwt, mso_mdoc)`,
+        "MISSING_SDJWT_META",
+        `credential '${credential.id}' with format 'dc+sd-jwt' must set meta.vct_values`,
         credential.id
       );
     }
-    if (credential.format === "dc+sd-jwt") {
-      const vctValues = credential.meta?.vct_values;
-      if (!vctValues || vctValues.length === 0) {
-        throw new exports.HaipValidationError(
-          "MISSING_SDJWT_META",
-          `credential '${credential.id}' with format 'dc+sd-jwt' must set meta.vct_values`,
-          credential.id
-        );
-      }
-    }
-    if (credential.format === "mso_mdoc") {
-      if (typeof credential.meta?.doctype_value !== "string") {
-        throw new exports.HaipValidationError(
-          "MISSING_MDOC_META",
-          `credential '${credential.id}' with format 'mso_mdoc' must set meta.doctype_value`,
-          credential.id
-        );
-      }
-    }
-    if (!credential.claims || credential.claims.length === 0) {
+  }
+  if (credential.format === "mso_mdoc") {
+    if (typeof credential.meta?.doctype_value !== "string") {
       throw new exports.HaipValidationError(
-        "NO_CLAIMS",
-        `credential '${credential.id}' must declare at least one claim`,
+        "MISSING_MDOC_META",
+        `credential '${credential.id}' with format 'mso_mdoc' must set meta.doctype_value`,
         credential.id
       );
     }
-    if (credential.claim_sets !== void 0) {
+  }
+  if (!credential.claims || credential.claims.length === 0) {
+    throw new exports.HaipValidationError(
+      "NO_CLAIMS",
+      `credential '${credential.id}' must declare at least one claim`,
+      credential.id
+    );
+  }
+  if (credential.claim_sets !== void 0) {
+    throw new exports.HaipValidationError(
+      "CLAIM_SETS_DISALLOWED",
+      `credential '${credential.id}' uses claim_sets, not permitted in HAIP-minimal`,
+      credential.id
+    );
+  }
+}
+function validateCredentialSetQuery(query) {
+  if (!query.credentials || query.credentials.length === 0) {
+    throw new exports.HaipValidationError(
+      "EMPTY_QUERY",
+      "query.credentials must have at least one entry"
+    );
+  }
+  if (!query.credential_sets || query.credential_sets.length === 0) {
+    throw new exports.HaipValidationError(
+      "MISSING_CREDENTIAL_SETS",
+      "a credential-set query must declare at least one credential_sets entry"
+    );
+  }
+  for (const credential of query.credentials) {
+    validateCredential(credential);
+  }
+  const declaredIds = new Set(query.credentials.map((c) => c.id));
+  for (const credentialSet of query.credential_sets) {
+    if (!credentialSet.options || credentialSet.options.length === 0) {
       throw new exports.HaipValidationError(
-        "CLAIM_SETS_DISALLOWED",
-        `credential '${credential.id}' uses claim_sets, not permitted in HAIP-minimal`,
-        credential.id
+        "EMPTY_OPTIONS",
+        "a credential set must offer at least one option"
       );
     }
+    for (const option of credentialSet.options) {
+      for (const id of option) {
+        if (!declaredIds.has(id)) {
+          throw new exports.HaipValidationError(
+            "UNKNOWN_OPTION_REFERENCE",
+            `credential_sets option references '${id}', which is not declared in query.credentials`,
+            id
+          );
+        }
+      }
+    }
   }
 }
 function isHaipQuery(query) {
@@ -9967,6 +10037,7 @@ function bytesToHex3(bytes) {
 
 // src/trust/LotlTrustStore.ts
 init_reflect_polyfill();
+init_errors();
 
 // src/trust/lotl-signing-anchors.ts
 init_reflect_polyfill();
@@ -10035,6 +10106,7 @@ var LotlFetcher = class {
     this.fetcher = opts.fetcher ?? globalThis.fetch.bind(globalThis);
   }
   async fetchSigned(url, signingAnchors) {
+    assertCryptoEngineRegistered();
     let xmlText;
     try {
       const response = await this.fetcher(url, { method: "GET" });
@@ -10087,6 +10159,22 @@ var LotlFetcher = class {
     );
   }
 };
+function assertCryptoEngineRegistered() {
+  let engine;
+  try {
+    engine = xmldsig__namespace.Application.crypto;
+  } catch (err) {
+    throw new exports.LotlConfigurationError(
+      `no xmldsigjs crypto engine registered \u2014 trusted-list signatures cannot be verified. Call xmldsig.Application.setEngine('NodeJS', new Crypto()) (e.g. from @peculiar/webcrypto) once at startup, before using LotlTrustStore. Underlying error: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err instanceof Error ? err : void 0 }
+    );
+  }
+  if (!engine) {
+    throw new exports.LotlConfigurationError(
+      "no xmldsigjs crypto engine registered \u2014 trusted-list signatures cannot be verified. Call xmldsig.Application.setEngine('NodeJS', new Crypto()) (e.g. from @peculiar/webcrypto) once at startup, before using LotlTrustStore."
+    );
+  }
+}
 async function verifyAgainst(doc, sigEl, anchor) {
   try {
     const signed = new xmldsig__namespace.SignedXml(doc);
@@ -10234,6 +10322,7 @@ function parsePointer(el) {
 
 // src/trust/NationalTlResolver.ts
 init_reflect_polyfill();
+init_errors();
 var TSL_NS2 = "http://uri.etsi.org/02231/v2#";
 var NationalTlResolver = class {
   constructor(opts) {
@@ -10249,6 +10338,7 @@ var NationalTlResolver = class {
         );
         return parseNationalTl(doc, pointer.country);
       } catch (err) {
+        if (err instanceof exports.LotlConfigurationError) throw err;
         console.warn(
           `[openid4vp] national TL for ${pointer.country} failed: ${err.message}`
         );
@@ -10427,6 +10517,7 @@ var LotlTrustStore = class {
         };
         return this.snapshot;
       } catch (err) {
+        if (err instanceof exports.LotlConfigurationError) throw err;
         if (this.snapshot) {
           console.warn(
             `[openid4vp] LOTL refresh failed; serving cached snapshot (${err.message})`
@@ -10474,7 +10565,7 @@ function equalBytes(a, b) {
 
 // src/index.ts
 init_errors();
-var VERSION = "0.11.1";
+var VERSION = "0.12.0";
 /*! Bundled license information:
 
 pvtsutils/build/index.es.js:
@@ -10560,6 +10651,7 @@ exports.MdocParser = MdocParser;
 exports.SdJwtParser = SdJwtParser;
 exports.StaticTrustStore = StaticTrustStore;
 exports.VERSION = VERSION;
+exports.buildCredentialSetQuery = buildCredentialSetQuery;
 exports.buildHaipQuery = buildHaipQuery;
 exports.buildOid4vpSessionTranscript = buildOid4vpSessionTranscript;
 exports.buildOpenID4VPHandoverSessionTranscript = buildOpenID4VPHandoverSessionTranscript;
@@ -10568,6 +10660,7 @@ exports.createSignedAuthorizationRequest = createSignedAuthorizationRequest;
 exports.decryptAuthorizationResponse = decryptAuthorizationResponse;
 exports.isHaipQuery = isHaipQuery;
 exports.parsePresentation = parsePresentation;
+exports.validateCredentialSetQuery = validateCredentialSetQuery;
 exports.validateHaipQuery = validateHaipQuery;
 exports.verifyAuthorizationResponse = verifyAuthorizationResponse;
 exports.verifyPresentation = verifyPresentation;