@openeudi/openid4vp 0.11.1 → 0.13.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,8 +390,36 @@ 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`.
+
+  The signer certificate (`x5c[0]` / `x5chain[0]`) is trusted when it **is** an anchor (byte-identical DER) or **chains to** one through verified signatures; the remaining `x5c` / `x5chain` entries are untrusted path candidates and never anchors. A list longer than 10 certificates, signer included, is rejected as malformed before any entry is parsed. Anchors may therefore be roots — such as the IACA certificates an ETSI TS 119 602 PID-providers list publishes — or the document-signer certificate itself:
+
+  ```ts
+  import { StaticTrustStore } from "@openeudi/openid4vp";
+
+  // DER bytes of every certificate listed for the PID providers you accept:
+  // IACA roots and directly-listed signer certificates alike.
+  const trustStore = new StaticTrustStore(listedCertificates);
+  await parsePresentation(vpToken, { trustedCertificates: [], trustStore, nonce, mdocSessionTranscript });
+  ```
+
+  Each link's signature, validity now **and** at issuance time (MSO `signed` / SD-JWT `iat`), `basicConstraints` cA + `keyUsage` keyCertSign on every CA, `digitalSignature` on the signer, `pathLenConstraint`, `nameConstraints` and a 5-certificate maximum are enforced. For `mso_mdoc`, built chains must also follow the ISO 18013-5 Annex B profile: the document signer carries EKU `1.0.18013.5.1.2` (`reason: 'extended_key_usage'` otherwise) and `keyUsage` is mandatory. A signer that is itself the listed anchor is trusted by presence and exempt from that profile. Anchors are never matched by Subject DN alone.
+
+  > **`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`.
+- `fetcher?` — HTTP transport for CRL/OCSP/LOTL fetches. Defaults to a guarded fetcher — see [Network access](#network-access). A fetcher you supply **replaces** the guards; wrap it with `createGuardedFetcher({ fetch: yourFetcher })` to keep them.
 - `cache?` — cache for CRL/OCSP/LOTL artefacts. Defaults to `new InMemoryCache()`.
 - `clockSkewTolerance?` — seconds of slack applied to certificate validity checks. Default 60.
 - `trustedIssuerJwks?` — opt-in alternate trust path for SD-JWT VCs whose issuer JWT lacks an `x5c` header. The library matches by `kid` (or iterates the array when no `kid` is present) and skips chain validation entirely. Intended for harness setups (e.g. OIDF conformance suite) where the wallet signs without `x5c` and the verifier knows the signing key out-of-band. **Not recommended for production verifiers** — `trustStore` is the secure path.
@@ -327,6 +427,38 @@ Both `parsePresentation` and `verifyPresentation` accept:
 - `allowedAlgorithms?` — restrict signature algorithms. Defaults to `['ES256','ES384','ES512']`.
 - `skipTrustCheck?` — skip trust checks entirely (dev/test only).
 - `expectedDocType?` — for mDOC verification, lock the credential `docType` (or SD-JWT `vct`).
+- `allowLegacyVcSdJwtTyp?` — **deprecated**. Also accept the legacy `vc+sd-jwt` issuer-JWT `typ`, which draft-ietf-oauth-sd-jwt-vc-19 removed. Default `false`; only for interoperating with wallets that have not migrated yet. Removed in 1.0.0.
+
+### Network access
+
+The library dereferences URLs only inside the trust module, and only when you opt into it:
+
+| Fetch | When | Method |
+|---|---|---|
+| EU LOTL + national trusted lists | `LotlTrustStore` | GET |
+| CRL distribution points | `revocationPolicy` `'prefer'`/`'require'` | GET |
+| OCSP responders (AIA) | `revocationPolicy` `'prefer'`/`'require'` | POST |
+
+It does **not** fetch SD-JWT VC issuer metadata (`/.well-known/jwt-vc-issuer`), `jwks_uri`, Type Metadata (`vct` resolution), Token Status Lists, or `x5u`. Issuer keys come from `x5c` or `trustedIssuerJwks`. **If your application dereferences any of those itself, it is responsible for applying the SD-JWT VC draft-19 HTTP retrieval rules** — `createGuardedFetcher()` (HTTPS-only by default) is exported for exactly that.
+
+All library fetches go through `createGuardedFetcher({ allowHttp: true })` unless you pass `fetcher`. It enforces:
+
+- `https:` only by default (`allowHttp: true` for the trust module: RFC 5280 CRLs and RFC 6960 OCSP are conventionally plain HTTP and every artefact is signature-verified); never an `https` → `http` redirect downgrade.
+- No loopback, RFC 1918, CGNAT, link-local (incl. `169.254.169.254`), ULA (incl. `fd00:ec2::254`), multicast, documentation or reserved targets — checked on the URL host *and* on every address it resolves to, including IPv4-mapped/compatible, NAT64 and 6to4 IPv6 forms. `localhost`/`*.localhost` are refused by name. A host that resolves to no addresses at all is refused as `dns_resolution_failed` rather than treated as public.
+- Redirects handled manually (`maxRedirects`, default 3); each target is re-validated before it is requested, and credentials headers are dropped on cross-origin hops.
+- One timeout (`timeoutMs`, default 15 000) for DNS, all hops and the body.
+- A size cap (`maxResponseBytes`, default 16 MiB), enforced from `Content-Length` and again while streaming.
+
+Rejections throw `GuardedFetchError` with a `reason` (`insecure_scheme`, `private_address`, `too_many_redirects`, `response_too_large`, `timeout`, …).
+
+```ts
+import { createGuardedFetcher, LotlTrustStore } from "@openeudi/openid4vp";
+
+const fetcher = createGuardedFetcher({ allowHttp: true, timeoutMs: 10_000, maxResponseBytes: 32 * 1024 * 1024 });
+const trustStore = new LotlTrustStore({ signingAnchors, fetcher });
+```
+
+> **Limits.** DNS rebinding: the guard resolves and validates the host, then the transport resolves it *again*, so a hostile DNS server can answer differently the second time. `fetch` gives no portable way to pin the validated address. If attacker-influenced URLs reach your verifier, also route egress through a filtering proxy, or inject a `fetch` whose connector checks the connected address (e.g. an undici `Agent` with a validating `connect.lookup`). In runtimes without `node:dns` (browsers, some edge workers) only IP literals and `localhost` are checked unless you pass `lookup`. Caching is handled by the `cache` option, not the fetcher.
 
 ## Supported formats
 
@@ -334,6 +466,7 @@ Both `parsePresentation` and `verifyPresentation` accept:
 
 Selective Disclosure JSON Web Token Verifiable Credentials. The token is a string in `jwt~disclosure~kb` format. The parser:
 
+- Requires the issuer JWT `typ` to be `dc+sd-jwt` (draft-ietf-oauth-sd-jwt-vc-19); the legacy `vc+sd-jwt` is rejected unless `allowLegacyVcSdJwtTyp` is set
 - Decodes the issuer JWT and extracts the `x5c` certificate chain
 - Verifies the issuer certificate against your trusted set
 - Checks credential expiry from the `exp` claim
@@ -348,7 +481,7 @@ Mobile Document credentials as defined in ISO 18013-5. The token is a CBOR-encod
 
 - Decodes the CBOR DeviceResponse structure
 - Extracts the issuer certificate from the COSE_Sign1 `issuerAuth` (x5chain label 33)
-- Verifies the certificate against your trusted set
+- Verifies the certificate against your trusted set — with `trustStore`, by building a chain from the document signer to an anchor such as an IACA (see [`trustStore`](#parseoptions--verifyoptions))
 - Checks the validity period from `validityInfo`
 - Extracts claims from the `eu.europa.ec.eudi.pid.1` namespace
 - Verifies each `IssuerSignedItem`'s digest against the MSO's `valueDigests`, computed over the full tag-24 `IssuerSignedItemBytes` (`#6.24(bstr .cbor IssuerSignedItem)`) per ISO 18013-5 §9.1.2.4 — not just the inner CBOR — matching how real wallets encode mdocs. mDOC verification, including this digest check and device authentication below, is validated against the OIDF conformance suite acting as an independent ISO 18013-5 mdl wallet.
