@openeudi/openid4vp 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -15,9 +15,49 @@ interface AuthorizationRequest {
     nonce: string;
     state: string;
 }
+interface SignedAuthorizationRequestInput {
+    hostname: string;
+    requestUri: string;
+    responseUri: string;
+    nonce: string;
+    state?: string;
+    responseMode?: 'direct_post' | 'direct_post.jwt';
+    signer: CryptoKeyPair;
+    signingAlgorithm?: 'ES256' | 'ES384' | 'RS256';
+    certificateChain: Uint8Array[];
+    encryptionKey?: {
+        publicJwk: JsonWebKey;
+        supportedEncValues?: string[];
+    };
+    vpFormatsSupported: Record<string, unknown>;
+}
+interface SignedAuthorizationRequest {
+    uri: string;
+    requestObject: string;
+    dcqlQuery: DcqlQuery;
+    nonce: string;
+    state: string;
+}
+interface AuthorizationResponse {
+    vp_token: Record<string, Array<string | object>>;
+    state?: string;
+    [key: string]: unknown;
+}
 
 declare function createAuthorizationRequest(input: AuthorizationRequestInput, query: DcqlQuery): AuthorizationRequest;
 
+/**
+ * Build a signed authorization request (JAR) per OpenID4VP 1.0 §5.10 / RFC 9101.
+ *
+ * Validates that the signing key is bound to the leaf certificate and that the
+ * leaf cert's SAN DNSName equals the declared hostname. Emits a short URI
+ * carrying only `client_id` + `request_uri`, plus the JWS string the caller
+ * must host at `requestUri` with Content-Type `application/oauth-authz-req+jwt`.
+ *
+ * Client Identifier Prefix is always `x509_san_dns` — other prefixes deferred.
+ */
+declare function createSignedAuthorizationRequest(input: SignedAuthorizationRequestInput, query: DcqlQuery): Promise<SignedAuthorizationRequest>;
+
 interface HaipQueryInput {
     credentialId: string;
     format: 'dc+sd-jwt' | 'mso_mdoc';
@@ -277,6 +317,27 @@ interface ParseOptions {
     cache?: Cache;
     /** Clock-skew tolerance in seconds for certificate validity checks. Default 60. */
     clockSkewTolerance?: number;
+    /**
+     * An explicit set of trusted issuer JWKs used as an alternate trust path when the
+     * SD-JWT VC's issuer JWT lacks an `x5c` header. When the header has no `x5c`:
+     *   - If this array is provided, the parser looks up the issuer key by `kid`
+     *     (or by exact `kty`/`crv`/`x`/`y` match when no `kid` is present). The
+     *     matched JWK is the trust anchor — cert-chain validation is skipped.
+     *   - If this array is absent (or empty), the parser falls back to the existing
+     *     behaviour and throws `MalformedCredentialError('Missing or invalid x5c in JWT header')`.
+     *
+     * **When the JWT header DOES include `x5c`** this option is ignored — the existing
+     * x5c/`trustedCertificates` / `trustStore` path runs unchanged.
+     *
+     * **Security notice**: opting in to this path skips certificate-chain trust
+     * evaluation entirely. The caller is explicitly asserting that they trust the
+     * supplied JWK(s) out-of-band. This is appropriate for CI harness setups (e.g.
+     * OIDF conformance suite, where the wallet signs without x5c and the verifier
+     * knows the signing key from the test-plan config). It is **not recommended for
+     * production verifiers** — cert-chain trust evaluation via `trustStore` is the
+     * secure path.
+     */
+    trustedIssuerJwks?: JsonWebKey[];
 }
 interface ICredentialParser {
     readonly format: CredentialFormat;
@@ -293,6 +354,12 @@ interface VerifyResult {
     submission: DcqlSubmission | null;
     valid: boolean;
 }
+interface EncryptedResponse {
+    response: string;
+}
+type VerifyAuthorizationResponseOptions = VerifyOptions & {
+    decryptionKey?: CryptoKey;
+};
 
 /**
  * Parses a VP token, then matches it against a DCQL query.
@@ -306,6 +373,34 @@ interface VerifyResult {
  * @param options parse + verify options (nonce, trusted issuers, etc.)
  */
 declare function verifyPresentation(vpToken: unknown, query: DcqlQuery, options: VerifyOptions): Promise<VerifyResult>;
+/**
+ * Verify an OpenID4VP 1.0 §8.1 Authorization Response envelope.
+ *
+ * Accepts either the unencrypted envelope (object-keyed `vp_token`) or a
+ * JWE-wrapped envelope `{ response: '<JWE>' }` for response_mode =
+ * direct_post.jwt. When encrypted, decrypts with `options.decryptionKey`
+ * first. For this release only single-credential single-presentation is
+ * supported — multi-credential envelopes throw
+ * {@link MultipleCredentialsNotSupportedError}. Otherwise delegates the
+ * extracted single presentation to the existing {@link verifyPresentation}.
+ *
+ * Callers MUST compare the envelope's `state` against the value they issued
+ * themselves — library is stateless and does not track state.
+ */
+declare function verifyAuthorizationResponse(envelope: AuthorizationResponse | EncryptedResponse, query: DcqlQuery, options: VerifyAuthorizationResponseOptions): Promise<VerifyResult>;
+
+/**
+ * Decrypt a JWE-wrapped OpenID4VP Authorization Response (response_mode =
+ * direct_post.jwt). Returns the inner §8.1 envelope.
+ *
+ * Supported JWE algorithms (others throw UnsupportedJweError):
+ *   - alg: ECDH-ES
+ *   - enc: A128GCM, A256GCM (HAIP requires both)
+ *
+ * Cryptographic failures (wrong key, tampered ciphertext) throw
+ * DecryptionFailedError.
+ */
+declare function decryptAuthorizationResponse(jwe: string, privateKey: CryptoKey): Promise<AuthorizationResponse>;
 
 /**
  * SD-JWT VC credential parser.
@@ -416,6 +511,33 @@ declare class LotlFetchError extends OpenID4VPError {
 declare class LotlSignatureError extends OpenID4VPError {
     readonly code: "lotl_signature_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';
+declare class SignedRequestBuildError extends OpenID4VPError {
+    readonly code: SignedRequestBuildErrorCode;
+    constructor(code: SignedRequestBuildErrorCode, message: string);
+}
+declare class UnsupportedJweError extends OpenID4VPError {
+    readonly code: "unsupported_jwe";
+    readonly alg: string;
+    readonly enc: string;
+    constructor(alg: string, enc: string);
+}
+declare class DecryptionFailedError extends OpenID4VPError {
+    readonly code: "decryption_failed";
+    constructor(message?: string, options?: {
+        cause?: Error;
+    });
+}
+declare class MissingDecryptionKeyError extends OpenID4VPError {
+    readonly code: "missing_decryption_key";
+    constructor(message?: string);
+}
+declare class MultipleCredentialsNotSupportedError extends OpenID4VPError {
+    readonly code: "multi_credential_unsupported";
+    readonly entryCount: number;
+    readonly presentationCount: number;
+    constructor(entryCount: number, presentationCount: number);
+}
 
 interface LotlTrustStoreOptions {
     /** Override the bundled signing anchors. Empty is rejected. */
@@ -454,6 +576,6 @@ declare class LotlTrustStore implements TrustStore {
     private refresh;
 }
 
-declare const VERSION = "0.5.0";
+declare const VERSION = "0.8.0";
 
-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 };
+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, 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, createAuthorizationRequest, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };

