@openeudi/openid4vp 0.11.1 → 0.13.0

package/dist/index.d.cts

@@ -79,10 +79,49 @@ interface HaipQueryInput {
     claims: string[];
     trustedAuthorities?: TrustedAuthoritiesQuery[];
 }
+/**
+ * Input to `buildCredentialSetQuery` — a DCQL `credential_sets` disjunction
+ * offering the wallet several alternative credentials for the same question.
+ */
+interface CredentialSetQueryInput {
+    /**
+     * The alternatives, **most-preferred first**. Option order is a privacy
+     * signal, not cosmetic: list the credential that discloses least first.
+     * Wallets are not obliged to honour the order.
+     */
+    options: HaipQueryInput[];
+    /** Whether the wallet must satisfy one option. Default: `true`. */
+    required?: boolean;
+}
 
 declare const HAIP_DOCTYPE_NAMESPACES: Record<string, string>;
 declare function buildHaipQuery(input: HaipQueryInput): DcqlQuery;
+/**
+ * Build a DCQL query offering the wallet a choice between several credentials —
+ * a `credential_sets` disjunction.
+ *
+ * The motivating case is a proof-of-age check: ask for a Proof-of-Age
+ * attestation (`mso_mdoc`, `age_over_18` in namespace `eu.europa.ec.av.1`) OR a
+ * PID (`dc+sd-jwt`, `birth_date`), because the PID carries no age attribute and
+ * proof-of-age attestations have almost no issuer coverage yet. The wallet
+ * satisfies ONE option and returns ONE presentation.
+ *
+ * This is deliberately NOT HAIP-minimal: `validateHaipQuery` rejects
+ * `credential_sets`, and `isHaipQuery` returns `false` for what this produces.
+ * That boundary is intentional — use `validateCredentialSetQuery` instead.
+ *
+ * Each option is built through {@link buildHaipQuery}, so per-credential
+ * validation and its `HaipValidationError` codes are identical.
+ */
+declare function buildCredentialSetQuery(input: CredentialSetQueryInput): DcqlQuery;
 declare function validateHaipQuery(query: DcqlQuery): void;
