herald

README

Herald - OTP and Verification Code Service

📧 Your Gateway to Secure Verification

🌐 Multi-language Documentation

• English | 中文 | Français | Italiano | 日本語 | Deutsch | 한국어

Herald is a production-ready, standalone OTP and verification code service that sends verification codes via email and SMS. It features built-in rate limiting, security controls, and audit logging. Herald is designed to work independently and can be integrated with other services as needed.

Core Features

• 🔒 Secure by Design: Challenge-based verification with Argon2 hash storage, multiple authentication methods (mTLS, HMAC, API Key)
• 📊 Built-in Rate Limiting: Multi-dimensional rate limiting (per user, per IP, per destination) with configurable thresholds
• 📝 Complete Audit Trail: Full audit logging for all operations with provider tracking
• 🔌 Pluggable Providers: Extensible email, SMS, and DingTalk provider architecture (email via herald-smtp, DingTalk via herald-dingtalk)
• ↩️ Challenge Revoke: POST /v1/otp/challenges/{id}/revoke to revoke (unbind/invalidate) a challenge when it is no longer needed
• 🔐 TOTP Proxy (Optional): When enabled, proxy TOTP (Authenticator) operations to herald-totp so one Herald URL covers OTP and TOTP

Quick Start

Using Docker Compose

The easiest way to get started is with Docker Compose, which includes Redis:

# Start Herald and Redis
docker-compose up -d

# Verify the service is running
curl http://localhost:8082/healthz

Expected response:

{
  "status": "ok",
  "service": "herald"
}

Test the API

Create a test challenge (requires authentication - see API Documentation):

# Set your API key (from docker-compose.yml: your-secret-api-key-here)
export API_KEY="your-secret-api-key-here"

# Create a challenge
curl -X POST http://localhost:8082/v1/otp/challenges \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user",
    "channel": "email",
    "destination": "user@example.com",
    "purpose": "login"
  }'

View Logs

# Docker Compose logs
docker-compose logs -f herald

Manual Deployment

For manual deployment and advanced configuration, see the Deployment Guide.

Basic Configuration

Herald requires minimal configuration to get started:

Variable	Description	Default	Required
PORT	Server port	:8082	No
REDIS_ADDR	Redis address	localhost:6379	No
API_KEY	API key for authentication	-	Recommended

For email channel via herald-smtp, set HERALD_SMTP_API_URL (and optionally HERALD_SMTP_API_KEY); see Deployment Guide. For DingTalk channel, set HERALD_DINGTALK_API_URL (and optionally HERALD_DINGTALK_API_KEY); see Deployment Guide.

For complete configuration options including rate limits, challenge expiry, and provider settings, see the Deployment Guide.

Documentation

For Developers

• API Documentation - Complete API reference with authentication methods, endpoints, and error codes
• Deployment Guide - Configuration options, Docker deployment, and integration examples

For Operations

• Monitoring Guide - Prometheus metrics, Grafana dashboards, and alerting
• Troubleshooting Guide - Common issues, diagnostic steps, and solutions

Documentation Index

For a complete overview of all documentation, see docs/enUS/README.md.

License

See LICENSE for details.