@digitalbazaar/oid4-client 5.7.2 → 5.8.0

package/lib/index.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2026 Digital Bazaar, Inc. All rights reserved.
  */
 export * as oid4vp from './oid4vp/index.js';
 export * as query from './query/index.js';

package/lib/oid4vp/authorizationRequest.js

@@ -85,6 +85,17 @@ export function getClientIdScheme({authorizationRequest} = {}) {
 }
 
 export function requestsFormat({authorizationRequest, format} = {}) {
+  /* e.g. DCQL requesting an mdoc:
+  {
+    credentials: [{
+      id: 'mdl-id',
+      format: 'mso_mdoc',
+      meta: {
+        doctype_value: 'org.iso.18013.5.1.mDL'
+      }
+    }]
+  }
+  */
   /* e.g. presentation definition requesting an mdoc:
   {
     id: 'mdl-test-age-over-21',
@@ -98,8 +109,13 @@ export function requestsFormat({authorizationRequest, format} = {}) {
     }]
   }
   */
-  return authorizationRequest.presentation_definition?.input_descriptors?.some(
-    e => e?.format?.[format]);
+  return (
+    // DCQL
+    authorizationRequest.dcql_query?.credentials?.some(
+      e => e?.format === format) ||
+    // PE
+    authorizationRequest.presentation_definition?.input_descriptors?.some(
+      e => e?.format?.[format]));
 }
 
 export function usesClientIdScheme({authorizationRequest, scheme} = {}) {

package/lib/oid4vp/authorizationResponse.js

@@ -1,9 +1,15 @@
 /*!
- * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2023-2026 Digital Bazaar, Inc.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
  */
+import * as base64url from 'base64url-universal';
 import {createNamedError, selectJwk} from '../util.js';
-import {EncryptJWT} from 'jose';
+import {encode as cborEncode} from 'cborg';
+import {encodeSessionTranscript} from './mdl.js';
+import {encrypt as hpkeEncrypt} from './hpke.js';
 import {httpClient} from '@digitalbazaar/http-client';
+import {encrypt as jwtEncrypt} from './jwt.js';
 import {pathsToVerifiableCredentialPointers} from '../convert/index.js';
 import {resolvePointer} from '../query/util.js';
 
@@ -15,7 +21,7 @@ export async function create({
   verifiablePresentation,
   presentationSubmission,
   authorizationRequest,
-  vpToken,
+  vpToken, vpTokenMediaType,
   encryptionOptions = {}
 } = {}) {
   if(!(verifiablePresentation || vpToken)) {
@@ -27,9 +33,10 @@ export async function create({
   // if no `vpToken` given, use VP
   vpToken = vpToken ?? JSON.stringify(verifiablePresentation);
 
-  // if no `presentationSubmission` provided, auto-generate one
+  // if no `presentationSubmission` provided, auto-generate one if no
+  // `vpTokenMediaType` is given
   let generatedPresentationSubmission = false;
-  if(!presentationSubmission) {
+  if(!presentationSubmission && vpTokenMediaType === undefined) {
     ({presentationSubmission} = createPresentationSubmission({
       presentationDefinition: authorizationRequest.presentation_definition,
       verifiablePresentation
@@ -37,29 +44,43 @@ export async function create({
     generatedPresentationSubmission = true;
   }
 
+  encryptionOptions = _normalizeEncryptionOptions({
+    authorizationRequest, encryptionOptions
+  });
+
   // prepare response body
   const body = {};
 
-  // if `authorizationRequest.response_mode` is `direct.jwt` generate a JWT
-  if(authorizationRequest.response_mode === 'direct_post.jwt') {
-    if(submitsFormat({presentationSubmission, format: 'mso_mdoc'}) &&
-      !encryptionOptions?.mdl?.sessionTranscript) {
+  // if `authorizationRequest.response_mode` is `direct.jwt` or
+  // `dc_api.jwt`, then generate a JWT
+  if(authorizationRequest.response_mode === 'direct_post.jwt' ||
+    authorizationRequest.response_mode === 'dc_api.jwt') {
+    // `presentationSubmission` is not used in OID4VP 1.0+
+    if((vpTokenMediaType === 'application/mdl-vp-token' ||
+      submitsFormat({presentationSubmission, format: 'mso_mdoc'})) &&
+      !encryptionOptions?.mdl?.handover) {
       throw createNamedError({
-        message: '"encryptionOptions.mdl.sessionTranscript" is required ' +
-          'when submitting an mDL presentation.',
+        message: '"encryptionOptions.mdl.handover" is required ' +
+          'to submit an mDL presentation.',
         name: 'DataError'
       });
     }
 
     const jwt = await _encrypt({
-      vpToken, presentationSubmission, authorizationRequest,
-      encryptionOptions
+      vpToken, presentationSubmission, authorizationRequest, encryptionOptions
     });
     body.response = jwt;
+  } else if(encryptionOptions?.mdl?.handover?.type === 'dcapi') {
+    // ISO 18013-7 Annex C (HPKE encrypted payload)
+    body.Response = await _encrypt({
+      vpToken, presentationSubmission, authorizationRequest, encryptionOptions
+    });
   } else {
-    // include vp token and presentation submittion directly in body
+    // include vp token and presentation submission directly in body
     body.vp_token = vpToken;
-    body.presentation_submission = JSON.stringify(presentationSubmission);
+    if(presentationSubmission) {
+      body.presentation_submission = JSON.stringify(presentationSubmission);
+    }
   }
 
   const authorizationResponse = body;
@@ -70,11 +91,19 @@ export async function create({
   return {authorizationResponse};
 }
 
+export function selectRecipientPublicJwk({authorizationRequest} = {}) {
+  // get recipient public JWK from client_metadata JWK key set
+  const jwks = authorizationRequest?.client_metadata?.jwks;
+  return selectJwk({
+    keys: jwks?.keys, alg: 'ECDH-ES', kty: 'EC', crv: 'P-256', use: 'enc'
+  });
+}
+
 export async function send({
   verifiablePresentation,
   presentationSubmission,
   authorizationRequest,
-  vpToken,
+  vpToken, vpTokenMediaType,
   encryptionOptions = {},
   authorizationResponse,
   agent
@@ -90,7 +119,7 @@ export async function send({
         verifiablePresentation,
         presentationSubmission,
         authorizationRequest,
-        vpToken,
+        vpToken, vpTokenMediaType,
         encryptionOptions
       }));
     } else if(verifiablePresentation || presentationSubmission || vpToken ||
@@ -204,48 +233,41 @@ export function submitsFormat({presentationSubmission, format} = {}) {
 async function _encrypt({
   vpToken, presentationSubmission, authorizationRequest, encryptionOptions
 }) {
-  // get recipient public JWK from client_metadata JWK key set
-  const jwks = authorizationRequest?.client_metadata?.jwks;
-  const recipientPublicJwk = selectJwk({
-    keys: jwks?.keys, alg: 'ECDH-ES', kty: 'EC', crv: 'P-256', use: 'enc'
-  });
+  // get recipient public JWK
+  const recipientPublicJwk = encryptionOptions?.recipientPublicJwk ??
+    selectRecipientPublicJwk({authorizationRequest});
   if(!recipientPublicJwk) {
     throw createNamedError({
-      message: 'No matching key found for "ECDH-ES" in client meta data ' +
-        'JWK key set.',
+      message:
+        'No matching key found for "ECDH-ES" in client meta data JWK key set.',
       name: 'NotFoundError'
     });
   }
+  encryptionOptions = {...encryptionOptions, recipientPublicJwk};
 
-  // configure `keyManagementParameters` for `EncryptJWT` API
-  const keyManagementParameters = {};
-  if(encryptionOptions?.mdl?.sessionTranscript) {
-    // ISO 18013-7: include specific session transcript params as apu + apv
+  // determine if encrypting to a JWT or using HPKE...
+
+  // only mDL Annex C uses HPKE at this time; handover type 'dcapi' === Annex C
+  if(encryptionOptions?.mdl?.handover?.type === 'dcapi') {
+    const pt = typeof vpToken === 'string' ?
+      base64url.decode(vpToken) : vpToken;
+    // set encoded session transcript as `info`
+    const info = await encodeSessionTranscript({
+      handover: encryptionOptions.mdl.handover
+    });
     const {
-      mdocGeneratedNonce,
-      // default to using `authorizationRequest.nonce` for verifier nonce
-      verifierGeneratedNonce = authorizationRequest.nonce
-    } = encryptionOptions.mdl.sessionTranscript;
-    // note: `EncryptJWT` API requires `apu/apv` (`partyInfoU`/`partyInfoV`)
-    // to be passed as Uint8Arrays; they will be encoded using `base64url` by
-    // that API
-    keyManagementParameters.apu = TEXT_ENCODER.encode(mdocGeneratedNonce);
-    keyManagementParameters.apv = TEXT_ENCODER.encode(verifierGeneratedNonce);
+      enc, ct: cipherText
+    } = await hpkeEncrypt({pt, info, encryptionOptions});
+    const EncryptedResponse = ['dcapi', {enc, cipherText}];
+    return base64url.encode(cborEncode(EncryptedResponse));
   }
 
-  const claimSet = {
-    vp_token: vpToken,
-    presentation_submission: presentationSubmission
-  };
-  const jwt = await new EncryptJWT(claimSet)
-    .setProtectedHeader({
-      alg: 'ECDH-ES',
-      enc: encryptionOptions?.enc ?? 'A256GCM',
-      kid: recipientPublicJwk.kid
-    })
-    .setKeyManagementParameters(keyManagementParameters)
-    .encrypt(recipientPublicJwk);
-  return jwt;
+  // all other cases presently use JWT
+  const payload = {vp_token: vpToken};
+  if(presentationSubmission) {
+    payload.presentation_submission = presentationSubmission;
+  }
+  return jwtEncrypt({payload, encryptionOptions});
 }
 
 function _filterToValue({filter, strict = false}) {
@@ -377,3 +399,53 @@ function _matchesInputDescriptor({
 
   return true;
 }
+
+function _normalizeEncryptionOptions({
+  authorizationRequest, encryptionOptions
+}) {
+  if(encryptionOptions?.mdl?.sessionTranscript &&
+    !encryptionOptions?.mdl.handover) {
+    // deprecated Annex B style handover info
+    encryptionOptions = {
+      ...encryptionOptions,
+      mdl: {
+        ...encryptionOptions.mdl,
+        handover: {
+          type: 'AnnexBHandover',
+          ...encryptionOptions.mdl.sessionTranscript
+        }
+      }
+    };
+  }
+
+  // configure `keyManagementParameters` for `EncryptJWT` API
+  if(!encryptionOptions?.keyManagementParameters) {
+    const keyManagementParameters = {};
+    if(encryptionOptions?.mdl?.handover) {
+      // ISO 18013-7 Annex B has specific handover params for apu + apv; for
+      // Annex D generate `apu` and use `nonce` for `apv` but this isn't a
+      // requirement; Annex C uses HPKE not a JWT so not relevant here
+      const {
+        mdocGeneratedNonce,
+        nonce,
+        verifierGeneratedNonce
+      } = encryptionOptions.mdl.handover;
+
+      // generate 128-bit random `apu` if no `mdocGeneratedNonce` provided
+      const apu = mdocGeneratedNonce ??
+        globalThis.crypto.getRandomValues(new Uint8Array(16));
+      // default to using `authorizationRequest.nonce` for verifier nonce
+      const apv = verifierGeneratedNonce ?? nonce ?? authorizationRequest.nonce;
+      // note: `EncryptJWT` API requires `apu/apv` (`partyInfoU`/`partyInfoV`)
+      // to be passed as Uint8Arrays; they will be encoded using `base64url` by
+      // that API
+      keyManagementParameters.apu = typeof apu === 'string' ?
+        TEXT_ENCODER.encode(apu) : apu;
+      keyManagementParameters.apv = typeof apv === 'string' ?
+        TEXT_ENCODER.encode(apv) : apv;
+    }
+    encryptionOptions = {...encryptionOptions, keyManagementParameters};
+  }
+
+  return encryptionOptions;
+}

package/lib/oid4vp/hpke.js

@@ -0,0 +1,116 @@
+/*!
+ * Copyright (c) 2023-2026 Digital Bazaar, Inc. All rights reserved.
+ */
+import {
+  Aes128Gcm,
+  CipherSuite,
+  DhkemP256HkdfSha256,
+  HkdfSha256
+} from '@hpke/core';
+import {createNamedError, selectJwk} from '../util.js';
+import {importJWK} from 'jose';
+
+// `enc`: encapsulated sender public key
+// `ct`: cipher text
+export async function decrypt({enc, ct, getDecryptParameters}) {
+  if(typeof getDecryptParameters !== 'function') {
+    throw new TypeError(
+      '"getDecryptParameters" is required for "direct_post.jwt" ' +
+      'response mode.');
+  }
+
+  // load decryption parameters
+  const params = await getDecryptParameters({enc});
+  const {keys} = params;
+  let {getKey} = params;
+  let recipientPublicJwk;
+  if(!getKey) {
+    // process `enc` to find key
+    getKey = async ({enc}) => {
+      // import sender key and export as JWK to find a matching recipient key
+      // for decryption
+      const jwk = await _rawPublicKeyToJwk({rawPublicKey: enc});
+      const match = selectJwk({keys, kty: jwk.kty, crv: jwk.crv});
+      if(!match) {
+        throw createNamedError({
+          message: 'No matching recipient cryptographic key found.',
+          name: 'NotSupportedError',
+          details: {httpStatusCode: 400, public: true}
+        });
+      }
+      const {d, ...rest} = match;
+      const recipientSecretJwk = {...rest, d};
+      recipientPublicJwk = {alg: 'ECDH-ES', use: 'enc', ...rest};
+      return importJWK(recipientSecretJwk, 'ECDH-ES', {extractable: true});
+    };
+  }
+  const recipientKey = await getKey({enc});
+  const info = await params?.getInfo?.({enc, recipientPublicJwk});
+  const aad = await params?.getAad?.({enc, info, recipientPublicJwk});
+
+  try {
+    // open: ciphertext + encapsulated key => plaintext
+    const suite = _createCiphersuite();
+    const recipient = await suite.createRecipientContext({
+      recipientKey, enc, info
+    });
+    const pt = new Uint8Array(await recipient.open(ct, aad));
+    return {pt, recipientPublicJwk};
+  } catch(cause) {
+    throw createNamedError({
+      message: `Decryption failed.`,
+      name: 'DataError',
+      details: {httpStatusCode: 400, public: true},
+      cause
+    });
+  }
+}
+
+export async function encrypt({pt, info, aad, encryptionOptions}) {
+  if(encryptionOptions?.enc && !(encryptionOptions.enc !== 'A128GCM')) {
+    throw createNamedError({
+      message:
+        `Unsupported encryption algorithm "${encryptionOptions.enc}"; ` +
+        'only "A128GCM" is supported.',
+      name: 'DataError'
+    });
+  }
+
+  // import recipient public key
+  const {recipientPublicJwk} = encryptionOptions;
+  const recipientPublicKey = await importJWK(recipientPublicJwk, 'ECDH-ES');
+
+  // seal: plaintext => ciphertext + encapsulated key
+  const suite = _createCiphersuite();
+  const sender = await suite.createSenderContext({
+    recipientPublicKey, info
+  });
+  const ct = await sender.seal(pt, aad);
+  return {enc: sender.enc, ct};
+}
+
+// only supported cipher suite
+function _createCiphersuite() {
+  return new CipherSuite({
+    kem: new DhkemP256HkdfSha256(),
+    kdf: new HkdfSha256(),
+    aead: new Aes128Gcm()
+  });
+}
+
+async function _rawPublicKeyToJwk({rawPublicKey}) {
+  try {
+    const publicKey = await globalThis.crypto.subtle.importKey(
+      'raw', rawPublicKey, {name: 'ECDH', namedCurve: 'P-256'},
+      true, []);
+    const jwk = await globalThis.crypto.subtle.exportKey('jwk', publicKey);
+    return jwk;
+  } catch(e) {
+    throw createNamedError({
+      message:
+        'Unsupported public key; it must be "ECDH-ES" with curve "P-256".',
+      name: 'NotSupportedError',
+      details: {httpStatusCode: 400, public: true}
+    });
+  }
+}

package/lib/oid4vp/index.js

@@ -1,9 +1,10 @@
 /*!
- * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2023-2026 Digital Bazaar, Inc. All rights reserved.
  */
 export * as authzRequest from './authorizationRequest.js';
 export * as authzResponse from './authorizationResponse.js';
 export * as convert from '../convert/index.js';
+export * as mdl from './mdl.js';
 export * as verifier from './verifier.js';
 
 // backwards compatibility APIs

package/lib/oid4vp/jwt.js

@@ -0,0 +1,66 @@
+/*!
+ * Copyright (c) 2023-2026 Digital Bazaar, Inc. All rights reserved.
+ */
+import {createNamedError, selectJwk} from '../util.js';
+import {EncryptJWT, importJWK, jwtDecrypt} from 'jose';
+
+export async function decrypt({jwt, getDecryptParameters}) {
+  if(typeof getDecryptParameters !== 'function') {
+    throw new TypeError(
+      '"getDecryptParameters" is required for "direct_post.jwt" ' +
+      'response mode.');
+  }
+
+  const params = await getDecryptParameters({jwt});
+  const {keys} = params;
+  let {getKey} = params;
+  let recipientPublicJwk;
+  if(!getKey) {
+    // note: `jose` lib's JWK key set feature cannot be used and passed to
+    // `jwtDecrypt()` as the second parameter because the expected `alg`
+    // "ECDH-ES" is not a unsupported algorithm for selecting a key from a set
+    getKey = protectedHeader => {
+      if(protectedHeader.alg !== 'ECDH-ES') {
+        throw createNamedError({
+          message: `Unsupported algorithm "${protectedHeader.alg}"; ` +
+            'algorithm must be "ECDH-ES".',
+          name: 'NotSupportedError',
+          details: {httpStatusCode: 400, public: true}
+        });
+      }
+      const {d, ...rest} = selectJwk({keys, kid: protectedHeader.kid});
+      const recipientSecretJwk = {...rest, d};
+      recipientPublicJwk = {alg: 'ECDH-ES', use: 'enc', ...rest};
+      return importJWK(recipientSecretJwk, 'ECDH-ES');
+    };
+  }
+
+  try {
+    const {payload, protectedHeader} = await jwtDecrypt(jwt, getKey, {
+      // only supported algorithms at this time:
+      contentEncryptionAlgorithms: ['A256GCM', 'A128GCM'],
+      keyManagementAlgorithms: ['ECDH-ES']
+    });
+    return {payload, protectedHeader, recipientPublicJwk};
+  } catch(cause) {
+    throw createNamedError({
+      message: `Decryption failed.`,
+      name: 'DataError',
+      details: {httpStatusCode: 400, public: true},
+      cause
+    });
+  }
+}
+
+export async function encrypt({payload, encryptionOptions}) {
+  const {keyManagementParameters, recipientPublicJwk} = encryptionOptions;
+  const jwt = await new EncryptJWT(payload)
+    .setProtectedHeader({
+      alg: 'ECDH-ES',
+      enc: encryptionOptions?.enc ?? 'A256GCM',
+      kid: recipientPublicJwk.kid
+    })
+    .setKeyManagementParameters(keyManagementParameters)
+    .encrypt(recipientPublicJwk);
+  return jwt;
+}

package/lib/oid4vp/mdl.js

@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) 2025-2026 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as base64url from 'base64url-universal';
+import {decode as cborDecode, encode as cborEncode, Token, Type} from 'cborg';
+import {createNamedError, jwkToCoseKey, sha256} from '../util.js';
+import {calculateJwkThumbprint} from 'jose';
+import {decrypt as hpkeDecrypt} from './hpke.js';
+
+const TEXT_ENCODER = new TextEncoder();
+
+/**
+ * Encodes a `SessionTranscript` for use with mDL (ISO 18013-7 variants).
+ *
+ * The `handover` parameter's properties, other than `type`, depend on the
+ * value of `type`:
+ *
+ * For 'AnnexBHandover':
+ *   mdocGeneratedNonce, clientId, responseUri, verifierGeneratedNonce
+ * For 'OpenID4VPDCAPIHandover':
+ *   origin, nonce, jwkThumbprint
+ * For 'dcapi':
+ *   nonce, recipientPublicKey.
+ *
+ * @param {object} options - The options.
+ * @param {object} options.handover - The handover options to use in the
+ *   session transcript, including the `type` and any type-specific properties;
+ *   the `type` can be any of the following:
+ *     'AnnexBHandover' for (ISO 18013-7 Annex B),
+ *     'OpenID4VPDCAPIHandover' for ISO 18013-7 Annex D "Google DC API",
+ *     'dcapi' for ISO 18013-7 Annex C "Apple DC API".
+ *
+ * @returns {Promise<Uint8Array>} The cbor-encoded session transcript.
+ */
+export async function encodeSessionTranscript({handover} = {}) {
+  // produce `Handover` component of mDL session transcript
+  let Handover;
+  if(handover.type === 'AnnexBHandover') {
+    Handover = await _encodeAnnexBHandover({handover});
+  } else if(handover.type === 'dcapi') {
+    Handover = await _encodeAnnexCHandover({handover});
+  } else if(handover.type === 'OpenID4VPDCAPIHandover') {
+    Handover = await _encodeAnnexDHandover({handover});
+  } else {
+    throw new Error(`Unknown handover type "${handover.type}".`);
+  }
+
+  // create session transcript which is always:
+  // `[DeviceEngagementBytes, EReaderKeyBytes, Handover]`
+  // where `DeviceEngagementBytes` and `EReaderKeyBytes` are `null`
+  const sessionTranscript = [null, null, Handover];
+
+  // session transcript bytes are encoded as a CBOR data item within a byte
+  // string (CBOR Tag 24):
+  const dataItem = cborEncode(sessionTranscript);
+  return cborEncode(dataItem, {
+    typeEncoders: {Uint8Array: createTag24Encoder(dataItem)}
+  });
+}
+
+export async function decryptAnnexCResponse({
+  base64urlEncryptedResponse, getDecryptParameters
+} = {}) {
+  // ISO 18013-7 Annex C, with hpke-encrypted payload
+  const EncryptedResponse = cborDecode(
+    base64url.decode(base64urlEncryptedResponse));
+  const [protocol] = EncryptedResponse;
+  if(protocol !== 'dcapi') {
+    throw createNamedError({
+      message: `Unsupported encryption protocol "${protocol}".`,
+      name: 'NotSupportedError'
+    });
+  }
+  const [, {enc, cipherText: ct}] = EncryptedResponse;
+  return hpkeDecrypt({enc, ct, getDecryptParameters});
+}
+
+function createTag24Encoder(value) {
+  return function tag24Encoder(obj) {
+    if(obj !== value) {
+      return null;
+    }
+    return [
+      new Token(Type.tag, 24),
+      new Token(Type.bytes, obj)
+    ];
+  };
+}
+
+// encode `handover` as ISO 18013-7 Annex B Handover
+async function _encodeAnnexBHandover({handover}) {
+  const {
+    mdocGeneratedNonce,
+    clientId,
+    responseUri,
+    verifierGeneratedNonce
+  } = handover;
+  return [mdocGeneratedNonce, clientId, responseUri, verifierGeneratedNonce];
+}
+
+// encode `handover` as ISO 18013-7 Annex C Handover
+async function _encodeAnnexCHandover({handover}) {
+  /* Details:
+
+  Handover = `['dcapi', dcapiInfoHash]`
+  dcapiInfo = [Base64EncryptionInfo, SerializedOrigin]
+
+  SerializedOrigin = tstr
+  dcapiInfoHash = bstr
+
+  `Base64EncryptionInfo` is the base64url-no-pad encoding of the cbor-encoded
+  `EncryptionInfo`.
+
+  EncryptionInfo = [
+    // encryption protocol identifier
+    'dcapi',
+    EncryptionParameters
+  ]
+
+  EncryptionParameters = {
+    // binary string
+    nonce,
+    // COSE key
+    recipientPublicKey
+  }
+  */
+  const {origin, nonce} = handover;
+  // if `recipientPublicKey` is not present, convert it from
+  // `recipientPublicKeyJwk`
+  const recipientPublicKey = handover.recipientPublicKey ??
+    jwkToCoseKey({jwk: handover.recipientPublicJwk});
+  const nonceBytes = typeof nonce === 'string' ?
+    TEXT_ENCODER.encode(nonce) : nonce;
+  const EncryptionParameters = [nonceBytes, recipientPublicKey];
+  const EncryptionInfo = ['dcapi', EncryptionParameters];
+  const Base64EncryptionInfo = base64url.encode(cborEncode(EncryptionInfo));
+  const dcapiInfo = [Base64EncryptionInfo, origin];
+  const dcapiInfoHash = await sha256(cborEncode(dcapiInfo));
+  return ['dcapi', dcapiInfoHash];
+}
+
+// encode `handover` as ISO 18013-7 Annex D Handover
+async function _encodeAnnexDHandover({handover}) {
+  // https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#appendix-B.2.6.2
+  // for `"response_mode": "dc_api"`, `jwkThumbprint` MUST be `null`
+  // for `"response_mode": "dc_api.jwt"`, `jwkThumbprint` MUST be the JWK
+  // SHA-256 Thumbprint of the verifier's public key used to encrypt
+  // the response (as a Uint8Array)
+  const {origin, nonce} = handover;
+
+  // calculate thumbprint if only `recipientPublicJwk` given
+  if(!handover.jwkThumbprint && handover.recipientPublicJwk) {
+    handover = {
+      ...handover,
+      jwkThumbprint: await calculateJwkThumbprint(handover.recipientPublicJwk)
+    };
+  }
+  const jwkThumbprint = typeof handover.jwkThumbprint === 'string' ?
+    base64url.decode(handover.jwkThumbprint) : handover.jwkThumbprint;
+  const handoverInfo = [origin, nonce, jwkThumbprint];
+  const handoverInfoHash = await sha256(cborEncode(handoverInfo));
+  return ['OpenID4VPDCAPIHandover', handoverInfoHash];
+}

package/lib/oid4vp/verifier.js

@@ -1,57 +1,115 @@
 /*!
- * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2023-2026 Digital Bazaar, Inc. All rights reserved.
  */
-import {createNamedError, parseJSON, selectJwk} from '../util.js';
-import {importJWK, jwtDecrypt} from 'jose';
+import * as base64url from 'base64url-universal';
+import {createNamedError, parseJSON} from '../util.js';
+import {calculateJwkThumbprint} from 'jose';
+import {decryptAnnexCResponse} from './mdl.js';
+import {decrypt as jwtDecrypt} from './jwt.js';
+
+// start of JSON object, array, or string
+const VP_TOKEN_JSON_PREFIXES = new Set(['{', '[', '"']);
 
 // parses (and decrypts) an authz response from a response body object
 export async function parseAuthorizationResponse({
   body = {},
-  supportedResponseModes = ['direct_post.jwt', 'direct_post'],
-  getDecryptParameters
+  getDecryptParameters,
+  authorizationRequest,
+  // only used if `authorizationRequest.response_mode` is not set, otherwise
+  // the response must match the authz request's response mode
+  supportedResponseModes = [
+    'direct_post.jwt', 'direct_post', 'dc_api.jwt', 'dc_api'
+  ]
 }) {
   let responseMode;
   const parsed = {};
+  let vpTokenMediaType = 'application/octet-stream';
   let payload;
   let protectedHeader;
+  let recipientPublicJwk;
 
-  supportedResponseModes = new Set(supportedResponseModes);
+  supportedResponseModes = new Set(authorizationRequest?.response_mode ?
+    [authorizationRequest.response_mode] : supportedResponseModes);
 
   if(body.response) {
-    // `body.response` is present which must contain an encrypted JWT
-    responseMode = 'direct_post.jwt';
+    // `body.response` is present which must contain an encrypted JWT;
+    // response mode can also be `dc_api.jwt` here, but distinction can only
+    // be made if `authorizationRequest` was passed
+    responseMode = authorizationRequest?.response_mode === 'dc_api.jwt' ?
+      'dc_api.jwt' : 'direct_post.jwt';
     _assertSupportedResponseMode({responseMode, supportedResponseModes});
     const jwt = body.response;
     ({
       payload,
-      protectedHeader
-    } = await _decrypt({jwt, getDecryptParameters}));
+      protectedHeader,
+      recipientPublicJwk
+    } = await jwtDecrypt({jwt, getDecryptParameters}));
     parsed.presentationSubmission = payload.presentation_submission;
+  } else if(body.Response) {
+    // ISO 18013-7 Annex C, with hpke-encrypted payload
+    responseMode = 'dc_api';
+    _assertSupportedResponseMode({responseMode, supportedResponseModes});
+    const base64urlEncryptedResponse = body.Response;
+    ({pt: payload, recipientPublicJwk} = await decryptAnnexCResponse({
+      base64urlEncryptedResponse, getDecryptParameters
+    }));
+    // normalize payload to base64url-encoded mDL device response
+    parsed.vpToken = base64url.encode(payload);
+    vpTokenMediaType = 'application/mdl-vp-token';
   } else {
     responseMode = 'direct_post';
     _assertSupportedResponseMode({responseMode, supportedResponseModes});
     payload = body;
-    parsed.presentationSubmission = parseJSON(
-      payload.presentation_submission, 'presentation_submission');
+    if(payload.presentation_submission) {
+      parsed.presentationSubmission = parseJSON(
+        payload.presentation_submission, 'presentation_submission');
+    }
   }
 
-  // `vp_token` is either:
-  // 1. a JSON object (a VP)
-  // 2. a JSON array (of something)
-  // 3. a JSON string (a quoted JWT: "<JWT>")
-  // 4. a JWT
-  // 5. a base64url-encoded mDL device response
-  // 6. unknown
-  const {vp_token} = payload;
-  if(typeof vp_token === 'string' &&
-    (vp_token.startsWith('{') || vp_token.startsWith('[') ||
-    vp_token.startsWith('"'))) {
-    parsed.vpToken = parseJSON(vp_token, 'vp_token');
-  } else {
-    parsed.vpToken = vp_token;
+  // if payload is set but not a Uint8Array (ISO 18013-7 Annex C case)...
+  if(payload && !(payload instanceof Uint8Array)) {
+    // `vp_token` is either:
+    // 1. a JSON object (a VP)
+    // 2. a JSON array (of something; unknown media type)
+    // 3. a JSON string (a quoted JWT: "<JWT>")
+    // 4. a JWT (starts with 'ey'...)
+    // 5. a base64url-encoded mDL device response
+    // 6. unknown
+    const {vp_token} = payload;
+    if(typeof vp_token === 'string') {
+      if(VP_TOKEN_JSON_PREFIXES.has(vp_token[0])) {
+        // cases: 1-3 - JSON
+        parsed.vpToken = parseJSON(vp_token, 'vp_token');
+        if(typeof parsed.vpToken === 'string') {
+          vpTokenMediaType = 'application/jwt';
+        } else if(!Array.isArray(parsed.vpToken)) {
+          vpTokenMediaType = 'application/vp';
+        }
+      } else {
+        // cases 4-5: JWT or mDL device response
+        parsed.vpToken = vp_token;
+        // if does not look like a JWT, assume mDL device response
+        vpTokenMediaType = vp_token.startsWith('ey') ?
+          'application/jwt' : 'application/mdl-vp-token';
+      }
+    } else {
+      // unknown case
+      parsed.vpToken = vp_token;
+    }
   }
 
-  return {responseMode, parsed, payload, protectedHeader};
+  // calculate JWK thumbprint for recipient public key, if any
+  let recipientPublicJwkThumbprint;
+  if(recipientPublicJwk) {
+    recipientPublicJwkThumbprint = await calculateJwkThumbprint(
+      recipientPublicJwk);
+  }
+
+  return {
+    responseMode, parsed, payload, protectedHeader,
+    recipientPublicJwk, recipientPublicJwkThumbprint,
+    vpTokenMediaType
+  };
 }
 
 function _assertSupportedResponseMode({
@@ -60,43 +118,8 @@ function _assertSupportedResponseMode({
   if(!supportedResponseModes.has(responseMode)) {
     throw createNamedError({
       message: `Unsupported response mode "${responseMode}".`,
-      name: 'NotSupportedError'
+      name: 'NotSupportedError',
+      details: {httpStatusCode: 400, public: true}
     });
   }
 }
-
-async function _decrypt({jwt, getDecryptParameters}) {
-  if(typeof getDecryptParameters !== 'function') {
-    throw new TypeError(
-      '"getDecryptParameters" is required for "direct_post.jwt" ' +
-      'response mode.');
-  }
-
-  const params = await getDecryptParameters({jwt});
-  const {keys} = params;
-  let {getKey} = params;
-  if(!getKey) {
-    // note: `jose` lib's JWK key set feature cannot be used and passed to
-    // `jwtDecrypt()` as the second parameter because the expected `alg`
-    // "ECDH-ES" is not a unsupported algorithm for selecting a key from a set
-    getKey = protectedHeader => {
-      if(protectedHeader.alg !== 'ECDH-ES') {
-        const error = createNamedError({
-          message: `Unsupported algorithm "${protectedHeader.alg}"; ` +
-            'algorithm must be "ECDH-ES".',
-          name: 'NotSupportedError',
-          details: {httpStatusCode: 400, public: true}
-        });
-        throw error;
-      }
-      const jwk = selectJwk({keys, kid: protectedHeader.kid});
-      return importJWK(jwk, 'ECDH-ES');
-    };
-  }
-
-  return jwtDecrypt(jwt, getKey, {
-    // only supported algorithms at this time:
-    contentEncryptionAlgorithms: ['A256GCM', 'A128GCM'],
-    keyManagementAlgorithms: ['ECDH-ES']
-  });
-}

package/lib/query/presentationExchange.js

@@ -6,6 +6,7 @@ import {exampleToJsonPointerMap} from './queryByExample.js';
 import {JSONPath} from 'jsonpath-plus';
 import jsonpointer from 'json-pointer';
 
+const MDOC_MDL = 'org.iso.18013.5.1.mDL';
 const VALUE_TYPES = new Set(['string', 'number', 'boolean']);
 const SUPPORTED_JWT_ALGS = ['EdDSA', 'Ed25519', 'ES256', 'ES384'];
 
@@ -98,6 +99,15 @@ export function vprGroupsToPresentationDefinition({
           };
           acceptsVcJwt = true;
         }
+        if(envelopes?.includes('application/mdl') ||
+          envelopes?.includes('application/mdoc')) {
+          inputDescriptor.format.mso_mdoc = {};
+          // `inputDescriptor` MUST be `org.iso.18013.5.1.mDL` for an mDL
+          // query for ecosystem compatibility
+          if(envelopes?.includes('application/mdl')) {
+            inputDescriptor.id = MDOC_MDL;
+          }
+        }
         if(cryptosuites?.length > 0) {
           inputDescriptor.format.ldp_vc = {
             proof_type: cryptosuites

package/lib/util.js

@@ -60,6 +60,48 @@ export function fetchJSON({url, agent} = {}) {
   return httpClient.get(url, fetchOptions);
 }
 
+// only supports keys used w/mDL at this time
+export function jwkToCoseKey({jwk} = {}) {
+  if(!(jwk.kty === 'EC' && (jwk.crv === 'P-256' || jwk.crv === 'P-384'))) {
+    throw new Error(
+      'Unknown supported JWK for mDL encryption; ' +
+      'only EC P-256 or P-384 are accepted.');
+  }
+
+  // https://datatracker.ietf.org/doc/html/rfc9053
+  return {
+    // `kty`; only types supported for mDL:
+    // `EC2` 2
+    1: 2,
+    // `crv`; only curves supported for mDL:
+    // `P-256` 1
+    // `P-384` 2
+    '-1': jwk.crv === 'P-256' ? 1 : 2,
+    // `x`
+    '-2': base64url.decode(jwk.x),
+    // `y`
+    '-3': base64url.decode(jwk.y)
+  };
+}
+
+export function coseKeyToJwk({coseKey} = {}) {
+  const {1: kty, '-1': crv, '-2': x, '-3': y} = coseKey;
+
+  if(!(kty === 'EC' && (crv === 'P-256' || crv === 'P-384'))) {
+    throw new Error(
+      'Unknown supported COSE key for mDL decryption; ' +
+      'only EC P-256 or P-384 are accepted.');
+  }
+
+  // https://datatracker.ietf.org/doc/html/rfc9053
+  return {
+    kty,
+    crv,
+    x: base64url.encode(x),
+    y: base64url.encode(y)
+  };
+}
+
 export function parseJSON(x, name) {
   try {
     return JSON.parse(x);
@@ -73,7 +115,9 @@ export function parseJSON(x, name) {
   }
 }
 
-export function selectJwk({keys, kid, alg, kty, crv, use} = {}) {
+export function selectJwk({
+  keys, kid, alg, kty, crv, use, x, y
+} = {}) {
   /* Example JWKs "keys":
   "jwks": {
     "keys": [
@@ -103,16 +147,21 @@ export function selectJwk({keys, kid, alg, kty, crv, use} = {}) {
     const kty1 = kty ?? jwk.kty;
     const crv1 = crv ?? jwk.crv;
     const use1 = use ?? jwk.use;
+    const x1 = x ?? jwk.x;
+    const y1 = y ?? jwk.y;
     const {
       // default missing `alg` value in `jwk` to search value
       alg: alg2 = alg1,
       kty: kty2,
       crv: crv2,
       // default missing `use` value in `jwk` to search value
-      use: use2 = use1
+      use: use2 = use1,
+      x: x2,
+      y: y2
     } = jwk;
     // return if `jwk` matches computed values
-    return alg1 === alg2 && kty1 === kty2 && crv1 === crv2 && use1 === use2;
+    return alg1 === alg2 && kty1 === kty2 && crv1 === crv2 && use1 === use2 &&
+      x1 == x2 && y1 === y2;
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalbazaar/oid4-client",
-  "version": "5.7.2",
+  "version": "5.8.0",
   "description": "An OID4 (VC + VP) client",
   "homepage": "https://github.com/digitalbazaar/oid4-client",
   "author": {
@@ -24,7 +24,9 @@
   ],
   "dependencies": {
     "@digitalbazaar/http-client": "^4.0.0",
+    "@hpke/core": "^1.7.5",
     "base64url-universal": "^2.0.0",
+    "cborg": "^4.5.8",
     "jose": "^6.1.0",
     "json-pointer": "^0.6.2",
     "jsonpath-plus": "^10.3.0",