@digitalbazaar/oid4-client 4.3.0 → 4.4.0

package/lib/authorizationRequest.js

@@ -0,0 +1,344 @@
+/*!
+ * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {
+  assert, assertOptional, createNamedError, fetchJSON, selectJwk
+} from './util.js';
+import {decodeJwt, jwtVerify} from 'jose';
+
+// get an authorization request from a verifier
+export async function get({url, getVerificationKey, agent} = {}) {
+  try {
+    assert(url, 'url', 'string');
+
+    let authorizationRequest;
+    let requestUrl;
+    let expectedClientId;
+    if(url.startsWith('https://')) {
+      // the request must be retrieved via HTTP
+      requestUrl = url;
+    } else {
+      // parse the request from the given URL
+      ({authorizationRequest} = _parseOID4VPUrl({url}));
+      expectedClientId = authorizationRequest.client_id;
+      if(authorizationRequest.request_uri) {
+        requestUrl = authorizationRequest.request_uri;
+      }
+      // if whole request is passed by reference, then it MUST be a signed JWT
+      if(authorizationRequest.request) {
+        authorizationRequest = await _parseJwt({
+          jwt: authorizationRequest.request,
+          getVerificationKey,
+          signatureRequired: true
+        });
+      }
+    }
+
+    // fetch request if necessary...
+    let fetched = false;
+    let response;
+    let jwt;
+    if(requestUrl) {
+      fetched = true;
+      ({
+        payload: authorizationRequest, response, jwt
+      } = await _fetch({requestUrl, getVerificationKey, agent}));
+    }
+
+    // ensure authorization request is valid
+    validate({authorizationRequest, expectedClientId});
+
+    // resolve and validate any additional parameters in the request
+    authorizationRequest = await resolveParams({authorizationRequest, agent});
+
+    return {authorizationRequest, fetched, requestUrl, response, jwt};
+  } catch(cause) {
+    const message = cause.data?.error_description ?? cause.message;
+    throw createNamedError({
+      message: `Could not get authorization request: ${message}`,
+      name: 'OperationError',
+      cause
+    });
+  }
+}
+
+export function requestsFormat({authorizationRequest, format} = {}) {
+  /* e.g. presentation definition requesting an mdoc:
+  {
+    id: 'mdl-test-age-over-21',
+    input_descriptors: [{
+      id: 'org.iso.18013.5.1.mDL',
+      format: {
+        mso_mdoc: {
+          alg: ['ES256']
+        }
+      }
+    }]
+  }
+  */
+  return authorizationRequest.presentation_definition?.input_descriptors?.some(
+    e => e?.format?.[format]);
+}
+
+// FIXME: in a major release, remove support for params requiring resolution
+export async function resolveParams({authorizationRequest, agent}) {
+  const {
+    client_metadata_uri,
+    presentation_definition_uri,
+    ...resolved
+  } = {...authorizationRequest};
+
+  // get client meta data from URL if specified
+  if(client_metadata_uri) {
+    const response = await fetchJSON({url: client_metadata_uri, agent});
+    if(!response.data) {
+      throw createNamedError({
+        message: 'Client meta data format is not JSON.',
+        name: 'DataError'
+      });
+    }
+    resolved.client_metadata = response.data;
+  }
+
+  // get presentation definition from URL if not embedded
+  if(presentation_definition_uri) {
+    const response = await fetchJSON(
+      {url: presentation_definition_uri, agent});
+    if(!response.data) {
+      throw createNamedError({
+        message: 'Presentation definition format is not JSON.',
+        name: 'DataError'
+      });
+    }
+    resolved.presentation_definition = response.data;
+  }
+
+  assert(resolved.presentation_definition, 'presentation_definition', 'object');
+  assert(
+    resolved.presentation_definition?.id,
+    'presentation_definition.id', 'string');
+
+  // FIXME: further validate `authorizationRequest.presentation_definition`
+  // FIXME: further validate `authorizationRequest.client_metadata`
+
+  // `direct_post.jwt` response mode requires encryption; ensure the client
+  // meta data has the necessary parameters
+  if(resolved.response_mode === 'direct_post.jwt') {
+    const {
+      authorization_encrypted_response_alg = 'ECDH-ES',
+      authorization_encrypted_response_enc = 'A256GCM',
+      jwks
+    } = resolved.client_metadata;
+    if(authorization_encrypted_response_alg !== 'ECDH-ES') {
+      throw createNamedError({
+        message: `"${authorization_encrypted_response_alg}" is not ` +
+          'supported; only "ECDH-ES" is supported.',
+        name: 'NotSupportedError'
+      });
+    }
+    if(authorization_encrypted_response_enc !== 'A256GCM') {
+      throw createNamedError({
+        message: `"${authorization_encrypted_response_enc}" is not ` +
+          'supported; only "A256GCM" is supported.',
+        name: 'NotSupportedError'
+      });
+    }
+    if(!selectJwk({
+      keys: jwks?.keys, alg: 'ECDH-ES', kty: 'EC', crv: 'P-256', use: 'enc'
+    })) {
+      throw createNamedError({
+        message: 'No matching key found for "ECDH-ES" in client meta data ' +
+          'JWK key set.',
+        name: 'NotFoundError'
+      });
+    }
+  }
+
+  return resolved;
+}
+
+export function usesClientIdScheme({authorizationRequest, scheme} = {}) {
+  return authorizationRequest?.client_id_scheme === scheme ||
+    authorizationRequest?.client_id?.startsWith(`${scheme}:`);
+}
+
+export async function validate({authorizationRequest, expectedClientId}) {
+  // validate payload (expected authorization request)
+  const {
+    client_id,
+    client_id_scheme,
+    client_metadata,
+    client_metadata_uri,
+    nonce,
+    presentation_definition,
+    presentation_definition_uri,
+    response_mode,
+    scope
+  } = authorizationRequest;
+  assert(client_id, 'client_id', 'string');
+  // ensure `client_id` matches expected client ID
+  if(expectedClientId !== undefined && client_id !== expectedClientId) {
+    throw createNamedError({
+      message: '"client_id" in fetched request does not match authorization ' +
+        'request URL parameter.',
+      name: 'DataError'
+    });
+  }
+  assert(nonce, 'nonce', 'string');
+  assertOptional(client_id_scheme, 'client_id_scheme', 'string');
+  assertOptional(client_metadata, 'client_metadata', 'object');
+  // FIXME: remove `client_metadata_uri` in a future revision, it is not
+  // supported in the latest OID4VP, bad practice, and rarely used
+  assertOptional(client_metadata_uri, 'client_metadata_uri', 'string');
+  assertOptional(
+    presentation_definition, 'presentation_definition', 'object');
+  // FIXME: remove `presentation_definition_uri` in a future revision, it is
+  // not supported in the latest OID4VP, bad practice, and rarely used
+  assertOptional(
+    presentation_definition_uri, 'presentation_definition_uri', 'string');
+  assertOptional(response_mode, 'response_mode', 'string');
+  assertOptional(scope, 'scope', 'string');
+  if(client_metadata && client_metadata_uri) {
+    throw createNamedError({
+      message: 'Only one of "client_metadata" and ' +
+        '"client_metadata_uri" must be present.',
+      name: 'DataError'
+    });
+  }
+  if(presentation_definition && presentation_definition_uri) {
+    throw createNamedError({
+      message: 'Only one of "presentation_definition" and ' +
+        '"presentation_definition_uri" must be present.',
+      name: 'DataError'
+    });
+  }
+  // Note: This implementation requires `response_mode` to be `direct_post`
+  // or `direct_post.jwt`; no other modes are supported.
+  if(!(response_mode === 'direct_post' ||
+    response_mode === 'direct_post.jwt')) {
+    throw createNamedError({
+      message: 'Only "direct_post" and "direct_post.jwt" ' +
+        'response modes are supported.',
+      name: 'NotSupportedError'
+    });
+  }
+}
+
+async function _fetch({requestUrl, getVerificationKey, agent}) {
+  // FIXME: every `fetchJSON` call needs to use a block list or other
+  // protections to prevent a confused deputy attack where the `requestUrl`
+  // accesses a location it should not, e.g., a URL `localhost` is used when
+  // it shouldn't be
+  const response = await fetchJSON({url: requestUrl, agent});
+
+  // parse payload from response data...
+  const contentType = response.headers.get('content-type');
+  const jwt = await response.text();
+
+  // verify response is a JWT-secured authorization request
+  if(!(contentType.includes('application/oauth-authz-req+jwt') &&
+    typeof jwt === 'string')) {
+    throw createNamedError({
+      message: 'Authorization request content-type must be ' +
+        '"application/oauth-authz-req+jwt".',
+      name: 'DataError'
+    });
+  }
+
+  // return parsed payload and original response
+  const payload = await _parseJwt({jwt, getVerificationKey});
+  return {payload, response, jwt};
+}
+
+function _get(sp, name) {
+  const value = sp.get(name);
+  return value === null ? undefined : value;
+}
+
+async function _parseJwt({jwt, getVerificationKey, signatureRequired}) {
+  const payload = decodeJwt(jwt);
+
+  // check if a signature on the JWT is required:
+  // - `client_metadata.require_signed_request_object` is `true`, OR
+  // - `client_id_scheme` requires the JWT to be signed
+  signatureRequired = signatureRequired ||
+    payload.client_metadata?.require_signed_request_object === true ||
+    usesClientIdScheme({authorizationRequest: payload, scheme: 'x509_san_dns'});
+  if(!signatureRequired) {
+    // no signature required, just use the decoded payload
+    return payload;
+  }
+
+  // create callback function to handle key lookup; `getVerificationKey` may
+  // return a promise
+  const getKey = protectedHeader => {
+    // FIXME: add parser for `x5c`?
+    if(getVerificationKey) {
+      return getVerificationKey({protectedHeader});
+    }
+    _throwKeyNotFound(protectedHeader);
+  };
+
+  // verify the JWT
+  const verifyResult = await jwtVerify(jwt, getKey, {alg: 'ES256'});
+  return verifyResult.payload;
+}
+
+function _parseOID4VPUrl({url}) {
+  const {searchParams} = new URL(url);
+  const request = _get(searchParams, 'request');
+  const request_uri = _get(searchParams, 'request_uri');
+  const response_type = _get(searchParams, 'response_type');
+  const response_mode = _get(searchParams, 'response_mode');
+  const presentation_definition = _get(
+    searchParams, 'presentation_definition');
+  const presentation_definition_uri = _get(
+    searchParams, 'presentation_definition_uri');
+  const client_id = _get(searchParams, 'client_id');
+  const client_id_scheme = _get(searchParams, 'client_id_scheme');
+  const client_metadata = _get(searchParams, 'client_metadata');
+  const nonce = _get(searchParams, 'nonce');
+  const response_uri = _get(searchParams, 'response_uri');
+  const state = _get(searchParams, 'state');
+  if(request && request_uri) {
+    const error = createNamedError({
+      message: 'Only one of "request" and "request_uri" may be present.',
+      name: 'DataError'
+    });
+    error.url = url;
+    throw error;
+  }
+  if(!(request || request_uri)) {
+    if(response_type !== 'vp_token') {
+      throw new Error(`Unsupported "response_type", "${response_type}".`);
+    }
+    if(!(response_mode === 'direct_post' ||
+      response_mode === 'direct_post.jwt')) {
+      throw new Error(`Unsupported "response_type", "${response_type}".`);
+    }
+  }
+  const authorizationRequest = {
+    request,
+    request_uri,
+    response_type,
+    response_mode,
+    presentation_definition: presentation_definition &&
+      JSON.parse(presentation_definition),
+    presentation_definition_uri,
+    client_id,
+    client_id_scheme,
+    client_metadata: client_metadata && JSON.parse(client_metadata),
+    response_uri,
+    nonce,
+    state
+  };
+  return {authorizationRequest};
+}
+
+function _throwKeyNotFound(protectedHeader) {
+  const error = new Error(
+    'Could not verify signed authorization request; ' +
+    `public key "${protectedHeader.kid}" not found.`);
+  error.name = 'NotFoundError';
+  throw error;
+}

