@bedrock/vc-delivery 1.0.0 → 3.0.0

package/lib/http.js

@@ -1,13 +1,14 @@
 /*!
- * Copyright (c) 2018-2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2018-2023 Digital Bazaar, Inc. All rights reserved.
  */
+import * as _openId from './openId.js';
 import * as bedrock from '@bedrock/core';
 import * as exchanges from './exchanges.js';
-import * as oidc4vci from './oidc4vci.js';
 import {createChallenge as _createChallenge, verify} from './verify.js';
 import {
   createExchangeBody, useExchangeBody
 } from '../schemas/bedrock-vc-exchanger.js';
+import {exportJWK, generateKeyPair, importJWK} from 'jose';
 import {metering, middleware} from '@bedrock/service-core';
 import {asyncHandler} from '@bedrock/express';
 import bodyParser from 'body-parser';
@@ -70,7 +71,7 @@ export async function addRoutes({app, service} = {}) {
       try {
         const {config} = req.serviceObject;
         const {
-          ttl, oidc4vci, variables = {},
+          ttl, openId, variables = {},
           // allow steps to be skipped by creator as needed
           step = config.initialStep
         } = req.body;
@@ -83,13 +84,41 @@ export async function addRoutes({app, service} = {}) {
           });
         }
 
+        // perform key generation if requested
+        if(openId?.oauth2?.generateKeyPair) {
+          const {oauth2} = openId;
+          const {algorithm} = oauth2.generateKeyPair;
+          const kp = await generateKeyPair(algorithm, {extractable: true});
+          const [privateKeyJwk, publicKeyJwk] = await Promise.all([
+            exportJWK(kp.privateKey),
+            exportJWK(kp.publicKey),
+          ]);
+          oauth2.keyPair = {privateKeyJwk, publicKeyJwk};
+          delete oauth2.generateKeyPair;
+        } else if(openId) {
+          // ensure key pair can be imported
+          try {
+            const {oauth2: {keyPair}} = openId;
+            await Promise.all([
+              importJWK(keyPair.privateKeyJwk),
+              importJWK(keyPair.publicKeyJwk)
+            ]);
+          } catch(e) {
+            throw new BedrockError('Could not import OpenID OAuth2 key pair.', {
+              name: 'DataError',
+              details: {httpStatusCode: 400, public: true},
+              cause: e
+            });
+          }
+        }
+
         // insert exchange
         const {id: exchangerId} = config;
         const exchange = {
           id: await generateRandom(),
           ttl,
           variables,
-          oidc4vci,
+          openId,
           step
         };
         await exchanges.insert({exchangerId, exchange});
@@ -189,7 +218,7 @@ export async function addRoutes({app, service} = {}) {
       res.json({verifiablePresentation});
     }));
 
-  // create OIDC4VCI routes to be used with each individual exchange
-  await oidc4vci.createRoutes(
+  // create OID4VCI routes to be used with each individual exchange
+  await _openId.createRoutes(
     {app, exchangeRoute: routes.exchange, getConfigMiddleware, getExchange});
 }

package/lib/index.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
  */
 import * as bedrock from '@bedrock/core';
 import * as exchangerSchemas from '../schemas/bedrock-vc-exchanger.js';

package/lib/{oidc4vci.js → openId.js}

@@ -1,10 +1,10 @@
 /*!
- * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
  */
 import * as exchanges from './exchanges.js';
 import {importJWK, SignJWT} from 'jose';
 import {
-  oidc4vciCredentialBody, oidc4vciTokenBody
+  openIdBatchCredentialBody, openIdCredentialBody, openIdTokenBody
 } from '../schemas/bedrock-vc-exchanger.js';
 import {asyncHandler} from '@bedrock/express';
 import bodyParser from 'body-parser';
@@ -15,10 +15,10 @@ import {timingSafeEqual} from 'node:crypto';
 import {createValidateMiddleware as validate} from '@bedrock/validation';
 import {verifyDidProofJwt} from './verify.js';
 
