@digitalbazaar/oid4-client 5.0.0 → 5.2.0

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.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;
+}

package/lib/query/presentationExchange.js

@@ -0,0 +1,328 @@
+/*!
+ * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {resolvePointer, toJsonPointerMap} from './util.js';
+import {exampleToJsonPointerMap} from './queryByExample.js';
+import {JSONPath} from 'jsonpath-plus';
+import jsonpointer from 'json-pointer';
+
+const VALUE_TYPES = new Set(['string', 'number', 'boolean']);
+
+export function presentationDefinitionToVprGroups({
+  presentation_definition, strict = false
+} = {}) {
+  const {input_descriptors: inputDescriptors} = presentation_definition;
+
+  // only one group (no "OR" with presentation exchange), every input
+  // input descriptor converts to a `QueryByExample` query in the same group
+  const queries = inputDescriptors.map(inputDescriptor => {
+    return {
+      type: 'QueryByExample',
+      credentialQuery: _toQueryByExampleQuery({inputDescriptor, strict})
+    };
+  });
+
+  // output group map with a single group with all `QueryByExample` queries
+  const group = new Map([['QueryByExample', queries]]);
+  const groupMap = new Map([[undefined, group]]);
+  return groupMap;
+}
+
+export function inputDescriptorToJsonPointerMap({inputDescriptor} = {}) {
+  const queryByExample = _toQueryByExampleQuery({inputDescriptor});
+  return exampleToJsonPointerMap(queryByExample);
+}
+
+export function vprGroupsToPresentationDefinition({
+  groupMap, prefixJwtVcPath
+} = {}) {
+  // only a single `QueryByExample` is supported at this time; use last one
+  const queryByExample = [...groupMap.values()]
+    .filter(g => g.has('QueryByExample'))
+    .map(g => g.get('QueryByExample'))
+    .at(-1);
+  if(!queryByExample) {
+    // no presentation definition
+    return;
+  }
+
+  const input_descriptors = [];
+  const presentationDefinition = {
+    id: crypto.randomUUID(),
+    input_descriptors
+  };
+
+  // note: same group ID is logical "AND" and different group ID is "OR"
+  const groups = [...groupMap.values()];
+  for(const queries of groups) {
+    // only `QueryByExample` is convertible
+    const queryByExamples = queries.get('QueryByExample');
+    if(!(queryByExamples?.length > 0)) {
+      continue;
+    }
+
+    // for each `QueryByExample`, add another input descriptor (for every
+    // "credentialQuery" within it
+    for(const queryByExample of queryByExamples) {
+      // should only be one `credentialQuery` but handle each one as a new
+      // set of input descriptors
+      const all = Array.isArray(queryByExample.credentialQuery) ?
+        queryByExample.credentialQuery : [queryByExample.credentialQuery];
+      for(const credentialQuery of all) {
+        input_descriptors.push(_fromQueryByExampleQuery({
+          credentialQuery, prefixJwtVcPath
+        }));
+      }
+    }
+  }
+
+  return presentationDefinition;
+}
+
+// exported for backwards compatibility only
+export function pathsToVerifiableCredentialPointers({paths} = {}) {
+  // get only the paths inside a verifiable credential
+  paths = Array.isArray(paths) ? paths : [paths];
+  paths = _getVerifiableCredentialPaths(paths);
+  // convert each JSON path to a JSON pointer
+  return paths.map(_jsonPathToJsonPointer);
+}
+
+function _filterToValue({filter, strict = false}) {
+  /* Each `filter` has a JSON Schema object. In recognition of the fact that
+  a query must be usable by common database engines (including perhaps
+  encrypted cloud databases) and of the fact that each JSON Schema object will
+  come from an untrusted source (and could have malicious regexes, etc.), only
+  simple JSON Schema types are supported:
+
+  simple type filters (`string`/`number`/`boolean`/`object`): with `const` or
+    `enum`, `format` is not supported and `pattern` has partial support as it
+    will be treated as a simple string not a regex; regex is a DoS attack
+    vector
+
+  `array`: with `contains` where uses a simple type filter
+
+  `allOf`: supported only with the above schemas present in it.
+
+  */
+  let value;
+
+  const {type} = filter;
+  if(type === 'array') {
+    if(filter.contains) {
+      if(Array.isArray(filter.contains)) {
+        return filter.contains.map(filter => _filterToValue({filter, strict}));
+      }
+      return _filterToValue({filter: filter.contains, strict});
+    }
+    if(Array.isArray(filter.allOf) && filter.allOf.every(f => f.contains)) {
+      return filter.allOf.map(
+        f => _filterToValue({filter: f.contains, strict}));
+    }
+    if(strict) {
+      throw new Error(
+        'Unsupported filter; array filters must use "allOf" and/or ' +
+        '"contains" with a simple type filter.');
+    }
+    return value;
+  }
+  if(VALUE_TYPES.has(type) || type === 'object' || type === undefined) {
+    if(filter.const !== undefined) {
+      value = filter.const;
+    } else if(filter.pattern) {
+      value = filter.pattern;
+    } else if(filter.enum) {
+      value = filter.enum.slice();
+    } else if(filter.type === 'object') {
+      value = {};
+    } else if(strict && type === 'string') {
+      throw new Error(
+        'Unsupported filter; string filters must use "const" or "pattern".');
+    }
+    return value;
+  }
+  if(strict) {
+    throw new Error(`Unsupported filter type "${type}".`);
+  }
+}
+
+// exported for testing purposes only
+export function _fromQueryByExampleQuery({credentialQuery, prefixJwtVcPath}) {
+  // determine `prefixJwtVcPath` default:
+  // if `credentialQuery` specifies `acceptedEnvelopes: ['application/jwt']`,
+  // then default `prefixJwtVcPath` to `true`
+  if(prefixJwtVcPath === undefined &&
+    (Array.isArray(credentialQuery.acceptedEnvelopes) &&
+    credentialQuery.acceptedEnvelopes.includes?.('application/jwt'))) {
+    prefixJwtVcPath = true;
+  }
+
+  const fields = [];
+  const inputDescriptor = {
+    id: crypto.randomUUID(),
+    constraints: {fields}
+  };
+  if(credentialQuery?.reason) {
+    inputDescriptor.purpose = credentialQuery?.reason;
+  }
+
+  // convert `example` into json pointers
+  const {example = {}} = credentialQuery || {};
+  const pointers = toJsonPointerMap({obj: example});
+
+  // walk pointers and produce fields
+  for(const [pointer, value] of pointers) {
+    const path = jsonpointer.parse(pointer);
+
+    const field = {
+      path: [
+        JSONPath.toPathString(['$', ...path])
+      ]
+    };
+    // include 'vc' path for queries against JWT payloads instead of VCs
+    if(prefixJwtVcPath) {
+      field.path.push(JSONPath.toPathString(['$', 'vc', ...path]));
+    }
+
+    if(value instanceof Set) {
+      field.filter = {
+        type: 'array',
+        allOf: [...value].map(value => ({
+          contains: _primitiveValueToFilter(value)
+        }))
+      };
+    } else {
+      field.filter = _primitiveValueToFilter(value);
+    }
+
+    fields.push(field);
+  }
+
+  return inputDescriptor;
+}
+
+function _getVerifiableCredentialPaths(paths) {
+  // remove any paths that start with what would be present in a
+  // presentation submission and adjust any paths that would be part of a
+  // JWT-secured VC, such that only actual VC paths remain
+  const removed = paths.filter(p => !_isPresentationSubmissionPath(p));
+  return [...new Set(removed.map(p => {
+    if(_isJWTPath(p)) {
+      return '$' + p.slice('$.vc'.length);
+    }
+    if(_isSquareJWTPath(p)) {
+      return '$' + p.slice('$[\'vc\']'.length);
+    }
+    return p;
+  }))];
+}
+
+function _isPresentationSubmissionPath(path) {
+  return path.startsWith('$.verifiableCredential[') ||
+    path.startsWith('$.vp.') ||
+    path.startsWith('$[\'verifiableCredential') || path.startsWith('$[\'vp');
+}
+
+function _isJWTPath(path) {
+  return path.startsWith('$.vc.');
+}
+
+function _isSquareJWTPath(path) {
+  return path.startsWith('$[\'vc\']');
+}
+
+function _jsonPathToJsonPointer(jsonPath) {
+  return JSONPath.toPointer(JSONPath.toPathArray(jsonPath));
+}
+
+function _toQueryByExampleQuery({inputDescriptor, strict = false}) {
+  // every input descriptor must have an `id`
+  if(typeof inputDescriptor?.id !== 'string') {
+    throw new TypeError('Input descriptor "id" must be a string.');
+  }
+
+  const example = {};
+  const credentialQuery = {example};
+  if(inputDescriptor.purpose) {
+    credentialQuery.reason = inputDescriptor.purpose;
+  }
+
+  /* Note: Each input descriptor object is currently mapped to a single example
+  query. If multiple possible path values appear for a single field, these will
+  be mapped to multiple properties in the example which may or may not be what
+  is intended. This behavior could be changed in a future revision if it
+  becomes clear there is a better approach. */
+
+  const fields = inputDescriptor.constraints?.fields || [];
+  for(const field of fields) {
+    const {path, filter, optional} = field;
+    // skip optional fields
+    if(optional === true) {
+      continue;
+    }
+
+    try {
+      // each field must have a `path` (which can be a string or an array)
+      if(!(Array.isArray(path) || typeof path === 'string')) {
+        throw new TypeError(
+          'Input descriptor field "path" must be a string or array.');
+      }
+
+      // process any filter
+      let value = '';
+      if(filter !== undefined) {
+        value = _filterToValue({filter, strict});
+      }
+      // no value understood, skip field
+      if(value === undefined) {
+        continue;
+      }
+      // normalize value to array
+      const originalValue = value;
+      if(!Array.isArray(value)) {
+        value = [value];
+      }
+
+      // get JSON pointers for every path inside a verifiable credential
+      const pointers = pathsToVerifiableCredentialPointers({paths: path});
+
+      // add values at each path, converting to an array / appending as needed
+      for(const pointer of pointers) {
+        const existing = resolvePointer(example, pointer);
+        if(existing === undefined) {
+          jsonpointer.set(example, pointer, originalValue);
+          continue;
+        }
+
+        if(Array.isArray(existing)) {
+          if(!existing.includes(value)) {
+            existing.push(...value);
+          }
+        } else if(existing !== value) {
+          jsonpointer.set(example, pointer, [existing, ...value]);
+        }
+      }
+    } catch(cause) {
+      const id = field.id || (JSON.stringify(field).slice(0, 50) + ' ...');
+      const error = new Error(
+        `Could not process input descriptor field: "${id}".`, {cause});
+      error.field = field;
+      throw error;
+    }
+  }
+
+  return credentialQuery;
+}
+
+function _primitiveValueToFilter(value) {
+  const filter = {
+    type: typeof value
+  };
+  if(VALUE_TYPES.has(filter.type)) {
+    filter.const = value;
+  } else {
+    // default to `object`
+    filter.type = 'object';
+  }
+  return filter;
+}

package/lib/query/queryByExample.js

@@ -0,0 +1,8 @@
+/*!
+ * Copyright (c) 2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {toJsonPointerMap} from './util.js';
+
+export function exampleToJsonPointerMap({example} = {}) {
+  return toJsonPointerMap({obj: example, flat: false});
+}