@digitalbazaar/oid4-client 5.1.0 → 5.2.1

package/lib/oid4vci/discovery.js

@@ -0,0 +1,126 @@
+/*!
+ * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {assert, fetchJSON} from '../util.js';
+
+const WELL_KNOWN_REGEX = /\/\.well-known\/([^\/]+)/;
+
+export async function discoverIssuer({issuerConfigUrl, agent} = {}) {
+  try {
+    assert(issuerConfigUrl, 'issuerConfigUrl', 'string');
+
+    const response = await fetchJSON({url: issuerConfigUrl, agent});
+    if(!response.data) {
+      const error = new Error('Issuer configuration format is not JSON.');
+      error.name = 'DataError';
+      throw error;
+    }
+    const {data: issuerMetaData} = response;
+    const {issuer, authorization_server} = issuerMetaData;
+
+    if(authorization_server && authorization_server !== issuer) {
+      // not yet implemented
+      throw new Error('Separate authorization server not yet implemented.');
+    }
+
+    // validate `issuer`
+    if(!(typeof issuer === 'string' && issuer.startsWith('https://'))) {
+      const error = new Error('"issuer" is not an HTTPS URL.');
+      error.name = 'DataError';
+      throw error;
+    }
+
+    // ensure `credential_issuer` matches `issuer`, if present
+    const {credential_issuer} = issuerMetaData;
+    if(credential_issuer !== undefined && credential_issuer !== issuer) {
+      const error = new Error('"credential_issuer" must match "issuer".');
+      error.name = 'DataError';
+      throw error;
+    }
+
+    /* Validate `issuer` value against `issuerConfigUrl` (per RFC 8414):
+
+    The `origin` and `path` element must be parsed from `issuer` and checked
+    against `issuerConfigUrl` like so:
+
+    For issuer `<origin>` (no path), `issuerConfigUrl` must match:
+    `<origin>/.well-known/<any-path-segment>`
+
+    For issuer `<origin><path>`, `issuerConfigUrl` must be:
+    `<origin>/.well-known/<any-path-segment><path>` */
+    const {pathname: wellKnownPath} = new URL(issuerConfigUrl);
+    const anyPathSegment = wellKnownPath.match(WELL_KNOWN_REGEX)[1];
+    const {origin, pathname} = new URL(issuer);
+    let expectedConfigUrl = `${origin}/.well-known/${anyPathSegment}`;
+    if(pathname !== '/') {
+      expectedConfigUrl += pathname;
+    }
+    if(issuerConfigUrl !== expectedConfigUrl) {
+      // alternatively, against RFC 8414, but according to OID4VCI, make sure
+      // the issuer config URL matches:
+      // <origin><path>/.well-known/<any-path-segment>
+      expectedConfigUrl = origin;
+      if(pathname !== '/') {
+        expectedConfigUrl += pathname;
+      }
+      expectedConfigUrl += `/.well-known/${anyPathSegment}`;
+      if(issuerConfigUrl !== expectedConfigUrl) {
+        const error = new Error('"issuer" does not match configuration URL.');
+        error.name = 'DataError';
+        throw error;
+      }
+    }
+
+    // fetch AS meta data
+    const asMetaDataUrl =
+      `${origin}/.well-known/oauth-authorization-server${pathname}`;
+    const asMetaDataResponse = await fetchJSON({url: asMetaDataUrl, agent});
+    if(!asMetaDataResponse.data) {
+      const error = new Error('Authorization server meta data is not JSON.');
+      error.name = 'DataError';
+      throw error;
+    }
+
+    const {data: asMetaData} = response;
+    // merge AS meta data into total issuer config
+    const issuerConfig = {...issuerMetaData, ...asMetaData};
+
+    // ensure `token_endpoint` is valid
+    const {token_endpoint} = asMetaData;
+    assert(token_endpoint, 'token_endpoint', 'string');
+
+    // return merged config and separate issuer and AS configs
+    const metadata = {issuer: issuerMetaData, authorizationServer: asMetaData};
+    return {issuerConfig, metadata};
+  } catch(cause) {
+    const error = new Error('Could not get OpenID issuer configuration.');
+    error.name = 'OperationError';
+    error.cause = cause;
+    throw error;
+  }
+}
+
+export async function robustDiscoverIssuer({issuer, agent} = {}) {
+  // try issuer config URLs based on OID4VCI (first) and RFC 8414 (second)
+  const parsedIssuer = new URL(issuer);
+  const {origin} = parsedIssuer;
+  const path = parsedIssuer.pathname === '/' ? '' : parsedIssuer.pathname;
+
+  const issuerConfigUrls = [
+    // OID4VCI
+    `${origin}${path}/.well-known/openid-credential-issuer`,
+    // RFC 8414
+    `${origin}/.well-known/openid-credential-issuer${path}`
+  ];
+
+  let error;
+  for(const issuerConfigUrl of issuerConfigUrls) {
+    try {
+      const config = await discoverIssuer({issuerConfigUrl, agent});
+      return config;
+    } catch(e) {
+      error = e;
+    }
+  }
+  throw error;
+}

