Environment & Setup

These steps are only required when self-hosting the wallet-server. You can skip this section if you deploy from Empeiria's One-Click Deployment Portal.

Prerequisites

• Node.js 20+

• Yarn 1.22.x (the repo pins [email protected] via packageManager)

• PostgreSQL 14+ (tested with 16.x)

Configuration (.env)

Create a .env file in the wallet-server root. Configuration is read from environment variables; the service validates the required ones at startup and refuses to boot if any are missing.

Required

• DATABASE_URL — PostgreSQL connection string for the datastore, e.g. postgres://user:pass@localhost:5432/ssi.

• ISSUER_BASE_URL — public base URL under which this service serves OpenID4VCI issuer endpoints and credential offers. Any base URL works; by convention it ends with the protocol's path segment, e.g. https://issuer.example.com/oid4vci (and https://verifier.example.com/oid4vp for the verifier URL below).

• VERIFIER_BASE_URL — public base URL under which this service serves OpenID4VP verifier endpoints. As with the issuer URL, a protocol path suffix is typically appended (e.g. https://verifier.example.com/oid4vp).

Authentication

Every non-public endpoint requires a valid OIDC JWT Bearer token (Authorization: Bearer <token>). Tokens are validated against a JWKS endpoint.

• OIDC_JWKS_URL — JWKS endpoint used to verify access tokens (e.g. a Keycloak realm's .../protocol/openid-connect/certs). Required unless AUTH_DISABLED=true.

• AUTH_DISABLED — set to true for local development only. Every request is then treated as an authenticated admin, so no token is needed. Never enable this in production.

did:web hosting

The hostname for a did:web is supplied per request, in the required domain field of POST /agent/did/web (e.g. issuer.example.com, optionally with a port such as example.com:8080). There is no environment-variable fallback.

Hosted did:web documents are keyed by a generated UUID and served by this service over HTTPS at a fixed route; there is no configurable path prefix. See "did:web & Hosting" for path rules and examples.

Other

• PORT — HTTP port (default 3000).

• ALLOW_INSECURE_HTTP — set to true to allow plain HTTP URLs during local development. OpenID4VC requires HTTPS in production, so leave this unset (or false) outside of local testing.

• NODE_ENV — when set to production, unhandled error messages returned to clients are replaced with a generic Internal server error; the real cause is only written to the logs.

Example

PORT=3000

# Datastore
DATABASE_URL=postgres://postgres:postgres@localhost:5432/ssi

# Public base URLs (a protocol path suffix is typically appended)
ISSUER_BASE_URL=https://issuer.example.com/oid4vci
VERIFIER_BASE_URL=https://verifier.example.com/oid4vp

# Authentication (JWKS endpoint for OIDC Bearer tokens)
OIDC_JWKS_URL=https://auth.example.com/realms/empe/protocol/openid-connect/certs
# Local-only shortcut: skip token validation, treat every caller as admin
# AUTH_DISABLED=true

# Local development over plain HTTP (never enable in production)
# ALLOW_INSECURE_HTTP=true

Install & Run

yarn install
yarn start:dev
# or
yarn build && yarn start:prod

Swagger UI: http://localhost:<PORT>/api-docs OpenAPI JSON: http://localhost:<PORT>/api-docs-json

A global rate limit of 60 requests per 60 seconds applies (serving of DID documents is exempt).

Database

• The datastore is PostgreSQL, configured through a single DATABASE_URL connection string.

• Database migrations run automatically at startup; no separate flag or command is required.

• Stored data includes hosted DID documents, tenant signing keys, credential schemas, issuance and verification session state, and credentials held by cloud wallets.

did:web Hosting Notes

• This service creates did:web and did:key (Ed25519) identifiers and serves the did:web documents itself.

• A hosted did:web document is served at GET /:uuid/did.json (and at GET /:uuid/.well-known/did.json), where :uuid is the identifier generated when the DID is created.

• The did:web identifier is built from the domain supplied in the POST /agent/did/web request body plus a generated UUID, producing a DID of the form did:web:issuer.example.com:<uuid>.

• See "did:web & Hosting" for path rules and examples.

Requirements

The wallet server runs as part of the EVDI SSI Core stack and shares its runtime requirements: Node.js 20 and PostgreSQL 16.