@bedrock/vc-delivery 4.0.0 → 4.1.0

package/lib/exchanges.js

@@ -84,7 +84,7 @@ export async function insert({exchangerId, exchange}) {
     localExchangerId,
     meta,
     // possible states are: `pending`, `complete`, or `invalid`
-    exchange: {...exchange, state: 'pending'}
+    exchange: {...exchange, sequence: 0, state: 'pending'}
   };
 
   // insert the exchange and get the updated record
@@ -153,6 +153,16 @@ export async function get({exchangerId, id, explain = false} = {}) {
     });
   }
 
+  // backwards compatibility; initialize `sequence`
+  if(record.exchange.sequence === undefined) {
+    await collection.updateOne({
+      localExchangerId,
+      'exchange.id': id,
+      'exchange.sequence': null
+    }, {$set: {'exchange.sequence': 0}});
+    record.exchange.sequence = 0;
+  }
+
   return record;
 }
 
@@ -163,29 +173,25 @@ export async function get({exchangerId, id, explain = false} = {}) {
  * @param {string} options.exchangerId - The ID of the exchanger the exchange
  *   is associated with.
  * @param {object} options.exchange - The exchange to update.
- * @param {string} [options.expectedStep] - The expected current step in the
- *   exchange.
  * @param {boolean} [options.explain=false] - An optional explain boolean.
  *
  * @returns {Promise<boolean | ExplainObject>} Resolves with `true` on update
  *   success or an ExplainObject if `explain=true`.
  */
-export async function update({
-  exchangerId, exchange, expectedStep, explain = false
-} = {}) {
+export async function update({exchangerId, exchange, explain = false} = {}) {
   assert.string(exchangerId, 'exchangerId');
   assert.object(exchange, 'exchange');
-  assert.optionalString(expectedStep, expectedStep);
   const {id} = exchange;
 
   // build update
   const now = Date.now();
   const update = {
+    $inc: {'exchange.sequence': 1},
     $set: {'meta.updated': now}
   };
-  // update exchange `variables.results[step]`, `step`, and `ttl`
-  if(exchange.variables?.results) {
-    update.$set['exchange.variables.results'] = exchange.variables.results;
+  // update exchange `variables`, `step`, and `ttl`
+  if(exchange.variables) {
+    update.$set['exchange.variables'] = exchange.variables;
   }
   if(exchange.step !== undefined) {
     update.$set['exchange.step'] = exchange.step;
@@ -200,15 +206,11 @@ export async function update({
   const query = {
     localExchangerId,
     'exchange.id': id,
+    // exchange sequence must match previous sequence
+    'exchange.sequence': exchange.sequence - 1,
     // previous state must be `pending` in order to update it
     'exchange.state': 'pending'
   };
-  // current step must match previous step
-  if(expectedStep === undefined) {
-    query['exchange.step'] = null;
-  } else {
-    query['exchange.step'] = expectedStep;
-  }
 
   if(explain) {
     // 'find().limit(1)' is used here because 'updateOne()' doesn't return a
@@ -259,24 +261,20 @@ export async function update({
  * @param {string} options.exchangerId - The ID of the exchanger the exchange
  *   is associated with.
  * @param {object} options.exchange - The exchange to mark as complete.
- * @param {string} [options.expectedStep] - The expected current step in the
- *   exchange.
  * @param {boolean} [options.explain=false] - An optional explain boolean.
  *
  * @returns {Promise<boolean | ExplainObject>} Resolves with `true` on update
  *   success or an ExplainObject if `explain=true`.
  */
-export async function complete({
-  exchangerId, exchange, expectedStep, explain = false
-} = {}) {
+export async function complete({exchangerId, exchange, explain = false} = {}) {
   assert.string(exchangerId, 'exchangerId');
   assert.object(exchange, 'exchange');
-  assert.optionalString(expectedStep, expectedStep);
   const {id} = exchange;
 
   // build update
   const now = Date.now();
   const update = {
+    $inc: {'exchange.sequence': 1},
     $set: {
       'exchange.state': 'complete',
       'meta.updated': now
@@ -299,15 +297,11 @@ export async function complete({
   const query = {
     localExchangerId,
     'exchange.id': id,
+    // exchange sequence must match previous sequence
+    'exchange.sequence': exchange.sequence - 1,
     // previous state must be `pending` in order to change to `complete`
     'exchange.state': 'pending'
   };
-  // current step must match previous step
-  if(expectedStep === undefined) {
-    query['exchange.step'] = null;
-  } else {
-    query['exchange.step'] = expectedStep;
-  }
 
   if(explain) {
     // 'find().limit(1)' is used here because 'updateOne()' doesn't return a
@@ -337,12 +331,29 @@ export async function complete({
   // exchange does not exist, a not found error will be automatically thrown
   const record = await get({exchangerId, id});
 
-  /* Note: Here the exchange *does* exist, but was already completed. This is
-  an error condition that must result in invalidating the exchange. */
+  /* Note: Here the exchange *does* exist, but couldn't be updated because
+  another process changed it. That change either left it in a still pending
+  state or it was already completed. If it was already completed, it is an
+  error condition that must result in invalidating the exchange. */
+  if(record.state === 'pending') {
+    // exchange still pending, another process updated it
+    throw new BedrockError('Could not update exchange; conflict error.', {
+      name: 'InvalidStateError',
+      details: {
+        public: true,
+        // this is a client-side conflict error
+        httpStatusCode: 409
+      }
+    });
+  }
 
-  // invalidate exchange, but do not throw any error to client; only log it
-  _invalidateExchange({record}).catch(
-    error => logger.error(`Could not invalidate exchange "${id}".`, {error}));
+  // state is either `complete` or `invalid`, so throw duplicate completed
+  // exchange error and invalidate exchange if needed, but do not throw any
+  // error to client; only log it
+  if(record.state !== 'invalid') {
+    _invalidateExchange({record}).catch(
+      error => logger.error(`Could not invalidate exchange "${id}".`, {error}));
+  }
 
   // throw duplicate completed exchange error
   throw new BedrockError('Could not complete exchange; already completed.', {

package/lib/helpers.js

@@ -11,11 +11,22 @@ import {ZcapClient} from '@digitalbazaar/ezcap';
 
 const {config} = bedrock;
 
-export async function evaluateTemplate({exchange, typedTemplate} = {}) {
+export async function evaluateTemplate({
+  exchanger, exchange, typedTemplate
+} = {}) {
   // run jsonata compiler; only `jsonata` template type is supported and this
   // assumes only this template type will be passed in
   const {template} = typedTemplate;
   const {variables = {}} = exchange;
+  // always include `globals` as keyword for self-referencing exchange info
+  variables.globals = {
+    exchanger: {
+      id: exchanger.id
+    },
+    exchange: {
+      id: exchange.id
+    }
+  };
   return jsonata(template).evaluate(variables, variables);
 }
 

package/lib/http.js

@@ -8,7 +8,7 @@ import {createChallenge as _createChallenge, verify} from './verify.js';
 import {
   createExchangeBody, useExchangeBody
 } from '../schemas/bedrock-vc-exchanger.js';
-import {evaluateTemplate, generateRandom} from './helpers.js';
+import {evaluateTemplate, generateRandom, getExchangerId} from './helpers.js';
 import {exportJWK, generateKeyPair, importJWK} from 'jose';
 import {metering, middleware} from '@bedrock/service-core';
 import {asyncHandler} from '@bedrock/express';
@@ -48,8 +48,7 @@ export async function addRoutes({app, service} = {}) {
   // used to fetch exchange record in parallel
   const getExchange = asyncHandler(async (req, res, next) => {
     const {localId, exchangeId: id} = req.params;
-    const {baseUri} = bedrock.config.server;
-    const exchangerId = `${baseUri}${routePrefix}/${localId}`;
+    const exchangerId = getExchangerId({routePrefix, localId});
     // expose access to result via `req`; do not wait for it to settle here
     const exchangePromise = exchanges.get({exchangerId, id}).catch(e => e);
     req.getExchange = async () => {
@@ -174,6 +173,7 @@ export async function addRoutes({app, service} = {}) {
       // process exchange step(s)
       let i = 0;
       let currentStep = exchange.step;
+      let step;
       while(true) {
         if(i++ > MAXIMUM_STEPS) {
           throw new BedrockError('Maximum steps exceeded.', {
@@ -188,12 +188,12 @@ export async function addRoutes({app, service} = {}) {
         }
 
         // get current step details
-        let step = exchanger.steps[currentStep];
+        step = exchanger.steps[currentStep];
         if(step.stepTemplate) {
           // generate step from the template; assume the template type is
           // `jsonata` per the JSON schema
           step = await evaluateTemplate(
-            {exchange, typedTemplate: step.stepTemplate});
+            {exchanger, exchange, typedTemplate: step.stepTemplate});
           if(Object.keys(step).length === 0) {
             throw new BedrockError('Empty step detected.', {
               name: 'DataError',
@@ -271,11 +271,9 @@ export async function addRoutes({app, service} = {}) {
 
           // update the exchange to go to the next step, then loop to send
           // next VPR
-          exchange.step = step.nextStep;
-          await exchanges.update({
-            exchangerId: exchanger.id, exchange, expectedStep: currentStep
-          });
-          currentStep = exchange.step;
+          currentStep = exchange.step = step.nextStep;
+          exchange.sequence++;
+          await exchanges.update({exchangerId: exchanger.id, exchange});
 
           // FIXME: there may be VCs to issue during this step, do so before
           // sending the VPR above
@@ -290,9 +288,8 @@ export async function addRoutes({app, service} = {}) {
       }
 
       // mark exchange complete
-      await exchanges.complete({
-        exchangerId: exchanger.id, exchange, expectedStep: currentStep
-      });
+      exchange.sequence++;
+      await exchanges.complete({exchangerId: exchanger.id, exchange});
 
       // FIXME: decide what the best recovery path is if delivery fails (but no
       // replay attack detected) after exchange has been marked complete
@@ -301,6 +298,11 @@ export async function addRoutes({app, service} = {}) {
       // VCs to issue
       const result = await issue({exchanger, exchange});
 
+      // if last `step` has a redirect URL, include it in the response
+      if(step?.redirectUrl) {
+        result.redirectUrl = step.redirectUrl;
+      }
+
       // send result
       res.json(result);
     }));

package/lib/issue.js

@@ -16,7 +16,7 @@ export async function issue({exchanger, exchange} = {}) {
 
   // evaluate template
   const credentials = await Promise.all(credentialTemplates.map(
-    typedTemplate => evaluateTemplate({exchange, typedTemplate})));
+    typedTemplate => evaluateTemplate({exchanger, exchange, typedTemplate})));
   // issue all VCs
   const vcs = await _issue({exchanger, credentials});
   verifiableCredential.push(...vcs);

package/lib/openId.js

@@ -1,19 +1,30 @@
 /*!
  * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
  */
+import * as bedrock from '@bedrock/core';
 import * as exchanges from './exchanges.js';
+import {
+  compile, schemas, createValidateMiddleware as validate
+} from '@bedrock/validation';
 import {importJWK, SignJWT} from 'jose';
 import {
-  openIdBatchCredentialBody, openIdCredentialBody, openIdTokenBody
+  openIdAuthorizationResponseBody, openIdBatchCredentialBody,
+  openIdCredentialBody, openIdTokenBody,
+  presentationSubmission as presentationSubmissionSchema
 } from '../schemas/bedrock-vc-exchanger.js';
+import {verify, verifyDidProofJwt} from './verify.js';
 import {asyncHandler} from '@bedrock/express';
 import bodyParser from 'body-parser';
 import {checkAccessToken} from '@bedrock/oauth2-verifier';
 import cors from 'cors';
+import {evaluateTemplate} from './helpers.js';
 import {issue} from './issue.js';
+import {klona} from 'klona';
+import {oid4vp} from '@digitalbazaar/oid4-client';
 import {timingSafeEqual} from 'node:crypto';
-import {createValidateMiddleware as validate} from '@bedrock/validation';
-import {verifyDidProofJwt} from './verify.js';
+import {UnsecuredJWT} from 'jose';
+
+const {util: {BedrockError}} = bedrock;
 
 /* NOTE: Parts of the OID4VCI design imply tight integration between the
 authorization server and the credential issuance / delivery server. This
@@ -50,17 +61,27 @@ export async function createRoutes({
 } = {}) {
   const openIdRoute = `${exchangeRoute}/openid`;
   const routes = {
+    // OID4VCI routes
     asMetadata: `/.well-known/oauth-authorization-server${exchangeRoute}`,
     ciMetadata: `/.well-known/openid-credential-issuer${exchangeRoute}`,
     batchCredential: `${openIdRoute}/batch_credential`,
     credential: `${openIdRoute}/credential`,
     token: `${openIdRoute}/token`,
-    jwks: `${openIdRoute}/jwks`
+    jwks: `${openIdRoute}/jwks`,
+    // OID4VP routes
+    authorizationRequest: `${openIdRoute}/client/authorization/request`,
+    authorizationResponse: `${openIdRoute}/client/authorization/response`
   };
 
   // urlencoded body parser (extended=true for rich JSON-like representation)
   const urlencoded = bodyParser.urlencoded({extended: true});
 
+  // create validators for x-www-form-urlencoded parsed data
+  const validatePresentation = compile(
+    {schema: schemas.verifiablePresentation()});
+  const validatePresentationSubmission = compile(
+    {schema: presentationSubmissionSchema});
+
   // an authorization server meta data endpoint
   // serves `.well-known` oauth2 AS config for each exchange; each config is
   // based on the exchanger used to create the exchange
@@ -118,9 +139,7 @@ export async function createRoutes({
     asyncHandler(async (req, res) => {
       const {exchange} = await req.getExchange();
       if(!exchange.openId) {
-        // FIXME: improve error
-        // unsupported protocol for the exchange
-        throw new Error('unsupported protocol');
+        _throwUnsupportedProtocol();
       }
       // serve exchange's public key
       res.json({keys: [exchange.openId.oauth2.keyPair.publicKeyJwk]});
@@ -141,9 +160,7 @@ export async function createRoutes({
       const exchangeRecord = await req.getExchange();
       const {exchange} = exchangeRecord;
       if(!exchange.openId) {
-        // FIXME: improve error
-        // unsupported protocol for the exchange
-        throw new Error('unsupported protocol');
+        _throwUnsupportedProtocol();
       }
 
       /* Examples of types of token requests:
@@ -167,7 +184,7 @@ export async function createRoutes({
       if(grantType !== PRE_AUTH_GRANT_TYPE) {
         // unsupported grant type
         // FIXME: throw proper oauth2 formatted error
-        throw new Error('unsupported grant type');
+        throw new Error('Unsupported grant type.');
       }
 
       // validate grant type
@@ -298,6 +315,48 @@ export async function createRoutes({
         vc => ({format: 'ldp_vc', credential: vc}));
       res.json({credential_responses: responses});
     }));
+
+  // an OID4VP verifier endpoint
+  // serves the authorization request, including presentation definition
+  // associated with the current step in the exchange
+  app.get(
+    routes.authorizationRequest,
+    cors(),
+    getConfigMiddleware,
+    getExchange,
+    asyncHandler(async (req, res) => {
+      const {authorizationRequest} = await _getAuthorizationRequest({req});
+      // construct and send authz request as unsecured JWT
+      const jwt = new UnsecuredJWT(authorizationRequest).encode();
+      res.set('content-type', 'application/oauth-authz-req+jwt');
+      res.send(jwt);
+    }));
+
+  // an OID4VP verifier endpoint
+  // receives an authorization response with vp_token
+  app.options(routes.authorizationResponse, cors());
+  app.post(
+    routes.authorizationResponse,
+    cors(),
+    urlencoded,
+    validate({bodySchema: openIdAuthorizationResponseBody()}),
+    getConfigMiddleware,
+    getExchange,
+    asyncHandler(async (req, res) => {
+      // get JSON `vp_token` and `presentation_submission`
+      const {vp_token, presentation_submission} = req.body;
+
+      // JSON parse and validate `vp_token` and `presentation_submission`
+      const presentation = _jsonParse(vp_token, 'vp_token');
+      const presentationSubmission = _jsonParse(
+        presentation_submission, 'presentation_submission');
+      _validate(validatePresentationSubmission, presentationSubmission);
+      _validate(validatePresentation, presentation);
+
+      const result = await _processAuthorizationResponse(
+        {req, presentation, presentationSubmission});
+      res.json(result);
+    }));
 }
 
 async function _createExchangeAccessToken({exchanger, exchangeRecord}) {
@@ -394,9 +453,7 @@ async function _processCredentialRequests({req, res, isBatchRequest}) {
   const exchangeRecord = await req.getExchange();
   const {exchange} = exchangeRecord;
   if(!exchange.openId) {
-    // FIXME: improve error
-    // unsupported protocol for the exchange
-    throw new Error('unsupported protocol');
+    _throwUnsupportedProtocol();
   }
 
   // ensure oauth2 access token is valid
@@ -458,9 +515,8 @@ async function _processCredentialRequests({req, res, isBatchRequest}) {
   }
 
   // mark exchange complete
-  await exchanges.complete({
-    exchangerId: exchanger.id, exchange, expectedStep: currentStep
-  });
+  exchange.sequence++;
+  await exchanges.complete({exchangerId: exchanger.id, exchange});
 
   // FIXME: decide what the best recovery path is if delivery fails (but no
   // replay attack detected) after exchange has been marked complete
@@ -502,6 +558,115 @@ async function _requestDidProof({res, exchangeRecord}) {
   });
 }
 
+async function _getAuthorizationRequest({req}) {
+  const {config: exchanger} = req.serviceObject;
+  const exchangeRecord = await req.getExchange();
+  let {exchange} = exchangeRecord;
+  let step;
+
+  while(true) {
+    // exchange step required for OID4VP
+    const currentStep = exchange.step;
+    if(!currentStep) {
+      _throwUnsupportedProtocol();
+    }
+
+    step = exchanger.steps[exchange.step];
+    if(step.stepTemplate) {
+      // generate step from the template; assume the template type is
+      // `jsonata` per the JSON schema
+      step = await evaluateTemplate(
+        {exchanger, exchange, typedTemplate: step.stepTemplate});
+      if(Object.keys(step).length === 0) {
+        throw new BedrockError('Could not create authorization request.', {
+          name: 'DataError',
+          details: {httpStatusCode: 500, public: true}
+        });
+      }
+    }
+
+    // step must have `openId` to perform OID4VP
+    if(!step.openId) {
+      _throwUnsupportedProtocol();
+    }
+
+    // get authorization request
+    let authorizationRequest = step.openId.authorizationRequest;
+    if(!authorizationRequest) {
+      // create authorization request...
+      // get variable name for authorization request
+      const authzReqName = step.openId.createAuthorizationRequest;
+      if(authzReqName === undefined) {
+        _throwUnsupportedProtocol();
+      }
+
+      // create or get cached authorization request
+      authorizationRequest = exchange.variables?.[authzReqName];
+      if(!authorizationRequest) {
+        const {verifiablePresentationRequest} = step;
+        authorizationRequest = oid4vp.fromVpr({verifiablePresentationRequest});
+
+        // add / override params from step `openId` information
+        const {
+          client_id, client_id_scheme,
+          client_metadata, client_metadata_uri,
+          nonce, response_uri
+        } = step.openId || {};
+        if(client_id) {
+          authorizationRequest.client_id = client_id;
+        }
+        if(client_id_scheme) {
+          authorizationRequest.client_id_scheme = client_id_scheme;
+        }
+        if(client_metadata) {
+          authorizationRequest.client_metadata = klona(client_metadata);
+        } else if(client_metadata_uri) {
+          authorizationRequest.client_metadata_uri = client_metadata_uri;
+        }
+        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;
+        }
+        if(response_uri) {
+          authorizationRequest.response_uri = response_uri;
+        } else if(authorizationRequest.response_mode === 'direct_post' &&
+          authorizationRequest.client_id_scheme === 'redirect_uri') {
+          // `authorizationRequest` uses `direct_post` so force client ID to
+          // be the exchange response URL per "Note" here:
+          // eslint-disable-next-line max-len
+          // https://openid.github.io/OpenID4VP/openid-4-verifiable-presentations-wg-draft.html#section-6.2
+          authorizationRequest.response_uri = authorizationRequest.client_id;
+        }
+
+        // store generated authorization request
+        if(!exchange.variables) {
+          exchange.variables = {};
+        }
+        exchange.variables[authzReqName] = authorizationRequest;
+        exchange.sequence++;
+        try {
+          await exchanges.update({exchangerId: exchanger.id, exchange});
+        } catch(e) {
+          if(e.name !== 'InvalidStateError') {
+            // unrecoverable error
+            throw e;
+          }
+          // get exchange and loop to try again on `InvalidStateError`
+          const record = await exchanges.get(
+            {exchangerId: exchanger.id, id: exchange.id});
+          ({exchange} = record);
+          continue;
+        }
+      }
+    }
+
+    return {authorizationRequest, exchange, step};
+  }
+}
+
 function _assertCredentialRequests({
   credentialRequests, expectedCredentialRequests
 }) {
@@ -525,3 +690,84 @@ function _matchCredentialRequest(a, b) {
   return (c1.length === c2.length && t1.length === t2.length &&
     c1.every((c, i) => c === c2[i]) && t1.every(t => t2.some(x => t === x)));
 }
+
+async function _processAuthorizationResponse({
+  req, presentation, presentationSubmission
+}) {
+  const {config: exchanger} = req.serviceObject;
+  const exchangeRecord = await req.getExchange();
+  let {exchange} = exchangeRecord;
+
+  // get authorization request and updated exchange associated with exchange
+  const arRequest = await _getAuthorizationRequest({req});
+  const {authorizationRequest, step} = arRequest;
+  ({exchange} = arRequest);
+
+  // verify the received VP
+  const {verifiablePresentationRequest} = await oid4vp.toVpr(
+    {authorizationRequest});
+  const {verificationMethod} = await verify({
+    exchanger,
+    verifiablePresentationRequest,
+    presentation,
+    expectedChallenge: authorizationRequest.nonce
+  });
+
+  // FIXME: check the VP against the presentation submission if requested
+
+  // store VP results in variables associated with current step
+  const currentStep = exchange.step;
+  if(!exchange.variables.results) {
+    exchange.variables.results = {};
+  }
+  exchange.variables.results[currentStep] = {
+    // common use case of DID Authentication; provide `did` for ease
+    // of use in template
+    did: verificationMethod.controller,
+    verificationMethod,
+    verifiablePresentation: presentation,
+    openId: {
+      authorizationRequest,
+      presentationSubmission
+    }
+  };
+
+  // mark exchange complete
+  exchange.sequence++;
+  await exchanges.complete({exchangerId: exchanger.id, exchange});
+
+  const result = {};
+
+  // include `redirect_uri` if specified in step
+  const redirect_uri = step.openId?.redirect_uri;
+  if(redirect_uri) {
+    result.redirect_uri = redirect_uri;
+  }
+
+  return result;
+}
+
+function _jsonParse(x, name) {
+  try {
+    return JSON.parse(x);
+  } catch(cause) {
+    throw new BedrockError(`Could not parse "${name}".`, {
+      name: 'DataError',
+      details: {httpStatusCode: 400, public: true},
+      cause
+    });
+  }
+}
+
+function _throwUnsupportedProtocol() {
+  // FIXME: improve error
+  // unsupported protocol for the exchange
+  throw new Error('Unsupported protocol.');
+}
+
+function _validate(validator, data) {
+  const result = validator(data);
+  if(!result.valid) {
+    throw result.error;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/vc-delivery",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "description": "Bedrock Verifiable Credential Delivery",
   "main": "./lib/index.js",
@@ -38,6 +38,7 @@
     "@digitalbazaar/ed25519-signature-2020": "^5.2.0",
     "@digitalbazaar/ed25519-verification-key-2020": "^4.1.0",
     "@digitalbazaar/ezcap": "^4.0.0",
+    "@digitalbazaar/oid4-client": "^3.1.0",
     "@digitalbazaar/vc": "^6.0.1",
     "assert-plus": "^1.0.0",
     "bnid": "^3.0.0",

package/schemas/bedrock-vc-exchanger.js

@@ -147,7 +147,8 @@ const step = {
         'createChallenge',
         'verifiablePresentationRequest',
         'jwtDidProofRequest',
-        'nextStep'
+        'nextStep',
+        'openId'
       ]
     }
   }, {
@@ -195,7 +196,37 @@ const step = {
     nextStep: {
       type: 'string'
     },
-    stepTemplate: typedTemplate
+    stepTemplate: typedTemplate,
+    // required to support OID4VP (but can be provided by step template instead)
+    openId: {
+      type: 'object',
+      additionalProperties: false,
+      // an authorization request or a directive to create one can be used,
+      // but not both
+      oneOf: [{
+        required: ['createAuthorizationRequest'],
+        // cannot also use `authorizationRequest
+        not: {
+          required: ['authorizationRequest']
+        }
+      }, {
+        required: ['authorizationRequest'],
+        // cannot also use `createAuthorizationRequest`
+        not: {
+          required: ['createAuthorizationRequest']
+        }
+      }],
+      properties: {
+        // value is name of variable to store the created authz request in
+        createAuthorizationRequest: {
+          type: 'string'
+        },
+        // ... or full authz request to use
+        authorizationRequest: {
+          type: 'object'
+        }
+      }
+    }
   }
 };
 
@@ -301,3 +332,67 @@ export const openIdTokenBody = {
     // }
   }
 };
+
+const presentationDescriptor = {
+  title: 'Presentation Submission Descriptor',
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'format', 'path'],
+  properties: {
+    id: {
+      type: 'string'
+    },
+    format: {
+      type: 'string'
+    },
+    path: {
+      type: 'string'
+    },
+    path_nested: {
+      type: 'object'
+    }
+  }
+};
+
+export const presentationSubmission = {
+  title: 'Presentation Submission',
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'definition_id', 'descriptor_map'],
+  properties: {
+    id: {
+      type: 'string'
+    },
+    definition_id: {
+      type: 'string'
+    },
+    descriptor_map: {
+      title: 'Presentation Submission Descriptor Map',
+      type: 'array',
+      minItems: 0,
+      items: presentationDescriptor
+    }
+  }
+};
+
+export function openIdAuthorizationResponseBody() {
+  return {
+    title: 'OID4VP Authorization Response',
+    type: 'object',
+    additionalProperties: false,
+    required: ['presentation_submission', 'vp_token'],
+    properties: {
+      // is a JSON string in the x-www-form-urlencoded body
+      presentation_submission: {
+        type: 'string'
+      },
+      // is a JSON string in the x-www-form-urlencoded body
+      vp_token: {
+        type: 'string'
+      },
+      state: {
+        type: 'string'
+      }
+    }
+  };
+}