package/lib/oid4vci/proofs.js

@@ -0,0 +1,50 @@
+/*!
+ * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {signJWT} from '../util.js';
+
+export async function generateDIDProofJWT({
+  signer, nonce, iss, aud, exp, nbf
+} = {}) {
+  /* Example:
+  {
+    "alg": "ES256",
+    "kid":"did:example:ebfeb1f712ebc6f1c276e12ec21/keys/1"
+  }.
+  {
+    "iss": "s6BhdRkqt3",
+    "aud": "https://server.example.com",
+    "iat": 1659145924,
+    "nonce": "tZignsnFbp"
+  }
+  */
+
+  if(exp === undefined) {
+    // default to 5 minute expiration time
+    exp = Math.floor(Date.now() / 1000) + 60 * 5;
+  }
+  if(nbf === undefined) {
+    // default to now
+    nbf = Math.floor(Date.now() / 1000);
+  }
+
+  const {id: kid} = signer;
+  const alg = _curveToAlg(signer.algorithm);
+  const payload = {nonce, iss, aud, exp, nbf};
+  const protectedHeader = {alg, kid};
+
+  return signJWT({payload, protectedHeader, signer});
+}
+
+function _curveToAlg(crv) {
+  if(crv === 'Ed25519' || crv === 'Ed448') {
+    return 'EdDSA';
+  }
+  if(crv?.startsWith('P-')) {
+    return `ES${crv.slice(2)}`;
+  }
+  if(crv === 'secp256k1') {
+    return 'ES256K';
+  }
+  return crv;
+}

package/lib/{authorizationRequest.js → oid4vp/authorizationRequest.js}

