herald-totp

README

herald-totp

Multi-language Documentation

• English | 中文

TOTP 2FA service for the Herald/Stargate stack: enroll (bind), verify, and optional backup codes. It does not send codes; users generate TOTP in an authenticator app (e.g. Google Authenticator). Stargate calls herald-totp for per-user TOTP instead of a single global secret.

Core Features

• Enroll: POST /v1/enroll/start (returns QR content) and POST /v1/enroll/confirm (confirm with one TOTP code).
• Verify: POST /v1/verify (TOTP or backup code), with optional challenge_id for replay protection.
• Status: GET /v1/status?subject=... to check if a user has TOTP enabled.
• Backup codes: 10 one-time codes returned on confirm; can be used in verify when the device is lost.
• Security: Encrypted secret storage (AES-GCM), rate limiting, time-step replay protection, API key or HMAC auth.
• Graceful shutdown: On SIGINT or SIGTERM, server stops accepting new requests and shuts down with a 10s timeout.

Protocol

• POST /v1/enroll/start – Start enrollment; returns enroll_id, otpauth_uri.
• POST /v1/enroll/confirm – Submit TOTP code to confirm; returns backup_codes.
• POST /v1/verify – Verify TOTP or backup code.
• GET /v1/status?subject=... – Check if TOTP is enabled for subject.
• GET /healthz – Service and Redis health (via health-kit).

Configuration

Variable	Description	Default	Required
PORT	Listen port (with or without leading colon)	:8084	No
HERALD_TOTP_ENCRYPTION_KEY	32-byte AES-256 key for secret encryption	``	Yes (for enroll/verify)
API_KEY	If set, callers must send X-API-Key	``	No
HMAC_SECRET / HERALD_TOTP_HMAC_KEYS	HMAC auth	``	No
REDIS_ADDR	Redis address	localhost:6379	Yes
LOG_LEVEL	Log level: trace, debug, info, warn, error	info	No

See docs/enUS/DEPLOYMENT.md for full options.

Stargate integration

• Set HERALD_TOTP_ENABLED=true, HERALD_TOTP_BASE_URL=http://herald-totp:8084, and HERALD_TOTP_API_KEY or HERALD_TOTP_HMAC_SECRET to match herald-totp.

Quick Start

Build & run (binary)

go build -o herald-totp .
./herald-totp

With HERALD_TOTP_ENCRYPTION_KEY and Redis configured, enroll and verify will work.

Run with Docker

docker build -t herald-totp .
docker run -d --name herald-totp -p 8084:8084 \
  -e HERALD_TOTP_ENCRYPTION_KEY="your-32-byte-encryption-key-here!!" \
  -e REDIS_ADDR=redis:6379 \
  herald-totp

Optional: add -e API_KEY=your_shared_secret and set HERALD_TOTP_API_KEY to the same value on Stargate.

Documentation

• Documentation Index (English) – API | Deployment | Troubleshooting | Security
• 文档索引（中文） – API | 部署 | 故障排查 | 安全

Testing

go test ./...

Coverage:

go test -cover ./...
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out
go tool cover -html=coverage.out

Lint: golangci-lint run.

Operation

• Graceful shutdown: On SIGINT or SIGTERM, the server stops accepting new requests and shuts down with a 10s timeout. Logs "shutting down" and any shutdown error.
• Logging: Structured JSON logs via logger-kit. Set LOG_LEVEL to debug for more detail.

License

See LICENSE for details.