@bedrock/vc-delivery 7.16.0 → 7.16.1

package/README.md

@@ -1 +1,573 @@
-# bedrock-vc-delivery
+# @bedrock/vc-delivery
+
+A [Bedrock][] module that provides a **Verifiable Credential (VC) Workflow
+Service** for issuing and exchanging VCs using multiple protocols. It enables
+configurable, multi-step credential exchange workflows with support for the
+VC-API, OpenID for Verifiable Credential Issuance (OID4VCI), OpenID for
+Verifiable Presentations (OID4VP), and an Invite Request protocol.
+
+## Table of Contents
+
+- [Background](#background)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Workflow Config](#workflow-config)
+  - [Credential Templates](#credential-templates)
+  - [Steps](#steps)
+  - [Issuer Instances](#issuer-instances)
+  - [OID4VCI Options](#oid4vci-options)
+  - [OID4VP Client Profiles](#oid4vp-client-profiles)
+- [HTTP API](#http-api)
+  - [Exchanges](#exchanges)
+  - [Protocols](#protocols)
+  - [OID4VCI Endpoints](#oid4vci-endpoints)
+  - [OID4VP Endpoints](#oid4vp-endpoints)
+  - [Invite Request Endpoints](#invite-request-endpoints)
+- [Protocols](#supported-protocols)
+  - [VC-API](#vc-api)
+  - [OID4VCI](#oid4vci)
+  - [OID4VP](#oid4vp)
+  - [Invite Request](#invite-request)
+- [Exchange Lifecycle](#exchange-lifecycle)
+- [Multi-Step Workflows](#multi-step-workflows)
+- [Security](#security)
+- [Backwards Compatibility](#backwards-compatibility)
+- [License](#license)
+
+## Background
+
+This module implements the server-side infrastructure for **Verifiable Credential
+delivery**. A *workflow* is a reusable configuration that defines how credentials
+are issued and/or verified. An *exchange* is a single instance of that workflow —
+a live, stateful session between a workflow service and an exchange client (e.g.
+a digital wallet).
+
+Workflows are registered with an associated set of authorization capabilities
+(zcaps) that grant the service permission to issue and verify credentials on
+behalf of the workflow owner.
+
+## Features
+
+- **Multi-protocol support**: VC-API, OID4VCI v1.0, OID4VP 1.0, and Invite
+  Request (with backwards compatibility for OID4VCI Draft 13 and OID4VP Draft
+  18).
+- **Multi-step exchanges**: Define sequential steps that mix presentation
+  verification and credential issuance within a single exchange.
+- **JSONata credential templates**: Dynamically generate credential content
+  from exchange variables using [JSONata][] expressions.
+- **Multiple issuer instances**: Configure up to 10 independent issuer
+  instances per workflow, each with its own zcap and supported credential
+  formats.
+- **OID4VP client profiles**: Configure up to 10 OID4VP client profiles per
+  workflow, including support for signed authorization requests and mDL/ISO
+  18013-7 presentation flows.
+- **OAuth2 / zcap authorization**: Workflow management endpoints support both
+  zcap-based and OAuth2-based authorization.
+- **Configurable exchange TTL**: Exchanges expire automatically (default 15
+  minutes, maximum 48 hours).
+
+## Requirements
+
+- Node.js >= 20
+- MongoDB (via [`@bedrock/mongodb`][])
+- A running [Bedrock][] application with the required peer dependencies (see
+  `peerDependencies` in `package.json`)
+
+
+
+## Installation
+
+```sh
+npm install @bedrock/vc-delivery
+```
+
+Then import the module in your Bedrock application entry point:
+
+```js
+import '@bedrock/vc-delivery';
+```
+
+The module self-registers with Bedrock on import and will set up all routes
+and storage on startup.
+
+## Quick Start
+
+### 1. Create a workflow configuration
+
+```js
+// POST /workflows
+{
+  "sequence": 0,
+  "controller": "did:key:z6Mk...",
+  "credentialTemplates": [{
+    "type": "jsonata",
+    "template": "{ '@context': ['https://www.w3.org/2018/credentials/v1'], 'type': ['VerifiableCredential'], 'credentialSubject': {'id': subject} }"
+  }],
+  "initialStep": "issue",
+  "steps": {
+    "issue": {
+      // you can use static step parameters like this, but also see
+      // `stepTemplate` below for more powerful dynamic steps instead!
+      "issueRequests": [{ "credentialTemplateIndex": 0 }]
+    }
+  },
+  "zcaps": {
+    "issue": { /* delegated issue zcap */ }
+  }
+}
+```
+
+### 2. Create an exchange
+
+```js
+// POST /workflows/:workflowId/exchanges
+{
+  "ttl": 900,
+  "variables": {
+    "subject": "did:example:holder123"
+  }
+}
+// Response: 204 No Content; Location header contains exchange URL
+```
+
+### 3. Execute the exchange (VC-API)
+
+```js
+// POST /workflows/:workflowId/exchanges/:exchangeId
+{}
+// Response:
+{
+  "verifiablePresentation": { /* VP containing issued VCs */ }
+}
+```
+
+## Configuration
+
+### Workflow Config
+
+Workflows are created and managed via the [`@bedrock/service-core`][] HTTP
+API at `/workflows`. The configuration body accepts the following custom
+properties in addition to standard service-core fields:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `credentialTemplates` | Array | No | List of JSONata credential templates to issue |
+| `steps` | Object | No | Named step definitions for multi-step exchanges |
+| `initialStep` | String | Required if `steps` present | Name of the first step to execute |
+| `issuerInstances` | Array | No | Up to 10 issuer instance configurations |
+| `zcaps` | Object | No | Authorization capability references |
+
+If `credentialTemplates` are provided, either a top-level `zcaps.issue`
+or at least one `issuerInstances` entry with its own issue zcap is required.
+
+### Credential Templates
+
+Credential templates use [JSONata][] to dynamically produce credential JSON.
+Exchange `variables` and built-in `globals` are available as template
+bindings.
+
+```js
+"credentialTemplates": [{
+  "type": "jsonata",
+  "id": "myTemplate",           // optional, for referencing in issueRequests
+  "template": "{ ... }"         // JSONata expression returning a VC object
+}]
+```
+
+**Built-in template globals:**
+
+| Variable | Description |
+|----------|-------------|
+| `globals.exchange.id` | The local exchange ID |
+| `globals.exchangeId` | The full exchange URL |
+| `globals.workflow.id` | The workflow ID |
+
+### Steps
+
+Steps define the interactive logic of an exchange. Each step can request a
+Verifiable Presentation, issue credentials, or both.
+
+```js
+"steps": {
+  "verify": {
+    "verifiablePresentationRequest": { /* VPR object */ },
+    "nextStep": "issue"
+  },
+  "issue": {
+    "issueRequests": [
+      { "credentialTemplateIndex": 0 }
+    ]
+  }
+},
+"initialStep": "verify"
+```
+
+**Step fields:**
+
+| Field | Description |
+|-------|-------------|
+| `issueRequests` | Array of credential issue request parameters |
+| `verifiablePresentationRequest` | VPR to send to the client |
+| `verifiablePresentation` | VP to return immediately without client input |
+| `createChallenge` | `true` to generate and attach a challenge nonce to the VPR |
+| `nextStep` | Name of the step to transition to after this one completes |
+| `openId` | OID4VP options for this step |
+| `jwtDidProofRequest` | Request a DID-bound JWT proof |
+| `divpDidProofRequest` | Request a DI-VP DID proof |
+| `callback.url` | URL to call when exchange state updates |
+| `presentationSchema` | JSON Schema to validate received presentations |
+| `verifyPresentationOptions` | Additional options for presentation verification |
+| `verifyPresentationResultSchema` | JSON Schema to validate verification results |
+| `allowUnprotectedPresentation` | Allow presentations without a proof |
+| `redirectUrl` | URL to redirect the exchange client upon completion |
+
+Steps may also be defined as **templated steps**, where a JSONata
+`stepTemplate` expression dynamically generates the step configuration from
+exchange variables at runtime:
+
+```js
+"steps": {
+  "issue": {
+    "stepTemplate": {
+      "type": "jsonata",
+      "template": "{ 'issueRequests': [{ 'credentialTemplateIndex': 0 }] }"
+    }
+  }
+}
+```
+
+### Issuer Instances
+
+`issuerInstances` allows a workflow to configure multiple issuers, each with
+different capabilities and supported credential media types. Up to 10 instances
+are supported.
+
+```js
+"issuerInstances": [{
+  "id": "myIssuer",                         // optional identifier
+  "supportedMediaTypes": ["application/vc"],
+  "zcapReferenceIds": {
+    "issue": "myIssuerZcap"
+  },
+  "oid4vci": {
+    "supportedCredentialConfigurations": {  // optional explicit OID4VCI config
+      "MyCredential_ldp_vc": { /* credential configuration */ }
+    }
+  }
+}]
+```
+
+Each issuer instance references a zcap in the workflow's `zcaps` map by its
+`zcapReferenceIds.issue` key.
+
+### OID4VCI Options
+
+When creating an exchange with OID4VCI support, pass an `openId` object in the
+exchange creation body:
+
+```js
+// POST /workflows/:workflowId/exchanges
+{
+  "openId": {
+    "preAuthorizedCode": "abc123",
+    "oauth2": {
+      "generateKeyPair": { "algorithm": "ES256" }
+      // or provide an existing key pair:
+      // "keyPair": { "privateKeyJwk": {...}, "publicKeyJwk": {...} }
+    }
+  }
+}
+```
+
+> **Deprecated:** `expectedCredentialRequests` is deprecated and should not be
+> used in new workflows. Credential configurations are inferred from
+> `issuerInstances` instead.
+
+### OID4VP Client Profiles
+
+OID4VP client profiles allow fine-grained control over how authorization
+requests are constructed and which wallet/verifier protocols are used. Up to 10
+profiles are supported per workflow step.
+
+```js
+// in a step:
+"openId": {
+  "clientProfiles": {
+    "myProfile": {
+      "createAuthorizationRequest": "/authzReqVar",
+      "client_id": "https://verifier.example",
+      "client_id_scheme": "redirect_uri",
+      "response_mode": "direct_post",
+      "response_uri": "https://verifier.example/callback",
+      "protocolUrlParameters": {
+        "name": "OID4VP",
+        "scheme": "openid4vp",
+        "version": "OID4VP-1.0"   // or "OID4VP-draft18"
+      }
+    }
+  }
+}
+```
+
+> **Deprecated:** `presentation_definition` (Presentation Exchange) is a
+> pre-OID4VP 1.0 mechanism and is deprecated. Prefer `dcql_query` for new
+> implementations.
+
+Supported `response_mode` values include `direct_post`, `direct_post.jwt`,
+`dc_api`, and `dc_api.jwt`.
+
+## HTTP API
+
+All endpoints support CORS. Authorization uses zcaps or OAuth2 — not cookies
+— so CSRF is not a concern.
+
+### Exchanges
+
+#### Create Exchange
+
+```
+POST /workflows/:workflowId/exchanges
+```
+
+**Body** (`application/json`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ttl` | Number | Seconds until expiry (default: 900, max: 172800) |
+| `expires` | String | ISO 8601 expiry date (alternative to `ttl`) |
+| `variables` | Object | Key/value pairs available in credential templates and step templates |
+| `openId` | Object | OID4VCI configuration (see [OID4VCI Options](#oid4vci-options)) |
+
+> **Note:** The schema uses `additionalProperties: false`; fields not listed above (including `step`) will be rejected by the validator.
+
+**Response**: `204 No Content` with a `Location` header pointing to the exchange URL.
+
+#### Get Exchange
+
+```
+GET /workflows/:workflowId/exchanges/:exchangeId
+```
+
+Returns the current exchange state. Private keys and secrets are never
+included in the response.
+
+#### Use Exchange (VC-API)
+
+```
+POST /workflows/:workflowId/exchanges/:exchangeId
+```
+
+**Body** (`application/json`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `verifiablePresentation` | Object | VP to submit (if requested by the current step) |
+
+**Response**: A JSON object, which may contain:
+- `verifiablePresentation` — a VP with issued credentials
+- `verifiablePresentationRequest` — a VPR requiring the client to submit a VP
+
+### Protocols
+
+#### Get Supported Protocols
+
+```
+GET /workflows/:workflowId/exchanges/:exchangeId/protocols
+```
+
+Returns a `{"protocols": {...}}` object listing all interaction URLs supported
+by the exchange. Key names are:
+- `vcapi` — always this literal string when VC-API is supported
+- `inviteRequest` — always this literal string when an invite request step is active
+- OID4VCI — always `OID4VCI`
+- OID4VP — defaults to `OID4VP` but is controlled by the `protocolUrlParameters.name`
+  field on each OID4VP client profile, so named profiles may produce arbitrary keys
+  (e.g. a profile with `"name": "bar"` produces a `bar` key)
+
+### OID4VCI Endpoints
+
+The well-known metadata endpoints are served at **two URL shapes** for maximum
+wallet compatibility:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/.well-known/openid-credential-issuer/workflows/:wfId/exchanges/:id` | Credential issuer metadata (prefix form) |
+| `GET` | `/workflows/:wfId/exchanges/:id/.well-known/openid-credential-issuer` | Credential issuer metadata (suffix form) |
+| `GET` | `/.well-known/oauth-authorization-server/workflows/:wfId/exchanges/:id` | AS metadata (prefix form) |
+| `GET` | `/workflows/:wfId/exchanges/:id/.well-known/oauth-authorization-server` | AS metadata (suffix form) |
+| `GET` | `…/exchanges/:id/openid/credential-offer` | Credential offer object |
+| `POST` | `…/exchanges/:id/openid/token` | Access token endpoint |
+| `POST` | `…/exchanges/:id/openid/credential` | Credential request endpoint |
+| `POST` | `…/exchanges/:id/openid/batch_credential` | Batch credential requests |
+| `GET` | `…/exchanges/:id/openid/jwks` | JSON Web Key Set |
+| `POST` | `…/exchanges/:id/openid/nonce` | Nonce endpoint |
+
+### OID4VP Endpoints
+
+Legacy (no client profile ID) and modern (with client profile ID) routes are
+both supported:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET/POST` | `…/exchanges/:id/openid/client/authorization/request` | Retrieve authorization request (default profile) |
+| `POST` | `…/exchanges/:id/openid/client/authorization/response` | Submit authorization response (default profile) |
+| `GET/POST` | `…/exchanges/:id/openid/clients/:clientProfileId/authorization/request` | Retrieve authorization request (named profile) |
+| `POST` | `…/exchanges/:id/openid/clients/:clientProfileId/authorization/response` | Submit authorization response (named profile) |
+
+### Invite Request Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `…/exchanges/:id/invite-request/response` | Submit invite response |
+
+## Supported Protocols
+
+### VC-API
+
+The [VC-API][] protocol is automatically supported for any workflow that has
+`credentialTemplates`, or for any step that has a
+`verifiablePresentationRequest` or `verifiablePresentation`. The exchange URL
+itself serves as the `vcapi` interaction endpoint.
+
+### OID4VCI
+
+[OpenID for Verifiable Credential Issuance][OID4VCI-spec] is supported when
+an exchange is created with an `openId` configuration object. Supported grant
+types:
+
+- Pre-authorized code flow (`urn:ietf:params:oauth:grant-type:pre-authorized_code`)
+
+Supported proof types for credential requests:
+
+- `jwt` (JWT-based DID proof)
+- `di_vp` (Data Integrity VP DID proof)
+
+Supported credential formats (OID4VCI v1.0):
+
+- `ldp_vc` / `application/vc` (JSON-LD Verifiable Credential)
+- `jwt_vc_json` / `application/jwt` (JWT Verifiable Credential)
+
+Supported for backwards compatibility with OID4VCI Draft 13 (deprecated):
+
+- `jwt_vc_json-ld` (JSON-LD-based VC-JWT envelope)
+
+> **Deprecated:** OID4VCI Draft 13 credential request formats are supported
+> for backwards compatibility but are deprecated. New implementations should
+> use OID4VCI v1.0.
+
+### OID4VP
+
+[OpenID for Verifiable Presentations][OID4VP-spec] is supported when a step
+includes an `openId` configuration. The module supports:
+
+- OID4VP 1.0+ (with prefixed `client_id` schemes and `request_uri_method=post`)
+- Signed authorization requests (via `authorizationRequestSigningParameters`)
+- Multiple response modes: `direct_post`, `direct_post.jwt`, `dc_api`, `dc_api.jwt`
+- mDL / ISO 18013-7 presentations (Annex B, C, and D handover types)
+- DCQL queries (`dcql_query`)
+
+Supported for backwards compatibility (deprecated):
+
+- OID4VP Draft 18
+- Presentation Definitions (`presentation_definition`)
+
+### Invite Request
+
+A lightweight invite-based protocol. When a step exposes an `inviteRequest`
+property, the exchange will include an `inviteRequest` URL in its `protocols`
+response. The client POSTs an invite response (containing a `url`, `purpose`,
+and optional `referenceId`) to complete this step.
+
+Because the static `computedStep` schema does not declare an `inviteRequest`
+property (it uses `additionalProperties: false`), the property must be injected
+at runtime via a `stepTemplate` rather than declared directly in the workflow
+configuration:
+
+```js
+"steps": {
+  "myStep": {
+    "stepTemplate": {
+      "type": "jsonata",
+      "template": "{ \"inviteRequest\": inviteRequest }"
+    }
+  }
+}
+```
+
+The exchange variable `inviteRequest` must be set to `true` when creating the
+exchange to activate the invite request protocol for that step.
+
+## Exchange Lifecycle
+
+```mermaid
+graph TD
+    A[Create Exchange]:::accent0 --> B[Exchange Pending]:::accent1
+    B --> C{Protocol}:::accent2
+    C -->|VC-API| D[POST to exchange URL]
+    C -->|OID4VCI| E[Pre-auth code flow]
+    C -->|OID4VP| F[Fetch authz request]
+    C -->|Invite| G[POST invite response]
+    D & E & F & G --> H{Step complete?}:::accent3
+    H -->|Next step exists| B
+    H -->|No more steps| I[Exchange Complete]:::accent4
+    B -->|TTL expires| J[Exchange Expired]:::accent5
+```
+
+Exchanges are stored in MongoDB. By default they expire after **15 minutes**
+(`ttl: 900`). The maximum TTL is **48 hours** (`ttl: 172800`). Expired
+exchanges are retained for an additional grace period of 3 days before being
+eligible for removal.
+
+Exchange `variables` hold the mutable state that flows between steps, including
+per-step results accessible at `variables.results[stepName]`.
+
+## Multi-Step Workflows
+
+A workflow can chain multiple steps using the `nextStep` field. This enables
+patterns such as:
+
+1. **Verify then Issue** — Require the holder to present an existing credential
+   before receiving a new one.
+2. **OID4VP then OID4VCI** — Verify via OID4VP and then issue via OID4VCI in
+   the same exchange session.
+3. **Invite then Issue** — Collect wallet/app metadata via invite request
+   before issuing credentials.
+
+Step results are stored in `exchange.variables.results[stepName]` and are
+accessible in subsequent JSONata step templates or credential templates.
+
+## Security
+
+- Workflow management routes require **zcap** or **OAuth2** authorization.
+- Exchange execution routes (VC-API `POST`) are unauthenticated by design,
+  relying on capability URLs for authorization; exchanges are single-use,
+  short-lived, and scoped to a specific workflow. Workflows themselves
+  can add authentication by asking for verifiable presentations and
+  verifiable credentials.
+- CORS is enabled on all endpoints. This is safe because authorization is
+  performed using HTTP signatures and capabilities (not cookies), making CSRF
+  impossible.
+- Private key material (`privateKeyJwk`) and exchange `secrets` are stripped
+  from all API responses.
+- VC-API exchange creation and exchange-use payloads are limited to **10 MB** (configured via `config.express.bodyParser.routes`). OID4VP authorization-response form posts are also limited to **10 MB** (via an inline `urlencoded` body parser). Other OID4VCI endpoints (token, credential, etc.) rely on the framework's default body-size limits. A feature exists to enable larger exchange state, but it has not been enabled at this time.
+
+## Backwards Compatibility
+
+This module previously exposed a `vc-exchanger` service at `/exchangers`. That
+service type and route prefix are still registered as aliases and will continue
+to function, but new deployments should use `vc-workflow` and `/workflows`.
+
+## License
+
+[New BSD License](LICENSE.md) © 2022-2026 Digital Bazaar, Inc.
+
+[Bedrock]: https://github.com/digitalbazaar/bedrock
+[JSONata]: https://jsonata.org
+[VC-API]: https://w3c-ccg.github.io/vc-api/
+[OID4VCI-spec]: https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html
+[OID4VP-spec]: https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
+[`@bedrock/mongodb`]: https://github.com/digitalbazaar/bedrock-mongodb
+[`@bedrock/service-core`]: https://github.com/digitalbazaar/bedrock-service-core

package/lib/storage/exchanges.js

@@ -183,7 +183,7 @@ export async function get({
   }
 
   let record = await collection.findOne(query, {projection});
-  if(!allowExpired) {
+  if(record && !allowExpired) {
     // ensure `expires` is enforced programmatically even if background job
     // has not yet removed the record; force unexpiring exchanges to be not
     // found via this code path -- any exchanges without an expiration date
@@ -191,7 +191,7 @@ export async function get({
     // in the database
     const now = new Date();
     // note: for undefined `expires`, this will be `NaN || now` => `now`
-    const expires = new Date(record.exchange.expires) || now;
+    const expires = new Date(Date.parse(record.exchange.expires) || now);
     if(now >= expires) {
       record = null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/vc-delivery",
-  "version": "7.16.0",
+  "version": "7.16.1",
   "type": "module",
   "description": "Bedrock Verifiable Credential Delivery",
   "main": "./lib/index.js",