@@ -405,6 +538,8 @@ 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` |
+| `GuardedFetchError`        | refusing … / exceeds … / timed out      | A guarded fetch is refused or cut off (`reason`)   |
 
 ```ts
 import { MalformedCredentialError, ExpiredCredentialError } from "@openeudi/openid4vp";
@@ -427,10 +562,10 @@ 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`.
+- **X.509 chain validation** — RFC 5280 chain building including `nameConstraints`, `StaticTrustStore`, `CompositeTrustStore`; IACA → document-signer chains for `mso_mdoc` with the ISO 18013-5 Annex B certificate profile.
 - **Revocation checking** — OCSP-first with CRL fallback (`revocationPolicy: 'skip' | 'prefer' | 'require'`).
 - **EU List of Trusted Lists** — `LotlTrustStore` resolves national trust lists via signed XML fetch + XAdES verification; populates `provenance` (LoA, qualified status, country, service name) on verified presentations.
 - **OIDF conformance** — automated against the OpenID Foundation conformance suite in CI (`oidf-pr.yml` happy-flow gate, `oidf-release.yml` full plan).
@@ -473,6 +608,7 @@ See [CHANGELOG.md](./CHANGELOG.md) for per-release changes. Key migration moment
 - **0.9.3** — `reflect-metadata` is loaded by the package itself in both ESM and CJS builds. If you added a manual `import "reflect-metadata"` before importing this library to work around the 0.9.2 bug, you can drop it.
 - **0.11.0** — **BREAKING:** `createSignedAuthorizationRequest` now rejects a self-signed leaf certificate with `SignedRequestBuildError: self_signed_leaf`, per HAIP 1.0 Final. Verifiers using a self-signed certificate for their own identity must either move to a CA-issued certificate (the correct fix) or pass `allowSelfSignedCertificate: true` to keep the previous behaviour. Verification of wallet presentations is unaffected — this concerns only the verifier's own request-signing certificate.
 - **0.10.0** — `createSignedAuthorizationRequest` gains `clientIdPrefix` (`x509_san_dns` default, or `x509_hash`), and `hostname` becomes optional — required only for `x509_san_dns`, but still validated against the leaf SAN whenever supplied. **Wire change for existing callers:** the emitted `client_metadata` no longer carries the singular ID3 `authorization_encrypted_response_alg` / `authorization_encrypted_response_enc` fields added in 0.8.0. Verifiers that read the 1.0 Final `encrypted_response_enc_values_supported` array (and `alg` from `client_metadata.jwks`) are unaffected; anything still reading the singular fields needs updating.
+- **0.13.0** — **BREAKING:** SD-JWT VC issuer JWTs must carry `typ: dc+sd-jwt` (draft-ietf-oauth-sd-jwt-vc-19); `vc+sd-jwt` is rejected unless you pass `allowLegacyVcSdJwtTyp: true`, which is already deprecated and goes in 1.0.0. **BREAKING:** trust-module fetches (LOTL / national TL, CRL, OCSP) are SSRF-guarded by default — a CA, OCSP responder or trusted list on a private network now needs `fetcher: createGuardedFetcher({ allowHttp: true, allowPrivateNetworks: true })`. IACA → document-signer chain building only applies on the `trustStore` path: `trustedCertificates` is still byte-equality, so pass `trustStore: new StaticTrustStore([...])` to accept PIDs whose list publishes the IACA rather than the signer.
 
 ## License