@digitalbazaar/oid4-client 5.0.0 → 5.2.0

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,68 +1,109 @@
 /*!
  * 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();
 
-export async function send({
+// creates an authorization response without sending it; use `send()` to create
+// and send one at once
+export async function create({
   verifiablePresentation,
   presentationSubmission,
   authorizationRequest,
   vpToken,
-  encryptionOptions = {},
-  agent
+  encryptionOptions = {}
 } = {}) {
-  try {
-    if(!(verifiablePresentation || vpToken)) {
+  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 = {};
+
+  // if `authorizationRequest.response_mode` is `direct.jwt` generate a JWT
+  if(authorizationRequest.response_mode === 'direct_post.jwt') {
+    if(submitsFormat({presentationSubmission, format: 'mso_mdoc'}) &&
+      !encryptionOptions?.mdl?.sessionTranscript) {
       throw createNamedError({
-        message: 'One of "verifiablePresentation" or "vpToken" must be given.',
+        message: '"encryptionOptions.mdl.sessionTranscript" is required ' +
+          'when submitting an mDL presentation.',
         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();
+    const jwt = await _encrypt({
+      vpToken, presentationSubmission, authorizationRequest,
+      encryptionOptions
+    });
+    body.response = jwt;
+  } else {
+    // include vp token and presentation submittion directly in body
+    body.vp_token = vpToken;
+    body.presentation_submission = JSON.stringify(presentationSubmission);
+  }
 
-    // if `authorizationRequest.response_mode` is `direct.jwt` generate a JWT
-    if(authorizationRequest.response_mode === 'direct_post.jwt') {
-      if(submitsFormat({presentationSubmission, format: 'mso_mdoc'}) &&
-        !encryptionOptions?.mdl?.sessionTranscript) {
-        throw createNamedError({
-          message: '"encryptionOptions.mdl.sessionTranscript" is required ' +
-            'when submitting an mDL presentation.',
-          name: 'DataError'
-        });
-      }
+  const authorizationResponse = body;
+  if(generatedPresentationSubmission) {
+    // return any generated presentation submission
+    return {authorizationResponse, presentationSubmission};
+  }
+  return {authorizationResponse};
+}
 
-      const jwt = await _encrypt({
-        vpToken, presentationSubmission, authorizationRequest,
+export async function send({
+  verifiablePresentation,
+  presentationSubmission,
+  authorizationRequest,
+  vpToken,
+  encryptionOptions = {},
+  authorizationResponse,
+  agent
+} = {}) {
+  try {
+    // create `authorizationResponse` if not passed
+    let generatedPresentationSubmission;
+    if(!authorizationResponse) {
+      ({
+        authorizationResponse,
+        presentationSubmission: generatedPresentationSubmission
+      } = await create({
+        verifiablePresentation,
+        presentationSubmission,
+        authorizationRequest,
+        vpToken,
         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));
+      }));
+    } else if(verifiablePresentation || presentationSubmission || vpToken ||
+      encryptionOptions) {
+      throw new TypeError(
+        'Only "authorizationResponse" or its components ( ' +
+        '"verifiablePresentation", "presentationSubmission", "vpToken", ' +
+        '"encryptionOptions") can be passed, but not both.');
     }
 
+    // prepare response body
+    const body = new URLSearchParams(authorizationResponse);
+
     // send response
     const response = await httpClient.post(authorizationRequest.response_uri, {
       agent, body, headers: {accept: 'application/json'},
@@ -75,7 +116,7 @@ export async function send({
     const result = response.data || {};
     if(generatedPresentationSubmission) {
       // return any generated presentation submission
-      return {result, presentationSubmission};
+      return {result, presentationSubmission: generatedPresentationSubmission};
     }
     return {result};
   } catch(cause) {
@@ -299,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,8 @@
  */
 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
 export {
@@ -13,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/oid4vp/verifier.js

@@ -0,0 +1,102 @@
+/*!
+ * Copyright (c) 2023-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {createNamedError, parseJSON, selectJwk} from '../util.js';
+import {importJWK, jwtDecrypt} from 'jose';
+
+// parses (and decrypts) an authz response from a response body object
+export async function parseAuthorizationResponse({
+  body = {},
+  supportedResponseModes = ['direct_post.jwt', 'direct_post'],
+  getDecryptParameters
+}) {
+  let responseMode;
+  const parsed = {};
+  let payload;
+  let protectedHeader;
+
+  supportedResponseModes = new Set(supportedResponseModes);
+
+  if(body.response) {
+    // `body.response` is present which must contain an encrypted JWT
+    responseMode = 'direct_post.jwt';
+    _assertSupportedResponseMode({responseMode, supportedResponseModes});
+    const jwt = body.response;
+    ({
+      payload,
+      protectedHeader
+    } = await _decrypt({jwt, getDecryptParameters}));
+    parsed.presentationSubmission = payload.presentation_submission;
+  } else {
+    responseMode = 'direct_post';
+    _assertSupportedResponseMode({responseMode, supportedResponseModes});
+    payload = body;
+    parsed.presentationSubmission = parseJSON(
+      payload.presentation_submission, 'presentation_submission');
+  }
+
+  // `vp_token` is either:
+  // 1. a JSON object (a VP)
+  // 2. a JSON array (of something)
+  // 3. a JSON string (a quoted JWT: "<JWT>")
+  // 4. a JWT
+  // 5. a base64url-encoded mDL device response
+  // 6. unknown
+  const {vp_token} = payload;
+  if(typeof vp_token === 'string' &&
+    (vp_token.startsWith('{') || vp_token.startsWith('[') ||
+    vp_token.startsWith('"'))) {
+    parsed.vpToken = parseJSON(vp_token, 'vp_token');
+  } else {
+    parsed.vpToken = vp_token;
+  }
+
+  return {responseMode, parsed, payload, protectedHeader};
+}
+
+function _assertSupportedResponseMode({
+  responseMode, supportedResponseModes
+}) {
+  if(!supportedResponseModes.has(responseMode)) {
+    throw createNamedError({
+      message: `Unsupported response mode "${responseMode}".`,
+      name: 'NotSupportedError'
+    });
+  }
+}
+
+async function _decrypt({jwt, getDecryptParameters}) {
+  if(typeof getDecryptParameters !== 'function') {
+    throw new TypeError(
+      '"getDecryptParameters" is required for "direct_post.jwt" ' +
+      'response mode.');
+  }
+
+  const params = await getDecryptParameters({jwt});
+  const {keys} = params;
+  let {getKey} = params;
+  if(!getKey) {
+    // note: `jose` lib's JWK key set feature cannot be used and passed to
+    // `jwtDecrypt()` as the second parameter because the expected `alg`
+    // "ECDH-ES" is not a unsupported algorithm for selecting a key from a set
+    getKey = protectedHeader => {
+      if(protectedHeader.alg !== 'ECDH-ES') {
+        const error = createNamedError({
+          message: `Unsupported algorithm "${protectedHeader.alg}"; ` +
+            'algorithm must be "ECDH-ES".',
+          name: 'NotSupportedError',
+          details: {httpStatusCode: 400, public: true}
+        });
+        throw error;
+      }
+      const jwk = selectJwk({keys, kid: protectedHeader.kid});
+      return importJWK(jwk, 'ECDH-ES');
+    };
+  }
+
+  return jwtDecrypt(jwt, getKey, {
+    // only supported algorithms at this time:
+    contentEncryptionAlgorithms: ['A256GCM'],
+    keyManagementAlgorithms: ['ECDH-ES']
+  });
+}

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';