+/**
+ * Validate a DCQL query that offers the wallet a choice — the profile
+ * `buildCredentialSetQuery` produces. Per-credential rules are identical to
+ * HAIP-minimal; the difference is that `credential_sets` is REQUIRED here
+ * rather than forbidden.
+ */
+declare function validateCredentialSetQuery(query: DcqlQuery): void;
 declare function isHaipQuery(query: DcqlQuery): boolean;
 
 interface IssuerInfo {
@@ -228,8 +267,9 @@ declare class StaticTrustStore implements TrustStore {
 }
 /**
  * Combines multiple `TrustStore` instances. Children are queried in parallel;
- * results concatenate in child-order; duplicate anchors are dropped by
- * Subject Key Identifier.
+ * results concatenate in child-order; duplicate anchors (byte-identical DER)
+ * are dropped, first occurrence wins. Distinct certificates that share a key
+ * (e.g. a re-issued root) are both kept, so neither validity window is lost.
  */
 declare class CompositeTrustStore implements TrustStore {
     private readonly stores;
@@ -291,7 +331,9 @@ interface PresentationResult {
 interface ParseOptions {
     /**
      * DER-encoded issuer leaf certificates used for byte-equality trust check.
-     * Kept for 0.4.0 compatibility.
+     * Kept for 0.4.0 compatibility. No chain building: a credential signed by a
+     * document signer issued under a listed root (e.g. an IACA) is rejected on
+     * this path — use `trustStore` for that.
      * @deprecated since 0.5.0. Use `trustStore: new StaticTrustStore([...])`
      * with root/intermediate CAs for RFC 5280 chain validation. Scheduled
      * for removal in 1.0.0.
@@ -332,6 +374,15 @@ interface ParseOptions {
      * Trust anchor resolver. When provided, the library performs RFC 5280
      * chain validation and ignores `trustedCertificates`. When unset, the
      * library falls back to 0.4.0 byte-equality against `trustedCertificates`.
+     *
+     * The credential's signer certificate (`x5c[0]` / `x5chain[0]`) is trusted
+     * when it either IS an anchor (byte-identical DER) or chains to one through
+     * verified signatures, using the remaining `x5c` / `x5chain` entries as
+     * untrusted path candidates. Anchors may be roots such as an ISO 18013-5
+     * IACA, or the document-signer certificate itself. For `mso_mdoc`, built
+     * chains must also satisfy the ISO 18013-5 Annex B certificate profile
+     * (DS EKU `1.0.18013.5.1.2`, mandatory keyUsage). Every certificate must be
+     * valid now and at the credential's issuance time (MSO `signed` / `iat`).
      */
     trustStore?: TrustStore;
     /**
@@ -339,7 +390,13 @@ interface ParseOptions {
      * ship in 0.5.0 workstream A.2 — passing them today throws.
      */
     revocationPolicy?: 'skip' | 'prefer' | 'require';
-    /** HTTP transport for CRL/OCSP/LOTL fetches. Defaults to `globalThis.fetch`. */
+    /**
+     * HTTP transport for CRL/OCSP/LOTL fetches. Defaults to a guarded fetcher
+     * (`createGuardedFetcher({ allowHttp: true })`): no private/loopback/metadata
+     * targets, manual re-validated redirects (max 3), 15 s timeout, 16 MiB cap.
+     * A caller-supplied fetcher replaces those guards entirely — wrap it with
+     * `createGuardedFetcher({ fetch: yourFetcher })` to keep them.
+     */
     fetcher?: Fetcher;
     /** Cache for CRL/OCSP/LOTL artefacts. Defaults to `new InMemoryCache()`. */
     cache?: Cache;
@@ -366,6 +423,15 @@ interface ParseOptions {
      * secure path.
      */
     trustedIssuerJwks?: JsonWebKey[];
+    /**
+     * Accept the legacy `vc+sd-jwt` media type in the SD-JWT VC issuer JWT's
+     * `typ` header, in addition to `dc+sd-jwt`. Default `false`.
+     *
+     * @deprecated draft-ietf-oauth-sd-jwt-vc-19 removed `vc+sd-jwt`; only
+     * `dc+sd-jwt` is conformant. This exists solely to keep interoperating
+     * with wallets that have not migrated yet and will be removed in 1.0.0.
+     */
+    allowLegacyVcSdJwtTyp?: boolean;
 }
 interface ICredentialParser {
     readonly format: CredentialFormat;
@@ -574,7 +640,7 @@ declare class MalformedCredentialError extends Error {
 declare class NonceValidationError extends Error {
     constructor(message?: string);
 }
-type HaipValidationCode = 'EMPTY_QUERY' | 'UNSUPPORTED_FORMAT' | 'MISSING_SDJWT_META' | 'MISSING_MDOC_META' | 'NO_CLAIMS' | 'CLAIM_SETS_DISALLOWED' | 'CREDENTIAL_SETS_DISALLOWED';
+type HaipValidationCode = 'EMPTY_QUERY' | 'UNSUPPORTED_FORMAT' | 'MISSING_SDJWT_META' | 'MISSING_MDOC_META' | 'NO_CLAIMS' | 'CLAIM_SETS_DISALLOWED' | 'CREDENTIAL_SETS_DISALLOWED' | 'EMPTY_OPTIONS' | 'DUPLICATE_CREDENTIAL_ID' | 'MISSING_CREDENTIAL_SETS' | 'UNKNOWN_OPTION_REFERENCE';
 declare class HaipValidationError extends Error {
     readonly code: HaipValidationCode;
     readonly credentialId?: string;
@@ -589,7 +655,7 @@ declare abstract class OpenID4VPError extends Error {
 declare class TrustAnchorNotFoundError extends OpenID4VPError {
     readonly code: "trust_anchor_not_found";
 }
-type ChainErrorReason = 'signature' | 'validity' | 'name_constraints' | 'key_usage' | 'basic_constraints' | 'path_length' | 'algorithm_disallowed' | 'aki_ski_mismatch';
+type ChainErrorReason = 'signature' | 'validity' | 'name_constraints' | 'key_usage' | 'extended_key_usage' | 'basic_constraints' | 'path_length' | 'algorithm_disallowed' | 'aki_ski_mismatch';
 declare class CertificateChainError extends OpenID4VPError {
     readonly code: "chain_invalid";
     readonly reason: ChainErrorReason;
@@ -624,6 +690,19 @@ declare class LotlFetchError extends OpenID4VPError {
 declare class LotlSignatureError extends OpenID4VPError {
     readonly code: "lotl_signature_invalid";
 }
+/**
+ * The environment is not configured to verify trusted-list signatures at all —
+ * distinct from a list whose signature did not verify.
+ *
+ * `xmldsigjs` needs a WebCrypto engine registered once per process, and this
+ * library deliberately leaves that to the consumer rather than picking a
+ * provider on their behalf. Without it, no trusted list can ever verify, so
+ * this is raised eagerly instead of degrading per-list: a configuration fault
+ * reported as a trust failure sends people bisecting valid XML.
+ */
+declare class LotlConfigurationError extends OpenID4VPError {
+    readonly code: "lotl_configuration_invalid";
+}
 type SignedRequestBuildErrorCode = 'empty_cert_chain' | 'hostname_cert_mismatch' | 'signing_key_cert_mismatch' | 'missing_encryption_jwk' | 'missing_encryption_alg' | 'missing_vp_formats' | 'unsupported_signing_alg' | 'empty_supported_enc_values' | 'missing_hostname' | 'self_signed_leaf';
 declare class SignedRequestBuildError extends OpenID4VPError {
     readonly code: SignedRequestBuildErrorCode;
@@ -655,6 +734,84 @@ declare class MultipleCredentialsNotSupportedError extends OpenID4VPError {
     readonly presentationCount: number;
     constructor(entryCount: number, presentationCount: number);
 }
+type GuardedFetchRejectReason = 'invalid_url' | 'insecure_scheme' | 'private_address' | 'dns_resolution_failed' | 'too_many_redirects' | 'invalid_redirect' | 'response_too_large' | 'timeout';
+/**
+ * A request was refused (or cut off) by the guarded fetcher before an
+ * untrusted endpoint could be reached or could exhaust resources.
+ */
+declare class GuardedFetchError extends OpenID4VPError {
+    readonly code: "guarded_fetch_rejected";
+    readonly reason: GuardedFetchRejectReason;
+    readonly url: string;
+    constructor(reason: GuardedFetchRejectReason, message: string, options: {
+        url: string;
+        cause?: Error;
+    });
+}
+
+/**
+ * Resolves a hostname to every IP address it currently maps to. Must return
+ * all records (A and AAAA): the guard rejects the host if ANY of them is
+ * non-public, and treats an empty result as a resolution failure.
+ */
+type HostLookup = (hostname: string) => Promise<readonly string[]>;
+interface GuardedFetcherOptions {
+    /**
+     * Underlying transport. Defaults to `globalThis.fetch`, resolved at call
+     * time. Must honour `redirect: 'manual'` and expose the `Location` header
+     * of 3xx responses (Node's fetch/undici does; browsers return an opaque
+     * redirect, which the guard rejects).
+     */
+    fetch?: Fetcher;
+    /**
+     * DNS resolver used for the private-address check. Defaults to
+     * `node:dns` `lookup(host, { all: true })` when available. In runtimes
+     * without `node:dns` (browsers, some edge workers) only IP-literal and
+     * `localhost` targets are checked — inject a resolver there if needed.
+     */
+    lookup?: HostLookup;
+    /** Permit `http:` targets. Default `false` (SD-JWT VC draft-19: HTTPS only). */
+    allowHttp?: boolean;
+    /** Permit loopback / private / link-local / metadata targets. Default `false`. */
+    allowPrivateNetworks?: boolean;
+    /** Maximum redirects followed; every hop is re-validated. Default 3. */
+    maxRedirects?: number;
+    /** Wall-clock budget for the whole exchange (DNS, redirects, body). Default 15 000 ms. */
+    timeoutMs?: number;
+    /** Maximum response body size, enforced while streaming. Default 16 MiB. */
+    maxResponseBytes?: number;
+}
+declare const GUARDED_FETCH_DEFAULTS: {
+    readonly maxRedirects: 3;
+    readonly timeoutMs: 15000;
+    readonly maxResponseBytes: number;
+};
+/**
+ * Builds a {@link Fetcher} that applies the HTTP-retrieval rules of
+ * draft-ietf-oauth-sd-jwt-vc-19 to every request:
+ *
+ *   - HTTPS only (unless `allowHttp`), and never an https → http downgrade
+ *   - no loopback / private / link-local / cloud-metadata targets, checked
+ *     on the URL host AND every address it resolves to (IPv4, IPv6,
+ *     IPv4-mapped/compatible, NAT64, 6to4)
+ *   - redirects handled manually, bounded, and re-validated hop by hop
+ *   - a single timeout covering DNS, every hop and the body
+ *   - a response-size cap enforced while streaming
+ *
+ * **DNS rebinding.** The guard resolves the host, validates the addresses,
+ * then hands the *hostname* to the transport, which resolves it again. An
+ * attacker-controlled DNS server can answer differently the second time
+ * (TOCTOU). Closing that gap requires pinning the validated address at the
+ * socket layer, which `fetch` does not expose portably. Deployments that
+ * dereference attacker-influenced URLs should additionally route egress
+ * through a filtering proxy or inject a transport whose connector validates
+ * the connected address (e.g. an undici `Agent` with a checking
+ * `connect.lookup`).
+ *
+ * Caching is out of scope here: the trust module caches CRL/OCSP/LOTL
+ * artefacts through its own {@link Cache} plug.
+ */
+declare function createGuardedFetcher(options?: GuardedFetcherOptions): Fetcher;
 
 interface LotlTrustStoreOptions {
     /** Override the bundled signing anchors. Empty is rejected. */
@@ -693,6 +850,6 @@ declare class LotlTrustStore implements TrustStore {
     private refresh;
 }
 
-declare const VERSION = "0.11.1";
+declare const VERSION = "0.13.0";
 
-export { type AuthorizationRequest, type AuthorizationRequestInput, type AuthorizationResponse, type Cache, CertificateChainError, type ChainErrorReason, CompositeTrustStore, type CredentialClaims, type CredentialFormat, DecryptionFailedError, type EncryptedResponse, ExpiredCredentialError, type Fetcher, HAIP_DOCTYPE_NAMESPACES, type HaipQueryInput, type HaipValidationCode, HaipValidationError, type ICredentialParser, InMemoryCache, InvalidSignatureError, type IssuerInfo, type LotlAnchorMetadata, LotlFetchError, LotlSignatureError, LotlTrustStore, type LotlTrustStoreOptions, MalformedCredentialError, MdocParser, MissingDecryptionKeyError, MissingVerifierEncryptionKeyError, MultipleCredentialsNotSupportedError, NonceValidationError, OpenID4VPError, type ParseOptions, type PresentationResult, RevocationCheckFailedError, RevokedCertificateError, SdJwtParser, type SignedAuthorizationRequest, type SignedAuthorizationRequestInput, SignedRequestBuildError, type SignedRequestBuildErrorCode, StaticTrustStore, type TrustAnchor, TrustAnchorNotFoundError, type TrustStore, type TrustStoreHint, type TrustStoreInput, UnsupportedFormatError, UnsupportedJweError, VERSION, type VerifyAuthorizationResponseOptions, type VerifyOptions, type VerifyResult, buildHaipQuery, buildOid4vpSessionTranscript, buildOpenID4VPHandoverSessionTranscript, createAuthorizationRequest, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };
+export { type AuthorizationRequest, type AuthorizationRequestInput, type AuthorizationResponse, type Cache, CertificateChainError, type ChainErrorReason, CompositeTrustStore, type CredentialClaims, type CredentialFormat, type CredentialSetQueryInput, DecryptionFailedError, type EncryptedResponse, ExpiredCredentialError, type Fetcher, GUARDED_FETCH_DEFAULTS, GuardedFetchError, type GuardedFetchRejectReason, type GuardedFetcherOptions, HAIP_DOCTYPE_NAMESPACES, type HaipQueryInput, type HaipValidationCode, HaipValidationError, type HostLookup, type ICredentialParser, InMemoryCache, InvalidSignatureError, type IssuerInfo, type LotlAnchorMetadata, LotlConfigurationError, LotlFetchError, LotlSignatureError, LotlTrustStore, type LotlTrustStoreOptions, MalformedCredentialError, MdocParser, MissingDecryptionKeyError, MissingVerifierEncryptionKeyError, MultipleCredentialsNotSupportedError, NonceValidationError, OpenID4VPError, type ParseOptions, type PresentationResult, RevocationCheckFailedError, RevokedCertificateError, SdJwtParser, type SignedAuthorizationRequest, type SignedAuthorizationRequestInput, SignedRequestBuildError, type SignedRequestBuildErrorCode, StaticTrustStore, type TrustAnchor, TrustAnchorNotFoundError, type TrustStore, type TrustStoreHint, type TrustStoreInput, UnsupportedFormatError, UnsupportedJweError, VERSION, type VerifyAuthorizationResponseOptions, type VerifyOptions, type VerifyResult, buildCredentialSetQuery, buildHaipQuery, buildOid4vpSessionTranscript, buildOpenID4VPHandoverSessionTranscript, createAuthorizationRequest, createGuardedFetcher, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateCredentialSetQuery, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };

package/dist/index.d.ts

@@ -79,10 +79,49 @@ interface HaipQueryInput {
     claims: string[];
     trustedAuthorities?: TrustedAuthoritiesQuery[];
 }
+/**
+ * Input to `buildCredentialSetQuery` — a DCQL `credential_sets` disjunction
+ * offering the wallet several alternative credentials for the same question.
+ */
+interface CredentialSetQueryInput {
+    /**
+     * The alternatives, **most-preferred first**. Option order is a privacy
+     * signal, not cosmetic: list the credential that discloses least first.
+     * Wallets are not obliged to honour the order.
+     */
+    options: HaipQueryInput[];
+    /** Whether the wallet must satisfy one option. Default: `true`. */
+    required?: boolean;
+}
 
 declare const HAIP_DOCTYPE_NAMESPACES: Record<string, string>;
 declare function buildHaipQuery(input: HaipQueryInput): DcqlQuery;
+/**
+ * Build a DCQL query offering the wallet a choice between several credentials —
+ * a `credential_sets` disjunction.
+ *
+ * The motivating case is a proof-of-age check: ask for a Proof-of-Age
+ * attestation (`mso_mdoc`, `age_over_18` in namespace `eu.europa.ec.av.1`) OR a
+ * PID (`dc+sd-jwt`, `birth_date`), because the PID carries no age attribute and
+ * proof-of-age attestations have almost no issuer coverage yet. The wallet
+ * satisfies ONE option and returns ONE presentation.
+ *
+ * This is deliberately NOT HAIP-minimal: `validateHaipQuery` rejects
+ * `credential_sets`, and `isHaipQuery` returns `false` for what this produces.
+ * That boundary is intentional — use `validateCredentialSetQuery` instead.
+ *
+ * Each option is built through {@link buildHaipQuery}, so per-credential
+ * validation and its `HaipValidationError` codes are identical.
+ */
+declare function buildCredentialSetQuery(input: CredentialSetQueryInput): DcqlQuery;
 declare function validateHaipQuery(query: DcqlQuery): void;
+/**
+ * Validate a DCQL query that offers the wallet a choice — the profile
+ * `buildCredentialSetQuery` produces. Per-credential rules are identical to
+ * HAIP-minimal; the difference is that `credential_sets` is REQUIRED here
+ * rather than forbidden.
+ */
+declare function validateCredentialSetQuery(query: DcqlQuery): void;
 declare function isHaipQuery(query: DcqlQuery): boolean;
 
 interface IssuerInfo {
@@ -228,8 +267,9 @@ declare class StaticTrustStore implements TrustStore {
 }
 /**
  * Combines multiple `TrustStore` instances. Children are queried in parallel;
- * results concatenate in child-order; duplicate anchors are dropped by
- * Subject Key Identifier.
+ * results concatenate in child-order; duplicate anchors (byte-identical DER)
+ * are dropped, first occurrence wins. Distinct certificates that share a key
+ * (e.g. a re-issued root) are both kept, so neither validity window is lost.
  */
 declare class CompositeTrustStore implements TrustStore {
     private readonly stores;
@@ -291,7 +331,9 @@ interface PresentationResult {
 interface ParseOptions {
     /**
      * DER-encoded issuer leaf certificates used for byte-equality trust check.
-     * Kept for 0.4.0 compatibility.
+     * Kept for 0.4.0 compatibility. No chain building: a credential signed by a
+     * document signer issued under a listed root (e.g. an IACA) is rejected on
+     * this path — use `trustStore` for that.
      * @deprecated since 0.5.0. Use `trustStore: new StaticTrustStore([...])`
      * with root/intermediate CAs for RFC 5280 chain validation. Scheduled
      * for removal in 1.0.0.
@@ -332,6 +374,15 @@ interface ParseOptions {
      * Trust anchor resolver. When provided, the library performs RFC 5280
      * chain validation and ignores `trustedCertificates`. When unset, the
      * library falls back to 0.4.0 byte-equality against `trustedCertificates`.
+     *
+     * The credential's signer certificate (`x5c[0]` / `x5chain[0]`) is trusted
+     * when it either IS an anchor (byte-identical DER) or chains to one through
+     * verified signatures, using the remaining `x5c` / `x5chain` entries as
+     * untrusted path candidates. Anchors may be roots such as an ISO 18013-5
+     * IACA, or the document-signer certificate itself. For `mso_mdoc`, built
+     * chains must also satisfy the ISO 18013-5 Annex B certificate profile
+     * (DS EKU `1.0.18013.5.1.2`, mandatory keyUsage). Every certificate must be
+     * valid now and at the credential's issuance time (MSO `signed` / `iat`).
      */
     trustStore?: TrustStore;
     /**
@@ -339,7 +390,13 @@ interface ParseOptions {
      * ship in 0.5.0 workstream A.2 — passing them today throws.
      */
     revocationPolicy?: 'skip' | 'prefer' | 'require';
-    /** HTTP transport for CRL/OCSP/LOTL fetches. Defaults to `globalThis.fetch`. */
+    /**
+     * HTTP transport for CRL/OCSP/LOTL fetches. Defaults to a guarded fetcher
+     * (`createGuardedFetcher({ allowHttp: true })`): no private/loopback/metadata
+     * targets, manual re-validated redirects (max 3), 15 s timeout, 16 MiB cap.
+     * A caller-supplied fetcher replaces those guards entirely — wrap it with
+     * `createGuardedFetcher({ fetch: yourFetcher })` to keep them.
+     */
     fetcher?: Fetcher;
     /** Cache for CRL/OCSP/LOTL artefacts. Defaults to `new InMemoryCache()`. */
     cache?: Cache;
@@ -366,6 +423,15 @@ interface ParseOptions {
      * secure path.
      */
     trustedIssuerJwks?: JsonWebKey[];
+    /**
+     * Accept the legacy `vc+sd-jwt` media type in the SD-JWT VC issuer JWT's
+     * `typ` header, in addition to `dc+sd-jwt`. Default `false`.
+     *
+     * @deprecated draft-ietf-oauth-sd-jwt-vc-19 removed `vc+sd-jwt`; only
+     * `dc+sd-jwt` is conformant. This exists solely to keep interoperating
+     * with wallets that have not migrated yet and will be removed in 1.0.0.
+     */
+    allowLegacyVcSdJwtTyp?: boolean;
 }
 interface ICredentialParser {
     readonly format: CredentialFormat;
@@ -574,7 +640,7 @@ declare class MalformedCredentialError extends Error {
 declare class NonceValidationError extends Error {
     constructor(message?: string);
 }
-type HaipValidationCode = 'EMPTY_QUERY' | 'UNSUPPORTED_FORMAT' | 'MISSING_SDJWT_META' | 'MISSING_MDOC_META' | 'NO_CLAIMS' | 'CLAIM_SETS_DISALLOWED' | 'CREDENTIAL_SETS_DISALLOWED';
+type HaipValidationCode = 'EMPTY_QUERY' | 'UNSUPPORTED_FORMAT' | 'MISSING_SDJWT_META' | 'MISSING_MDOC_META' | 'NO_CLAIMS' | 'CLAIM_SETS_DISALLOWED' | 'CREDENTIAL_SETS_DISALLOWED' | 'EMPTY_OPTIONS' | 'DUPLICATE_CREDENTIAL_ID' | 'MISSING_CREDENTIAL_SETS' | 'UNKNOWN_OPTION_REFERENCE';
 declare class HaipValidationError extends Error {
     readonly code: HaipValidationCode;
     readonly credentialId?: string;
@@ -589,7 +655,7 @@ declare abstract class OpenID4VPError extends Error {
 declare class TrustAnchorNotFoundError extends OpenID4VPError {
     readonly code: "trust_anchor_not_found";
 }
-type ChainErrorReason = 'signature' | 'validity' | 'name_constraints' | 'key_usage' | 'basic_constraints' | 'path_length' | 'algorithm_disallowed' | 'aki_ski_mismatch';
+type ChainErrorReason = 'signature' | 'validity' | 'name_constraints' | 'key_usage' | 'extended_key_usage' | 'basic_constraints' | 'path_length' | 'algorithm_disallowed' | 'aki_ski_mismatch';
 declare class CertificateChainError extends OpenID4VPError {
     readonly code: "chain_invalid";
     readonly reason: ChainErrorReason;
@@ -624,6 +690,19 @@ declare class LotlFetchError extends OpenID4VPError {
 declare class LotlSignatureError extends OpenID4VPError {
     readonly code: "lotl_signature_invalid";
 }
+/**
+ * The environment is not configured to verify trusted-list signatures at all —
+ * distinct from a list whose signature did not verify.
+ *
+ * `xmldsigjs` needs a WebCrypto engine registered once per process, and this
+ * library deliberately leaves that to the consumer rather than picking a
+ * provider on their behalf. Without it, no trusted list can ever verify, so
+ * this is raised eagerly instead of degrading per-list: a configuration fault
+ * reported as a trust failure sends people bisecting valid XML.
+ */
+declare class LotlConfigurationError extends OpenID4VPError {
+    readonly code: "lotl_configuration_invalid";
+}
 type SignedRequestBuildErrorCode = 'empty_cert_chain' | 'hostname_cert_mismatch' | 'signing_key_cert_mismatch' | 'missing_encryption_jwk' | 'missing_encryption_alg' | 'missing_vp_formats' | 'unsupported_signing_alg' | 'empty_supported_enc_values' | 'missing_hostname' | 'self_signed_leaf';
 declare class SignedRequestBuildError extends OpenID4VPError {
     readonly code: SignedRequestBuildErrorCode;
@@ -655,6 +734,84 @@ declare class MultipleCredentialsNotSupportedError extends OpenID4VPError {
     readonly presentationCount: number;
     constructor(entryCount: number, presentationCount: number);
 }
+type GuardedFetchRejectReason = 'invalid_url' | 'insecure_scheme' | 'private_address' | 'dns_resolution_failed' | 'too_many_redirects' | 'invalid_redirect' | 'response_too_large' | 'timeout';
+/**
+ * A request was refused (or cut off) by the guarded fetcher before an
+ * untrusted endpoint could be reached or could exhaust resources.
+ */
+declare class GuardedFetchError extends OpenID4VPError {
+    readonly code: "guarded_fetch_rejected";
+    readonly reason: GuardedFetchRejectReason;
+    readonly url: string;
+    constructor(reason: GuardedFetchRejectReason, message: string, options: {
+        url: string;
+        cause?: Error;
+    });
+}
+
+/**
+ * Resolves a hostname to every IP address it currently maps to. Must return
+ * all records (A and AAAA): the guard rejects the host if ANY of them is
+ * non-public, and treats an empty result as a resolution failure.
+ */
+type HostLookup = (hostname: string) => Promise<readonly string[]>;
+interface GuardedFetcherOptions {
+    /**
+     * Underlying transport. Defaults to `globalThis.fetch`, resolved at call
+     * time. Must honour `redirect: 'manual'` and expose the `Location` header
+     * of 3xx responses (Node's fetch/undici does; browsers return an opaque
+     * redirect, which the guard rejects).
+     */
+    fetch?: Fetcher;
+    /**
+     * DNS resolver used for the private-address check. Defaults to
+     * `node:dns` `lookup(host, { all: true })` when available. In runtimes
+     * without `node:dns` (browsers, some edge workers) only IP-literal and
+     * `localhost` targets are checked — inject a resolver there if needed.
+     */
+    lookup?: HostLookup;
+    /** Permit `http:` targets. Default `false` (SD-JWT VC draft-19: HTTPS only). */
+    allowHttp?: boolean;
+    /** Permit loopback / private / link-local / metadata targets. Default `false`. */
+    allowPrivateNetworks?: boolean;
+    /** Maximum redirects followed; every hop is re-validated. Default 3. */
+    maxRedirects?: number;
+    /** Wall-clock budget for the whole exchange (DNS, redirects, body). Default 15 000 ms. */
+    timeoutMs?: number;
+    /** Maximum response body size, enforced while streaming. Default 16 MiB. */
+    maxResponseBytes?: number;
+}
+declare const GUARDED_FETCH_DEFAULTS: {
+    readonly maxRedirects: 3;
+    readonly timeoutMs: 15000;
+    readonly maxResponseBytes: number;
+};
+/**
+ * Builds a {@link Fetcher} that applies the HTTP-retrieval rules of
+ * draft-ietf-oauth-sd-jwt-vc-19 to every request:
+ *
+ *   - HTTPS only (unless `allowHttp`), and never an https → http downgrade
+ *   - no loopback / private / link-local / cloud-metadata targets, checked
+ *     on the URL host AND every address it resolves to (IPv4, IPv6,
+ *     IPv4-mapped/compatible, NAT64, 6to4)
+ *   - redirects handled manually, bounded, and re-validated hop by hop
+ *   - a single timeout covering DNS, every hop and the body
+ *   - a response-size cap enforced while streaming
+ *
+ * **DNS rebinding.** The guard resolves the host, validates the addresses,
+ * then hands the *hostname* to the transport, which resolves it again. An
+ * attacker-controlled DNS server can answer differently the second time
+ * (TOCTOU). Closing that gap requires pinning the validated address at the
+ * socket layer, which `fetch` does not expose portably. Deployments that
+ * dereference attacker-influenced URLs should additionally route egress
+ * through a filtering proxy or inject a transport whose connector validates
+ * the connected address (e.g. an undici `Agent` with a checking
+ * `connect.lookup`).
+ *
+ * Caching is out of scope here: the trust module caches CRL/OCSP/LOTL
+ * artefacts through its own {@link Cache} plug.
+ */
+declare function createGuardedFetcher(options?: GuardedFetcherOptions): Fetcher;
 
 interface LotlTrustStoreOptions {
     /** Override the bundled signing anchors. Empty is rejected. */
@@ -693,6 +850,6 @@ declare class LotlTrustStore implements TrustStore {
     private refresh;
 }
 
-declare const VERSION = "0.11.1";
+declare const VERSION = "0.13.0";
 
-export { type AuthorizationRequest, type AuthorizationRequestInput, type AuthorizationResponse, type Cache, CertificateChainError, type ChainErrorReason, CompositeTrustStore, type CredentialClaims, type CredentialFormat, DecryptionFailedError, type EncryptedResponse, ExpiredCredentialError, type Fetcher, HAIP_DOCTYPE_NAMESPACES, type HaipQueryInput, type HaipValidationCode, HaipValidationError, type ICredentialParser, InMemoryCache, InvalidSignatureError, type IssuerInfo, type LotlAnchorMetadata, LotlFetchError, LotlSignatureError, LotlTrustStore, type LotlTrustStoreOptions, MalformedCredentialError, MdocParser, MissingDecryptionKeyError, MissingVerifierEncryptionKeyError, MultipleCredentialsNotSupportedError, NonceValidationError, OpenID4VPError, type ParseOptions, type PresentationResult, RevocationCheckFailedError, RevokedCertificateError, SdJwtParser, type SignedAuthorizationRequest, type SignedAuthorizationRequestInput, SignedRequestBuildError, type SignedRequestBuildErrorCode, StaticTrustStore, type TrustAnchor, TrustAnchorNotFoundError, type TrustStore, type TrustStoreHint, type TrustStoreInput, UnsupportedFormatError, UnsupportedJweError, VERSION, type VerifyAuthorizationResponseOptions, type VerifyOptions, type VerifyResult, buildHaipQuery, buildOid4vpSessionTranscript, buildOpenID4VPHandoverSessionTranscript, createAuthorizationRequest, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };
+export { type AuthorizationRequest, type AuthorizationRequestInput, type AuthorizationResponse, type Cache, CertificateChainError, type ChainErrorReason, CompositeTrustStore, type CredentialClaims, type CredentialFormat, type CredentialSetQueryInput, DecryptionFailedError, type EncryptedResponse, ExpiredCredentialError, type Fetcher, GUARDED_FETCH_DEFAULTS, GuardedFetchError, type GuardedFetchRejectReason, type GuardedFetcherOptions, HAIP_DOCTYPE_NAMESPACES, type HaipQueryInput, type HaipValidationCode, HaipValidationError, type HostLookup, type ICredentialParser, InMemoryCache, InvalidSignatureError, type IssuerInfo, type LotlAnchorMetadata, LotlConfigurationError, LotlFetchError, LotlSignatureError, LotlTrustStore, type LotlTrustStoreOptions, MalformedCredentialError, MdocParser, MissingDecryptionKeyError, MissingVerifierEncryptionKeyError, MultipleCredentialsNotSupportedError, NonceValidationError, OpenID4VPError, type ParseOptions, type PresentationResult, RevocationCheckFailedError, RevokedCertificateError, SdJwtParser, type SignedAuthorizationRequest, type SignedAuthorizationRequestInput, SignedRequestBuildError, type SignedRequestBuildErrorCode, StaticTrustStore, type TrustAnchor, TrustAnchorNotFoundError, type TrustStore, type TrustStoreHint, type TrustStoreInput, UnsupportedFormatError, UnsupportedJweError, VERSION, type VerifyAuthorizationResponseOptions, type VerifyOptions, type VerifyResult, buildCredentialSetQuery, buildHaipQuery, buildOid4vpSessionTranscript, buildOpenID4VPHandoverSessionTranscript, createAuthorizationRequest, createGuardedFetcher, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateCredentialSetQuery, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };