@openeudi/openid4vp 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -287,8 +287,23 @@ interface ParseOptions {
     nonce: string;
     /** Expected audience for key binding JWT verification. Optional. */
     audience?: string;
+    /**
+     * Force holder-binding verification even when the issuer JWT carries no
+     * `cnf` claim. When the credential IS holder-bound (`cnf` present), a
+     * KB-JWT is ALWAYS required regardless of this flag — this flag only
+     * extends the requirement to credentials that lack `cnf`. Default: false.
+     */
+    requireKeyBinding?: boolean;
     /** Allowed JWT signature algorithms. Defaults to ['ES256', 'ES384', 'ES512']. */
     allowedAlgorithms?: string[];
+    /**
+     * CBOR bytes of the ISO 18013-5 `SessionTranscript` data item for the current
+     * OpenID4VP exchange. REQUIRED to verify mDOC device authentication — the
+     * mDOC parser fails closed without it, since device proof-of-possession and
+     * replay/nonce binding cannot otherwise be checked. Construct it from the
+     * OpenID4VP handover (client_id, response_uri, nonce, mdoc-generated-nonce).
+     */
+    mdocSessionTranscript?: Uint8Array;
     /**
      * Explicit opt-in to skip the trust check. When omitted or `false`,
      * either `trustedCertificates` must be non-empty OR `trustStore` must be
@@ -359,6 +374,42 @@ interface EncryptedResponse {
 }
 type VerifyAuthorizationResponseOptions = VerifyOptions & {
     decryptionKey?: CryptoKey;
+    /**
+     * The OpenID4VP verifier's `client_id`, as sent in the authorization request.
+     * Combined with {@link responseUri}, {@link ParseOptions.nonce} and the
+     * `mdoc-generated-nonce` (carried in the JWE `apu` header, ISO 18013-7 Annex B),
+     * it lets the encrypted-response path auto-build the mDOC SessionTranscript the
+     * mDOC parser requires — so callers need not construct the CBOR by hand. Ignored
+     * when the caller supplies {@link ParseOptions.mdocSessionTranscript} explicitly.
+     */
+    clientId?: string;
+    /**
+     * The OpenID4VP verifier's `response_uri`, as sent in the authorization request.
+     * See {@link clientId} — used to auto-build the mDOC SessionTranscript.
+     */
+    responseUri?: string;
+    /**
+     * Which mDOC SessionTranscript layout to auto-build when {@link clientId},
+     * {@link responseUri} and {@link ParseOptions.nonce} are present and the
+     * caller has not supplied {@link ParseOptions.mdocSessionTranscript}:
+     *
+     * - `'iso-18013-7'` (default): the ISO 18013-7 Annex B `OID4VPHandover`,
+     *   derived from the `mdoc-generated-nonce` carried in the JWE `apu` header.
+     *   This is the id2/id3-era layout and is kept as the default for
+     *   backwards compatibility.
+     * - `'openid4vp-1.0'`: the OpenID4VP 1.0 (Final) `OpenID4VPHandover`
+     *   (§B.2.6), derived from {@link verifierEncryptionJwk}'s RFC 7638
+     *   thumbprint instead of an `apu` nonce.
+     */
+    sessionTranscriptProfile?: 'iso-18013-7' | 'openid4vp-1.0';
+    /**
+     * The verifier's response-encryption public JWK. Required when
+     * {@link sessionTranscriptProfile} is `'openid4vp-1.0'` and the response is
+     * encrypted — its RFC 7638 SHA-256 thumbprint is embedded in the
+     * OpenID4VPHandover SessionTranscript. Ignored for the `'iso-18013-7'`
+     * profile (which uses the JWE `apu` header instead).
+     */
+    verifierEncryptionJwk?: JsonWebKey;
 };
 
 /**
@@ -402,6 +453,55 @@ declare function verifyAuthorizationResponse(envelope: AuthorizationResponse | E
  */
 declare function decryptAuthorizationResponse(jwe: string, privateKey: CryptoKey): Promise<AuthorizationResponse>;
 
