This document provides a comprehensive, technical overview of the multi-layered security architecture, cryptographic standards, threat mitigations, and engineering rationale implemented across the AuthORS authentication engine.

• Why Implemented: By default, Express leaks headers like X-Powered-By: Express, allowing attackers to fingerprint the server stack and target known version vulnerabilities. Furthermore, web browsers default to permissive behaviors that expose users to Clickjacking and MIME-type sniffing.
• What It Does:
  • X-Frame-Options: DENY: Blocks Clickjacking attacks by forbidding third-party domains from embedding your authentication UI inside invisible <iframe> elements.
  • X-Content-Type-Options: nosniff: Forces browsers to strictly adhere to declared MIME types, preventing executable scripts disguised as images or text from executing.
  • Strict-Transport-Security (HSTS): Instructs browsers to enforce encrypted TLS/HTTPS connections for the next 180 days (max-age=15552000; includeSubDomains).
  • X-XSS-Protection: Enables browser-level Cross-Site Scripting filters.
• Why Better Than Alternatives: Manual header configuration is error-prone and often misses emerging browser standards. Helmet dynamically injects 11+ industry-standard security headers on every response with zero performance overhead.

• Why Implemented: Because authentication relies on httpOnly secure cookies for refresh token transmission, browsers strictly restrict Cross-Origin requests. Using a wildcard (*) alongside cookies is a critical vulnerability.
• What It Does:
  • Validates the incoming Origin header against an explicit whitelist of trusted frontend URLs (FRONTEND_URL, http://localhost:5173, etc.).
  • Enforces credentials: true only for trusted origins, allowing cookies to pass securely while blocking unauthorized cross-domain access.
• Why Better Than Alternatives: Prevents CSRF token interception and cross-site data harvesting from malicious domains attempting to query your API from unauthorized origins.

• Why Implemented: Authentication APIs are the primary target for automated botnets running Credential Stuffing (testing millions of breached email/password pairs) and Dictionary Attacks (guessing 6-digit OTP codes).
• Matrix of Rate Limits:

• Why It Is Better Than Alternatives:
  • Better than Captcha-on-every-request: Avoids degrading the user experience for legitimate users while silently throttling malicious IPs.
  • Better than in-memory manual counters: Provides standardized Retry-After headers and automatic sliding window expirations.

• Why Implemented: Traditional manual validation (if (!req.body.email) ...) suffers from JavaScript type-coercion bugs, NoSQL injection exploits (e.g. passing { "password": { "$gt": "" } }), and uncaught runtime exceptions.
• What It Does:
  • Runtime Type Safety: Validates types, formats, and structural constraints before any controller logic executes.
  • String Sanitization: Trims all whitespace and converts emails to canonical lowercase strings to prevent duplicate user collisions (Aditya@mail.com vs aditya@mail.com).
  • Password Complexity: Enforces a minimum of 8 characters containing at least 1 uppercase letter, 1 lowercase letter, 1 number, and 1 special symbol (@$!%*?&).
• Why Better Than Alternatives (e.g., Joi / Manual Checks): Zod strips unknown keys, integrates seamlessly with modern TypeScript/ESM workflows, and formats human-readable error messages without leaking backend stack traces.

• Why Implemented: When an attacker tests emails against a "Forgot Password" or "Login" route, different error messages (e.g., "User not found" vs "Invalid password") reveal whether high-profile targets (like ceo@company.com) have accounts on the platform.
• What It Does: The /forgot-password endpoint always returns a generic 200 OK response ("If an account with that email exists, a password reset link has been sent."), preventing account harvesting.

• Why Implemented: Traditional hashing algorithms (MD5, SHA-256, SHA-512) are designed to be fast, making them vulnerable to modern graphics cards (GPUs) and specialized ASIC chips that compute billions of guesses per second.
• Technical Specifications:
  • Algorithm: Argon2id (Winner of the Password Hashing Competition & OWASP Top Recommendation).
  • Memory-Hardness: Configured with memoryCost: 19456 KB (~19 MB RAM per hash), timeCost: 2, and parallelism: 1.
  • Hybrid Design: Combines Argon2d (data-dependent memory access for maximum GPU resistance) with Argon2i (data-independent memory access for side-channel cache timing resistance).
• Why Argon2id is Better than Bcrypt & PBKDF2:

• Why Implemented: Upgrading a database from Bcrypt to Argon2id without users' plain-text passwords is traditionally impossible without forcing everyone to reset their credentials.
• How It Works:
  1. On login, the engine checks if the stored hash begins with $argon2.
  2. If it is an older Bcrypt hash ($2b$), it verifies the password using bcrypt.compare().
  3. Upon successful verification, it automatically re-hashes the password using Argon2id and updates MongoDB in the background.
• Why It Is Better: Zero downtime, zero user disruption, and seamless organic database migration over normal traffic cycles.

• Why Implemented: Single long-lived JWTs (e.g. 30-day tokens) stored in browser storage cannot be invalidated if stolen without querying the database on every single API request, destroying the performance benefits of JWTs.
• What It Does:
  • Access Token (Short-Lived: 15m): Stateless VIP pass stored in memory and sent via Authorization: Bearer headers. If intercepted, the attacker's window of opportunity is limited to 15 minutes.
  • Refresh Token (Long-Lived: 7d): Stored as a SHA-256 digest in database sessions, used exclusively to rotate access tokens.

• Why Implemented: Storing tokens in localStorage or sessionStorage exposes them to any malicious third-party npm package, CDN script, or browser extension via Cross-Site Scripting (XSS).
• Security Flags:
  • httpOnly: true: JavaScript running in the browser (document.cookie) cannot read or access the cookie $\rightarrow$ 100% immune to XSS token theft.
  • secure: true: Transmitted exclusively over encrypted HTTPS connections, preventing man-in-the-middle sniffing.
  • sameSite: strict: The cookie is never sent with requests initiated by third-party sites $\rightarrow$ Eliminates Cross-Site Request Forgery (CSRF).

• Why Implemented: Standard token rotation alone is insufficient: if a hacker steals a refresh token and uses it before the legitimate user, both parties would receive separate valid tokens indefinitely.
• How It Works:
  • Every login generates a unique familyId UUID.
  • When rotating tokens, the parent token is marked as isUsed: true and a descendant session is spawned in the same family.
  • If an already-used or revoked token is ever presented again, the server detects a token replay attack, immediately revokes all active sessions across that entire family lineage, clears the client cookie, and returns 403 Forbidden.
• Why It Is Better: Converts token theft from an undetectable vulnerability into an actionable security event that automatically terminates compromised sessions.

• Why Implemented: Storing raw TOTP Base32 secret keys in plaintext in MongoDB creates a massive vulnerability: any database backup leak or read replica compromise would expose all users' 2FA keys.
• What It Does:
  • Every secret is encrypted using AES-256-GCM with a 96-bit random Initialization Vector (IV) and a 128-bit authentication tag before being saved to the database.
  • Format stored: iv:authTag:ciphertext.
  • The secret is decrypted strictly in volatile memory during code validation.

• Why Implemented: A vulnerable 2FA system might return a full access token upon password validation and rely on the client to redirect to a 2FA page. Malicious actors could bypass 2FA by ignoring the UI.
• What It Does:
  • When a 2FA-enabled account enters valid credentials, the server does NOT issue access or refresh tokens.
  • Instead, it issues a short-lived Pre-Auth JWT (5-minute TTL) with { stage: "2FA_PENDING" }.
  • Full access and refresh tokens are issued only after /2fa/verify successfully passes.

• What It Does:
  • ±1 Step Clock Drift (epochTolerance: 30): Accepts codes generated within 30 seconds before or after the current step to account for client-server clock desynchronization and mobile network latency.
  • Strict Replay Prevention: Tracks twoFactorLastUsed timestamp window. If a valid code is submitted a second time within its validity period, it is rejected immediately.

• What It Does:
  • Generates 10 high-entropy 8-character recovery codes (A1B2C3D4).
  • Stored in MongoDB strictly as SHA-256 digests ({ codeHash, used: Boolean }).
  • Plaintext backup codes are displayed to the user only once during initial enrollment or manual regeneration.
  • Consuming a backup code permanently invalidates it (used: true), allowing account recovery if a user loses their phone.

• Why Implemented: Storing temporary OTPs and reset tokens permanently in the database bloats storage and creates a security risk if stale tokens remain valid.
• What It Does:
  • OTPs (otps collection): Configured with a native MongoDB index { createdAt: 1 }, { expireAfterSeconds: 600 } (10 minutes).
  • Password Resets (password_resets collection): Configured with { createdAt: 1 }, { expireAfterSeconds: 900 } (15 minutes).
• Why It Is Better Than Cron Jobs:
  • Runs directly inside MongoDB’s background C++ engine thread with zero application memory overhead.
  • Guaranteed execution even if Node.js server restarts or experiences downtime.

• Why Implemented: Short or predictable reset links (e.g. timestamp hashes or 6-digit PINs) can be guessed via parallel HTTP requests.
• What It Does: Password reset tokens are generated using cryptographically secure pseudorandom numbers (crypto.randomBytes(32) $\rightarrow$ 64 hex characters), providing $2^{256}$ ($1.15 \times 10^{77}$) possible combinations, rendering brute-forcing mathematically impossible.
• Immediate Single-Use Consumption: The moment a token is verified during /verify-email or /reset-password, the document is immediately deleted from the database (deleteMany), guaranteeing zero token reuse.

• Why Implemented: Passwords are the #1 attack vector for user accounts (phishing, weak passwords, credential reuse). OAuth 2.0 delegates authentication to battle-tested identity providers.
• What It Does:
  • Implements the official OAuth 2.0 Authorization Code Flow.
  • Pre-Verified Emails: Social accounts are automatically verified (verified: true) because Google/GitHub have already verified email ownership.
  • Account Linking: If a user previously registered with a local password and later clicks "Sign in with Google", the system links their googleId to the existing account without creating duplicate user records.
  • Username Collision Fallback: Automatically appends random identifiers if a social display name collides with an existing username, preventing MongoDB duplicate key crashes.

• Why Implemented: Users need visibility into which devices are logged into their accounts and the ability to remotely terminate compromised sessions.
• What It Does:
  • Every session records the client's IP address, Device User-Agent, and timestamp.
  • Single-Device Logout (POST /api/auth/logout): Revokes only the active token family and clears the client's cookie.
  • Universal Account Kill-Switch (POST /api/auth/logout-all): Revokes every active session across all devices globally (sessionModel.updateMany({ user: id }, { revoked: true })).
  • Password Reset Revocation: Successfully resetting a password automatically revokes all existing sessions across all phones, tablets, and PCs worldwide.

• Why Implemented: In enterprise environments and compliance audits (SOC 2, HIPAA, ISO 27001), organizations must prove an immutable audit trail of who accessed what, when, and from where.
• What It Does:
  • Records every security-critical lifecycle event in a dedicated audit_logs collection:
    • LOGIN_SUCCESS, LOGIN_FAILED
    • TOKEN_ROTATED, TOKEN_REUSE_ATTACK_DETECTED
    • 2FA_ENROLL_INITIATED, 2FA_ENABLED, 2FA_DISABLED, 2FA_VERIFIED_SUCCESS, 2FA_BACKUP_CODE_USED
    • PASSWORD_RESET_REQUESTED, PASSWORD_RESET_COMPLETED
    • LOGOUT, LOGOUT_ALL
  • Captures actor user ID, email, ip, userAgent, timestamp, and custom event details.
  • Optimized with compound indexes { user: 1, createdAt: -1 } for sub-millisecond forensic lookups.
• Non-Blocking Architecture: Audit writes are fully non-blocking and wrapped in fail-safe try/catch blocks so logging never increases user request latency or crashes an authentication flow.

AuthORS is architected to align with NIST SP 800-63B Authenticator Assurance Level 2 (AAL2) standards:

If you discover a security vulnerability within this repository, please report it responsibly by contacting me directly. Avoid creating public GitHub issues for sensitive security exploits.