package/dist/index.d.ts

@@ -15,9 +15,49 @@ interface AuthorizationRequest {
     nonce: string;
     state: string;
 }
+interface SignedAuthorizationRequestInput {
+    hostname: string;
+    requestUri: string;
+    responseUri: string;
+    nonce: string;
+    state?: string;
+    responseMode?: 'direct_post' | 'direct_post.jwt';
+    signer: CryptoKeyPair;
+    signingAlgorithm?: 'ES256' | 'ES384' | 'RS256';
+    certificateChain: Uint8Array[];
+    encryptionKey?: {
+        publicJwk: JsonWebKey;
+        supportedEncValues?: string[];
+    };
+    vpFormatsSupported: Record<string, unknown>;
+}
+interface SignedAuthorizationRequest {
+    uri: string;
+    requestObject: string;
+    dcqlQuery: DcqlQuery;
+    nonce: string;
+    state: string;
+}
+interface AuthorizationResponse {
+    vp_token: Record<string, Array<string | object>>;
+    state?: string;
+    [key: string]: unknown;
+}
 
 declare function createAuthorizationRequest(input: AuthorizationRequestInput, query: DcqlQuery): AuthorizationRequest;
 
+/**
+ * Build a signed authorization request (JAR) per OpenID4VP 1.0 §5.10 / RFC 9101.
+ *
+ * Validates that the signing key is bound to the leaf certificate and that the
+ * leaf cert's SAN DNSName equals the declared hostname. Emits a short URI
+ * carrying only `client_id` + `request_uri`, plus the JWS string the caller
+ * must host at `requestUri` with Content-Type `application/oauth-authz-req+jwt`.
+ *
+ * Client Identifier Prefix is always `x509_san_dns` — other prefixes deferred.
+ */
+declare function createSignedAuthorizationRequest(input: SignedAuthorizationRequestInput, query: DcqlQuery): Promise<SignedAuthorizationRequest>;
+
 interface HaipQueryInput {
     credentialId: string;
     format: 'dc+sd-jwt' | 'mso_mdoc';
@@ -277,6 +317,27 @@ interface ParseOptions {
     cache?: Cache;
     /** Clock-skew tolerance in seconds for certificate validity checks. Default 60. */
     clockSkewTolerance?: number;
+    /**
+     * An explicit set of trusted issuer JWKs used as an alternate trust path when the
+     * SD-JWT VC's issuer JWT lacks an `x5c` header. When the header has no `x5c`:
+     *   - If this array is provided, the parser looks up the issuer key by `kid`
+     *     (or by exact `kty`/`crv`/`x`/`y` match when no `kid` is present). The
+     *     matched JWK is the trust anchor — cert-chain validation is skipped.
+     *   - If this array is absent (or empty), the parser falls back to the existing
+     *     behaviour and throws `MalformedCredentialError('Missing or invalid x5c in JWT header')`.
+     *
+     * **When the JWT header DOES include `x5c`** this option is ignored — the existing
+     * x5c/`trustedCertificates` / `trustStore` path runs unchanged.
+     *
+     * **Security notice**: opting in to this path skips certificate-chain trust
+     * evaluation entirely. The caller is explicitly asserting that they trust the
+     * supplied JWK(s) out-of-band. This is appropriate for CI harness setups (e.g.
+     * OIDF conformance suite, where the wallet signs without x5c and the verifier
+     * knows the signing key from the test-plan config). It is **not recommended for
+     * production verifiers** — cert-chain trust evaluation via `trustStore` is the
+     * secure path.
+     */
+    trustedIssuerJwks?: JsonWebKey[];
 }
 interface ICredentialParser {
     readonly format: CredentialFormat;
@@ -293,6 +354,12 @@ interface VerifyResult {
     submission: DcqlSubmission | null;
     valid: boolean;
 }
+interface EncryptedResponse {
+    response: string;
+}
+type VerifyAuthorizationResponseOptions = VerifyOptions & {
+    decryptionKey?: CryptoKey;
+};
 
 /**
  * Parses a VP token, then matches it against a DCQL query.
@@ -306,6 +373,34 @@ interface VerifyResult {
  * @param options parse + verify options (nonce, trusted issuers, etc.)
  */
 declare function verifyPresentation(vpToken: unknown, query: DcqlQuery, options: VerifyOptions): Promise<VerifyResult>;
+/**
+ * Verify an OpenID4VP 1.0 §8.1 Authorization Response envelope.
+ *
+ * Accepts either the unencrypted envelope (object-keyed `vp_token`) or a
+ * JWE-wrapped envelope `{ response: '<JWE>' }` for response_mode =
+ * direct_post.jwt. When encrypted, decrypts with `options.decryptionKey`
+ * first. For this release only single-credential single-presentation is
+ * supported — multi-credential envelopes throw
+ * {@link MultipleCredentialsNotSupportedError}. Otherwise delegates the
+ * extracted single presentation to the existing {@link verifyPresentation}.
+ *
+ * Callers MUST compare the envelope's `state` against the value they issued
+ * themselves — library is stateless and does not track state.
+ */
+declare function verifyAuthorizationResponse(envelope: AuthorizationResponse | EncryptedResponse, query: DcqlQuery, options: VerifyAuthorizationResponseOptions): Promise<VerifyResult>;
+
+/**
+ * Decrypt a JWE-wrapped OpenID4VP Authorization Response (response_mode =
+ * direct_post.jwt). Returns the inner §8.1 envelope.
+ *
+ * Supported JWE algorithms (others throw UnsupportedJweError):
+ *   - alg: ECDH-ES
+ *   - enc: A128GCM, A256GCM (HAIP requires both)
+ *
+ * Cryptographic failures (wrong key, tampered ciphertext) throw
+ * DecryptionFailedError.
+ */
+declare function decryptAuthorizationResponse(jwe: string, privateKey: CryptoKey): Promise<AuthorizationResponse>;
 
 /**
  * SD-JWT VC credential parser.
@@ -416,6 +511,33 @@ declare class LotlFetchError extends OpenID4VPError {
 declare class LotlSignatureError extends OpenID4VPError {
     readonly code: "lotl_signature_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';
+declare class SignedRequestBuildError extends OpenID4VPError {
+    readonly code: SignedRequestBuildErrorCode;
+    constructor(code: SignedRequestBuildErrorCode, message: string);
+}
+declare class UnsupportedJweError extends OpenID4VPError {
+    readonly code: "unsupported_jwe";
+    readonly alg: string;
+    readonly enc: string;
+    constructor(alg: string, enc: string);
+}
+declare class DecryptionFailedError extends OpenID4VPError {
+    readonly code: "decryption_failed";
+    constructor(message?: string, options?: {
+        cause?: Error;
+    });
+}
+declare class MissingDecryptionKeyError extends OpenID4VPError {
+    readonly code: "missing_decryption_key";
+    constructor(message?: string);
+}
+declare class MultipleCredentialsNotSupportedError extends OpenID4VPError {
+    readonly code: "multi_credential_unsupported";
+    readonly entryCount: number;
+    readonly presentationCount: number;
+    constructor(entryCount: number, presentationCount: number);
+}
 
 interface LotlTrustStoreOptions {
     /** Override the bundled signing anchors. Empty is rejected. */
@@ -454,6 +576,6 @@ declare class LotlTrustStore implements TrustStore {
     private refresh;
 }
 
-declare const VERSION = "0.5.0";
+declare const VERSION = "0.8.0";
 
-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 };
+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, 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, createAuthorizationRequest, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };