Authentication Architecture

Overview

QODY implements multi-role authentication with separate flows for:

Staff — venue-scoped (email + password + venueSlug)
SuperAdmin — cross-venue global admin (email + password)
Guest — anonymous/session-based (no credential auth required)

Security: Rate-Limiting & Brute-Force Protection

Critical Vulnerability Fixed — 2026-07-03 (MC #104585)

Vulnerability

Impact: CRITICAL — Unlimited brute-force / password-spray against owner/admin/SUPERADMIN accounts.

The login rate limiter trusted the client-supplied X-Forwarded-For header (first value) to key rate-limit buckets. An attacker could rotate a forged X-Forwarded-For value on each request to obtain a fresh rate-limit bucket every time, bypassing all protections.

Affected Endpoints:

POST /staff/auth/login
POST /superadmin/auth/login
POST /auth/forgot-password

Live Exploitation Verified: 2026-07-01 (Securion security review)

7 consecutive requests, same email, different spoofed X-Forwarded-For on every request:
All attempts → HTTP 401 (unlimited, rate limiter never triggered)
Evidence: ~/system/evidence/104554/qody-ratelimit-securion-review-20260701.md

Fix (Deployed 2026-07-03)

Strategy: Rate-limit on NON-SPOOFABLE dimensions instead of client IP.

New Design:

Email-only bucket: 5 failures per email per 15 minutes (keyed on email.trim().lowercase() — no IP component)
Scope bucket: 20 failures per scope per 15 minutes
- Staff login: keyed on venueSlug (per-venue spray protection)
- SuperAdmin login: keyed on constant "superadmin-crossvenue" (global spray protection)
Forgot Password: Email-only bucket (3 requests per 15 minutes, privacy-preserving — always returns HTTP 200 even when rate-limited)

ClientIpResolver.kt: A helper for trusted-last-hop IP resolution was added (TRUSTED_PROXY_HOPS=1) but is used ONLY for non-critical post-auth ApiRateLimiter IP dimension + audit logs — NOT the login security key. Login security does NOT depend on IP trust.

Implementation:

LoginRateLimiter.kt — complete rewrite
StaffRoutes.kt, SuperAdminRoutes.kt — scope-based rate-limit keys
PasswordResetService.kt — email-only key for forgot-password
ClientIpResolver.kt — NEW (non-critical uses only)

Deployment

Commit: f176357 (security(api): fix XFF-bypass login rate-limiter — MC #104585)
Image: qodyprodacr.azurecr.io/qody-api:f176357
Revision: qody-api-prod--0000012 @ 100% traffic
Environment: rg-qody-prod (swedencentral), api.qody.ba
Deploy Date: 2026-07-03

Verification (Live Production Replay)

Test: Replayed XFF-rotation exploit on production api.qody.ba with fresh email + rotating forged X-Forwarded-For values (same attack that succeeded unlimited pre-fix).

Attempt	Forged XFF	Result
1	203.0.113.1	HTTP 401
2	203.0.113.2	HTTP 401
3	203.0.113.3	HTTP 401
4	203.0.113.4	HTTP 401
5	203.0.113.5	HTTP 401
6	203.0.113.6	HTTP 429 — Rate limited ✅

Outcome: Email-based limiter triggered at threshold despite XFF rotation. Fix confirmed live.

Unit Tests: 261 total, 0 failures, including a regression test replaying the exact exploit.

Evidence: ~/system/evidence/104585/qody-xff-fix-deploy-verify-20260703.md

Follow-Up (Non-Blocking, L-Priority)

Empirically verify ACA Envoy XFF hop-count to validate/tune the ClientIpResolver TRUSTED_PROXY_HOPS default (does not affect login security, which is now email+scope keyed).

JWT & Refresh Tokens

(Planned section — JWT structure, rotation policy, HttpOnly cookies, etc.)

Password Hashing

(Planned section — Argon2id parameters, rotation, etc.)

Session Management

(Planned section — Staff/SuperAdmin session lifecycle, logout, etc.)