@@ -2,8 +2,9 @@
  * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
  */
 import {
-  assert, assertOptional, base64Encode, createNamedError, fetchJSON, selectJwk
-} from './util.js';
+  assert, assertOptional, base64Encode,
+  createNamedError, fetchJSON, selectJwk, sha256
+} from '../util.js';
 import {decodeJwt, importX509, jwtVerify} from 'jose';
 import {
   hasDomainSubjectAltName, parseCertificateChain, verifyCertificateChain
@@ -269,7 +270,7 @@ async function _checkClientIdSchemeRequirements({
       and it includes the client ID. */
     } else if(clientIdScheme === 'x509_hash') {
       // `x509_hash:<base64url sha256-hash of DER leaf cert>`
-      const hash = base64Encode(await _sha256(chain[0].toBER()));
+      const hash = base64Encode(await sha256(chain[0].toBER()));
       if(clientId !== hash) {
         throw createNamedError({
           message:
@@ -444,14 +445,6 @@ function _parseOID4VPUrl({url}) {
   return {authorizationRequest};
 }
 
-async function _sha256(data) {
-  if(typeof data === 'string') {
-    data = new TextEncoder().encode(data);
-  }
-  const algorithm = {name: 'SHA-256'};
-  return new Uint8Array(await crypto.subtle.digest(algorithm, data));
-}
-
 function _throwKeyNotFound(protectedHeader) {
   const error = new Error(
     'Could not verify signed authorization request; ' +

package/lib/{authorizationResponse.js → oid4vp/authorizationResponse.js}

@@ -1,11 +1,11 @@
 /*!
  * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
  */
-import {createNamedError, selectJwk} from './util.js';
+import {createNamedError, selectJwk} from '../util.js';
 import {EncryptJWT} from 'jose';
 import {httpClient} from '@digitalbazaar/http-client';
-import jsonpointer from 'jsonpointer';
-import {pathsToVerifiableCredentialPointers} from './convert.js';
+import {pathsToVerifiableCredentialPointers} from '../convert/index.js';
+import {resolvePointer} from '../query/util.js';
 
 const TEXT_ENCODER = new TextEncoder();
 
@@ -340,7 +340,7 @@ function _matchesInputDescriptor({
 
       // check for a value at at least one path
       for(const pointer of pointers) {
-        const existing = jsonpointer.get(verifiableCredential, pointer);
+        const existing = resolvePointer(verifiableCredential, pointer);
         if(existing === undefined) {
           // VC does not match
           return false;

package/lib/{oid4vp.js → oid4vp/index.js}

@@ -3,7 +3,7 @@
  */
 export * as authzRequest from './authorizationRequest.js';
 export * as authzResponse from './authorizationResponse.js';
-export * as convert from './convert.js';
+export * as convert from '../convert/index.js';
 export * as verifier from './verifier.js';
 
 // backwards compatibility APIs
@@ -14,11 +14,7 @@ export {
   createPresentationSubmission,
   send as sendAuthorizationResponse
 } from './authorizationResponse.js';
-export {
-  fromVpr, toVpr,
-  // exported for testing purposes only
-  _fromQueryByExampleQuery
-} from './convert.js';
+export {fromVpr, toVpr} from '../convert/index.js';
 
 // Note: for examples of presentation request and responses, see:
 // eslint-disable-next-line max-len

package/lib/{verifier.js → oid4vp/verifier.js}

@@ -1,7 +1,7 @@
 /*!
  * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
  */
-import {createNamedError, selectJwk} from './util.js';
+import {createNamedError, parseJSON, selectJwk} from '../util.js';
 import {importJWK, jwtDecrypt} from 'jose';
 
 // parses (and decrypts) an authz response from a response body object
@@ -31,7 +31,7 @@ export async function parseAuthorizationResponse({
     responseMode = 'direct_post';
     _assertSupportedResponseMode({responseMode, supportedResponseModes});
     payload = body;
-    parsed.presentationSubmission = _jsonParse(
+    parsed.presentationSubmission = parseJSON(
       payload.presentation_submission, 'presentation_submission');
   }
 
@@ -46,7 +46,7 @@ export async function parseAuthorizationResponse({
   if(typeof vp_token === 'string' &&
     (vp_token.startsWith('{') || vp_token.startsWith('[') ||
     vp_token.startsWith('"'))) {
-    parsed.vpToken = _jsonParse(vp_token, 'vp_token');
+    parsed.vpToken = parseJSON(vp_token, 'vp_token');
   } else {
     parsed.vpToken = vp_token;
   }
@@ -100,16 +100,3 @@ async function _decrypt({jwt, getDecryptParameters}) {
     keyManagementAlgorithms: ['ECDH-ES']
   });
 }
-
-function _jsonParse(x, name) {
-  try {
-    return JSON.parse(x);
-  } catch(cause) {
-    throw createNamedError({
-      message: `Could not parse "${name}".`,
-      name: 'DataError',
-      details: {httpStatusCode: 400, public: true},
-      cause
-    });
-  }
-}

package/lib/{x509.js → oid4vp/x509.js}

@@ -6,7 +6,7 @@ import {
   CertificateChainValidationEngine,
   id_SubjectAltName
 } from 'pkijs';
-import {base64Decode} from './util.js';
+import {base64Decode} from '../util.js';
 
 export function fromPemOrBase64(str) {
   const tag = 'CERTIFICATE';

package/lib/query/dcql.js

@@ -0,0 +1,244 @@
+/*!
+ * Copyright (c) 2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {
+  fromJsonPointerMap, isNumber, toJsonPointerMap, toNumberIfNumber
+} from './util.js';
+import {exampleToJsonPointerMap} from './queryByExample.js';
+import jsonpointer from 'json-pointer';
+
+const MDOC_MDL = 'org.iso.18013.5.1.mDL';
+
+export function dcqlQueryToVprGroups({dcql_query} = {}) {
+  const {credentials = []} = dcql_query;
+  let {credential_sets: credentialSets} = dcql_query;
+  if(!credentialSets) {
+    credentialSets = [{
+      options: [credentials.map(q => q.id)]
+    }];
+  }
+
+  // convert `credentials` into a map based on `ID`
+  const credentialQueryMap = new Map(credentials.map(
+    query => [query.id, query]));
+
+  // output group map
+  const groupMap = new Map();
+  for(const credentialSet of credentialSets) {
+    for(const option of credentialSet.options) {
+      const groupId = crypto.randomUUID();
+      const queries = option.map(id => {
+        const dcqlCredentialQuery = credentialQueryMap.get(id);
+        return {
+          type: 'QueryByExample',
+          group: groupId,
+          credentialQuery: _toQueryByExampleQuery({dcqlCredentialQuery})
+        };
+      });
+      groupMap.set(groupId, new Map([['QueryByExample', queries]]));
+    }
+  }
+  return groupMap;
+}
+
+export function dcqlCredentialQueryToJsonPointerMap({
+  dcqlCredentialQuery
+} = {}) {
+  const queryByExample = _toQueryByExampleQuery({dcqlCredentialQuery});
+  return exampleToJsonPointerMap(queryByExample);
+}
+
+export function vprGroupsToDcqlQuery({groupMap, options = {}} = {}) {
+  // if there is any DCQL query, return it as-is
+  const groups = [...groupMap.values()];
+  let dcqlQuery = groups
+    .filter(g => g.has('DigitalCredentialQueryLanguage'))
+    .map(g => g.get('DigitalCredentialQueryLanguage'))
+    .at(-1);
+  if(dcqlQuery) {
+    return dcqlQuery;
+  }
+
+  // convert all `QueryByExample` queries to a single DCQL query
+  const {nullyifyArrayIndices = false} = options;
+  dcqlQuery = {};
+  const credentials = [];
+  const credentialSets = [{options: []}];
+
+  // note: same group ID is logical "AND" and different group ID is "OR"
+  for(const queries of groups) {
+    // only `QueryByExample` is convertible
+    const queryByExamples = queries.get('QueryByExample');
+    if(!(queryByExamples?.length > 0)) {
+      continue;
+    }
+
+    // for each `QueryByExample`, add another option
+    const option = [];
+    for(const queryByExample of queryByExamples) {
+      // should only be one `credentialQuery` but handle each one as a new
+      // DCQL credential query
+      const all = Array.isArray(queryByExample.credentialQuery) ?
+        queryByExample.credentialQuery : [queryByExample.credentialQuery];
+      for(const credentialQuery of all) {
+        const result = _fromQueryByExampleQuery({
+          credentialQuery, nullyifyArrayIndices
+        });
+        credentials.push(result);
+        // DCQL credential set "option" includes all queries in the "AND" group
+        option.push(result.id);
+      }
+    }
+
+    // add "option" as another "OR" in the DCQL "options"
+    credentialSets[0].options.push(option);
+  }
+
+  if(credentials.length > 0) {
+    dcqlQuery.credentials = credentials;
+  }
+  if(credentialSets[0].options?.length > 0) {
+    dcqlQuery.credential_sets = credentialSets;
+  }
+
+  return dcqlQuery;
+}
+
+// exported for testing purposes only
+export function _fromQueryByExampleQuery({
+  credentialQuery, nullyifyArrayIndices = false
+}) {
+  const result = {
+    id: crypto.randomUUID(),
+    format: 'ldp_vc',
+    meta: {
+      type_values: ['https://www.w3.org/2018/credentials#VerifiableCredential']
+    }
+  };
+  if(credentialQuery?.reason) {
+    result.meta.reason = credentialQuery.reason;
+  }
+
+  const {example = {}} = credentialQuery ?? {};
+
+  // determine credential format
+  if(Array.isArray(credentialQuery.acceptedEnvelopes)) {
+    const set = new Set(credentialQuery.acceptedEnvelopes);
+    if(set.has('application/jwt')) {
+      result.format = 'jwt_vc_json';
+    } else if(set.has('application/mdl')) {
+      result.format = 'mso_mdoc';
+      result.meta = {doctype_value: MDOC_MDL};
+    } else if(set.has('application/dc+sd-jwt')) {
+      result.format = 'dc+sd-jwt';
+      result.meta = {vct_values: []};
+      if(Array.isArray(example?.type)) {
+        result.meta.vct_values.push(...example.type);
+      } else if(typeof example.type === 'string') {
+        result.meta.vct_values.push(example.type);
+      }
+    }
+  }
+
+  // convert `example` into json pointers and walk to produce DCQL claim paths
+  const pointers = toJsonPointerMap({obj: example, flat: true});
+  const pathsMap = new Map();
+  for(const [pointer, value] of pointers) {
+    // parse path into DCQL path w/ numbers for array indexes
+    let path = jsonpointer.parse(pointer).map(toNumberIfNumber);
+
+    // special process non-`@context` paths to convert some array indexes
+    // to DCQL `null` (which means "any" index)
+    if(path[0] !== '@context') {
+      if(nullyifyArrayIndices) {
+        // brute force convert every array index to `null` by request
+        path = path.map(p => isNumber(p) ? null : p);
+      } else if(isNumber(path.at(-1)) && !isNumber(path.at(-2))) {
+        // when a pointer terminates at an array element it means candidate
+        // matching values are expressed in the `example`, so make sure to
+        // share the path for all candidates
+        path[path.length - 1] = null;
+      }
+    }
+
+    // compile processed path back to a key to consolidate `values`
+    const key = jsonpointer.compile(path.map(p => p === null ? 'null' : p));
+
+    // create shared entry for path and candidate matching values
+    let entry = pathsMap.get(key);
+    if(!entry) {
+      entry = {path, valueSet: new Set()};
+      pathsMap.set(key, entry);
+    }
+
+    // add any non-QueryByExample-wildcard as a DCQL candidate match value
+    if(!(value === '' || value instanceof Map || value instanceof Set)) {
+      entry.valueSet.add(value);
+    }
+  }
+
+  // produce DCQL `claims`
+  const claims = [...pathsMap.values()].map(({path, valueSet}) => {
+    const claim = {path};
+    if(valueSet.size > 0) {
+      claim.values = [...valueSet];
+    }
+    return claim;
+  });
+
+  if(claims.length > 0) {
+    result.claims = claims;
+  }
+
+  return result;
+}
+
+// exported for testing purposes only
+export function _toQueryByExampleQuery({dcqlCredentialQuery}) {
+  // convert DCQL credential query to pointers
+  const pointers = new Map();
+  const {format, meta, claims = []} = dcqlCredentialQuery;
+  for(const claim of claims) {
+    const {values} = claim;
+
+    // a trailing `null` in a path means `values` should be treated as a set
+    // of candidates inside an array value at path-1
+    const path = claim.path?.at(-1) === null ?
+      claim.path.slice(0, -1) : claim.path;
+
+    // convert `null` path tokens to an index; assume the use of `null` will
+    // not be combined with any other index
+    const pointer = jsonpointer.compile(path.map(p => p === null ? '0' : p));
+    if(!values) {
+      pointers.set(pointer, '');
+    } else if(values.length === 1 && claim.path.at(-1) !== null) {
+      // convert a single choice for a non-array value to a primitive
+      pointers.set(pointer, values[0]);
+    } else {
+      pointers.set(pointer, new Set(values));
+    }
+  }
+
+  const credentialQuery = {};
+  if(meta?.reason) {
+    credentialQuery.reason = meta.reason;
+  }
+
+  // convert pointers to example object
+  credentialQuery.example = fromJsonPointerMap({map: pointers});
+
+  if(format === 'jwt_vc_json') {
+    credentialQuery.acceptedEnvelopes = ['application/jwt'];
+  } else if(format === 'mso_mdoc') {
+    if(meta?.doctype_value === MDOC_MDL) {
+      credentialQuery.acceptedEnvelopes = ['application/mdl'];
+    } else {
+      credentialQuery.acceptedEnvelopes = ['application/mdoc'];
+    }
+  } else if(format === 'dc+sd-jwt') {
+    // FIXME: consider adding `vct_values` as params
+    credentialQuery.acceptedEnvelopes = ['application/dc+sd-jwt'];
+  }
+
+  return credentialQuery;
+}

package/lib/query/index.js

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) 2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {dcqlCredentialQueryToJsonPointerMap} from './dcql.js';
+import {exampleToJsonPointerMap} from './queryByExample.js';
+import {inputDescriptorToJsonPointerMap} from './presentationExchange.js';
+
+export {credentialMatches} from './match.js';
+
+export const dcql = {
+  toJsonPointerMap: dcqlCredentialQueryToJsonPointerMap
+};
+export const presentationExchange = {
+  toJsonPointerMap: inputDescriptorToJsonPointerMap
+};
+export const queryByExample = {
+  toJsonPointerMap: exampleToJsonPointerMap
+};

package/lib/query/match.js

@@ -0,0 +1,80 @@
+/*!
+ * Copyright (c) 2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {isObject, resolvePointer, toNumberIfNumber} from './util.js';
+
+/**
+ * Returns whether a credential matches against a JSON pointer map.
+ *
+ * A JSON pointer map must be created from a QueryByExample `example`, a DCQL
+ * `credential` query value, or a Presentation Exchange input descriptor
+ * by calling the respective utility APIs in this library. It is more efficient
+ * to produce this JSON pointer map just once when looking for matches in a
+ * list of more than one credential.
+ *
+ * @param {object} options - The options.
+ * @param {object} options.credential - The credential to try to match.
+ * @param {Map} options.map - The JSON pointer map.
+ * @param {object} options.options - Match options, such as:
+ *   [coerceNumbers=true] - String/numbers will be coerced.
+ *
+ * @returns {boolean} `true` if the credential matches, `false` if not.
+ */
+export function credentialMatches({
+  credential, map, options = {coerceNumbers: true}
+} = {}) {
+  // credential must be an object to match
+  if(!isObject(credential)) {
+    return false;
+  }
+  return _match({cursor: credential, matchValue: map, options});
+}
+
+function _match({cursor, matchValue, options}) {
+  // handle wildcard matching
+  if(_isWildcard(matchValue)) {
+    return true;
+  }
+
+  if(matchValue instanceof Set) {
+    // some element in the set must match `cursor`
+    return [...matchValue].some(e => _match({cursor, matchValue: e, options}));
+  }
+
+  if(matchValue instanceof Map) {
+    // all pointers and values in the map must match `cursor`
+    return [...matchValue.entries()].every(([pointer, matchValue]) => {
+      const value = resolvePointer(cursor, pointer);
+      if(value === undefined) {
+        // no value at `pointer`; no match
+        return false;
+      }
+      // handles case where `value` is an empty array + wildcard `matchValue`
+      if(_isWildcard(matchValue)) {
+        return true;
+      }
+      // normalize value to an array for matching
+      const values = Array.isArray(value) ? value : [value];
+      return values.some(v => _match({cursor: v, matchValue, options}));
+    });
+  }
+
+  // primitive comparison
+  if(cursor === matchValue) {
+    return true;
+  }
+
+  // string/number coercion
+  if(options.coerceNumbers) {
+    const cursorNumber = toNumberIfNumber(cursor);
+    const matchNumber = toNumberIfNumber(matchValue);
+    return cursorNumber !== undefined && cursorNumber === matchNumber;
+  }
+
+  return false;
+}
+
+function _isWildcard(value) {
+  // empty string, Map, or Set
+  return value === '' || value?.size === 0;
+}