Security model

The security guarantees OpenCred makes — and their boundaries. Start here before adopting it in production.

If you operate OpenCred in production, or you're auditing it before adoption, start here.

The single most important rule

OpenCred never receives, handles, or stores issuer private keys.

All signing happens locally — on the issuer's Desktop machine, or inside the issuer-operated Docker container. There is no code path — no endpoint, no function, no IPC handler — that accepts an issuer's private key as input. There is no hosted OpenCred service; NFH Trust Labs operates no servers that touch issuer credentials. This rule underpins the entire model.

At a glance

Area	Guarantee
Issuer keys	Never received by OpenCred. Loaded locally, held in memory as opaque KeyObject instances.
Key generation	Always CSPRNG (crypto.generateKeyPairSync, crypto.randomBytes). Math.random() is forbidden.
Logging	Key material is stripped by a redaction hook before any log record reaches disk.
Error responses	Use the OpenCredError hierarchy — sanitised by design; no internal paths or buffers leak.
Session data	Credential payloads, packaged outputs, and batch results are purged within OPENCRED_SESSION_TTL (default 4 hours).
JSON-LD contexts	Bundled at build time; never fetched from the network at runtime.
did:web resolution	HTTPS only, no redirects, 10-second timeout, DNS-resolved IPs validated as public before fetch (SSRF protection).

The seven invariants

OpenCred's behaviour is governed by seven mandatory invariants, enforced in code (not just documented). The first is the never-touch-issuer-keys rule above; the rest cover CSPRNG-only key generation, log redaction, sanitised errors, session-data expiry, build-time context bundling, and hardened did:web resolution. Each invariant names the place it is enforced.

Deployment hardening

The Docker image follows these invariants by default — non-root user, pinned base digests, no secrets in image layers, read-only filesystem and dropped capabilities in the shipped Compose file, and structured logging with key material redacted. See Docker → Security defaults.

Reporting a vulnerability

Do not open a public GitHub issue for a security problem. Use GitHub's private security-advisory flow on the opencred-releases repository, or the security contact listed in the project's SECURITY.md / README.