+/**
+ * Build the ISO 18013-7 Annex B `OID4VPHandover` SessionTranscript:
+ *
+ *   SessionTranscript = [ null, null, OID4VPHandover ]
+ *   OID4VPHandover = [ clientIdHash, responseUriHash, nonce ]
+ *   clientIdHash = SHA-256(cbor([clientId, mdocGeneratedNonce]))
+ *   responseUriHash = SHA-256(cbor([responseUri, mdocGeneratedNonce]))
+ *
+ * Used to bind an mdoc DeviceAuthentication to the OpenID4VP authorization
+ * request/response exchange it was presented in.
+ */
+declare function buildOid4vpSessionTranscript(params: {
+    clientId: string;
+    responseUri: string;
+    nonce: string;
+    mdocGeneratedNonce: string;
+}): Promise<Uint8Array>;
+/**
+ * Build the OpenID for Verifiable Presentations 1.0 (Final) `OpenID4VPHandover`
+ * SessionTranscript (OID4VP 1.0 §B.2.6, `response_uri` flavour):
+ *
+ *   SessionTranscript = [ null, null, OpenID4VPHandover ]
+ *   OpenID4VPHandover = [ "OpenID4VPHandover", SHA-256(cbor(OpenID4VPHandoverInfo)) ]
+ *   OpenID4VPHandoverInfo = [ clientId, nonce, jwkThumbprint | null, responseUri ]
+ *
+ * `jwkThumbprint` is the RFC 7638 SHA-256 thumbprint of the verifier's response
+ * ENCRYPTION public JWK as RAW 32 bytes, or CBOR `null` for an unencrypted
+ * response. `clientId` is passed verbatim and is expected to already carry its
+ * client-id-prefix (e.g. `x509_san_dns:v.example`) — the suite hashes the same
+ * `client_id` string it received in the request.
+ *
+ * This is a DIFFERENT structure from the ISO 18013-7 Annex B `OID4VPHandover`
+ * built by `buildOid4vpSessionTranscript` above (which uses an mdoc-generated
+ * nonce and separate client_id/response_uri hashes). 1.0-Final wallets tested
+ * by the OIDF `oid4vp-1final-verifier-*` modules require THIS layout.
+ *
+ * Layout confirmed against OID4VP 1.0 Final §B.2.6 and the suite class
+ * net.openid.conformance.condition.client.AbstractCreateVP1FinalIsoMdocRedirectSessionTranscript
+ * at tag release-v5.1.42: element order [clientId, nonce, thumb|null, responseUri];
+ * thumbprint embedded as raw bytes; outer hash is SHA-256 over the CBOR of the
+ * 4-element info array.
+ */
+declare function buildOpenID4VPHandoverSessionTranscript(params: {
+    clientId: string;
+    nonce: string;
+    responseUri: string;
+    verifierEncryptionJwk?: JsonWebKey;
+}): Promise<Uint8Array>;
+
 /**
  * SD-JWT VC credential parser.
  *
@@ -578,4 +678,4 @@ declare class LotlTrustStore implements TrustStore {
 
 declare const VERSION = "0.8.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, 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 };
+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, buildOid4vpSessionTranscript, buildOpenID4VPHandoverSessionTranscript, createAuthorizationRequest, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };

package/dist/index.d.ts

@@ -287,8 +287,23 @@ interface ParseOptions {
     nonce: string;
     /** Expected audience for key binding JWT verification. Optional. */
     audience?: string;
+    /**
+     * Force holder-binding verification even when the issuer JWT carries no
+     * `cnf` claim. When the credential IS holder-bound (`cnf` present), a
+     * KB-JWT is ALWAYS required regardless of this flag — this flag only
+     * extends the requirement to credentials that lack `cnf`. Default: false.
+     */
+    requireKeyBinding?: boolean;
     /** Allowed JWT signature algorithms. Defaults to ['ES256', 'ES384', 'ES512']. */
     allowedAlgorithms?: string[];
+    /**
+     * CBOR bytes of the ISO 18013-5 `SessionTranscript` data item for the current
+     * OpenID4VP exchange. REQUIRED to verify mDOC device authentication — the
+     * mDOC parser fails closed without it, since device proof-of-possession and
+     * replay/nonce binding cannot otherwise be checked. Construct it from the
+     * OpenID4VP handover (client_id, response_uri, nonce, mdoc-generated-nonce).
+     */
+    mdocSessionTranscript?: Uint8Array;
     /**
      * Explicit opt-in to skip the trust check. When omitted or `false`,
      * either `trustedCertificates` must be non-empty OR `trustStore` must be
@@ -359,6 +374,42 @@ interface EncryptedResponse {
 }
 type VerifyAuthorizationResponseOptions = VerifyOptions & {
     decryptionKey?: CryptoKey;
+    /**
+     * The OpenID4VP verifier's `client_id`, as sent in the authorization request.
+     * Combined with {@link responseUri}, {@link ParseOptions.nonce} and the
+     * `mdoc-generated-nonce` (carried in the JWE `apu` header, ISO 18013-7 Annex B),
+     * it lets the encrypted-response path auto-build the mDOC SessionTranscript the
+     * mDOC parser requires — so callers need not construct the CBOR by hand. Ignored
+     * when the caller supplies {@link ParseOptions.mdocSessionTranscript} explicitly.
+     */
+    clientId?: string;
+    /**
+     * The OpenID4VP verifier's `response_uri`, as sent in the authorization request.
+     * See {@link clientId} — used to auto-build the mDOC SessionTranscript.
+     */
+    responseUri?: string;
+    /**
+     * Which mDOC SessionTranscript layout to auto-build when {@link clientId},
+     * {@link responseUri} and {@link ParseOptions.nonce} are present and the
+     * caller has not supplied {@link ParseOptions.mdocSessionTranscript}:
+     *
+     * - `'iso-18013-7'` (default): the ISO 18013-7 Annex B `OID4VPHandover`,
+     *   derived from the `mdoc-generated-nonce` carried in the JWE `apu` header.
+     *   This is the id2/id3-era layout and is kept as the default for
+     *   backwards compatibility.
+     * - `'openid4vp-1.0'`: the OpenID4VP 1.0 (Final) `OpenID4VPHandover`
+     *   (§B.2.6), derived from {@link verifierEncryptionJwk}'s RFC 7638
+     *   thumbprint instead of an `apu` nonce.
+     */
+    sessionTranscriptProfile?: 'iso-18013-7' | 'openid4vp-1.0';
+    /**
+     * The verifier's response-encryption public JWK. Required when
+     * {@link sessionTranscriptProfile} is `'openid4vp-1.0'` and the response is
+     * encrypted — its RFC 7638 SHA-256 thumbprint is embedded in the
+     * OpenID4VPHandover SessionTranscript. Ignored for the `'iso-18013-7'`
+     * profile (which uses the JWE `apu` header instead).
+     */
+    verifierEncryptionJwk?: JsonWebKey;
 };
 
 /**
@@ -402,6 +453,55 @@ declare function verifyAuthorizationResponse(envelope: AuthorizationResponse | E
  */
 declare function decryptAuthorizationResponse(jwe: string, privateKey: CryptoKey): Promise<AuthorizationResponse>;
 
