Digital Credential Common Service

A multi-tenant API providing a format-agnostic abstraction layer for Digital Credential operations. The service normalizes issue/verify/hold patterns across credential formats and backend agents, enabling seamless integration of diverse credential ecosystems.

Overview

The Digital Credential Common Service acts as a unified gateway for Digital Credential operations. It abstracts away the complexity of working with multiple credential formats and allows applications to interact with credentials through a standardized API.

Key Features

• Multi-tenant Architecture: Isolated tenant environments with secure data segregation
• Format-Agnostic Operations: Support for multiple Digital Credential formats
• Standardized API: Consistent interfaces for issue, verify, and hold operations
• Job Processing: Asynchronous job queue for long-running operations
• Graceful Shutdown: Clean application shutdown with resource cleanup
• Health Monitoring: Built-in health check endpoints for service monitoring

Technology Stack

• Framework: NestJS - Progressive Node.js framework
• Database: PostgreSQL - Relational database
• ORM: TypeORM - Data persistence layer
• Job Queue: pg-boss - PostgreSQL-backed job queue
• Language: TypeScript

Quick Start

Prerequisites

• Node.js v24 (pinned in .mise.toml — mise install gets you the right version)
• Docker & Docker Compose (recommended)
• PostgreSQL 18+ (or use Docker)

Installation & Setup

1. Clone the repository and install dependencies

   npm install

2. Configure environment

   cp .env.example .env

3. Generate a local OIDC signing key

   # Docker-only workflow
   docker compose run --build --rm --no-deps app node scripts/generate-oidc-keys.mjs oidc-keys.json
   mv oidc-keys.json config/oidc-keys.json

   The generated key is gitignored and must not be committed. If Node 24 is installed locally, you can instead run node scripts/generate-oidc-keys.mjs config/oidc-keys.json.

4. Start the application

   # With Docker Compose (recommended)
   docker compose up
   
   # Or locally with npm
   npm run start:dev

   After the first Compose start, follow Export and trust the Caddy local CA before opening https://app.localhost in a browser.

The application will be available at http://localhost:3000

Database Migrations

Migrations run automatically when starting with Docker Compose. For local development:

npm run build
npm run migrate:up

See DEVELOPER.md for detailed migration instructions.

Integration Test Database Profile

Use Docker Compose's test profile for an isolated PostgreSQL-only integration test database on localhost:5433, then run integration tests against it:

docker compose --profile test up -d db-test migrate-test seed-test
npm run test:integration
docker compose --profile test down -v

See DEVELOPER.md for details on this and the other test tiers (unit/integration/e2e), plus MockAdapter and test data factory usage.

Local Observability Stack

Grafana, Loki, Tempo, Mimir and an OpenTelemetry Collector run locally in a single container, mirroring the backends the deployed stack uses:

docker compose --profile obs up -d lgtm

Grafana is then at http://localhost:3001 (or https://grafana.localhost through Caddy). Set OTEL_ENABLED=true in your .env to send it data.

See DEVELOPER.md for the full walkthrough, including what to look for in Grafana and how the local setup differs from OpenShift.

Documentation

• DEVELOPER.md - Detailed setup, running, testing, and troubleshooting guide
• ARCHITECTURE.md - System architecture and design decisions
• openapi.yaml - API specification

Project Structure

apps/
  └── digital-trust-common-service/        # Main application
      ├── src/
      │   ├── main.ts           # Entry point
      │   ├── app.module.ts     # Root module
      │   ├── health/           # Health check
      │   ├── tenants/          # Tenant management
      │   ├── tenant-users/     # User management
      │   ├── jobs/             # Job processing
      │   └── shutdown/         # Shutdown coordination
      └── test/                 # E2E tests

libs/
  ├── database/                 # Database setup & migrations
  ├── auth/                     # Authentication & authorization
  ├── pg-boss/                  # Job queue service
  └── common/                   # Common utilities

Development

# Start development server with hot reload
npm run start:dev

# Run unit tests
npm run test

# Run integration tests
npm run test:integration

# Run tests in watch mode
npm run test:watch

# Run e2e tests
npm run test:e2e

# Lint and format code
npm run lint
npm run format

For comprehensive development instructions, see DEVELOPER.md.

API Endpoints

• GET /health/live - Service health check

See openapi.yaml for complete API documentation.

Support

For issues, questions, or contributions, please refer to:

• DEVELOPER.md - Troubleshooting guide
• ARCHITECTURE.md - System design documentation

License

UNLICENSED