package/lib/authorizationResponse.js

@@ -0,0 +1,312 @@
+/*!
+ * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+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';
+
+const TEXT_ENCODER = new TextEncoder();
+
+export async function send({
+  verifiablePresentation,
+  presentationSubmission,
+  authorizationRequest,
+  vpToken,
+  encryptionOptions = {},
+  agent
+} = {}) {
+  try {
+    if(!(verifiablePresentation || vpToken)) {
+      throw createNamedError({
+        message: 'One of "verifiablePresentation" or "vpToken" must be given.',
+        name: 'DataError'
+      });
+    }
+    // if no `vpToken` given, use VP
+    vpToken = vpToken ?? JSON.stringify(verifiablePresentation);
+
+    // if no `presentationSubmission` provided, auto-generate one
+    let generatedPresentationSubmission = false;
+    if(!presentationSubmission) {
+      ({presentationSubmission} = createPresentationSubmission({
+        presentationDefinition: authorizationRequest.presentation_definition,
+        verifiablePresentation
+      }));
+      generatedPresentationSubmission = true;
+    }
+
+    // prepare response body
+    const body = new URLSearchParams();
+
+    // if `authorizationRequest.response_mode` is `direct.jwt` generate a JWT
+    if(authorizationRequest.response_mode === 'direct_post.jwt') {
+      const jwt = await _encrypt({
+        vpToken, presentationSubmission, authorizationRequest,
+        encryptionOptions
+      });
+      body.set('response', jwt);
+    } else {
+      // include vp token and presentation submittion directly in body
+      body.set('vp_token', vpToken);
+      body.set(
+        'presentation_submission', JSON.stringify(presentationSubmission));
+    }
+
+    // send response
+    const response = await httpClient.post(authorizationRequest.response_uri, {
+      agent, body, headers: {accept: 'application/json'},
+      // FIXME: limit response size
+      // timeout in ms for response
+      timeout: 5000
+    });
+
+    // return response data as `result`
+    const result = response.data || {};
+    if(generatedPresentationSubmission) {
+      // return any generated presentation submission
+      return {result, presentationSubmission};
+    }
+    return {result};
+  } catch(cause) {
+    const message = cause.data?.error_description ?? cause.message;
+    const error = new Error(
+      `Could not send OID4VP authorization response: ${message}.`,
+      {cause});
+    error.name = 'OperationError';
+    throw error;
+  }
+}
+
+// creates a "presentation submission" from a presentation definition and VP
+export function createPresentationSubmission({
+  presentationDefinition, verifiablePresentation
+} = {}) {
+  const descriptor_map = [];
+  const presentationSubmission = {
+    id: crypto.randomUUID(),
+    definition_id: presentationDefinition.id,
+    descriptor_map
+  };
+
+  try {
+    // walk through each input descriptor object and match it to a VC
+    let {verifiableCredential: vcs} = verifiablePresentation;
+    const single = !Array.isArray(vcs);
+    if(single) {
+      vcs = [vcs];
+    }
+    /* Note: It is conceivable that the same VC could match multiple input
+    descriptors. In this simplistic implementation, the first VC that matches
+    is used. This may result in VCs in the VP not being mapped to an input
+    descriptor, but every input descriptor having a VC that matches (i.e., at
+    least one VC will be shared across multiple input descriptors). If
+    some other behavior is more desirable, this can be changed in a future
+    version. */
+    for(const inputDescriptor of presentationDefinition.input_descriptors) {
+      // walk through each VC and try to match it to the input descriptor
+      for(let i = 0; i < vcs.length; ++i) {
+        const verifiableCredential = vcs[i];
+        if(_matchesInputDescriptor({inputDescriptor, verifiableCredential})) {
+          descriptor_map.push({
+            id: inputDescriptor.id,
+            path: '$',
+            format: 'ldp_vp',
+            path_nested: {
+              format: 'ldp_vc',
+              path: single ?
+                '$.verifiableCredential' :
+                '$.verifiableCredential[' + i + ']'
+            }
+          });
+          break;
+        }
+      }
+    }
+  } catch(cause) {
+    throw createNamedError({
+      message: `Could not create presentation submission: ${cause.message}`,
+      name: 'OperationError',
+      cause
+    });
+  }
+
+  return {presentationSubmission};
+}
+
+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'
+  });
+  if(!recipientPublicJwk) {
+    throw createNamedError({
+      message: 'No matching key found for "ECDH-ES" in client meta data ' +
+        'JWK key set.',
+      name: 'NotFoundError'
+    });
+  }
+
+  // configure `keyManagementParameters` for `EncryptJWT` API
+  const keyManagementParameters = {};
+  if(encryptionOptions?.mdoc?.sessionTranscript) {
+    // ISO 18013-7: include specific session transcript params as apu + apv
+    const {
+      mdocGeneratedNonce,
+      // default to using `authorizationRequest.nonce` for verifier nonce
+      verifierGeneratedNonce = authorizationRequest.nonce
+    } = encryptionOptions.mdoc.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);
+  }
+
+  const claimSet = {
+    vp_token: vpToken,
+    presentation_submission: presentationSubmission
+  };
+  const jwt = await new EncryptJWT(claimSet)
+    .setProtectedHeader({
+      alg: 'ECDH-ES', enc: 'A256GCM',
+      kid: recipientPublicJwk.kid
+    })
+    .setKeyManagementParameters(keyManagementParameters)
+    .encrypt(recipientPublicJwk);
+  return jwt;
+}
+
+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:
+
+  `string`: 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 `string` 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 string filter.');
+    }
+    return value;
+  }
+  if(type === 'string' || 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(strict) {
+      throw new Error(
+        'Unsupported filter; string filters must use "const" or "pattern".');
+    }
+    return value;
+  }
+  if(strict) {
+    throw new Error(`Unsupported filter type "${type}".`);
+  }
+}
+
+function _matchesInputDescriptor({
+  inputDescriptor, verifiableCredential, strict = false
+}) {
+  // walk through each field ensuring there is a matching value
+  const fields = inputDescriptor?.constraints?.fields || [];
+  for(const field of fields) {
+    const {path, filter, optional} = field;
+    if(optional) {
+      // skip field, it is optional
+      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 Error(
+          'Input descriptor field "path" must be a string or array.');
+      }
+
+      // process any filter
+      let value = '';
+      if(filter !== undefined) {
+        value = _filterToValue({filter, strict});
+      }
+      // no value to match, presume no match
+      if(value === undefined) {
+        return false;
+      }
+      // normalize value to array
+      if(!Array.isArray(value)) {
+        value = [value];
+      }
+
+      // get JSON pointers for every path inside a verifiable credential
+      const pointers = pathsToVerifiableCredentialPointers({paths: path});
+
+      // check for a value at at least one path
+      for(const pointer of pointers) {
+        const existing = jsonpointer.get(verifiableCredential, pointer);
+        if(existing === undefined) {
+          // VC does not match
+          return false;
+        }
+        // look for at least one matching value in `existing`
+        let match = false;
+        for(const v of value) {
+          if(Array.isArray(existing)) {
+            if(existing.includes(v)) {
+              match = true;
+              break;
+            }
+          } else if(existing === v) {
+            match = true;
+            break;
+          }
+        }
+        if(!match) {
+          return false;
+        }
+      }
+    } catch(cause) {
+      const id = field.id || (JSON.stringify(field).slice(0, 50) + ' ...');
+      const error = createNamedError({
+        message: `Could not process input descriptor field: "${id}".`,
+        name: 'DataError',
+        cause
+      });
+      error.field = field;
+      throw error;
+    }
+  }
+
+  return true;
+}