+/**
+ * Build the ISO 18013-7 Annex B `OID4VPHandover` SessionTranscript:
+ *
+ *   SessionTranscript = [ null, null, OID4VPHandover ]
+ *   OID4VPHandover = [ clientIdHash, responseUriHash, nonce ]
+ *   clientIdHash = SHA-256(cbor([clientId, mdocGeneratedNonce]))
+ *   responseUriHash = SHA-256(cbor([responseUri, mdocGeneratedNonce]))
+ *
+ * Used to bind an mdoc DeviceAuthentication to the OpenID4VP authorization
+ * request/response exchange it was presented in.
+ */
+declare function buildOid4vpSessionTranscript(params: {
+    clientId: string;
+    responseUri: string;
+    nonce: string;
+    mdocGeneratedNonce: string;
+}): Promise<Uint8Array>;
+/**
+ * Build the OpenID for Verifiable Presentations 1.0 (Final) `OpenID4VPHandover`
+ * SessionTranscript (OID4VP 1.0 §B.2.6, `response_uri` flavour):
+ *
+ *   SessionTranscript = [ null, null, OpenID4VPHandover ]
+ *   OpenID4VPHandover = [ "OpenID4VPHandover", SHA-256(cbor(OpenID4VPHandoverInfo)) ]
+ *   OpenID4VPHandoverInfo = [ clientId, nonce, jwkThumbprint | null, responseUri ]
+ *
+ * `jwkThumbprint` is the RFC 7638 SHA-256 thumbprint of the verifier's response
+ * ENCRYPTION public JWK as RAW 32 bytes, or CBOR `null` for an unencrypted
+ * response. `clientId` is passed verbatim and is expected to already carry its
+ * client-id-prefix (e.g. `x509_san_dns:v.example`) — the suite hashes the same
+ * `client_id` string it received in the request.
+ *
+ * This is a DIFFERENT structure from the ISO 18013-7 Annex B `OID4VPHandover`
+ * built by `buildOid4vpSessionTranscript` above (which uses an mdoc-generated
+ * nonce and separate client_id/response_uri hashes). 1.0-Final wallets tested
+ * by the OIDF `oid4vp-1final-verifier-*` modules require THIS layout.
+ *
+ * Layout confirmed against OID4VP 1.0 Final §B.2.6 and the suite class
+ * net.openid.conformance.condition.client.AbstractCreateVP1FinalIsoMdocRedirectSessionTranscript
+ * at tag release-v5.1.42: element order [clientId, nonce, thumb|null, responseUri];
+ * thumbprint embedded as raw bytes; outer hash is SHA-256 over the CBOR of the
+ * 4-element info array.
+ */
+declare function buildOpenID4VPHandoverSessionTranscript(params: {
+    clientId: string;
+    nonce: string;
+    responseUri: string;
+    verifierEncryptionJwk?: JsonWebKey;
+}): Promise<Uint8Array>;
+
 /**
  * SD-JWT VC credential parser.
  *
@@ -578,4 +678,4 @@ declare class LotlTrustStore implements TrustStore {
 
 declare const VERSION = "0.8.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, 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 };
+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, buildOid4vpSessionTranscript, buildOpenID4VPHandoverSessionTranscript, createAuthorizationRequest, createSignedAuthorizationRequest, decryptAuthorizationResponse, isHaipQuery, parsePresentation, validateHaipQuery, verifyAuthorizationResponse, verifyPresentation };