Security & Deployment

This guide covers the IDToken Auth Server’s security model and production deployment configuration.

Security Model

Authentication Layers

Layer	Mechanism	Details
Transport	TLS 1.3	Via Cloudflare reverse proxy (HTTPS + WSS)
User auth	ECDSA P-256	Mobile app signs sessions with enrolled key pair
OTP	HMAC-SHA256	Server-generated, derived from master secret + session context
JWT	ES256	Signed with server’s ECDSA P-256 key
WebSocket	HMAC token	Constant-time verification prevents timing attacks
Admin	JWT + scopes	Role-based access control for admin endpoints

Attack Mitigations

Attack	Mitigation
Brute-force OTP	Max 3 attempts per session, then HTTP 429
Replay	Sessions are single-use, deleted after verification
MitM	Out-of-band OTP delivery via FCM; response hash for anti-forgery
Phishing	Mutual authentication — user verifies service via OTP match
Timing	Constant-time HMAC comparison for wsToken and OTP
Rate abuse	Per-route rate limiting (10/min auth, 5/hr enroll)
XSS / injection	@fastify/helmet CSP headers, Zod input validation
DDoS	Cloudflare edge protection

Cryptographic Algorithms

Purpose	Algorithm	Key Size
VDS signatures	ECDSA P-256	256-bit
JWT signing	ES256 (ECDSA P-256)	256-bit
OTP derivation	HKDF + HMAC-SHA256	256-bit
Response hash	HMAC-SHA256	256-bit
SAML signing	ECDSA or RSA	256-bit / 2048-bit
SAML encryption	AES-128 + RSA-OAEP	128-bit / 2048-bit

Audit Trail

All security-relevant events are logged to an immutable audit table in PostgreSQL:

• INSERT-only (UPDATE/DELETE blocked by PostgreSQL rules)
• Indexed on token_id, event_type, occurred_at
• OTP values are never stored in plaintext (only SHA-256 hash)
• Client IP and user agent captured per event

See Admin API for querying the audit log.

Multi-Instance Deployment

The server supports horizontal scaling with multiple instances:

• Stateless sessions — No sticky sessions required; any instance can handle any request
• Real-time event delivery — WebSocket events are delivered correctly regardless of which instance the browser is connected to

Health Monitoring

The GET /health endpoint returns dependency status:

{
  "status": "ok",
  "version": "1.0.0",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "vdsTrust": "ok"
  }
}

• status: "ok" — all dependencies healthy
• status: "degraded" — one or more dependencies unhealthy

Use this endpoint for container health checks and load balancer probes.

Deployment Configuration

Infrastructure Requirements

Component	Specification
Runtime	Node.js 22 LTS
Database	PostgreSQL 17+
Cache	Redis 8+
Edge proxy	TLS termination, DDoS protection, WebSocket support
Push service	Firebase Cloud Messaging

Key Management

Key	Format	Purpose
Server signing key	ECDSA P-256 PEM	JWT and Service VDS signing
SAML signing key	ECDSA or RSA PEM	SAML assertion signing
SAML encryption key	ECDSA or RSA PEM	SAML assertion encryption (optional)
OTP master secret	32+ byte hex	OTP derivation and HMAC computations

All private keys should be generated with strong randomness, stored with restricted file permissions, rotated periodically, and never committed to version control.

Database Migrations

Migrations run automatically on server startup and are idempotent:

Migration	Purpose
001_init	Enable cryptographic extensions
002_enrollments	Enrollment and session tables
003_audit_log	Immutable audit log
004_admin_operators	Console operator management
005_saml_service_providers	SAML SP registration
006_service_scopes	Service registration and consent tracking