@digitalbazaar/oid4-client 4.2.0 → 4.4.0

package/lib/OID4Client.js

@@ -18,8 +18,47 @@ export class OID4Client {
     this.offer = offer;
   }
 
+  async getNonce({agent, headers = HEADERS} = {}) {
+    let response;
+    try {
+      // get nonce endpoint
+      const {nonce_endpoint: url} = this.issuerConfig;
+      if(url === undefined) {
+        const error = new Error('Credential issuer has no "nonce_endpoint".');
+        error.name = 'DataError';
+        throw error;
+      }
+      if(!url?.startsWith('https://')) {
+        const error = new Error(
+          `Nonce endpoint "${url}" does not start with "https://".`);
+        error.name = 'DataError';
+        throw error;
+      }
+
+      // get nonce
+      response = await httpClient.post(url, {agent, headers});
+      if(!response.data) {
+        const error = new Error('Nonce response format is not JSON.');
+        error.name = 'DataError';
+        throw error;
+      }
+      if(response.data.c_nonce === undefined) {
+        const error = new Error('Nonce not provided in response.');
+        error.name = 'DataError';
+        throw error;
+      }
+    } catch(cause) {
+      const error = new Error('Could not get nonce.', {cause});
+      error.name = 'DataError';
+      throw error;
+    }
+
+    const {c_nonce: nonce} = response.data;
+    return {nonce, response};
+  }
+
   async requestCredential({
-    credentialDefinition, did, didProofSigner, agent, format = 'ldp_vc'
+    credentialDefinition, did, didProofSigner, nonce, agent, format = 'ldp_vc'
   } = {}) {
     const {issuerConfig, offer} = this;
     let requests;
@@ -41,13 +80,21 @@ export class OID4Client {
         credential_definition: credentialDefinition
       }];
     }
-    return this.requestCredentials({requests, did, didProofSigner, agent});
+    return this.requestCredentials({
+      requests, did, didProofSigner, nonce, agent
+    });
   }
 
   async requestCredentials({
-    requests, did, didProofSigner, agent, format = 'ldp_vc',
+    requests, did, didProofSigner, agent, nonce, format = 'ldp_vc',
     alwaysUseBatchEndpoint = false
   } = {}) {
+    // if `nonce` is given, then `did` and `didProofSigner` must also be
+    if(nonce !== undefined && !(did && didProofSigner)) {
+      throw new Error(
+        'If "nonce" is given then "did" and "didProofSigner" are required.');
+    }
+
     const {issuerConfig, offer} = this;
     if(requests === undefined && offer) {
       requests = _createCredentialRequestsFromOffer({
@@ -61,7 +108,8 @@ export class OID4Client {
     requests = requests.map(r => ({format, ...r}));
 
     try {
-      /* First send credential request(s) to DS without DID proof JWT, e.g.:
+      /* First send credential request(s) to DS without DID proof JWT (unless
+      `nonce` is given) e.g.:
 
       POST /credential HTTP/1.1
       Host: server.example.com
@@ -71,7 +119,7 @@ export class OID4Client {
       {
         "format": "ldp_vc",
         "credential_definition": {...},
-        // only present on retry after server requests it
+        // only present on retry after server requests it or if nonce is given
         "proof": {
           "proof_type": "jwt",
           "jwt": "eyJraW..."
@@ -109,6 +157,11 @@ export class OID4Client {
         json = {...requests[0]};
       }
 
+      if(nonce !== undefined) {
+        // add DID proof JWT to json
+        await _addDIDProofJWT({issuerConfig, json, nonce, did, didProofSigner});
+      }
+
       let result;
       const headers = {
         ...HEADERS,
@@ -149,32 +202,16 @@ export class OID4Client {
           }
 
           // validate that `result` has
-          const {data: {c_nonce: nonce}} = cause;
+          let {data: {c_nonce: nonce}} = cause;
           if(!(nonce && typeof nonce === 'string')) {
-            const error = new Error('No DID proof challenge specified.');
-            error.name = 'DataError';
-            throw error;
+            // try to get a nonce
+            ({nonce} = await this.getNonce({agent}));
           }
 
-          // generate a DID proof JWT
-          const {issuer: aud} = this.issuerConfig;
-          const jwt = await generateDIDProofJWT({
-            signer: didProofSigner,
-            nonce,
-            // the entity identified by the DID is issuing this JWT
-            iss: did,
-            // audience MUST be the target issuer per the OID4VCI spec
-            aud
+          // add DID proof JWT to json
+          await _addDIDProofJWT({
+            issuerConfig, json, nonce, did, didProofSigner
           });
-
-          // add proof to body to be posted and loop to retry
-          const proof = {proof_type: 'jwt', jwt};
-          if(json.credential_requests) {
-            json.credential_requests = json.credential_requests.map(
-              cr => ({...cr, proof}));
-          } else {
-            json.proof = proof;
-          }
         }
       }
 
@@ -344,6 +381,30 @@ export class OID4Client {
   }
 }
 
+async function _addDIDProofJWT({
+  issuerConfig, json, nonce, did, didProofSigner
+}) {
+  // generate a DID proof JWT
+  const {issuer: aud} = issuerConfig;
+  const jwt = await generateDIDProofJWT({
+    signer: didProofSigner,
+    nonce,
+    // the entity identified by the DID is issuing this JWT
+    iss: did,
+    // audience MUST be the target issuer per the OID4VCI spec
+    aud
+  });
+
+  // add proof to body to be posted and loop to retry
+  const proof = {proof_type: 'jwt', jwt};
+  if(json.credential_requests) {
+    json.credential_requests = json.credential_requests.map(
+      cr => ({...cr, proof}));
+  } else {
+    json.proof = proof;
+  }
+}
+
 function _assertRequest(request) {
   if(!(request && typeof request === 'object')) {
     throw new TypeError('"request" must be an object.');

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