Vault42
Production-grade JWT authentication server written in Go, with an integrated Vue frontend, honeypot mode for threat observation, and 3 direct production dependencies -- 18 Go modules once everything those three pull in is counted. JWT, Redis, TOTP, CORS, JWKS, and migrations are all hand-rolled.
Vault42 issues its own tokens and is an OAuth2 client of other providers. It is not an OAuth2 authorization server and not an OIDC provider: there is no authorize endpoint, no consent screen, and no redirect_uri a third-party client registers against it.
Install
Every release publishes signed container images, a signed Helm chart and the two .NET SDKs.
The commands below need no clone.
# Helm chart, from the OCI registry the release pushes it to
helm pull oci://ghcr.io/42-v/charts/vault-auth --version 1.1.3
# Images: the server, the mTLS admin gateway, the honeypot bridge
docker pull ghcr.io/42-v/vault42:1.1.3
docker pull ghcr.io/42-v/vault42-admin-gateway:1.1.3
docker pull ghcr.io/42-v/vault42-bridge:1.1.3
# Client SDKs
dotnet add package Vault42.AspNetCore --version 1.1.3
dotnet add package Vault42.Blazor --version 1.1.3
A default helm install renders, but it will not come up on its own: the Deployment mounts
eight keys out of a Secret you supply and expects a PostgreSQL you already run, because the
chart's bundled one is a development convenience and is off by default.
docs/deployment-guide.md is the path from here to a running
install; scripts/deploy-dev.sh stands the whole thing up locally against a self-signed CA if
you only want to look at it.
Every artifact above is keyless-signed -- see Verifying a release.
Highlights
- RS256 JWT: algorithm whitelist (rejects
none, HS256, all others), fingerprint-bound, 8KB size limit
- Argon2id: 46 MiB / 1 iteration, per-password salt and server-side pepper, 15-char enforced password minimum outside dev (dev floor 8), HIBP breach check
- Refresh token rotation: family tracking, single-use, replay detection nukes the entire family
- KMS unwrap oracle:
POST /kms/unwrap KEK envelope-unwrap, gated by the kms:unwrap scope, fail-closed rate limit, synchronous audit, every failure collapsed to one opaque error; the vault kms wrap CLI produces envelopes
- WebAuthn/FIDO2: passkey registration and authentication
- TOTP 2FA: RFC 6238, hand-rolled (~80 lines), backup codes for recovery
- OAuth2/OIDC login: GitHub, Google, Facebook, plus generic OIDC (Okta, Auth0, Keycloak, Entra via
VAULT_OIDC_PROVIDERS); PKCE S256 on every provider with no downgrade path, single-use verifier, and the outbound authorize URL checked to be absolute HTTPS before the browser is sent to it
- Delegated signing:
POST /mint signs an assertion about a subject vault42 never authenticated, for a service that already knows who its caller is. Off unless VAULT_MINT_ENABLED is set with a VAULT_MINT_AUDIENCE distinct from the origin, gated by the mint:token scope on a client credential, fail-closed rate limit, and every refusal audited. Read docs/security.md AR-16 before enabling it
- Encrypted identity store: AES-256-GCM encrypted PII, HMAC-SHA256 pseudonymous keys
- DB-backed signing keys: encrypted at rest (AES-256-GCM, kid as AAD), multi-pod refresh, zero-downtime rotation via the admin gateway
- Encrypted blob storage: compress-then-encrypt (DEFLATE + AES-GCM), per-user quotas
- Account erasure + escrow: GDPR right-to-be-forgotten with recoverable encrypted escrow (server holds only a recovery public key), bounded by
VAULT_RECOVERY_RETENTION_DAYS + sweeper
- IP access control and geo-fencing: allowlist/blocklist, dynamic runtime bans, proxy-agnostic
- Append-only audit log: DB-level enforcement (app role has no DELETE/TRUNCATE/DDL)
- mTLS admin plane: the admin gateway requires a client certificate, and beyond "signed by our CA" it pins the peer's CN and SANs against and checks on every handshake. Both are optional so an upgrade does not break, and an unset allowlist logs a warning naming what it costs: every certificate the CA ever signed reaches the admin plane, including a decommissioned operator's
DPoP (RFC 9449) is a working sender-constraint. With VAULT_DPOP_ENABLED, a request that
presents a valid proof gets back a token stamped with that key's JWK thumbprint in cnf.jkt,
and every authenticated route then refuses that token unless the request carries a fresh
single-use proof over the matching key, presented under the DPoP authorization scheme rather
than Bearer. A token issued without a proof carries no cnf.jkt and stays an ordinary bearer
token, which is what keeps non-DPoP clients working with the flag on. The binding is what makes
the proof checking worth anything: a proof never compared against a key the token committed to
only demonstrates that the caller can sign something.
Two limits are real, and one of them narrowed. Refresh families are sender-bound as of migration
038: a family opened with a proof records that key's thumbprint in auth.refresh_tokens.dpop_jkt
and every rotation inherits it, so enforceDPoPBinding refuses a redemption presenting the wrong
key or no key, and the successor pair is bound to the stored thumbprint rather than to whatever
the redemption happened to present. What is still unbound is a family that opened without a
proof: dpop_jkt is NULL there, which means an ordinary bearer family, and there is deliberately
no backfill, so a session predating DPoP keeps working and keeps its old exposure. And there is
no DPoP-Nonce, so a proof's freshness rests on its own iat inside a five-minute window plus
the single-use JTI cache; the server cannot require a proof minted after a value it chose.
Architecture
cmd/vault/ Entry point (also hosts the `vault ...` admin CLI)
cmd/admin-gateway/ mTLS admin gateway (key rotation, erasure, RBAC), with the
client-certificate CN/SAN allowlist and CRL check
cmd/bridge/ Honeypot bridge proxy (standalone, stdlib only)
cmd/recover/ Offline account-recovery tool (decrypts erasure escrow)
internal/
handler/ HTTP handlers (auth, user, oauth, 2fa, password, identity, blobs,
kms, mint, service documents). Admin HTTP is adminapi, not here
service/ Business logic (token lifecycle, MFA, HIBP, identity, blobs,
erasure, mint, service documents, the retention sweepers)
repository/ PostgreSQL via pgx
adminapi/ Admin gateway HTTP layer (RBAC, sessions, email branding)
middleware/ Auth, fingerprint, rate limiting, CORS, DPoP, security headers, IP access
dpop/ Carries a validated proof's thumbprint from middleware to issuance,
which is what lets a minted token commit to the key (cnf.jkt)
jwt/ Stdlib-only RS256 sign/verify, ES256 verify, parsing, claims
crypto/ Argon2id, AES-256-GCM, HMAC, TOTP, JWKS, DPoP
kms/ KEK envelope-unwrap oracle (HKDF-derived per-kid KEKs)
keystore/ DB-backed signing keys, encrypted at rest, multi-pod refresh
redis/ RESP2 client + connection pool (stdlib net)
cache/ Pluggable: Redis, in-memory, PostgreSQL
config/ Env vars, _FILE secret loading, profiles
server/ HTTP server, TLS 1.3, middleware wiring
migrate/ SQL migration runner
model/ Domain types + WebAuthn adapter (there is no internal/webauthn
package; WebAuthn lives in model, repository, handler and server)
rbac/ Admin role/permission checks
metrics/ Hand-rolled Prometheus text exposition
audit/ Append-only audit logger
email/ SMTP + SendGrid, go:embed HTML templates, per-app white-label
deferwork/ Bounded pool for work that outlives its request, drained on shutdown,
so an unauthenticated caller cannot decide how many goroutines run
firstboot/ Hands a once-only generated credential to the operator without
putting it in the process log
ipintel/ Embedded IP-intelligence table (VPN, hosting, Tor) and its lookup
cli/ Admin CLI (add-client, rotate-jwks, list-clients, seed, etc.)
seed/ Declarative JSON seeding for clients and users
oauth2/ GitHub, Google, Facebook, and generic OIDC providers
honeypot/ Trap user detection, webhook alerts
frontend/ Embedded Vue SPA (go:embed)
httputil/ JSON helpers, log sanitization
sanitize/ Input validation
useragent/ User-Agent parser
packages/vue/ @vault42/vue: composables + i18n (38 locales)
packages/dotnet/ Vault42.AspNetCore + Vault42.Blazor (published to nuget.org)
web/ Vue 3 + Vite + Tailwind SPA
site/ Static landing page for vault.42-v.com (no build step)
charts/vault/ Helm chart (default, embedded, honeypot, bridge, dev, local values)
migrations/ PostgreSQL DDL (auth, audit, identity, objects schemas)
tests/
unit/ Table-driven unit tests
attack/ Attack vector simulations (alg confusion, replay, injection, timing, DPoP)
compliance/ NIST SP 800-63B + OWASP ASVS verification
spec/ Executable assertions about the chart, the workflows and the wiring
integration/ Testcontainers (real PostgreSQL + Redis)
e2e/ End-to-end flows, including a multi-replica keystore setup
fuzz/ Go native fuzzing (JWT, TOTP, Argon2, ES256, email, identity, kid,
DPoP, PKCE, OAuth state, mint, service documents)
browser/ Chromedp browser security tests (separate go.mod)
e2e-browser/ Playwright suite (separate toolchain)
admin/ Admin-gateway E2E over real mTLS
honeypot/ Bridge + honeypot E2E tests (honeypot_e2e build tag)
stress/ Load suite (stress build tag)
mocks/, testutil/ Shared fakes and container-runtime detection
Quick Start
# Kubernetes dev environment (requires mkcert, docker, kubectl, helm, nginx-ingress)
scripts/deploy-dev.sh
# → https://vault.localhost
# Build from source
CGO_ENABLED=0 go build -ldflags="-s -w" -o vault42 ./cmd/vault
# ARM64 (RPi5)
CGO_ENABLED=0 GOARCH=arm64 go build -ldflags="-s -w" -o vault42 ./cmd/vault
# Tests
scripts/t.sh # all
scripts/t.sh ./tests/attack/... # attack suite
scripts/tcount.sh # quick count
# Coverage report → docs/test-coverage.md (per-package + per-function breakdown)
scripts/coverage.sh
# Full security pass (govulncheck, gosec, trivy fs, attack suite, coverage).
# Run this before tagging a release; it mirrors the nightly CI workflow.
scripts/release-check.sh
Deployment Profiles
| Profile | Cache | Use Case |
|---|
production | Redis | Full features, TLS 1.3, external PostgreSQL + Redis |
embedded | In-memory | RPi5 / edge (~60 MB RAM), 5 conns. Point it at a PostgreSQL you run; the chart's bundled one is a development convenience, off by default, and did not start on any released version -- see deployment-guide |
honeypot | Redis | Production defaults plus auto-migrate and the embedded SPA, so the trap looks like a real deployment. Trap user detection and webhook alerts |
dev | Inherits production | Auto-migrate, permissive CORS, 24h refresh TTL, 5s shutdown. Logging is not louder in dev; there is no log-level setting |
Dependencies
3 direct production dependencies, and 15 more the build links through them (full table):
| Dependency | Purpose |
|---|
pgx/v5 | PostgreSQL driver + pool |
go-webauthn | WebAuthn/FIDO2 passkeys |
x/crypto | Argon2id hashing |
Everything else (JWT, Redis, TOTP, CORS, JWKS, config, migrations, password hashing) is stdlib or hand-written.
The badge table splits the same way for the frontend and the .NET SDKs. The Deps row is what each of them declares and can drop; the Transitive row is what those declarations resolve to, and it is the one a supply-chain question is really about. The transitive figures come from what each toolchain resolves rather than from a manifest: go list -deps ./..., the pnpm lockfile, and the NuGet restore graph. Go's direct count is filtered through the same build closure, so requires only the test suites import are not credited to the release.
Testing
Twelve Go suites under tests/: unit, attack simulation (93 vector files), NIST/OWASP/OpenSSF-Scorecard compliance, spec (chart and workflow assertions), integration (testcontainers), end-to-end including a multi-replica keystore, fuzz (18 targets), browser (chromedp), Playwright, admin-gateway E2E over real mTLS, honeypot E2E (bridge + trap flows), and stress. The frontend adds its own vitest runs in web/ and packages/vue/, and the published .NET SDKs carry an xunit suite gated at 100.00% line coverage by scripts/dotnet-coverage.sh. Several suites need a container runtime, a build tag or a browser and are skipped without one; the Suites CI cannot run job fails the build if a suite neither ran nor said why.
Coverage tooling lives in scripts/:
| Script | Purpose |
|---|
scripts/t.sh [path] | Run Go tests (default: all packages, single path supported) |
scripts/tcount.sh | Test-count summary. It runs the suite; what it saves you is reading the output, not the wait |
scripts/coverage.sh | Regenerate docs/test-coverage.md with per-package + per-function coverage |
scripts/dotnet-coverage.sh | Build, test and coverage-gate the published .NET SDKs (floor 100.00, no exclusions) |
scripts/security-scan.sh | Standalone Go + frontend security pass (go vet, gosec, govulncheck, staticcheck, pnpm audit, hadolint) |
scripts/release-check.sh | Full pre-release gate, twelve of them: the security pass (govulncheck, gosec, trivy fs, attack suite, coverage) plus version consistency, module hygiene, golangci-lint at zero, helm, doc chart paths, a changelog section for the version, and a clean tree |
scripts/precommit.sh | Pre-commit verification: build, vet, gosec, tests, badges, docs |
Docs
Full index with one line on each document: docs/README.md.
| |
|---|
| Specification | Authoritative spec (verified against implementation) |
| Architecture | Auth flows, middleware chain, token architecture |
| Configuration | Every env var, profiles, _FILE convention, fail-closed overrides |
| API Reference | 108 endpoints, schemas, curl examples: 62 on the main server, 46 on the admin gateway |
| Deployment Guide | Kubernetes install, KMS root key, upgrades, backup |
| Admin Gateway | mTLS admin plane, RBAC model, admin endpoints |
| Bridge Deployment | Honeypot bridge proxy |
| Security & Accepted Risks | AR-1 through AR-18: what is deliberately not defended |
| Attack Cheatsheet | Attack vectors with defenses and the tests that prove them |
| Standards Compliance | NIST SP 800-63B, OWASP ASVS, Top 10, RFC family |
| Privacy Policy |
Contributing
Read CONTRIBUTING.md first. scripts/precommit.sh is the gate and no hook
runs it, and commits are commitlint-enforced. Releases are cut by pushing a v*.*.* tag at a
commit that is already on main; nothing in a commit subject triggers one.
Security
Found a vulnerability? Do not open a public issue.
Email [email protected] (Tuta, end-to-end encrypted). See SECURITY.md for the
intake process, how a security fix ships, the supported-version and semver policy, and how to
verify a release with cosign.
Verifying a release
Images, the Helm chart and the release checksum file are all signed with keyless cosign, and
the images carry SBOM and SLSA provenance attestations:
cosign verify \
--certificate-identity-regexp '^https://github\.com/42-v/vault42/\.github/workflows/release\.yml@refs/tags/v.+$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/42-v/vault42:1.1.3
Full instructions, covering all four artifact classes, are in
SECURITY.md.
Disclaimer
This software is provided "as is", without warranty of any kind. It is designed with security as a core principle (constant-time comparisons, algorithm whitelisting, least-privilege DB roles, append-only audit), but it is only as secure as the system it is deployed on. Review the code before deploying to production. See LICENSE (MIT).
