Security Model

AuthNexus follows a defense-in-depth security philosophy with fail-closed semantics at every layer. This document covers the key security mechanisms from network edge to application logic.

Fail-Closed Design

AuthNexus defaults to denying access when any security subsystem is unavailable:

Subsystem	Fail-Closed Behavior
PKI not initialized	CP serves only setup endpoints; /cp/* is disabled
CP Agent not connected	Server does not open business TLS port
OCSP revocation	Node staples revoked response; SDK rejects handshake
Blacklist cache unavailable	Optionally reject all requests (--blacklist-fail-closed)
Auth epoch unavailable	Token validation falls back to strict (shorter) expiry

Staged Startup Enforcement

The server's StageRunner enforces that critical configurations are applied before the business port opens. If the CP Agent fails to connect and deliver initial configs, the TCP listener never binds -- clients cannot connect to an unconfigured node.

Password Hashing

Algorithm: HMAC-SHA256 (Versioned)

AuthNexus uses a high-speed HMAC-SHA256 password hash, optimized for online authentication throughput rather than offline brute-force resistance.

Format:

$authnexus-fast-hmac-sha256$v=1$<salt_hex>$<hash_hex>

Component	Detail
Algorithm	HMAC-SHA256
Version	v=1
Salt	16 bytes, cryptographically random
Hash	32 bytes
Domain separation	AuthNexusPasswordFastHashV1

Design Rationale

Traditional slow hashes (Argon2, bcrypt, scrypt) are designed to resist offline dictionary attacks. AuthNexus prioritizes:

• Online throughput -- thousands of concurrent logins per second.
• Low latency -- sub-millisecond hash computation.
• Server-side secret -- the HMAC key is a server-held secret, meaning offline attacks require both the database and the key.

Legacy hash formats (plain SHA256, Argon2id) are rejected at login time. There is no automatic migration -- passwords must be explicitly reset.

Auth Epoch

The auth epoch is a per-user monotonic counter that serves as the foundation for session invalidation.

How It Works

1. Each user has an auth_epoch value stored in the Control DB.
2. When an admin bumps a user's epoch (e.g., via forced logout, password reset, or security action), the new value propagates to server nodes via Channel 3 (DB delta).
3. Server nodes compare the epoch in the user's token against the current epoch. Tokens with a stale epoch are rejected.

Propagation Path

Admin action (CP)
    → auth_epoch_changes table (Control DB)
    → Channel 2 SSE hint: epoch.bumped
    → Channel 3 delta pull (RuntimeSecurityDeltaPuller)
    → Server Runtime DB + in-memory cache
    → Token validation rejects stale epoch

Timing

Under normal SSE conditions, epoch changes propagate to server nodes within seconds. If SSE degrades, the delta puller tightens its interval to 800ms to minimize the invalidation window.

Blacklist System

AuthNexus maintains two separate blacklist systems:

Server Blacklist (Runtime)

Enforced by server_app on the business data path. Entries can match:

• IP addresses
• Device IDs
• User IDs

Changes propagate from the Control DB to server nodes via Channel 3 delta sync. The server's local Runtime DB is the single source of truth for enforcement -- there is no full-snapshot push.

Control Blacklist (Admin)

Enforced by control_plane_app on the admin API. Protects the management interface from unauthorized access.

Admin API Endpoints

GET    /admin/v1/blacklist              # List server blacklist entries
POST   /admin/v1/blacklist              # Add entry
PATCH  /admin/v1/blacklist/:id          # Update entry
DELETE /admin/v1/blacklist/:id          # Remove entry
POST   /admin/v1/blacklist/batch/remove # Batch remove

GET    /admin/v1/control-blacklist      # List control blacklist entries
POST   /admin/v1/control-blacklist      # Add entry
PATCH  /admin/v1/control-blacklist/:id  # Update entry
DELETE /admin/v1/control-blacklist/:id  # Remove entry

Token Management

Admin Tokens

Admin (agent) tokens are managed in-memory by the Control Plane. They support:

• JWT-based authentication with refresh token rotation.
• Per-agent revocation via epoch bump.
• Token listing and forced revocation through the admin API.

User Session Tokens

User session tokens are 32-byte opaque values issued during login. They are:

• Validated on every request against the auth epoch.
• Bound to a specific device ID.
• Subject to session expiry and service expiry (two independent clocks).

Rate Limiting and Security Scheduling

The server includes a unified scheduler (TaskScheduler) that manages periodic security tasks:

• Login rate limiting -- per-IP and per-username throttling.
• Blacklist cache refresh -- periodic sync from Runtime DB to in-memory.
• Session cleanup -- eviction of expired sessions.
• Metrics collection -- security event counters for CP checkin.

The scheduler tick interval defaults to 500ms and can be tuned via --scheduler-tick. It can be disabled entirely with --no-scheduler for testing.

Audit Logging

All security-sensitive operations are logged to the Control DB:

Log Type	Source	Content
User login logs	Server -> CP	Login attempts, success/failure, IP, device
User audit logs	CP	Account changes, card key operations
Agent login logs	CP	Admin login attempts
Agent audit logs	CP	Admin operations on resources
PKI audit logs	CP	Certificate operations, revocations
Node audit logs	CP	Node enrollment, config changes

Logs are queryable through the admin API:

GET /admin/v1/login-logs
GET /admin/v1/audit-logs
GET /admin/v1/agent-login-logs
GET /admin/v1/agent-audit-logs
GET /admin/v1/pki/audit-logs
GET /admin/v1/nodes/audit-logs

Network Security Defaults

Setting	Default	Rationale
Admin API bind	127.0.0.1 (loopback)	Requires reverse proxy for external access
CP southbound bind	0.0.0.0:9091	Nodes may connect remotely
Business TCP	0.0.0.0:8080	SDK clients connect from anywhere
TLS version	1.3 only	No downgrade to TLS 1.2
OCSP	Plain HTTP :9092	Self-signed responses; TLS unnecessary

Next Steps

• TLS & PKI -- certificate infrastructure details
• Auth & Sessions -- session lifecycle and token management
• Deployment Guide -- production hardening checklist