-/* NOTE: Parts of the OIDC4VCI design imply tight integration between the
+/* NOTE: Parts of the OID4VCI design imply tight integration between the
 authorization server and the credential issuance / delivery server. This
 file provides the routes for both and treats them as integrated; supporting
-the OIDC4VCI pre-authz code flow only as a result. However, we also try to
+the OID4VCI pre-authz code flow only as a result. However, we also try to
 avoid tight-coupling where possible to enable the non-pre-authz code flow
 that would use, somehow, a separate authorization server.
 
@@ -30,7 +30,7 @@ authentic without breaking some abstraction around how the Authorization
 Server is implemented behind its API. Here we do not implement this option,
 instead, if a challenge is required, the credential delivery server will send
 an error with the challenge nonce if one was not provided in the payload to the
-credential endpoint. This error follows the OIDC4VCI spec and avoids this
+credential endpoint. This error follows the OID4VCI spec and avoids this
 particular tight coupling.
 
 Other tight couplings cannot be avoided at this time -- such as the fact that
@@ -43,17 +43,18 @@ instantiating a new authorization server instance per VC exchange. */
 const PRE_AUTH_GRANT_TYPE =
   'urn:ietf:params:oauth:grant-type:pre-authorized_code';
 
-// creates OIDC4VCI Authorization Server + Credential Delivery Server
+// creates OID4VCI Authorization Server + Credential Delivery Server
 // endpoints for each individual exchange
 export async function createRoutes({
   app, exchangeRoute, getConfigMiddleware, getExchange
 } = {}) {
-  const oidc4vciRoute = `${exchangeRoute}/oidc4vci`;
+  const openIdRoute = `${exchangeRoute}/openid`;
   const routes = {
     asMetadata: `/.well-known/oauth-authorization-server${exchangeRoute}`,
-    credential: `${oidc4vciRoute}/credential`,
-    token: `${oidc4vciRoute}/token`,
-    jwks: `${oidc4vciRoute}/jwks`
+    batchCredential: `${openIdRoute}/batch_credential`,
+    credential: `${openIdRoute}/credential`,
+    token: `${openIdRoute}/token`,
+    jwks: `${openIdRoute}/jwks`
   };
 
   // urlencoded body parser (extended=true for rich JSON-like representation)
@@ -72,9 +73,11 @@ export async function createRoutes({
       const exchangeId = `${exchanger.id}/exchanges/${req.params.exchangeId}`;
       const oauth2Config = {
         issuer: exchangeId,
-        jwks_uri: `${exchangeId}/oidc4vci/jwks`,
-        token_endpoint: `${exchangeId}/oidc4vci/token`,
-        credential_endpoint: `${exchangeId}/oidc4vci/credential`
+        jwks_uri: `${exchangeId}/openid/jwks`,
+        token_endpoint: `${exchangeId}/openid/token`,
+        credential_endpoint: `${exchangeId}/openid/credential`,
+        batch_credential_endpoint: `${exchangeId}/openid/batch_credential`
+        // FIXME: add `credentials_supported`
       };
       res.json(oauth2Config);
     }));
