CredTrail App

Open-source Open Badges 3.0 platform with Cloudflare Workers SaaS and Docker self-host runtime profiles.

Standards-compliant verifiable credential issuance and verification for educational achievements.

What Can CredTrail Do?

✅ Core Badge Management

• Badge template creation - Define reusable badge designs with achievement criteria, images, and metadata
• Manual badge issuance - Issue badges to individual learners with signed verifiable credentials
• Cryptographic signing - Ed25519-based credential signing with did:web issuer identities
• Immutable storage - Store signed credentials as .jsonld files in object storage (R2/S3)
• Badge revocation - Revoke credentials with BitstringStatusList status tracking
• Email notifications - Automatic learner notifications on badge issuance

✅ Learner Experience

• Learner dashboard - View all earned badges in one place
• Governed learner pathways - Follow institution-defined, versioned programs with ordered badge and verified-record requirements
• Explainable progress - See exact evidence states, the next unmet requirement, and durable completion history
• Public badge pages - Shareable URLs for each credential with verification indicators
• Badge sharing - Copy URL, download VC JSON, add to LinkedIn profile directly
• Account linking - Link institutional identities with email fallback for post-graduation access
• Identity recovery - Maintain badge access after institutional email loss
• Multiple identities - Support for learner identity aliases across institutions
• Learner DID settings - Optional did:key, did:web, or did:ion subject IDs for privacy-preserving issuance

✅ Verification & Standards Compliance

• Public verification API - /credentials/v1/{id} endpoint for third-party verification
• Open Badges 3.0 - Full OB3 spec compliance with W3C Verifiable Credentials Data Model 2.0
• IMS Global validator - Deep-links to official IMS validator on badge pages
• Proof formats - Support for both VC-JWT and JSON-LD embedded proofs (EdDSA)
• Verifiable Presentations - VP create/verify APIs for holder-bound credential sharing
• DID documents - Serve did:web documents for issuer public key discovery
• Canonical URLs - OB3 JSON discovery links on public pages
• Achievement metadata - Rich achievement descriptions with evidence links

✅ Authentication & Access Control

• Hosted authentication - Better Auth-backed passwordless email login through CredTrail wrapper routes
• Institutional SSO integration - Better Auth-backed institutional sign-in with learner identity linking
• Multi-tenant RBAC - Tenant-scoped roles: owner, admin, issuer
• Session management - Better Auth sessions with tenant-scoped authorization and secure cookie handling
• Guided onboarding - New tenant setup flow with first badge template and issuance walkthrough

✅ Open Badges 3.0 API Compliance

• OAuth 2.0 flows - Authorization Code Grant with Dynamic Client Registration
• PKCE enforcement - S256 code challenge method required
• Service discovery - /.well-known/openid-credential-issuer endpoint with OpenAPI documentation
• Secure REST endpoints - /ims/ob/v3p0/credentials and /ims/ob/v3p0/profile with scoped authorization
• Token management - Refresh token rotation and revocation endpoints
• Content negotiation - Accept both VC-JWT and JSON-LD formats
• Credential upsert - Update existing credentials while maintaining immutability

✅ Governance & Compliance

• Audit logging - Immutable logs for issuance, revocation, and role changes
• Pathway governance - Publish immutable pathway versions, record approved exceptions, and require human review before final credential issuance
• Tenant isolation - Strict data separation between organizations
• Type safety - Full TypeScript with strict mode enabled
• Input validation - Zod schemas at all HTTP and queue boundaries

✅ Infrastructure & Operations

• Database-backed queues - Simple Postgres table for async jobs (issue_badge, revoke_badge)
• Monorepo structure - Turborepo-based workspace with shared packages
• CI/CD pipeline - Automated linting, type checking, and testing
• Observability - Structured JSON logging with Logpush export
• Runtime profiles - Cloudflare Workers (SaaS) and Node + Docker (self-host)

App layout

• apps/api-worker: Primary Worker serving API + server-rendered Hono JSX UI.
• packages/core-domain: Shared domain models, VC signing, and cryptographic helpers.
• packages/db: Postgres query helpers, tenant scoping utilities, and DB-backed job queue storage.
• packages/validation: Zod schemas for HTTP and queue boundaries.
• docs: Implementation docs and ADRs (including docs/LEARNER_DID_SETUP.md, docs/LEARNER_WALLET_IMPORT.md, docs/DCC_LCW_COMPATIBILITY.md, docs/VERIFIABLE_PRESENTATIONS.md, and docs/LMS_INDEPENDENCE_MIGRATION_RUNBOOK.md).

