Architecture Log: Ecosystem-Wide Passwordless Authentication

Context

The ecosystem spans a desktop game launcher, a web portal, and a standalone VR client. Typing passwords via VR controllers or console interfaces presents a UX bottleneck that hinders user conversion and onboarding.

Decision

Eliminated passwords in favor of FIDO2/WebAuthn. Implemented cross-device bridging and UX-driven device fingerprinting to label credentials.

Rationale

• Frictionless Flow: Users register hardware once. Subsequent logins on constrained interfaces are handled via biometric prompts or cross-device QR handoffs.
• Reduced Liability: The database only stores public keys, making it unusable by attackers and eliminating the compute cost of password hashing.
• Device Fingerprinting: The registration flow parses the User-Agent to generate readable labels (e.g., 'Chrome on Windows') for credential managers.

Context

The stateless API layer requires a secure session token mechanism. While JSON Web Tokens (JWTs) are standard, they introduce cryptographic liability (e.g., algorithm confusion attacks).

Decision

Implemented PASETO v4 Local (Symmetric) for all session tokens.

Rationale

• Secure Defaults: PASETO removes cryptographic agility from the header. The verification algorithm is hardcoded on the server, preventing downgrade attacks.
• Developer Experience: Eliminates the need to validate token headers manually or configure complex JWT libraries.
• Standardization: Ensures all backend microservices share a single cryptographic standard for session management.

Context

Passwordless onboarding relies on email OTPs. Exposing an unauthenticated endpoint invites automated abuse, email bombing, and OTP brute-forcing.

Decision

Adopted Zoho's ZeptoMail for transactional delivery, secured by a Valkey-backed rate limiting and lockout mechanism.

Rationale

• Provider Selection: ZeptoMail integrated frictionlessly with existing infrastructure and proved cost-effective while prohibiting marketing bulk to protect sender reputation.
• OOM Protection: A strict 1MB request body limit applied at the middleware layer mitigates memory exhaustion attacks.
• Dual-Vector Rate Limiting: Valkey middleware independently tracks raw client IPs and requested email addresses. The `/register-init` endpoint is strictly limited, making email-bombing cost-prohibitive.
• Brute-Force Lockout: Valkey tracks failed OTP attempts. Upon reaching 5 failures, the OTP and counter are purged, locking the user out.

Context

OTP and WebAuthn flows generate ephemeral data. Storing this in a relational database triggers vacuum cycles and increases storage costs.

Decision

Route ephemeral state to Valkey (with native TTLs) and reserve AWS Aurora PostgreSQL for permanent data.

Rationale

• Database Health: Prevents Postgres from accumulating dead tuples from expired sessions.
• Infrastructure Efficiency: Leverages Valkey's native TTLs to garbage-collect expired sessions without background cron jobs.

Context

If a database is compromised, plain-text refresh tokens grant attackers persistent access to user accounts.

Decision

Enforce SHA-256 hashing on all refresh tokens before database insertion and implement a cascading revocation mechanism.

Rationale

• Data Protection: Storing only the SHA-256 hash renders compromised databases unusable for generating tokens.
• Reuse Detection: Standard Refresh Token Rotation (RTR) is enforced. Presenting a previously used token indicates a compromised client or replay attack.
• Cascading Revocation: Detecting reuse triggers immediate invalidation of the token family, terminating all sessions and requiring re-authentication.

Context

A distributed system requires unified tracing and logging to diagnose bottlenecks. Basic `stdout` statements are inadequate for production debugging.

Decision

Standardized on OpenTelemetry (OTel) across the stack, utilizing a custom multi-handler logger and injecting OTel directly into the database connection pool.

Rationale

• Deep Database Tracing: OpenTelemetry is wired into the Postgres connection pool via `otelpgx`, providing span-level visibility into query execution times.
• Unified Logging: A custom `multiHandler` logger mirrors structured logs to `stdout` for local development and the OTel log exporter for production aggregation.
• Vendor Agnosticism: The OTel standard prevents vendor lock-in, routing telemetry seamlessly to any backend via the OTel Collector.