Security
How HelloJohn protects your users and your data — from password hashing to token signing, rate limiting, and vulnerability disclosure.
Security
HelloJohn is built with security as a first-class concern. This page summarizes the security model, default behaviors, and configuration options.
Threat model
HelloJohn protects against:
| Threat | Mitigation |
|---|---|
| Password theft | Argon2id hashing, never stored in plaintext |
| Token forgery | Ed25519-signed JWTs, short TTL (15 min) |
| Credential stuffing | Rate limiting, lockouts, breach detection |
| Session hijacking | Refresh token rotation, IP/UA binding (optional) |
| Replay attacks | Short-lived tokens, nonce tracking for magic links |
| Brute force | Exponential backoff after failed attempts |
| CSRF | SameSite=Lax cookies, CORS origin validation |
| Bot sign-ups | Configurable bot detection (Turnstile, hCaptcha, custom) |
| Phishing | MFA, passkeys, SAML SSO |
| Supply chain | Minimal dependencies, signed release artifacts |
Password security
HelloJohn uses Argon2id to hash passwords — the winner of the Password Hashing Competition, recommended by OWASP and NIST.
Default parameters:
algorithm: Argon2id
memory: 64 MB
iterations: 3
parallelism: 2
salt length: 16 bytes (random per password)
hash length: 32 bytesThese parameters are tuned to take approximately 100ms on modern hardware — fast enough for good UX, slow enough to be computationally expensive to crack.
Passwords are never logged, never stored in plaintext, and never returned in API responses.
See Password Policy for configuring minimum strength requirements.
Token security
Access tokens
- Format: JSON Web Token (JWT)
- Algorithm: EdDSA (Ed25519) by default; HS256 supported
- TTL: 15 minutes (configurable)
- Verification: Stateless — verify via JWKS, no network call per request
- Contents:
sub,email,tenant_id,org_id,role,iat,exp
Refresh tokens
- Format: Opaque 256-bit random string
- Storage: Hashed with SHA-256 in PostgreSQL (never stored raw)
- TTL: 30 days (configurable)
- Rotation: Every use issues a new refresh token and invalidates the old one
- Family tracking: Reuse of an old token immediately revokes the entire token family
Magic link tokens
- Format: Opaque 128-bit random string
- TTL: 15 minutes (configurable)
- Single-use: Token is invalidated immediately after first use
- Rate limited: 5 requests per email per 10-minute window
JWKS endpoint
Public keys for JWT verification are available at:
GET /.well-known/jwks.jsonCache the response with the Cache-Control max-age header (typically 1 hour). Keys are rotated on a schedule; the JWKS endpoint always serves all currently valid keys.
Session security
| Feature | Default | Configuration |
|---|---|---|
| Refresh token rotation | ✓ enabled | REFRESH_TOKEN_ROTATION |
| Token family revocation | ✓ enabled | Always on |
| IP binding | ✗ disabled | SESSION_BIND_IP=true |
| User agent binding | ✗ disabled | SESSION_BIND_UA=true |
| Concurrent session limit | unlimited | SESSION_MAX_CONCURRENT |
IP binding rejects refresh token use from a different IP than the one that obtained it. Useful for high-security environments, but causes issues for mobile users on changing networks.
Email security
- Magic link tokens are single-use and expire in 15 minutes
- Email verification links expire in 24 hours
- Password reset links expire in 1 hour
- All tokens are generated with
crypto/rand(CSPRNG) - Email sending uses SMTP with STARTTLS or TLS
Transport security
- HelloJohn itself only serves HTTP — TLS is terminated at the reverse proxy
- All external integrations (SMTP, OAuth providers, webhooks) use TLS
- Webhook payloads are signed with HMAC-SHA256
Cryptographic randomness
All tokens, secrets, and nonces are generated using crypto/rand — the OS-provided cryptographically secure pseudorandom number generator (CSPRNG). math/rand is never used for security-sensitive values.
Dependencies
HelloJohn minimizes its dependency tree to reduce supply chain risk. Key dependencies:
| Package | Purpose |
|---|---|
golang.org/x/crypto | Argon2id, Ed25519, bcrypt |
github.com/lestrrat-go/jwx/v2 | JWT creation and verification |
github.com/jackc/pgx/v5 | PostgreSQL driver |
github.com/go-redis/redis/v9 | Redis client |
All dependencies are pinned with go.sum checksums. Release artifacts are signed with Cosign.
Compliance
HelloJohn is designed to help you achieve compliance with:
- SOC 2 Type II — Audit logs, MFA, access controls, encryption at rest (your DB)
- GDPR — User deletion, data export, consent management
- HIPAA — Audit logs, MFA enforcement, session timeout, encryption
- ISO 27001 — Access control policies, audit trails, incident response
HelloJohn Cloud holds a SOC 2 Type II report. Contact security@hellojohn.dev for a copy under NDA.