@bedrock/vc-delivery 7.3.0 → 7.5.0

package/lib/constants.js

@@ -1,5 +1,7 @@
 /*!
- * Copyright (c) 2024 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2024-2025 Digital Bazaar, Inc. All rights reserved.
  */
-// maximum number of issuer instances that can be associated with a workflow
+// maximum # of issuer instances that can be associated with a workflow
 export const MAX_ISSUER_INSTANCES = 10;
+// maximum # of OID4VP client profiles that can be associated with a workflow
+export const MAX_OID4VP_CLIENT_PROFILES = 10;

package/lib/exchanges.js

@@ -87,23 +87,23 @@ export async function insert({workflowId, exchange}) {
   assert.object(exchange, 'exchange');
   assert.string(exchange.id, 'exchange.id');
   // optional time to live in seconds
-  assert.optionalNumber(exchange.ttl);
+  assert.optionalNumber(exchange.ttl, 'exchange.ttl');
   // optional variables to use in VC templates
-  assert.optionalObject(exchange.variables);
+  assert.optionalObject(exchange.variables, 'exchange.variables');
   // optional current step in the exchange
-  assert.optionalString(exchange.step);
+  assert.optionalString(exchange.step, 'exchange.step');
+  // optional expires in exchange
+  assert.optionalString(exchange.expires, 'exchange.expires');
+  // optional protocols in exchange
+  assert.optionalObject(exchange.protocols, 'exchange.protocols');
 
   // build exchange record
   const now = Date.now();
   const meta = {created: now, updated: now};
   // possible states are: `pending`, `active`, `complete`, or `invalid`
   exchange = {...exchange, sequence: 0, state: 'pending'};
-  if(exchange.ttl !== undefined) {
-    // TTL is in seconds, convert to `expires`
-    const expires = new Date(now + exchange.ttl * 1000);
-    meta.expires = expires;
-    exchange.expires = expires.toISOString().replace(/\.\d+Z$/, 'Z');
-    delete exchange.ttl;
+  if(exchange.expires !== undefined) {
+    meta.expires = new Date(exchange.expires);
   }
   const {localId: localWorkflowId} = parseLocalId({id: workflowId});
   const record = {
@@ -569,7 +569,11 @@ function _buildUpdate({exchange, complete}) {
   const now = Date.now();
   const update = {
     $inc: {'exchange.sequence': 1},
-    $set: {'exchange.state': exchange.state, 'meta.updated': now},
+    $set: {
+      'exchange.state': exchange.state,
+      'exchange.secrets': exchange.secrets,
+      'meta.updated': now
+    },
     $unset: {}
   };
   if(complete && typeof exchange.variables !== 'string') {

package/lib/helpers.js

@@ -4,6 +4,7 @@
 import * as bedrock from '@bedrock/core';
 import * as vcjwt from './vcjwt.js';
 import {decodeId, generateId} from 'bnid';
+import {compile} from '@bedrock/validation';
 import {Ed25519Signature2020} from '@digitalbazaar/ed25519-signature-2020';
 import {httpClient} from '@digitalbazaar/http-client';
 import {httpsAgent} from '@bedrock/https-agent';
@@ -86,6 +87,18 @@ export async function evaluateTemplate({
   return jsonata(template).evaluate(variables, variables);
 }
 
+export async function evaluateExchangeStep({
+  workflow, exchange, stepName = exchange.step
+}) {
+  let step = workflow.steps[stepName];
+  if(step.stepTemplate) {
+    step = await evaluateTemplate(
+      {workflow, exchange, typedTemplate: step.stepTemplate});
+  }
+  await validateStep({step});
+  return step;
+}
+
 export function getTemplateVariables({workflow, exchange} = {}) {
   const {variables = {}} = exchange;
   // always include `globals` as keyword for self-referencing exchange info
@@ -231,12 +244,16 @@ export function createVerifyOptions({
   options.checks = [...checkSet];
 
   // update `challenge`
-  options.challenge = expectedChallenge ??
-    verifiablePresentationRequest.challenge ??
-    presentation?.proof?.challenge;
+  if(options.challenge === undefined) {
+    options.challenge = expectedChallenge ??
+      verifiablePresentationRequest.challenge ??
+      presentation?.proof?.challenge;
+  }
 
   // update `domain`
-  options.domain = domain;
+  if(options.domain === undefined) {
+    options.domain = domain;
+  }
 
   return options;
 }
@@ -352,3 +369,11 @@ function _getEnvelope({envelope, format}) {
       details: {httpStatusCode: 400, public: true}
     });
 }
+
+export function validateVerifiablePresentation({schema, presentation}) {
+  const validate = compile({schema});
+  const {valid, error} = validate(presentation);
+  if(!valid) {
+    throw error;
+  }
+}

package/lib/http.js

@@ -1,10 +1,10 @@
 /*!
- * Copyright (c) 2018-2024 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2018-2025 Digital Bazaar, Inc. All rights reserved.
  */
 import * as bedrock from '@bedrock/core';
 import * as exchanges from './exchanges.js';
 import * as oid4 from './oid4/http.js';
-import {createExchange, processExchange} from './vcapi.js';
+import {createExchange, getProtocols, processExchange} from './vcapi.js';
 import {
   createExchangeBody, useExchangeBody
 } from '../schemas/bedrock-vc-workflow.js';
@@ -18,7 +18,8 @@ import {createValidateMiddleware as validate} from '@bedrock/validation';
 
 const {util: {BedrockError}} = bedrock;
 
-// FIXME: remove and apply at top-level application
+// FIXME: remove and apply to specific routes via
+// `bedrock.express.bodyParser.routes` + `@bedrock/express@8.4`
 bedrock.events.on('bedrock-express.configure.bodyParser', app => {
   app.use(bodyParser.json({
     // allow json values that are not just objects or arrays
@@ -66,7 +67,7 @@ export async function addRoutes({app, service} = {}) {
   app.post(
     routes.exchanges,
     cors(),
-    validate({bodySchema: createExchangeBody}),
+    validate({bodySchema: createExchangeBody()}),
     getConfigMiddleware,
     middleware.authorizeServiceObjectRequest(),
     asyncHandler(async (req, res) => {
@@ -75,11 +76,13 @@ export async function addRoutes({app, service} = {}) {
       try {
         const {config: workflow} = req.serviceObject;
         const {
-          ttl, openId, variables = {},
-          // allow steps to be skipped by creator as needed
-          step = workflow.initialStep
+          expires,
+          ttl,
+          variables = {},
+          step,
+          openId
         } = req.body;
-        const exchange = {ttl, openId, variables, step};
+        const exchange = {expires, ttl, variables, step, openId};
         const {id} = await createExchange({workflow, exchange});
         const location = `${workflow.id}/exchanges/${id}`;
         res.status(204).location(location).send();
@@ -101,8 +104,9 @@ export async function addRoutes({app, service} = {}) {
     middleware.authorizeServiceObjectRequest(),
     asyncHandler(async (req, res) => {
       const {exchange} = await req.getExchange();
-      // do not return any oauth2 credentials
+      // do not return any secret credentials
       delete exchange.openId?.oauth2?.keyPair?.privateKeyJwk;
+      delete exchange.secrets;
       res.json({exchange});
     }));
 
@@ -138,28 +142,8 @@ export async function addRoutes({app, service} = {}) {
             details: {httpStatusCode: 406, public: true}
           });
       }
-      // construct and return `protocols` object
-      const {config: workflow} = req.serviceObject;
-      const {exchange} = await req.getExchange();
-      const exchangeId = `${workflow.id}/exchanges/${exchange.id}`;
-      const protocols = {
-        vcapi: exchangeId
-      };
-      const openIdRoute = `${exchangeId}/openid`;
-      if(oid4.supportsOID4VCI({exchange})) {
-        // OID4VCI supported; add credential offer URL
-        const searchParams = new URLSearchParams();
-        const uri = `${openIdRoute}/credential-offer`;
-        searchParams.set('credential_offer_uri', uri);
-        protocols.OID4VCI = `openid-credential-offer://?${searchParams}`;
-      } else if(await oid4.supportsOID4VP({workflow, exchange})) {
-        // OID4VP supported; add openid4vp URL
-        const searchParams = new URLSearchParams({
-          client_id: `${openIdRoute}/client/authorization/response`,
-          request_uri: `${openIdRoute}/client/authorization/request`
-        });
-        protocols.OID4VP = `openid4vp://?${searchParams}`;
-      }
+
+      const protocols = await getProtocols({req});
       res.json({protocols});
     }));
 

package/lib/index.js

@@ -4,9 +4,11 @@
 import * as bedrock from '@bedrock/core';
 import * as workflowSchemas from '../schemas/bedrock-vc-workflow.js';
 import {createService, schemas} from '@bedrock/service-core';
+import {
+  MAX_ISSUER_INSTANCES, MAX_OID4VP_CLIENT_PROFILES
+} from './constants.js';
 import {addRoutes} from './http.js';
 import {initializeServiceAgent} from '@bedrock/service-agent';
-import {MAX_ISSUER_INSTANCES} from './constants.js';
 import {parseLocalId} from './helpers.js';
 import '@bedrock/express';
 
@@ -37,8 +39,9 @@ async function _initService({serviceType, routePrefix}) {
     schema.properties.issuerInstances = issuerInstances;
     // allow zcaps by custom reference ID
     schema.properties.zcaps = structuredClone(schemas.zcaps);
-    // max of 4 basic zcaps + max issuer instances
-    schema.properties.zcaps.maxProperties = 4 + MAX_ISSUER_INSTANCES;
+    // max of 3 basic zcaps + max issuer instances + max OID4VP client profiles
+    schema.properties.zcaps.maxProperties =
+      3 + MAX_ISSUER_INSTANCES + MAX_OID4VP_CLIENT_PROFILES;
     schema.properties.zcaps.additionalProperties = schemas.delegatedZcap;
     // note: credential templates are not required; if any other properties
     // become required, add them here
@@ -65,6 +68,9 @@ async function _initService({serviceType, routePrefix}) {
       },
       // these zcaps are optional (by reference ID)
       zcapReferenceIds: [{
+        // `issue` reference ID is deprecated; use `issuerInstances` option
+        // instead to specify issuer options and an `issue` zcap for each
+        // issuer instance
         referenceId: 'issue',
         required: false
       }, {

package/lib/oid4/authorizationRequest.js

@@ -0,0 +1,238 @@
+/*!
+ * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import {AsymmetricKey, KmsClient} from '@digitalbazaar/webkms-client';
+import {exportJWK, generateKeyPair, UnsecuredJWT} from 'jose';
+import {oid4vp, signJWT} from '@digitalbazaar/oid4-client';
+import {getClientBaseUrl} from './clientProfiles.js';
+import {getZcapClient} from '../helpers.js';
+import {httpsAgent} from '@bedrock/https-agent';
+import {randomUUID} from 'node:crypto';
+
+const {util: {BedrockError}} = bedrock;
+
+export async function create({
+  workflow, exchange,
+  clientProfile, clientProfileId,
+  verifiablePresentationRequest
+}) {
+  const authorizationRequest = oid4vp.fromVpr({verifiablePresentationRequest});
+
+  // get params from step OID4VP client profile to apply to the AR
+  const {
+    client_id, client_id_scheme,
+    nonce,
+    presentation_definition,
+    response_mode, response_uri
+  } = clientProfile;
+  const clientBaseUrl = getClientBaseUrl({workflow, exchange, clientProfileId});
+
+  // client_id_scheme (draft versions of OID4VP use this param)
+  authorizationRequest.client_id_scheme = client_id_scheme ?? 'redirect_uri';
+
+  // presentation_definition
+  authorizationRequest.presentation_definition = presentation_definition ??
+    authorizationRequest.presentation_definition;
+
+  // response_mode
+  authorizationRequest.response_mode = response_mode ?? 'direct_post';
+
+  // response_uri
+  authorizationRequest.response_uri = response_uri ??
+    `${clientBaseUrl}/authorization/response`;
+
+  // client_id (defaults to `response_uri`)
+  // FIXME: newer versions of OID4VP require a prefix of `redirect_uri:` for
+  // the default case -- which is incompatible with some draft versions
+  authorizationRequest.client_id = client_id ??
+    authorizationRequest.response_uri;
+
+  // `x509_san_dns` requires the `direct_post.jwt` response mode when using
+  // `direct_post`
+  if(authorizationRequest.response_mode === 'direct_post' &&
+    oid4vp.authzRequest.usesClientIdScheme({
+      authorizationRequest, scheme: 'x509_san_dns'
+    })) {
+    authorizationRequest.response_mode += '.jwt';
+  }
+
+  // nonce
+  if(nonce) {
+    authorizationRequest.nonce = nonce;
+  } else if(authorizationRequest.nonce === undefined) {
+    // if no nonce has been set for the authorization request, use the
+    // exchange ID
+    authorizationRequest.nonce = exchange.id;
+  }
+
+  // client_metadata; create from the `clientProfile` the rest of the AR and
+  // generate any necessary secrets for it
+  const {client_metadata, secrets} = await _createClientMetaData({
+    authorizationRequest, clientProfile
+  });
+  authorizationRequest.client_metadata = client_metadata;
+
+  // only set default `aud` for signed OID4VP authz requests
+  if(client_metadata.require_signed_request_object) {
+    authorizationRequest.aud = 'https://self-issued.me/v2';
+  }
+
+  return {authorizationRequest, secrets};
+}
+
+export async function encode({
+  workflow, clientProfile, authorizationRequest
+} = {}) {
+  // if required, construct authz request as signed JWT
+  if(authorizationRequest.client_metadata.require_signed_request_object) {
+    return _createJwt({workflow, clientProfile, authorizationRequest});
+  }
+
+  // construct authz request as unsecured JWT
+  return new UnsecuredJWT(authorizationRequest).encode();
+}
+
+async function _createClientMetaData({
+  authorizationRequest, clientProfile
+} = {}) {
+  // for storing client profile secrets
+  const secrets = {};
+
+  // create base `client_metadata` from client profile if given
+  const client_metadata = clientProfile.client_metadata ?
+    structuredClone(clientProfile.client_metadata) : {};
+
+  // ensure `vp_formats` exists and track whether it was present or not
+  const hasVpFormats = !!client_metadata.vp_formats;
+  if(!hasVpFormats) {
+    client_metadata.vp_formats = {};
+  }
+
+  // add `mso_mdoc` format if requested and not already present
+  if(!client_metadata.vp_formats.mso_mdoc &&
+    oid4vp.authzRequest.requestsFormat({
+      authorizationRequest, format: 'mso_mdoc'
+    })) {
+    client_metadata.vp_formats.mso_mdoc = {
+      alg: ['EdDSA', 'ES256']
+    };
+  }
+
+  // add `jwt_vp` format if requested and not already present
+  if(!client_metadata.vp_formats.jwt_vp &&
+    oid4vp.authzRequest.requestsFormat({
+      authorizationRequest, format: 'jwt_vp'
+    })) {
+    // support various aliases for different versions of OID4VP
+    client_metadata.vp_formats.jwt_vp =
+    client_metadata.vp_formats.jwt_vp_json = {
+      alg: ['EdDSA', 'Ed25519', 'ES256', 'ES384']
+    };
+  }
+
+  // add `ldp_vp` format if requested and not already present or if no other
+  // formats are present
+  if(!hasVpFormats || (!client_metadata.vp_formats.ldp_vp &&
+    oid4vp.authzRequest.requestsFormat({
+      authorizationRequest, format: 'ldp_vp'
+    }))) {
+    // support various aliases for different versions of OID4VP
+    client_metadata.vp_formats.di_vp =
+    client_metadata.vp_formats.ldp_vp = {
+      proof_type: [
+        'ecdsa-rdfc-2019',
+        'eddsa-rdfc-2022',
+        'Ed25519Signature2020'
+      ]
+    };
+  }
+
+  // `x509_san_dns` client ID scheme requires authz request signing;
+  // any client ID scheme that requires this
+  if(oid4vp.authzRequest.usesClientIdScheme({
+    authorizationRequest, scheme: 'x509_san_dns'
+  })) {
+    client_metadata.require_signed_request_object = true;
+  }
+
+  // for response mode `direct_post.jwt`, offer encryption options
+  if(authorizationRequest.response_mode === 'direct_post.jwt') {
+    // generate ECDH-ES P-256 key
+    const kp = await generateKeyPair('ECDH-ES', {
+      crv: 'P-256', extractable: true
+    });
+    const [privateKeyJwk, publicKeyJwk] = await Promise.all([
+      exportJWK(kp.privateKey),
+      exportJWK(kp.publicKey)
+    ]);
+    publicKeyJwk.use = 'enc';
+    publicKeyJwk.alg = 'ECDH-ES';
+    privateKeyJwk.kid = publicKeyJwk.kid = `urn:uuid:${randomUUID()}`;
+    secrets.keyAgreementKeyPairs = [{privateKeyJwk, publicKeyJwk}];
+
+    // create / prepend to public JWK key set
+    client_metadata.jwks = {
+      ...client_metadata.jwks,
+      keys: [publicKeyJwk].concat(client_metadata.jwks?.keys ?? [])
+    };
+  }
+
+  return {client_metadata, secrets};
+}
+
+async function _createJwt({workflow, clientProfile, authorizationRequest}) {
+  try {
+    // create zcap client
+    const {zcapClient, zcaps} = await getZcapClient({workflow});
+
+    // get any `x5c` and the zcap to use to sign the authz request via
+    // the client profile
+    const {
+      authorizationRequestSigningParameters: {x5c} = {},
+      zcapReferenceIds: {signAuthorizationRequest: refId} = {}
+    } = clientProfile;
+    if(refId === undefined) {
+      throw new BedrockError(
+        'The OID4VP client profile does not specify which capability in the ' +
+        'workflow configuration to use to sign authorization requests.', {
+          name: 'DataError',
+          details: {httpStatusCode: 500, public: true}
+        });
+    }
+    const capability = zcaps[refId];
+    if(capability === undefined) {
+      throw new BedrockError(
+        'The capability specified by the OID4VP client profile for signing ' +
+        'authorization requests was not found in the workflow configuration.', {
+          name: 'DataError',
+          details: {httpStatusCode: 500, public: true}
+        });
+    }
+
+    // create a WebKMS `signer` interface
+    const {invocationSigner} = zcapClient;
+    const kmsClient = new KmsClient({httpsAgent});
+    const signer = await AsymmetricKey.fromCapability({
+      capability, invocationSigner, kmsClient
+    });
+    const keyDescription = await signer.getKeyDescription();
+    const kid = keyDescription.id;
+
+    // create the JWT payload and header to be signed
+    const payload = {
+      ...authorizationRequest
+    };
+    const protectedHeader = {typ: 'JWT', alg: 'ES256', kid, x5c};
+
+    // create the JWT
+    return signJWT({payload, protectedHeader, signer});
+  } catch(cause) {
+    throw new BedrockError(
+      `Could not sign authorization request: ${cause.message}`, {
+        name: cause instanceof BedrockError ? cause.name : 'OperationError',
+        cause,
+        details: {httpStatusCode: 500, public: true}
+      });
+  }
+}

package/lib/oid4/authorizationResponse.js

@@ -0,0 +1,117 @@
+/*!
+ * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import {
+  presentationSubmission as presentationSubmissionSchema,
+  verifiablePresentation as verifiablePresentationSchema
+} from '../../schemas/bedrock-vc-workflow.js';
+import {compile} from '@bedrock/validation';
+import {oid4vp} from '@digitalbazaar/oid4-client';
+import {unenvelopePresentation} from '../helpers.js';
+
+const {util: {BedrockError}} = bedrock;
+
+const VALIDATORS = {
+  presentation: null,
+  presentationSubmission: null
+};
+
+const VC_CONTEXT_2 = 'https://www.w3.org/ns/credentials/v2';
+
+bedrock.events.on('bedrock.init', () => {
+  // create validators for x-www-form-urlencoded parsed data
+  VALIDATORS.presentation = compile({schema: verifiablePresentationSchema()});
+  VALIDATORS.presentationSubmission = compile({
+    schema: presentationSubmissionSchema
+  });
+});
+
+export async function parse({req, exchange, clientProfileId} = {}) {
+  try {
+    const {body} = req;
+    const {
+      responseMode, parsed, protectedHeader
+    } = await oid4vp.verifier.parseAuthorizationResponse({
+      body,
+      getDecryptParameters() {
+        return _getDecryptParameters({exchange, clientProfileId});
+      }
+    });
+
+    // validate parsed presentation submission
+    const {presentationSubmission} = parsed;
+    _validate(VALIDATORS.presentationSubmission, presentationSubmission);
+
+    // obtain `presentation` and optional `envelope` from parsed `vpToken`
+    const {vpToken} = parsed;
+    let presentation;
+    let envelope;
+
+    if(oid4vp.authzResponse.submitsFormat({
+      presentationSubmission, format: 'mso_mdoc'
+    })) {
+      // `vp_token` is declared to be a base64url-encoded mDL device response
+      presentation = {
+        '@context': VC_CONTEXT_2,
+        id: `data:application/mdl-vp-token,${vpToken}`,
+        type: 'EnvelopedVerifiablePresentation'
+      };
+    } else if(typeof vpToken === 'string') {
+      // FIXME: remove unenveloping here and delegate it to VC API verifier;
+      // FIXME: check if envelope matches submission once verified
+      const {
+        envelope: raw, presentation: contents, format
+      } = await unenvelopePresentation({
+        envelopedPresentation: vpToken,
+        // FIXME: check `presentationSubmission` for VP format
+        format: 'application/jwt'
+      });
+      _validate(VALIDATORS.presentation, contents);
+      presentation = {
+        '@context': VC_CONTEXT_2,
+        id: `data:${format},${raw}`,
+        type: 'EnvelopedVerifiablePresentation'
+      };
+      envelope = {raw, contents, format};
+    } else {
+      // simplest case: `vpToken` is a VP; validate it
+      presentation = vpToken;
+      _validate(VALIDATORS.presentation, presentation);
+      // FIXME: validate VP against presentation submission
+    }
+
+    return {
+      responseMode,
+      presentationSubmission,
+      presentation,
+      envelope,
+      protectedHeader
+    };
+  } catch(cause) {
+    throw new BedrockError(
+      `Could not parse authorization response: ${cause.message}`, {
+        name: cause.name ?? 'OperationError',
+        cause,
+        details: {
+          httpStatusCode: cause?.details?.httpStatusCode ?? 400,
+          public: true
+        }
+      });
+  }
+}
+
+function _getDecryptParameters({exchange, clientProfileId}) {
+  // get private key agreement keys in JWT format
+  const {keyAgreementKeyPairs} = exchange.secrets?.oid4vp?.clientProfiles
+    ?.[clientProfileId ?? 'default'] ?? {};
+  const keys = keyAgreementKeyPairs.map(({privateKeyJwk}) => privateKeyJwk);
+  return {keys};
+}
+
+function _validate(validator, data) {
+  const result = validator(data);
+  if(!result.valid) {
+    throw result.error;
+  }
+}

package/lib/oid4/clientProfiles.js

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) 2022-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+const {util: {BedrockError}} = bedrock;
+
+export function getClientBaseUrl({workflow, exchange, clientProfileId}) {
+  const openIdBaseUrl = `${workflow.id}/exchanges/${exchange.id}/openid`;
+  return openIdBaseUrl + (clientProfileId !== undefined ?
+    `/clients/${clientProfileId}` : '/client');
+}
+
+export function getClientProfile({step, clientProfileId}) {
+  const {openId: {clientProfiles}} = step;
+
+  let clientProfile;
+  if(clientProfileId !== undefined) {
+    if(clientProfiles) {
+      clientProfile = clientProfiles[clientProfileId];
+    }
+  } else if(!clientProfiles) {
+    // legacy step without any client profiles
+    clientProfile = step.openId;
+  }
+
+  if(!clientProfile) {
+    throw new BedrockError(
+      'The selected OID4VP profile is not supported by this exchange.', {
+        name: 'NotSupportedError',
+        details: {httpStatusCode: 400, public: true}
+      });
+  }
+
+  return clientProfile;
+}