@@ -88,13 +91,13 @@ export async function createRoutes({
     getExchange,
     asyncHandler(async (req, res) => {
       const {exchange} = await req.exchange;
-      if(!exchange.oidc4vci) {
+      if(!exchange.openId) {
         // FIXME: improve error
         // unsupported protocol for the exchange
         throw new Error('unsupported protocol');
       }
       // serve exchange's public key
-      res.json({keys: [exchange.oidc4vci.oauth2.keyPair.publicKeyJwk]});
+      res.json({keys: [exchange.openId.oauth2.keyPair.publicKeyJwk]});
     }));
 
   // an authorization server endpoint
@@ -105,13 +108,13 @@ export async function createRoutes({
     routes.token,
     cors(),
     urlencoded,
-    validate({bodySchema: oidc4vciTokenBody}),
+    validate({bodySchema: openIdTokenBody}),
     getConfigMiddleware,
     getExchange,
     asyncHandler(async (req, res) => {
       const exchangeRecord = await req.exchange;
       const {exchange} = exchangeRecord;
-      if(!exchange.oidc4vci) {
+      if(!exchange.openId) {
         // FIXME: improve error
         // unsupported protocol for the exchange
         throw new Error('unsupported protocol');
@@ -142,7 +145,7 @@ export async function createRoutes({
       }
 
       // validate grant type
-      const {oidc4vci: {preAuthorizedCode: expectedCode}} = exchange;
+      const {openId: {preAuthorizedCode: expectedCode}} = exchange;
       if(expectedCode) {
         // ensure expected pre-authz code matches
         if(!timingSafeEqual(
@@ -173,7 +176,7 @@ export async function createRoutes({
   app.post(
     routes.credential,
     cors(),
-    validate({bodySchema: oidc4vciCredentialBody}),
+    validate({bodySchema: openIdCredentialBody}),
     getConfigMiddleware,
     getExchange,
     asyncHandler(async (req, res) => {
@@ -184,8 +187,17 @@ export async function createRoutes({
       Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW
 
       {
-        "type": "https://did.example.org/healthCard"
         "format": "ldp_vc",
+        "credential_description": {
+          "@context": [
+            "https://www.w3.org/2018/credentials/v1",
+            "https://www.w3.org/2018/credentials/examples/v1"
+          ],
+          "type": [
+            "VerifiableCredential",
+            "UniversityDegreeCredential"
+          ]
+        },
         "did": "did:example:ebfeb1f712ebc6f1c276e12ec21",
         "proof": {
           "proof_type": "jwt",
@@ -193,54 +205,72 @@ export async function createRoutes({
         }
       }
       */
-      const {config: exchanger} = req.serviceObject;
-      const exchangeRecord = await req.exchange;
-      const {exchange} = exchangeRecord;
-      if(!exchange.oidc4vci) {
-        // FIXME: improve error
-        // unsupported protocol for the exchange
-        throw new Error('unsupported protocol');
+      const result = await _processCredentialRequests(
+        {req, res, isBatchRequest: false});
+      if(!result) {
+        // DID proof request response sent
+        return;
       }
 
-      // ensure oauth2 access token is valid
-      await _checkAuthz({req, exchanger, exchange});
+      // send VC
+      res.json({
+        format: 'ldp_vc',
+        /* Note: The `/credential` route only supports sending a single VC;
+        assume here that this exchanger is configured for a single VC and an
+        error code would have been sent to the client to use the batch
+        endpoint if there was more than one VC to deliver. */
+        credential: result.verifiablePresentation.verifiableCredential[0]
+      });
+    }));
 
-      // process exchange step if present
-      if(exchange.step) {
-        const step = exchanger.steps[exchange.step];
+  // a batch credential delivery server endpoint
+  // receives N credential requests and returns N VCs
+  app.options(routes.batchCredential, cors());
+  app.post(
+    routes.batchCredential,
+    cors(),
+    validate({bodySchema: openIdBatchCredentialBody}),
+    getConfigMiddleware,
+    getExchange,
+    asyncHandler(async (req, res) => {
+      /* Clients must POST, e.g.:
+      POST /batch_credential HTTP/1.1
+      Host: server.example.com
+      Content-Type: application/json
+      Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW
 
-        // handle JWT DID Proof request; if step requires it, then `proof` must
-        // be in the credential request
-        if(step.jwtDidProofRequest) {
-          // if no proof is in the body...
-          if(!req?.body?.proof?.jwt) {
-            return _requestDidProof({res, exchangeRecord});
+      {
+        credential_requests: [{
+          "format": "ldp_vc",
+          "credential_description": {
+            "@context": [
+              "https://www.w3.org/2018/credentials/v1",
+              "https://www.w3.org/2018/credentials/examples/v1"
+            ],
+            "type": [
+              "VerifiableCredential",
+              "UniversityDegreeCredential"
+            ]
+          },
+          "did": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+          "proof": {
+            "proof_type": "jwt",
+            "jwt": "eyJra...nOzM"
           }
-          // verify the DID proof
-          const {body: {proof: {jwt}}} = req;
-          const {did} = await verifyDidProofJwt({exchanger, exchange, jwt});
-          // add `did` to exchange variables
-          exchange.variables[exchange.step] = {did};
-        }
+        }]
+      }
+      */
+      const result = await _processCredentialRequests(
+        {req, res, isBatchRequest: true});
+      if(!result) {
+        // DID proof request response sent
+        return;
       }
 
-      // mark exchange complete
-      await exchanges.complete({exchangerId: exchanger.id, id: exchange.id});
-
-      // FIXME: decide what the best recovery path is if delivery fails (but no
-      // replay attack detected) after exchange has been marked complete
-
-      // issue VCs
-      const {verifiablePresentation} = await issue({exchanger, exchange});
-
-      // send VC
-      res.json({
-        format: 'ldp_vc',
-        /* Note: OIDC4VCI only supports sending a single VC; assume here that
-        the exchanger is configured to only allow OIDC4VCI when a single
-        VC is being issued. */
-        credential: verifiablePresentation.verifiableCredential[0]
-      });
+      // send VCs
+      const responses = result.verifiablePresentation.verifiableCredential.map(
+        vc => ({format: 'ldp_vc', credential: vc}));
+      res.json({credential_responses: responses});
     }));
 }
 
@@ -253,7 +283,7 @@ async function _createExchangeAccessToken({exchanger, exchangeRecord}) {
   // FIXME: allow per-service-object-instance agent via `signer` and custom
   // JWT signer code instead?
   const {exchange} = exchangeRecord;
-  const {oidc4vci: {oauth2: {keyPair: {privateKeyJwk}}}} = exchange;
+  const {openId: {oauth2: {keyPair: {privateKeyJwk}}}} = exchange;
   const exchangeId = `${exchanger.id}/exchanges/${exchange.id}`;
   const {accessToken, ttl} = await _createOAuth2AccessToken({
     privateKeyJwk, audience: exchangeId, action: 'write', target: exchangeId,
@@ -265,9 +295,10 @@ async function _createExchangeAccessToken({exchanger, exchangeRecord}) {
 async function _createOAuth2AccessToken({
   privateKeyJwk, audience, action, target, exp, iss, nbf, typ = 'at+jwt'
 }) {
+  const alg = _getAlgFromPrivateKey({privateKeyJwk});
   const scope = `${action}:${target}`;
   const builder = new SignJWT({scope})
-    .setProtectedHeader({alg: 'EdDSA', typ})
+    .setProtectedHeader({alg, typ})
     .setIssuer(iss)
     .setAudience(audience);
   let ttl;
@@ -282,14 +313,14 @@ async function _createOAuth2AccessToken({
   if(nbf !== undefined) {
     builder.setNotBefore(nbf);
   }
-  const key = await importJWK({...privateKeyJwk, alg: 'EdDSA'});
+  const key = await importJWK({...privateKeyJwk, alg});
   const accessToken = await builder.sign(key);
   return {accessToken, ttl};
 }
 
 async function _checkAuthz({req, exchanger, exchange}) {
   // optional oauth2 options
-  const {oauth2} = exchange.oidc4vci;
+  const {oauth2} = exchange.openId;
   const {maxClockSkew} = oauth2;
 
   // audience is always the `exchangeId` and cannot be configured; this
@@ -311,6 +342,97 @@ async function _checkAuthz({req, exchanger, exchange}) {
   await checkAccessToken({req, issuerConfigUrl, maxClockSkew, audience});
 }
 
+function _getAlgFromPrivateKey({privateKeyJwk}) {
+  if(privateKeyJwk.alg) {
+    return privateKeyJwk.alg;
+  }
+  if(privateKeyJwk.kty === 'EC' && privateKeyJwk.crv) {
+    if(privateKeyJwk.crv.startsWith('P-')) {
+      return `ES${privateKeyJwk.crv.slice(2)}`;
+    }
+    if(privateKeyJwk.crv === 'secp256k1') {
+      return 'ES256K';
+    }
+  }
+  if(privateKeyJwk.kty === 'OKP' && privateKeyJwk.crv?.startsWith('Ed')) {
+    return 'EdDSA';
+  }
+  if(privateKeyJwk.kty === 'RSA') {
+    return 'PS256';
+  }
+  return 'invalid';
+}
+
+async function _processCredentialRequests({req, res, isBatchRequest}) {
+  const {config: exchanger} = req.serviceObject;
+  const exchangeRecord = await req.exchange;
+  const {exchange} = exchangeRecord;
+  if(!exchange.openId) {
+    // FIXME: improve error
+    // unsupported protocol for the exchange
+    throw new Error('unsupported protocol');
+  }
+
+  // ensure oauth2 access token is valid
+  await _checkAuthz({req, exchanger, exchange});
+
+  // validate body against expected credential requests
+  const {openId: {expectedCredentialRequests}} = exchange;
+  let credentialRequests;
+  if(isBatchRequest) {
+    ({credential_requests: credentialRequests} = req.body);
+  } else {
+    if(expectedCredentialRequests.length > 1) {
+      // clients interacting with exchanges with more than one VC to be
+      // delivered must use the "batch credential" endpoint
+      // FIXME: improve error
+      throw new Error('batch_credential_endpoint must be used');
+    }
+    credentialRequests = [req.body];
+  }
+  _assertCredentialRequests(
+    {credentialRequests, expectedCredentialRequests});
+
+  // process exchange step if present
+  if(exchange.step) {
+    const step = exchanger.steps[exchange.step];
+
+    // handle JWT DID Proof request; if step requires it, then `proof` must
+    // be in every credential request
+    if(step.jwtDidProofRequest) {
+      // if no proof is one of the requests...
+      if(credentialRequests.some(cr => !cr.proof?.jwt)) {
+        return _requestDidProof({res, exchangeRecord});
+      }
+      // verify every DID proof and get resulting DIDs
+      const results = await Promise.all(
+        credentialRequests.map(async cr => {
+          const {proof: {jwt}} = cr;
+          const {did} = await verifyDidProofJwt({exchanger, exchange, jwt});
+          return did;
+        }));
+      // require `did` to be the same for every proof
+      // FIXME: determine if this needs to be more flexible
+      const did = results[0];
+      if(results.some(d => did !== d)) {
+        // FIXME: improve error
+        throw new Error('every DID must be the same');
+      }
+      // add `did` to exchange variables
+      exchange.variables[exchange.step] = {did};
+    }
+  }
+
+  // mark exchange complete
+  await exchanges.complete({exchangerId: exchanger.id, id: exchange.id});
+
+  // FIXME: decide what the best recovery path is if delivery fails (but no
+  // replay attack detected) after exchange has been marked complete
+
+  // issue VCs
+  return issue({exchanger, exchange});
+}
+
 async function _requestDidProof({res, exchangeRecord}) {
   /* `9.4 Credential Issuer-provided nonce` allows the credential
   issuer infrastructure to provide the nonce via an error:
@@ -327,7 +449,7 @@ async function _requestDidProof({res, exchangeRecord}) {
     "c_nonce_expires_in": 86400
   }*/
 
-  /* OIDC4VCI exchanges themselves are not replayable and single-step, so the
+  /* OID4VCI exchanges themselves are not replayable and single-step, so the
   challenge to be signed is just the exchange ID itself. An exchange cannot
   be reused and neither can a challenge. */
   const {exchange, meta: {expires}} = exchangeRecord;
@@ -343,3 +465,27 @@ async function _requestDidProof({res, exchangeRecord}) {
     c_nonce_expires_in: ttl
   });
 }
+
+function _assertCredentialRequests({
+  credentialRequests, expectedCredentialRequests
+}) {
+  // ensure every credential request matches against an expected one and none
+  // are missing
+  if(!(credentialRequests.length === expectedCredentialRequests.length &&
+    credentialRequests.every(cr => expectedCredentialRequests.some(
+      ecr => _matchCredentialRequest(ecr, cr))))) {
+    // FIXME: improve error
+    throw new Error('unexpected credential request');
+  }
+}
+
+function _matchCredentialRequest(a, b) {
+  if(a.format !== b.format) {
+    return false;
+  }
+  const {credential_definition: {'@context': c1, type: t1}} = a;
+  const {credential_definition: {'@context': c2, type: t2}} = b;
+  // contexts must match exact order but types can have different order
+  return (c1.length === c2.length && t1.length === t2.length &&
+    c1.every((c, i) => c === c2[i]) && t1.every(t => t2.some(x => t === x)));
+}

package/lib/verify.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
  */
 import * as bedrock from '@bedrock/core';
 import {importJWK, jwtVerify} from 'jose';
@@ -60,7 +60,7 @@ export async function verify({
 
 export async function verifyDidProofJwt({exchanger, exchange, jwt} = {}) {
   // optional oauth2 options
-  const {oauth2} = exchange.oidc4vci;
+  const {oauth2} = exchange.openId;
   const {maxClockSkew} = oauth2;
 
   // audience is always the `exchangeId` and cannot be configured; this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/vc-delivery",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "Bedrock Verifiable Credential Delivery",
   "main": "./lib/index.js",
@@ -40,25 +40,25 @@
   "peerDependencies": {
     "@bedrock/app-identity": "4.0.0",
     "@bedrock/core": "^6.0.1",
-    "@bedrock/did-io": "^9.0.1",
+    "@bedrock/did-io": "^10.0.0",
     "@bedrock/express": "^8.0.0",
     "@bedrock/https-agent": "^4.0.0",
     "@bedrock/mongodb": "^10.0.0",
     "@bedrock/oauth2-verifier": "^1.0.0",
-    "@bedrock/service-agent": "^6.0.0",
-    "@bedrock/service-core": "^7.0.1",
+    "@bedrock/service-agent": "^7.0.0",
+    "@bedrock/service-core": "^8.0.0",
     "@bedrock/validation": "^7.1.0"
   },
   "directories": {
     "lib": "./lib"
   },
   "devDependencies": {
-    "eslint": "^8.18.0",
-    "eslint-config-digitalbazaar": "^4.0.1",
-    "eslint-plugin-jsdoc": "^39.3.3",
-    "eslint-plugin-unicorn": "^43.0.0",
-    "jsdoc": "^3.6.10",
-    "jsdoc-to-markdown": "^7.1.1"
+    "eslint": "^8.41.0",
+    "eslint-config-digitalbazaar": "^5.0.1",
+    "eslint-plugin-jsdoc": "^45.0.0",
+    "eslint-plugin-unicorn": "^47.0.0",
+    "jsdoc": "^4.0.2",
+    "jsdoc-to-markdown": "^8.0.0"
   },
   "engines": {
     "node": ">=16"