@digitalbazaar/oid4-client 5.1.0 → 5.2.0

package/lib/OID4Client.js

@@ -1,8 +1,10 @@
 /*!
- * Copyright (c) 2022-2024 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
  */
-import {generateDIDProofJWT, robustDiscoverIssuer} from './util.js';
+import {createCredentialRequestsFromOffer} from './oid4vci/credentialOffer.js';
+import {generateDIDProofJWT} from './oid4vci/proofs.js';
 import {httpClient} from '@digitalbazaar/http-client';
+import {robustDiscoverIssuer} from './oid4vci/discovery.js';
 
 const GRANT_TYPES = new Map([
   ['preAuthorizedCode', 'urn:ietf:params:oauth:grant-type:pre-authorized_code']
@@ -66,7 +68,7 @@ export class OID4Client {
       if(!offer) {
         throw new TypeError('"credentialDefinition" must be an object.');
       }
-      requests = _createCredentialRequestsFromOffer({
+      requests = createCredentialRequestsFromOffer({
         issuerConfig, offer, format
       });
       if(requests.length > 1) {
@@ -97,7 +99,7 @@ export class OID4Client {
 
     const {issuerConfig, offer} = this;
     if(requests === undefined && offer) {
-      requests = _createCredentialRequestsFromOffer({
+      requests = createCredentialRequestsFromOffer({
         issuerConfig, offer, format
       });
     } else if(!(Array.isArray(requests) && requests.length > 0)) {
@@ -464,73 +466,3 @@ function _isPresentationRequired(error) {
   const errorType = error.data?.error;
   return error.status === 400 && errorType === 'presentation_required';
 }
-
-function _createCredentialRequestsFromOffer({
-  issuerConfig, offer, format
-}) {
-  // get any supported credential configurations from issuer config
-  const supported = _createSupportedCredentialsMap({issuerConfig});
-
-  // build requests from credentials identified in `offer` and remove any
-  // that do not match the given format
-  const credentials = offer.credential_configuration_ids ?? offer.credentials;
-  const requests = credentials.map(c => {
-    if(typeof c === 'string') {
-      // use supported credential config
-      return _getSupportedCredentialById({id: c, supported});
-    }
-    return c;
-  }).filter(r => r.format === format);
-
-  if(requests.length === 0) {
-    throw new Error(
-      `No supported credential(s) with format "${format}" found.`);
-  }
-
-  return requests;
-}
-
-function _createSupportedCredentialsMap({issuerConfig}) {
-  const {
-    credential_configurations_supported,
-    credentials_supported
-  } = issuerConfig;
-
-  let supported;
-  if(credential_configurations_supported &&
-    typeof credential_configurations_supported === 'object') {
-    supported = new Map(Object.entries(
-      issuerConfig.credential_configurations_supported));
-  } else if(Array.isArray(credentials_supported)) {
-    // handle legacy `credentials_supported` array
-    supported = new Map();
-    for(const entry of issuerConfig.credentials_supported) {
-      supported.set(entry.id, entry);
-    }
-  } else {
-    // no supported credentials from issuer config
-    supported = new Map();
-  }
-
-  return supported;
-}
-
-function _getSupportedCredentialById({id, supported}) {
-  const meta = supported.get(id);
-  if(!meta) {
-    throw new Error(`No supported credential "${id}" found.`);
-  }
-  const {format, credential_definition} = meta;
-  if(typeof format !== 'string') {
-    throw new Error(
-      `Invalid supported credential "${id}"; "format" not specified.`);
-  }
-  if(!(Array.isArray(credential_definition?.['@context']) &&
-    (Array.isArray(credential_definition?.types) ||
-    Array.isArray(credential_definition?.type)))) {
-    throw new Error(
-      `Invalid supported credential "${id}"; "credential_definition" not ` +
-      'fully specified.');
-  }
-  return {format, credential_definition};
-}

package/lib/convert/index.js

@@ -0,0 +1,349 @@
+/*!
+ * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {dcqlQueryToVprGroups, vprGroupsToDcqlQuery} from '../query/dcql.js';
+import {
+  presentationDefinitionToVprGroups,
+  vprGroupsToPresentationDefinition
+} from '../query/presentationExchange.js';
+import {
+  validate as validateAuthorizationRequest
+} from '../oid4vp/authorizationRequest.js';
+
+// backwards compatible exports
+export {
+  pathsToVerifiableCredentialPointers
+} from '../query/presentationExchange.js';
+
+// currently supported VPR query types for conversion
+const DID_AUTHENTICATION = 'DIDAuthentication';
+const QUERY_BY_EXAMPLE = 'QueryByExample';
+const DCQL = 'DigitalCredentialQueryLanguage';
+const CONVERTIBLE_QUERY_TYPES = new Set([
+  QUERY_BY_EXAMPLE, DID_AUTHENTICATION, DCQL
+]);
+
+// converts a VPR to partial "authorization request"
+export function fromVpr({
+  verifiablePresentationRequest,
+  strict = false,
+  queryFormats = {
+    // can replace `true` with options:
+    // e.g., dcql options: {nullifyArrayIndices: true}
+    dcql: true,
+    presentationExchange: true
+  },
+  // presentation exchange (deprecated) options:
+  prefixJwtVcPath,
+  // authorization request options (`false` for backwards compatibility, use
+  // `true` for OID4VP 1.0+)
+  useClientIdPrefix = false
+} = {}) {
+  try {
+    if(!(queryFormats?.dcql || queryFormats?.presentationExchange)) {
+      throw new Error(
+        'At least one of "queryFormats.dcql" or ' +
+        '"queryFormats.presentationExchange" is required.');
+    }
+
+    // convert to query groups structure for processing
+    const groupMap = _vprQueryToGroups({verifiablePresentationRequest});
+    if(strict) {
+      _strictCheckVprGroups({groupMap, queryFormats});
+    }
+
+    // core authz request
+    const authorizationRequest = {
+      response_type: 'vp_token',
+      // default to `direct_post`; caller can override
+      response_mode: 'direct_post'
+    };
+    // include requested authn params
+    if(verifiablePresentationRequest.domain) {
+      // since a `domain` was provided, set these defaults:
+      authorizationRequest.client_id = verifiablePresentationRequest.domain;
+      authorizationRequest.response_uri = authorizationRequest.client_id;
+      if(useClientIdPrefix) {
+        authorizationRequest.client_id =
+          `redirect_uri:${authorizationRequest.client_id}`;
+      } else {
+        authorizationRequest.client_id_scheme = 'redirect_uri';
+      }
+    }
+    if(verifiablePresentationRequest.challenge) {
+      authorizationRequest.nonce = verifiablePresentationRequest.challenge;
+    }
+    // only a single `DIDAuthentication` query is supported at this time; use
+    // the last one
+    const didAuthnQuery = [...groupMap.values()]
+      .filter(g => g.has(DID_AUTHENTICATION))
+      .map(g => g.get(DID_AUTHENTICATION))
+      .at(-1);
+    if(didAuthnQuery) {
+      const [query] = didAuthnQuery;
+      const client_metadata = _fromDIDAuthenticationQuery({query, strict});
+      if(client_metadata) {
+        authorizationRequest.client_metadata = client_metadata;
+      }
+    }
+
+    // add credential queries
+    if(queryFormats?.dcql) {
+      const dcql_query = vprGroupsToDcqlQuery({
+        groupMap, options: queryFormats.dcql === true ? {} : queryFormats.dcql
+      });
+      if(dcql_query) {
+        authorizationRequest.dcql_query = dcql_query;
+      }
+    }
+    if(queryFormats?.presentationExchange) {
+      const presentation_definition = vprGroupsToPresentationDefinition({
+        groupMap, prefixJwtVcPath
+      });
+      if(presentation_definition) {
+        authorizationRequest.presentation_definition = presentation_definition;
+      }
+    }
+
+    return authorizationRequest;
+  } catch(cause) {
+    const error = new Error(
+      'Could not convert verifiable presentation request to ' +
+      'an OID4VP authorization request.', {cause});
+    error.name = 'OperationError';
+    throw error;
+  }
+}
+
+// converts an OID4VP authorization request (including its
+// "presentation definition") to a VPR
+export function toVpr({authorizationRequest, strict = false} = {}) {
+  try {
+    // ensure authorization request is valid
+    validateAuthorizationRequest({authorizationRequest});
+
+    const {
+      client_id,
+      client_metadata,
+      dcql_query,
+      nonce,
+      presentation_definition,
+      response_uri
+    } = authorizationRequest;
+
+    // disallow unsupported `submission_requirements` in strict mode
+    if(strict && presentation_definition.submission_requirements) {
+      const error = new Error('"submission_requirements" is not supported.');
+      error.name = 'NotSupportedError';
+      throw error;
+    }
+
+    // generate base VPR from presentation definition
+    const verifiablePresentationRequest = {};
+
+    let didAuthnQuery;
+    if(client_metadata) {
+      didAuthnQuery = _toDIDAuthenticationQuery({client_metadata, strict});
+    }
+
+    // prefer conversion from DCQL query over presentation exchange
+    let groupMap;
+    if(dcql_query) {
+      groupMap = dcqlQueryToVprGroups({dcql_query});
+    } else if(presentation_definition) {
+      groupMap = presentationDefinitionToVprGroups({
+        presentation_definition, strict
+      });
+    }
+    if(groupMap?.size > 0) {
+      verifiablePresentationRequest.query = _vprGroupsToQuery({groupMap});
+
+      // clone `DIDAuthentication` query for every query group
+      if(didAuthnQuery) {
+        for(const groupId of groupMap.keys()) {
+          verifiablePresentationRequest.query.push(groupId === undefined ?
+            didAuthnQuery : {
+              ...structuredClone(didAuthnQuery),
+              group: groupId
+            });
+        }
+      }
+    } else if(didAuthnQuery) {
+      // add `DIDAuthentication` query once
+      verifiablePresentationRequest.query = [didAuthnQuery];
+    }
+
+    // map `response_uri` or `client_id` to `domain`
+    if(response_uri !== undefined || client_id !== undefined) {
+      verifiablePresentationRequest.domain = response_uri ?? client_id;
+    }
+
+    // map `nonce` to `challenge`
+    if(nonce !== undefined) {
+      verifiablePresentationRequest.challenge = nonce;
+    }
+
+    return {verifiablePresentationRequest};
+  } catch(cause) {
+    const error = new Error(
+      'Could not convert OID4VP authorization request to ' +
+      'verifiable presentation request.', {cause});
+    error.name = 'OperationError';
+    throw error;
+  }
+}
+
+function _strictCheckVprGroups({groupMap, queryFormats}) {
+  const groups = [...groupMap.values()];
+  let didAuthenticationCount = 0;
+  let queryByExampleCount = 0;
+  let dcqlCount = 0;
+  for(const group of groups) {
+    for(const type of group.keys()) {
+      if(!CONVERTIBLE_QUERY_TYPES.has(type)) {
+        const error = new Error(
+          'Query type not convertible at this time; supported query types ' +
+          `are: ${[...CONVERTIBLE_QUERY_TYPES].join(', ')}`);
+        error.name = 'NotSupportedError';
+        throw error;
+      }
+      if(type === DID_AUTHENTICATION) {
+        didAuthenticationCount++;
+      } else if(type === QUERY_BY_EXAMPLE) {
+        queryByExampleCount++;
+      } else if(type === DCQL) {
+        dcqlCount++;
+      }
+    }
+  }
+
+  // multiple DCQL queries are not supported; there should be a single group ID
+  // with a single DCQL query (or none at all)
+  if(dcqlCount > 1) {
+    const error = new Error(
+      `Multiple VPR "${DCQL}" queries are not supported.`);
+    error.name = 'NotSupportedError';
+    throw error;
+  }
+
+  // if presentation exchange output is expected, then only one
+  // `QueryByExample` is supported
+  if(queryFormats?.presentationExchange && queryByExampleCount > 1) {
+    const error = new Error(
+      `Multiple VPR "${QUERY_BY_EXAMPLE}" queries are not supported when ` +
+      'strictly converting to presentation exchange.');
+    error.name = 'NotSupportedError';
+    throw error;
+  }
+
+  // only one `DIDAuthentication` query is supported
+  if(didAuthenticationCount > 1) {
+    const error = new Error(
+      `Multiple VPR "${DID_AUTHENTICATION}" queries are not supported when ` +
+      'strictly converting to an OID4VP Authorization Request.');
+    error.name = 'NotSupportedError';
+    throw error;
+  }
+
+  // there must be at least one convertible type; DCQL is only acceptable
+  const convertibleCount = queryByExampleCount + didAuthenticationCount +
+    (queryFormats.dcql ? dcqlCount : 0);
+
+  // there must be at least one convertible type
+  if(convertibleCount === 0) {
+    const error = new Error(`No convertible query types found.`);
+    error.name = 'NotSupportedError';
+    throw error;
+  }
+}
+
+function _fromDIDAuthenticationQuery({query, strict = false}) {
+  const cryptosuites = query.acceptedCryptosuites?.map(
+    ({cryptosuite}) => cryptosuite);
+  if(!(cryptosuites?.length > 0)) {
+    if(strict) {
+      const error = new Error(
+        '"query.acceptedCryptosuites" must be a non-array with specified ' +
+        `cryptosuites to convert from a "${DID_AUTHENTICATION}" query.`);
+      error.name = 'NotSupportedError';
+      throw error;
+    }
+    return;
+  }
+  const client_metadata = {
+    require_signed_request_object: false,
+    vp_formats: {
+      ldp_vp: {
+        proof_type: cryptosuites
+      }
+    },
+    vp_formats_supported: {
+      ldp_vc: {
+        proof_type_values: ['DataIntegrityProof']
+      },
+      cryptosuite_values: cryptosuites
+    }
+  };
+  // compatibility with legacy cryptosuite
+  if(cryptosuites.includes('Ed25519Signature2020')) {
+    client_metadata.vp_formats.supported.ldp_vc
+      .proof_type_values.push('Ed25519Signature2020');
+  }
+
+  return client_metadata;
+}
+
+function _toDIDAuthenticationQuery({client_metadata, strict = false}) {
+  const {vp_formats_supported, vp_formats} = client_metadata;
+  const proofTypes = vp_formats_supported?.ldp_vc?.cryptosuite_values ??
+    vp_formats?.ldp_vp?.proof_type;
+  if(!Array.isArray(proofTypes)) {
+    if(strict) {
+      const error = new Error(
+        '"client_metadata.vp_formats.ldp_vp.proof_type" must be an array to ' +
+        `convert to "${DID_AUTHENTICATION}" query.`);
+      error.name = 'NotSupportedError';
+      throw error;
+    }
+    return;
+  }
+  return {
+    type: DID_AUTHENTICATION,
+    acceptedCryptosuites: proofTypes.map(cryptosuite => ({cryptosuite}))
+  };
+}
+
+function _vprGroupsToQuery({groupMap}) {
+  const query = [];
+  for(const group of groupMap.values()) {
+    query.push(...[...group.values()].flat());
+  }
+  return query;
+}
+
+function _vprQueryToGroups({verifiablePresentationRequest}) {
+  // normalize queries into groups, each group ID defines a different "OR"
+  // condition, the same group ID defines an "AND" group; the group ID
+  // `undefined` is used when no group is present (every `undefined` group is
+  // the same "AND" group)
+  const groups = new Map();
+  let {query} = verifiablePresentationRequest;
+  if(!Array.isArray(query)) {
+    query = [query];
+  }
+  for(const q of query) {
+    // each group is a map of query type => queries
+    let group = groups.get(q?.group);
+    if(!group) {
+      group = new Map();
+      groups.set(q?.group, group);
+    }
+    const queries = group.get(q?.type);
+    if(queries) {
+      queries.push(q);
+    } else {
+      group.set(q?.type, [q]);
+    }
+  }
+  return groups;
+}

package/lib/index.js

@@ -1,14 +1,19 @@
 /*!
  * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
  */
-export * as oid4vp from './oid4vp.js';
+export * as oid4vp from './oid4vp/index.js';
+export * as query from './query/index.js';
 export {
   discoverIssuer,
-  generateDIDProofJWT,
+  robustDiscoverIssuer
+} from './oid4vci/discovery.js';
+export {
   getCredentialOffer,
-  parseCredentialOfferUrl,
-  robustDiscoverIssuer,
+  parseCredentialOfferUrl
+} from './oid4vci/credentialOffer.js';
+export {
   signJWT,
   selectJwk
 } from './util.js';
+export {generateDIDProofJWT} from './oid4vci/proofs.js';
 export {OID4Client} from './OID4Client.js';

package/lib/oid4vci/credentialOffer.js

@@ -0,0 +1,138 @@
+/*!
+ * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {assert, fetchJSON} from '../util.js';
+
+export function createCredentialRequestsFromOffer({
+  issuerConfig, offer, format
+} = {}) {
+  // get any supported credential configurations from issuer config
+  const supported = _createSupportedCredentialsMap({issuerConfig});
+
+  // build requests from credentials identified in `offer` and remove any
+  // that do not match the given format
+  const credentials = offer.credential_configuration_ids ?? offer.credentials;
+  const requests = credentials.map(c => {
+    if(typeof c === 'string') {
+      // use supported credential config
+      return _getSupportedCredentialById({id: c, supported});
+    }
+    return c;
+  }).filter(r => r.format === format);
+
+  if(requests.length === 0) {
+    throw new Error(
+      `No supported credential(s) with format "${format}" found.`);
+  }
+
+  return requests;
+}
+
+export async function getCredentialOffer({url, agent} = {}) {
+  const {protocol, searchParams} = new URL(url);
+  if(protocol !== 'openid-credential-offer:') {
+    throw new SyntaxError(
+      '"url" must express a URL with the ' +
+      '"openid-credential-offer" protocol.');
+  }
+  const offer = searchParams.get('credential_offer');
+  if(offer) {
+    return JSON.parse(offer);
+  }
+
+  // try to fetch offer from URL
+  const offerUrl = searchParams.get('credential_offer_uri');
+  if(!offerUrl) {
+    throw new SyntaxError(
+      'OID4VCI credential offer must have "credential_offer" or ' +
+      '"credential_offer_uri".');
+  }
+
+  if(!offerUrl.startsWith('https://')) {
+    const error = new Error(
+      `"credential_offer_uri" (${offerUrl}) must start with "https://".`);
+    error.name = 'NotSupportedError';
+    throw error;
+  }
+
+  const response = await fetchJSON({url: offerUrl, agent});
+  if(!response.data) {
+    const error = new Error(
+      `Credential offer fetched from "${offerUrl}" is not JSON.`);
+    error.name = 'DataError';
+    throw error;
+  }
+  return response.data;
+}
+
+export function parseCredentialOfferUrl({url} = {}) {
+  assert(url, 'url', 'string');
+
+  /* Parse URL, e.g.:
+
+  'openid-credential-offer://?' +
+    'credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2F' +
+    'localhost%3A18443%2Fexchangers%2Fz19t8xb568tNRD1zVm9R5diXR%2F' +
+    'exchanges%2Fz1ADs3ur2s9tm6JUW6CnTiyn3%22%2C%22credentials' +
+    '%22%3A%5B%7B%22format%22%3A%22ldp_vc%22%2C%22credential_definition' +
+    '%22%3A%7B%22%40context%22%3A%5B%22https%3A%2F%2Fwww.w3.org%2F2018%2F' +
+    'credentials%2Fv1%22%2C%22https%3A%2F%2Fwww.w3.org%2F2018%2F' +
+    'credentials%2Fexamples%2Fv1%22%5D%2C%22type%22%3A%5B%22' +
+    'VerifiableCredential%22%2C%22UniversityDegreeCredential' +
+    '%22%5D%7D%7D%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams' +
+    '%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22' +
+    'pre-authorized_code%22%3A%22z1AEvnk2cqeRM1Mfv75vzHSUo%22%7D%7D%7D';
+  */
+  const {protocol, searchParams} = new URL(url);
+  if(protocol !== 'openid-credential-offer:') {
+    throw new SyntaxError(
+      '"url" must express a URL with the ' +
+      '"openid-credential-offer" protocol.');
+  }
+  return JSON.parse(searchParams.get('credential_offer'));
+}
+
+function _createSupportedCredentialsMap({issuerConfig}) {
+  const {
+    credential_configurations_supported,
+    credentials_supported
+  } = issuerConfig;
+
+  let supported;
+  if(credential_configurations_supported &&
+    typeof credential_configurations_supported === 'object') {
+    supported = new Map(Object.entries(
+      issuerConfig.credential_configurations_supported));
+  } else if(Array.isArray(credentials_supported)) {
+    // handle legacy `credentials_supported` array
+    supported = new Map();
+    for(const entry of issuerConfig.credentials_supported) {
+      supported.set(entry.id, entry);
+    }
+  } else {
+    // no supported credentials from issuer config
+    supported = new Map();
+  }
+
+  return supported;
+}
+
+function _getSupportedCredentialById({id, supported}) {
+  const meta = supported.get(id);
+  if(!meta) {
+    throw new Error(`No supported credential "${id}" found.`);
+  }
+  const {format, credential_definition} = meta;
+  if(typeof format !== 'string') {
+    throw new Error(
+      `Invalid supported credential "${id}"; "format" not specified.`);
+  }
+  if(!(Array.isArray(credential_definition?.['@context']) &&
+    (Array.isArray(credential_definition?.types) ||
+    Array.isArray(credential_definition?.type)))) {
+    throw new Error(
+      `Invalid supported credential "${id}"; "credential_definition" not ` +
+      'fully specified.');
+  }
+  return {format, credential_definition};
+}