API worker module layout (apps/api-worker/src)

• app.ts: Composition root only (dependency wiring + route registration).
• routes/: Route handlers by feature area.
• auth/: Tenant/session permission helpers.
• badges/: Issuance flow, public badge rendering/view models, revocation helpers.
• credentials/: Verification checks and proof verification helpers.
• signing/: Signing key/registry resolution, DID/JWKS docs, credential signer helpers.
• ob3/: Open Badges 3.0 OAuth/discovery/access-token helpers.
• http/: Common middleware and shared HTTP utility helpers.
• queue/: Queue job payload/building/processing/scheduled trigger helpers.

Server-rendered UI

• Server-rendered app pages are authored in Hono JSX (.tsx) and rendered through appPage / renderAppPage from apps/api-worker/src/ui/render-page.tsx.
• Page modules return AppPage; route handlers render them with renderAppPage(c, page, status?).
• Use page asset keys and PageAssets for CSS and feature-local JavaScript. CSS and client script source strings live under apps/api-worker/src/ui/page-assets/content.
• Do not add React, Kiwa, Tailwind, client components, hydration, hono/html, raw(), dangerouslySetInnerHTML, or interpolated full-document HTML strings.
• JSX owns text and attribute escaping for page markup. Validate boundary input with Zod and keep manual HTML escaping out of page modules.

Async jobs

• Queue messages are stored in Postgres table job_queue_messages.
• Use POST /v1/jobs/process to lease and process pending jobs.
• Hosted deployment can run the same processor via Cloudflare Cron scheduled events.
• Self-host deployment can run the queue polling worker process in Docker.
• Jobs: issue_badge, revoke_badge, rebuild_verification_cache, import_migration_batch

Commands

Run from the workspace root:

• pnpm export:ob3-openapi
• pnpm check:ob3-openapi
• pnpm build:design-tokens
• pnpm check:design-tokens
• pnpm lint
• pnpm lint:fix
• pnpm format
• pnpm format:check
• pnpm typecheck
• pnpm test
• pnpm check

OB3 OpenAPI snapshot file: docs/openapi/ims-ob-v3p0.openapi.json

Accessibility lint allows explicit native list and table roles: Safari can drop list semantics after styling, and the mobile badge table uses block/grid layout. Table containers and cells are excluded from control-label checks; their controls are checked separately, and nested summary labels are inspected three levels deep. prefer-tag-over-role is disabled because its replacements cannot represent composite charts, inline SVG, action groups, or live status messages correctly.

Local development

Use Wrangler local with local Postgres and Wrangler R2 emulation for daily app development:

• First run: pnpm dev:up
• Daily Wrangler watch after bootstrap: pnpm dev
• Print health and demo routes: pnpm dev:status
• Print the seeded admin login URL: pnpm dev:login-as
• Reset and reseed demo data: pnpm dev:reset
• Watch a headed browser create real demo data: pnpm dev:demo
• Run browser regression checks: pnpm test:e2e

The default seeded tenant is tenant_123; the seeded admin is admin@credtrail.local. The seed includes a public credential DB row and local Wrangler R2 object for /badges/trusted-demo-credential. See docs/LOCAL_DEV.md for the full local demo contract and troubleshooting notes.

Self-host Docker

Copy .env.selfhost.example to .env.selfhost, then set your Postgres DATABASE_URL and S3 or R2 bucket credentials. The default stack uses an existing database, such as AWS RDS:

docker compose --env-file .env.selfhost -f docker-compose.selfhost.yml up --build --wait

For local Postgres, set DATABASE_URL=postgres://credtrail:credtrail@postgres:5432/credtrail and add -f docker-compose.selfhost-postgres.yml before up. See the Docker runbook for certificate mounts, production settings, backups, and validation. Docker installations can send email through SMTP or Amazon SES. The SMTP setup and image email check cover mounted passwords, Reply-To, and optional copies of badge notifications.

Observability

• Structured logs are emitted as JSON and can be exported through Logpush configuration.

Institution integration API

See the integration API guide for issuing and revoking badges, tracking completion, discovering templates, and reconciling issued credentials with scoped API keys. The OpenAPI document is also served at /v1/programmatic/openapi.json.