fido-vc-middleware

Express middleware that orchestrates FIDO-VC user flows between the browser (WebAuthn API), the walt.id Wallet API, and the holder's FIDO authenticator. Part of the FIDO4VC project.

What it does

The middleware exposes three flows under /api/fido/*, each spanning a "start" and "finish" endpoint:

Flow	Endpoints	Purpose
Register	POST /register/start, POST /register/finish	Run a WebAuthn registration ceremony, convert the COSE public key to JWK, derive a did:jwk, and register the DID with the walt.id Wallet API.
Issue	POST /issuance/start, POST /issuance/finish	When receiving an OpenID4VCI credential offer, ask the wallet to prepare an unsigned ldp_vp proof of possession, canonicalize it into a WebAuthn challenge, prompt the FIDO authenticator, fold the resulting assertion into the proof, submit to the issuer.
Verify	POST /verification/start, POST /verification/finish	Same shape as issuance but for OpenID4VP presentation — prepare unsigned VP, FIDO-sign, submit to the verifier.

All three flows use the same primitive: take an unsigned LD document, canonicalize it with the fido4vc-jcs-2026 cryptosuite, get the FIDO authenticator to sign over the resulting hash, and embed the assertion as the proof value.

Architecture

[Browser (Wallet UI)]
        ↓ HTTP /api/fido/*
[fido-vc-middleware]  ← this repo
        ↓ HTTP
[walt.id Wallet API]

The middleware is the bridge: the Wallet UI runs WebAuthn ceremonies in the browser; this middleware coordinates the multi-step state and translates between WebAuthn assertions and walt.id's external-signature exchange flows.

Prerequisites

• Node.js ≥ 18
• MySQL database (or compatible) for storing WebAuthn credential records
• walt.id services running locally or accessible over the network — at minimum, the Wallet API. See the walt.id-identity fork.

Install & configure

git clone https://github.com/fido4vc/fido-vc-middleware
cd fido-vc-middleware
npm install

Create a .env file in the project root (or copy from .env.example if one is provided):

# server
PORT=8080
SESSION_SECRET=<random secret>

# database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=<your password>
DB_NAME=webauthn_db

# upstream walt.id Wallet API
WALLET_API_URL=http://localhost:7001

The middleware uses express-session with the SESSION_SECRET to persist short-lived state across the two halves of each flow. Sessions live for the duration of a register/issue/verify ceremony.

Run

# development with hot-reload (ts-node + nodemon)
npm run dev:nodemon

# development without reload
npm run dev

# production
npm run build && npm start

The middleware starts on PORT (default 8080).

Endpoints

All endpoints require an Authorization: Bearer <token> header issued by the walt.id Wallet API. The /test route is unauthenticated and useful for health checks.

Route	Body	Returns
GET /api/fido/test	—	{ message, timestamp, endpoint }
POST /api/fido/register/start	{ alias }	WebAuthn PublicKeyCredentialCreationOptions
POST /api/fido/register/finish	WebAuthn RegistrationResponseJSON	{ verified, jwkPublicKey, did }
POST /api/fido/issuance/start	{ did, offerURL }	WebAuthn PublicKeyCredentialRequestOptions
POST /api/fido/issuance/finish	WebAuthn AuthenticationResponseJSON	{ walletId, credentialResult, submissionPayload }
POST /api/fido/verification/start	{ did, credId, presentationRequest }	WebAuthn PublicKeyCredentialRequestOptions
POST /api/fido/verification/finish	WebAuthn AuthenticationResponseJSON	{ walletId, credentialResult, submissionPayload }

Docker

A Dockerfile is provided. The recommended deployment uses the multi-service docker-compose.yml in the waltid-identity fork under waltid-applications/fido-vc-app/, which starts the middleware alongside the database, Wallet UI, and verifier sidecar.

Related projects

Part of the FIDO4VC project:

• fido-vc-cryptosuite-ts — the cryptosuite this middleware uses for canonicalization and proof assembly.
• fido-vc-wallet-ui — the Next.js frontend that calls these endpoints.
• fido-vc-verifier-sidecar — HTTP service for verifying VPs.

License

Licensed under the Apache License 2.0.