@openeudi/openid4vp 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,37 @@
+import { DcqlQuery, TrustedAuthoritiesQuery, DcqlMatchResult, DcqlSubmission } from '@openeudi/dcql';
+export { DcqlMatchError, DcqlMatchResult, DcqlQuery, DcqlSubmission, DcqlValidationError, DcqlValidationErrorCode } from '@openeudi/dcql';
+import { X509Certificate } from '@peculiar/x509';
+
+interface AuthorizationRequestInput {
+    clientId: string;
+    responseUri: string;
+    nonce: string;
+    state?: string;
+    responseMode?: 'direct_post' | 'direct_post.jwt';
+}
+interface AuthorizationRequest {
+    uri: string;
+    dcqlQuery: DcqlQuery;
+    nonce: string;
+    state: string;
+}
+
+declare function createAuthorizationRequest(input: AuthorizationRequestInput, query: DcqlQuery): AuthorizationRequest;
+
+interface HaipQueryInput {
+    credentialId: string;
+    format: 'dc+sd-jwt' | 'mso_mdoc';
+    vctValues?: string[];
+    doctypeValue?: string;
+    claims: string[];
+    trustedAuthorities?: TrustedAuthoritiesQuery[];
+}
+
+declare const HAIP_DOCTYPE_NAMESPACES: Record<string, string>;
+declare function buildHaipQuery(input: HaipQueryInput): DcqlQuery;
+declare function validateHaipQuery(query: DcqlQuery): void;
+declare function isHaipQuery(query: DcqlQuery): boolean;
+
 interface IssuerInfo {
     certificate: Uint8Array;
     country: string;
@@ -5,6 +39,168 @@ interface IssuerInfo {
     organization?: string;
 }
 
+/**
+ * Content-addressed cache for CRL responses, OCSP responses, and LOTL
+ * snapshots. Keys are library-defined strings; values are raw bytes.
+ *
+ * Implementations MUST be safe to call concurrently.
+ */
+interface Cache {
+    get(key: string): Promise<Uint8Array | null>;
+    set(key: string, value: Uint8Array, ttlSeconds: number): Promise<void>;
+}
+/**
+ * Default `Cache` implementation — bounded-size LRU with wall-clock TTL.
+ * Cache dies with the process; inject a persistent `Cache` impl for
+ * servers that should survive restarts.
+ */
+declare class InMemoryCache implements Cache {
+    private readonly entries;
+    private readonly maxEntries;
+    constructor(opts?: {
+        maxEntries?: number;
+    });
+    get(key: string): Promise<Uint8Array | null>;
+    set(key: string, value: Uint8Array, ttlSeconds: number): Promise<void>;
+}
+
+/**
+ * HTTP transport plug. Defaults to `globalThis.fetch` when unset in
+ * `ParseOptions`. Consumers may inject a custom implementation for proxies,
+ * timeouts, retry policies, request tracing, or test doubles.
+ *
+ * MUST be safe to call concurrently.
+ */
+type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * A certificate used as the root of a trust chain. `source` tracks provenance
+ * so consumers can distinguish static config from LOTL-derived anchors.
+ */
+interface TrustAnchor {
+    readonly certificate: X509Certificate;
+    readonly source: 'static' | 'lotl';
+    readonly metadata?: LotlAnchorMetadata;
+    /**
+     * Authority identifiers this anchor stands for. Populated by
+     * `LotlTrustStore` from `ServiceDigitalIdentity`'s SKI; synthesized by
+     * `TrustEvaluator` from the anchor SKI for static stores. Used by
+     * `verifyPresentation` to populate `DecodedCredential.trusted_authority_ids`.
+     */
+    readonly trustedAuthorityIds?: readonly string[];
+}
+/**
+ * Metadata attached to anchors sourced from the EU LOTL (populated by
+ * `LotlTrustStore` in A.3 — left optional here so the shape is stable today).
+ */
+interface LotlAnchorMetadata {
+    /** ISO 3166-1 alpha-2 country code of the TL scheme operator */
+    readonly country: string;
+    readonly serviceName: string;
+    /** e.g. `http://uri.etsi.org/TrstSvc/Svctype/CA/QC` */
+    readonly serviceTypeIdentifier: string;
+    readonly serviceStatus: string;
+    readonly qualified: boolean;
+    readonly loa?: 'substantial' | 'high';
+}
+
+/**
+ * Internal types for the LOTL (List of Trusted Lists) module. NOT exported
+ * from the package root. Consumed only by `LotlFetcher`, `LotlParser`,
+ * `NationalTlResolver`, `LotlTrustStore`, and `ProvenanceResolver`.
+ */
+
+/**
+ * One `TSPService` inside a national TL, flattened with its provider's
+ * `TSPInformation` and resolved certificates.
+ */
+interface TspService {
+    /** `TSPInformation.TSPName` of the provider that owns this service. */
+    readonly providerName: string;
+    /** ISO 3166-1 alpha-2 scheme territory the national TL belongs to. */
+    readonly country: string;
+    /** `ServiceTypeIdentifier`, e.g. `http://uri.etsi.org/TrstSvc/Svctype/CA/QC`. */
+    readonly serviceTypeIdentifier: string;
+    /** `ServiceStatus`, e.g. `http://uri.etsi.org/TrstSvc/TrustedList/Svcstatus/granted`. */
+    readonly serviceStatus: string;
+    /** `ServiceName` (first language variant — English preferred). */
+    readonly serviceName: string;
+    /** All X.509 certs in `ServiceDigitalIdentity`. */
+    readonly certificates: readonly X509Certificate[];
+    /**
+     * `AdditionalServiceInformation/URI` values. Used by the LoA mapping
+     * in `lotl-loa-mapping.ts` to derive `'substantial' | 'high'`.
+     */
+    readonly additionalServiceInformationUris: readonly string[];
+}
+/** One national TL, parsed + verified. */
+interface NationalTlSnapshot {
+    readonly country: string;
+    readonly issueDate: Date;
+    readonly nextUpdate: Date | null;
+    readonly services: readonly TspService[];
+}
+
+/**
+ * Resolves trust anchors for a given leaf credential. The library calls
+ * `getAnchors()` once per verification after extracting the leaf's issuer
+ * hints (DN, Authority Key Identifier, JWT/COSE key ID).
+ *
+ * Implementations MUST be safe to call concurrently. Stores that cannot
+ * satisfy the hint MUST return `[]`, not throw.
+ */
+interface TrustStore {
+    getAnchors(hint: TrustStoreHint): Promise<TrustAnchor[]>;
+}
+interface TrustStoreHint {
+    /** Leaf cert's Issuer DN (RFC 4514 string). */
+    issuer?: string;
+    /** Leaf cert's Authority Key Identifier extension bytes. */
+    aki?: Uint8Array;
+    /** JWT/COSE key ID, used by LOTL-backed stores. */
+    kid?: string;
+}
+type TrustStoreInput = X509Certificate | Uint8Array | string;
+/**
+ * Trust store backed by a fixed list of certificates supplied at construction
+ * time. No I/O, no refresh. Suitable for development, testing, and consumers
+ * with a static issuer allowlist.
+ */
+declare class StaticTrustStore implements TrustStore {
+    private readonly anchors;
+    private readonly skiIndex;
+    private readonly subjectIndex;
+    constructor(certs: Iterable<TrustStoreInput>);
+    getAnchors(hint: TrustStoreHint): Promise<TrustAnchor[]>;
+}
+/**
+ * Combines multiple `TrustStore` instances. Children are queried in parallel;
+ * results concatenate in child-order; duplicate anchors are dropped by
+ * Subject Key Identifier.
+ */
+declare class CompositeTrustStore implements TrustStore {
+    private readonly stores;
+    constructor(stores: TrustStore[]);
+    getAnchors(hint: TrustStoreHint): Promise<TrustAnchor[]>;
+    getNationalTls(): Promise<readonly NationalTlSnapshot[]>;
+}
+
+interface TrustEvaluationResult {
+    chain: X509Certificate[];
+    anchor: TrustAnchor;
+    revocationStatus: 'good' | 'revoked' | 'unknown' | 'skipped';
+    revocationCheckedAt?: Date;
+    revokedAt?: Date;
+    revocationReason?: string;
+    trustedAuthorityIds?: readonly string[];
+    provenance?: {
+        loa?: 'substantial' | 'high';
+        qualified?: boolean;
+        country?: string;
+        serviceName?: string;
+    };
+}
+
 type CredentialFormat = 'sd-jwt-vc' | 'mdoc';
 interface CredentialClaims {
     age_over_18?: boolean;
@@ -20,24 +216,33 @@ interface PresentationResult {
     claims: CredentialClaims;
     issuer: IssuerInfo;
     error?: string;
-}
-
-interface AuthorizationRequestInput {
-    requestedAttributes: string[];
-    acceptedFormats: CredentialFormat[];
-    responseUri: string;
-    nonce: string;
-    clientId: string;
-    state?: string;
-}
-interface AuthorizationRequest {
-    uri: string;
-    presentationDefinition: object;
-    nonce: string;
-    state: string;
+    /** SD-JWT type (Verifiable Credential Type URI). Populated for `sd-jwt-vc` format. */
+    vct?: string;
+    /** mDOC docType (ISO 18013-5). Populated for `mdoc` format. */
+    docType?: string;
+    /**
+     * mDOC claims grouped by namespace. Populated for `mdoc` format.
+     * DCQL claim paths address this shape: `['org.iso.18013.5.1', 'age_over_18']`.
+     */
+    namespacedClaims?: Record<string, Record<string, unknown>>;
+    /**
+     * Populated when `ParseOptions.trustStore` was provided and trust
+     * evaluation succeeded. Contains the validated chain, matched anchor,
+     * and revocation + provenance metadata (populated incrementally across
+     * 0.5.0 A.1/A.2/A.3). Omitted when `skipTrustCheck: true` or when
+     * `trustStore` was not provided.
+     */
+    trust?: TrustEvaluationResult;
 }
 
 interface ParseOptions {
+    /**
+     * DER-encoded issuer leaf certificates used for byte-equality trust check.
+     * Kept for 0.4.0 compatibility.
+     * @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.
+     */
     trustedCertificates: Uint8Array[];
     nonce: string;
     /** Expected audience for key binding JWT verification. Optional. */
@@ -46,18 +251,32 @@ interface ParseOptions {
     allowedAlgorithms?: string[];
     /**
      * Explicit opt-in to skip the trust check. When omitted or `false`,
-     * `trustedCertificates` must be non-empty — otherwise parsing throws
-     * `MalformedCredentialError`. Set to `true` for demo/mock environments
-     * where no trusted issuer set is available.
+     * either `trustedCertificates` must be non-empty OR `trustStore` must be
+     * provided — otherwise parsing throws `MalformedCredentialError`.
      */
     skipTrustCheck?: boolean;
     /**
      * When set, the parsed credential's `docType` (mDOC) or `vct` (SD-JWT)
      * must equal this value — otherwise parsing throws `MalformedCredentialError`.
-     * Defends against doc-type confusion attacks when the verifier expects a
-     * specific credential class (e.g. `'eu.europa.ec.eudi.pid.1'`).
      */
     expectedDocType?: string;
+    /**
+     * 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`.
+     */
+    trustStore?: TrustStore;
+    /**
+     * Revocation checking policy. Default `'skip'`. `'prefer'` and `'require'`
+     * 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`. */
+    fetcher?: Fetcher;
+    /** Cache for CRL/OCSP/LOTL artefacts. Defaults to `new InMemoryCache()`. */
+    cache?: Cache;
+    /** Clock-skew tolerance in seconds for certificate validity checks. Default 60. */
+    clockSkewTolerance?: number;
 }
 interface ICredentialParser {
     readonly format: CredentialFormat;
@@ -65,6 +284,29 @@ interface ICredentialParser {
     parse(vpToken: unknown, options: ParseOptions): Promise<PresentationResult>;
 }
 
+declare function parsePresentation(vpToken: unknown, options: ParseOptions): Promise<PresentationResult>;
+
+type VerifyOptions = ParseOptions;
+interface VerifyResult {
+    parsed: PresentationResult;
+    match: DcqlMatchResult;
+    submission: DcqlSubmission | null;
+    valid: boolean;
+}
+
+/**
+ * Parses a VP token, then matches it against a DCQL query.
+ *
+ * Cryptographic / structural parser failures still throw (via `parsePresentation`).
+ * Query-level mismatches are surfaced as `match.unmatched` entries so callers can
+ * show per-claim diagnostics.
+ *
+ * @param vpToken raw VP token (SD-JWT string or mDOC Uint8Array)
+ * @param query  DCQL query describing the required credential(s)
+ * @param options parse + verify options (nonce, trusted issuers, etc.)
+ */
+declare function verifyPresentation(vpToken: unknown, query: DcqlQuery, options: VerifyOptions): Promise<VerifyResult>;
+
 /**
  * SD-JWT VC credential parser.
  *
@@ -124,11 +366,94 @@ 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';
+declare class HaipValidationError extends Error {
+    readonly code: HaipValidationCode;
+    readonly credentialId?: string;
+    constructor(code: HaipValidationCode, message: string, credentialId?: string);
+}
+declare abstract class OpenID4VPError extends Error {
+    abstract readonly code: string;
+    constructor(message: string, options?: {
+        cause?: 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';
+declare class CertificateChainError extends OpenID4VPError {
+    readonly code: "chain_invalid";
+    readonly reason: ChainErrorReason;
+    constructor(message: string, options: {
+        reason: ChainErrorReason;
+        cause?: Error;
+    });
+}
+declare class RevokedCertificateError extends OpenID4VPError {
+    readonly code: "certificate_revoked";
+    readonly serial: string;
+    readonly revokedAt: Date;
+    readonly reason?: string;
+    constructor(message: string, options: {
+        serial: string;
+        revokedAt: Date;
+        reason?: string;
+        cause?: Error;
+    });
+}
+declare class RevocationCheckFailedError extends OpenID4VPError {
+    readonly code: "revocation_check_failed";
+}
+declare class LotlFetchError extends OpenID4VPError {
+    readonly code: "lotl_fetch_failed";
+    readonly url: string;
+    constructor(message: string, options: {
+        url: string;
+        cause?: Error;
+    });
+}
+declare class LotlSignatureError extends OpenID4VPError {
+    readonly code: "lotl_signature_invalid";
+}
 
-declare function createAuthorizationRequest(input: AuthorizationRequestInput): AuthorizationRequest;
-
-declare function parsePresentation(vpToken: unknown, options: ParseOptions): Promise<PresentationResult>;
+interface LotlTrustStoreOptions {
+    /** Override the bundled signing anchors. Empty is rejected. */
+    signingAnchors?: readonly X509Certificate[];
+    fetcher?: Fetcher;
+    cache?: Cache;
+    /** ms between snapshot refreshes. Default: 24h. */
+    refreshInterval?: number;
+    /** Override the LOTL URL. Defaults to the EC production URL. */
+    lotlUrl?: string;
+}
+/**
+ * Public TrustStore backed by the EU LOTL + national TLs. Loads lazily on
+ * the first `getAnchors()` call; subsequent calls within `refreshInterval`
+ * hit the in-memory snapshot. Graceful degradation: refresh failures serve
+ * the prior snapshot with a `console.warn`. Single-flight: concurrent
+ * refreshes share one in-flight promise.
+ */
+declare class LotlTrustStore implements TrustStore {
+    private readonly fetcher;
+    private readonly resolver;
+    private readonly signingAnchors;
+    private readonly refreshInterval;
+    private readonly lotlUrl;
+    private readonly cache;
+    private snapshot;
+    private inFlight;
+    constructor(opts?: LotlTrustStoreOptions);
+    getAnchors(hint: TrustStoreHint): Promise<TrustAnchor[]>;
+    /**
+     * Internal accessor — used by `TrustEvaluator` for `ProvenanceResolver`.
+     * Not part of the public `TrustStore` contract.
+     */
+    getNationalTls(): Promise<readonly NationalTlSnapshot[]>;
+    private getSnapshot;
+    private refresh;
+}
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.5.0";
 
-export { type AuthorizationRequest, type AuthorizationRequestInput, type CredentialClaims, type CredentialFormat, ExpiredCredentialError, type ICredentialParser, InvalidSignatureError, type IssuerInfo, MalformedCredentialError, MdocParser, NonceValidationError, type ParseOptions, type PresentationResult, SdJwtParser, UnsupportedFormatError, VERSION, createAuthorizationRequest, parsePresentation };
+export { type AuthorizationRequest, type AuthorizationRequestInput, type Cache, CertificateChainError, type ChainErrorReason, CompositeTrustStore, type CredentialClaims, type CredentialFormat, 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, NonceValidationError, OpenID4VPError, type ParseOptions, type PresentationResult, RevocationCheckFailedError, RevokedCertificateError, SdJwtParser, StaticTrustStore, type TrustAnchor, TrustAnchorNotFoundError, type TrustStore, type TrustStoreHint, type TrustStoreInput, UnsupportedFormatError, VERSION, type VerifyOptions, type VerifyResult, buildHaipQuery, createAuthorizationRequest, isHaipQuery, parsePresentation, validateHaipQuery, verifyPresentation };