herald

command module
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

README

Herald - OTP and Verification Code Service

Go Test Coverage Go Report Card License Go Version

Herald v1.9.0 adds HERALD_CODE_HASH_KEY_PREVIOUS, a list of keys under which stored verification code digests are verified but not written, so HERALD_CODE_HASH_KEY can be changed without refusing outstanding challenges. It is empty by default and nothing changes unless it is set; challenge-kit moves to v1.14.0. Read the upgrade and rollback guidance before changing the key on more than one instance. For enabling the key introduced in v1.8.0, see upgrade from v1.7.0 to v1.8.0.

📧 Your Gateway to Secure Verification

🌐 Multi-language Documentation

Herald

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.

The HTTP server uses Fiber v3. Dependency versions and the Go toolchain are pinned in go.mod (Go 1.27.4 or later). Builds and validation run on Linux; use Linux containers on macOS, Windows and other hosts.

Architecture

Herald architecture

Core Features

  • 🔒 Secure by Design: Challenge-based verification with Argon2 hash storage, HMAC or API-key request authentication with optional mTLS transport
  • 📊 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

Current security upgrades

HMAC challenge creation requires v3. Use the v2 verification API with expected user, purpose and channel from trusted application state. Upgrades from before v1.3.10 require a coordinated activation index upgrade. Keep Redis and audit volumes persistent. See provider diagnostics for log field changes and historical log/trace handling. Other-language translations are historical; current operational guides are maintained in English and Chinese.

For v1.3.13, follow the HMAC identity upgrade before resuming creation traffic. Single-secret HMAC accepts only an omitted key ID or default; legacy ambiguous records need reconciliation. Production CORS lists must not contain standalone * entries. See the changelog for this release.

Quick Start

Using Docker Compose

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

# Required secrets: Compose refuses insecure repository-known defaults.
export REDIS_PASSWORD="$(openssl rand -hex 32)"
export HERALD_API_KEY="$(openssl rand -hex 32)"

# Needed to send email codes (see "Test the API"). Use an SMTP server that
# offers STARTTLS. Skip these to start Herald without a delivery provider.
export SMTP_HOST="smtp.example.com"
export SMTP_USER="herald@example.com"
export SMTP_PASSWORD="your-smtp-password"
export SMTP_FROM="herald@example.com"

# Start Herald and Redis in API-key mode
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). Herald can only deliver a code on a channel that has a provider. The Compose file registers the built-in SMTP provider for the email channel when the SMTP_* variables above were set before docker compose up; replace user@example.com with an address you can read.

# Reuse the key exported before docker compose up
export API_KEY="$HERALD_API_KEY"

# 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"
  }'

With a working SMTP provider the code is sent and the response is:

{
  "challenge_id": "ch_...",
  "expires_in": 300,
  "next_resend_in": 60
}

Without a provider for the channel, or when the SMTP server rejects the message, no code is sent and the response is an error with "ok": false and a reason. The Compose stack uses the strict provider policy, so a failed delivery is never reported as success. When the failure shows that no message can have been accepted (the SMTP host does not resolve, nothing listens on the port, the certificate is not trusted, the credentials are refused), the request can be repeated at once. After any other failed send (a timeout, a dropped connection, a command the server rejected) the resend cooldown (60 seconds by default) stays in place and repeating the request answers 429/resend_cooldown. The Herald log line Failed to send verification code via provider carries a failure_category that says where the SMTP delivery stopped (see troubleshooting). For SMS, DingTalk and the HTTP email plugin see the Deployment Guide.

View Logs
# Docker Compose logs
docker compose logs -f herald
Manual Deployment

Builds and validation run on Linux. For macOS, Windows, and other environments, we recommend deploying Herald in a Linux container using Docker Compose.

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 REQUEST_AUTH_MODE=api_key - Required in production API-key mode

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
Documentation Index

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

License

See LICENSE for details.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
internal
auth
Package auth implements Herald's request authentication policy.
Package auth implements Herald's request authentication policy.
destination
Package destination provides a single canonical normalization and validation point for OTP destinations (email / SMS / DingTalk).
Package destination provides a single canonical normalization and validation point for OTP destinations (email / SMS / DingTalk).
security
Package security provides small privacy-preserving primitives shared across Herald: peppered digests for PII that must be used as a stable key/label (rate-limit keys, audit fingerprints) without landing raw email/phone values in Redis or logs.
Package security provides small privacy-preserving primitives shared across Herald: peppered digests for PII that must be used as a stable key/label (rate-limit keys, audit fingerprints) without landing raw email/phone values in Redis or logs.
server
Package server owns Herald's HTTP lifecycle: it builds a TLS or plaintext listener from config, starts serving, and performs an ordered graceful shutdown (stop accepting -> drain in-flight -> flush audit writer -> shutdown tracer).
Package server owns Herald's HTTP lifecycle: it builds a TLS or plaintext listener from config, starts serving, and performs an ordered graceful shutdown (stop accepting -> drain in-flight -> flush audit writer -> shutdown tracer).
pkg

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL