This document describes the security architecture of the AI3L Community Platform. Each section covers a threat domain, the specific risks it addresses, and the controls that mitigate them.

1. Authentication & Session Management
2. Authorization & Role Enforcement
3. CSRF Protection
4. File Upload Security
5. Input Sanitization & Injection Prevention
6. Rate Limiting & Abuse Prevention
7. Real-Time Connection Security
8. Network & Infrastructure Security
9. GDPR & Privacy Compliance
10. Audit Trail
11. Threat Model Summary

Every authenticated request is validated against two independent conditions:

1. JWT cryptographic signature — the token must be signed with the server's JWT_SECRET_KEY and must not be expired.
2. Redis session record — the token's jti (JWT ID) must exist in the active session store in Redis.

A valid signature alone is not sufficient. This means:

• Logout is immediate. On POST /auth/logout, the jti is removed from Redis and added to a blacklist. Any subsequent request using that token — even with a valid signature — is rejected.
• Forced revocation works. When an admin bans a user, all of that user's jti values are deleted from Redis, terminating every active session instantly.
• Token theft is bounded. A stolen token cannot be used indefinitely; it is invalidated the moment the legitimate user logs out or an admin acts.

Passwords are hashed with Argon2id via passlib. Argon2id is the winner of the Password Hashing Competition (PHC) and is resistant to GPU cracking and side-channel attacks. Plain-text passwords are never stored, logged, or transmitted after the initial request.

The session JWT is delivered as an HttpOnly, SameSite cookie:

In production (COOKIE_SECURE=true), both cookies are set with the Secure flag and are only transmitted over HTTPS.

Sessions are short-lived and differentiated by privilege level:

Higher-privilege sessions expire sooner to limit the damage window of a compromised token. The client calls POST /auth/heartbeat to extend the TTL while actively using the platform.

POST /auth/login and POST /auth/register require a valid CAPTCHA answer alongside credentials. The server generates an image challenge (GET /auth/captcha), stores the answer server-side with a short TTL, and rejects any login attempt that does not include the correct solution. This prevents automated credential stuffing and bulk registration abuse.

Non-existent or deleted user lookups run the same Argon2id password verification as valid ones. A module-level _DUMMY_HASH is computed at import time and used whenever the user is not found in the database. Without this, an attacker could enumerate valid usernames by timing the difference between "user not found" (fast) and "wrong password" (slow, due to hashing). With it, both code paths take the same time.

Passwords are validated on registration and change against five independent requirements:

1. Minimum 8 characters
2. At least one uppercase letter (A–Z)
3. At least one lowercase letter (a–z)
4. At least one digit (0–9)
5. At least one special character: !@#$%^&*()_+-=[]{}|;:,.<>?/~

Validation is enforced in app/core/security.py (validate_password_policy()). The function returns the first failing rule as a user-facing message. Plain-text passwords are never stored, logged, or transmitted after the initial request.

Guest accounts created via invite codes are bounded by two independent caps:

• Global concurrent cap: 30 simultaneous guest sessions platform-wide.
• Per-IP cap: 3 simultaneous guest sessions per IP address per hour.

Both limits are enforced via Redis atomic counters. Exceeding either returns a 429 error before a session is created.

SUPER_ADMIN
    └── ADMIN
         └── MEMBER
              └── GUEST

The require_role(roles) FastAPI dependency enforces role checks at the endpoint level before any service logic executes. Roles are stored in the JWT payload and re-validated on every request.

Role enforcement alone is not sufficient for resources with per-object ownership. The service layer performs explicit ownership checks before allowing mutations:

• A user can only edit or delete their own posts and comments.
• A SIG admin can only manage forms and members within their own SIG.
• Admin bulk operations are separated into dedicated endpoints (/bulk, /bulk-role) that require elevated roles and are placed before parameter routes in the router to prevent route collision.

Guest sessions are blocked from:

• Creating posts or comments
• Accessing member-only pages (e.g. the About/Contributors page)
• Generating invite codes

The frontend enforces this via route guards (meta.requiresMember). The backend enforces it independently via require_role — frontend enforcement is defense-in-depth, not the primary control.

The platform uses the double-submit cookie pattern with a cryptographically bound token:

1. On authentication, the server derives the CSRF token by computing HMAC-SHA256(SECRET_KEY, jti), where jti is the unique JWT session identifier. The token is deterministic for a given session but unpredictable to any third party that does not know both the jti and the secret key.
2. The derived token is set as a readable (HttpOnly=False) cookie named csrf_token.
3. The frontend reads this cookie and includes its value in the X-CSRF-Token request header on every state-mutating request.
4. The CSRF middleware reads both values and rejects the request if they do not match. On session rotation the token automatically changes because the jti changes.

An attacker on a different origin cannot read the csrf_token cookie value (enforced by the browser's Same-Origin Policy), so they cannot forge the X-CSRF-Token header. A forged request without the correct header value is rejected by the middleware before reaching any endpoint handler.

Safe HTTP methods (GET, HEAD, OPTIONS) bypass CSRF checks. All mutating methods (POST, PUT, PATCH, DELETE) are always checked.

The declared Content-Type header of an upload is never trusted. Before any file is written to object storage, app/core/file_validation.py reads the file's first bytes and compares them against a whitelist of known magic number signatures:

A mismatch raises AppError with code FILE_001 and the upload is rejected. A renamed executable cannot pass this check. The ZIP structure validation for DOCX prevents JAR, APK, and other ZIP-based file formats from masquerading as Word documents.

PDF files pass through an additional sanitization step using pikepdf, backed by the C++ qpdf engine. The sanitizer strips:

• /JS and /JavaScript — embedded JavaScript
• /AA and /OpenAction — auto-actions triggered on open
• /Launch, /SubmitForm, /ImportData — dangerous action types
• Macros and encrypted objects that cannot be inspected

A corrupted or invalid PDF that cannot be parsed is rejected before reaching storage. Sanitized PDFs are stored without executable content.

After a file is stored in MinIO, it is queued for asynchronous scanning via the VirusTotal API. The scan result is stored in the file_scans table. Clients can poll GET /files/scan-status/{key} to retrieve the scan status and verdict (pending / clean / malicious). Files flagged as malicious return HTTP 451 from the content proxy.

This provides a second line of defense against malware that passes magic byte checks (e.g. a valid PDF with malicious content). The UI surfaces the scan status to the user (pending / clean / flagged).

Files in MinIO are never publicly accessible. Read access is served in two ways:

• Editor-embedded images: accessed via the stable backend proxy GET /files/content/{key}. The proxy streams the file from MinIO and requires authentication. This avoids the expiry problem of embedded presigned URLs.
• Attachments / on-demand downloads: the backend generates short-lived presigned URLs scoped to a single object. TTLs vary by context:
  • GET /files/presigned/{key} — 1-hour TTL (general file downloads)
  • Album photos and thumbnails — 15-minute TTL (generated inline when serving album data)
  • Site export archives — 15-minute TTL (regenerated on each progress poll)

When MinIO is accessed through a different hostname from the browser (e.g. behind Nginx or in Docker development), MINIO_PUBLIC_URL rewrites the internal hostname in generated presigned URLs so the browser can reach the file without the internal service name being exposed.

Per-user upload rate is limited to 10 uploads / minute for editor attachments (separate limits apply to album and DM uploads). Upload size limits are enforced both at the Nginx layer and in application middleware before file content is read.

All database interactions use asyncpg parameterized queries. No raw string interpolation is used anywhere in the repository layer. The query and its parameters are always passed separately to the database driver.

Full-text search uses PostgreSQL's websearch_to_tsquery('english', $1) function, which safely handles special characters (&, |, !, quotes) without risk of query injection. The previously used to_tsquery was replaced specifically because it crashes on unescaped special input.

User-generated HTML is sanitized at two independent layers:

Both sanitizers strip all script tags, event handlers, and dangerous attributes. The backend sanitization ensures content is safe even if retrieved by a non-browser client or a future client that omits frontend sanitization.

Configuration note: rel is excluded from the allowed attributes for <a> tags in nh3 — including it causes a panic in the underlying Rust library.

In production, Starlette's TrustedHostMiddleware validates the Host header against the configured domain. Requests with an unrecognized Host value are rejected with a 400 response before reaching any endpoint logic.

Rate limiting is enforced at two independent layers, so that bypassing one does not eliminate protection.

All zones use nodelay burst handling. Clients that exceed the limit receive 429 Too Many Requests. GET and HEAD requests bypass the write zone. The dm_write zone is more permissive than write because real-time messaging generates higher legitimate write frequency.

Redis atomic counters with fixed TTL windows enforce granular limits per endpoint and per identity (IP or user):

Post creation is additionally limited to 50 posts per user per day (Redis counter, resets at midnight UTC). Error code SYS_429 is returned when this limit is reached.

WebSocket connections do not use cookie-based authentication because browsers send cookies on the WebSocket upgrade request via Cookie headers, which are not CSRF-protected and can be triggered cross-origin.

Instead, the platform uses one-time tickets:

1. The authenticated client calls POST /auth/ws-ticket (cookie is sent automatically on this standard HTTP request).
2. The server generates a cryptographically random ticket, stores it in Redis with a 30-second TTL, and returns it.
3. The client connects: ws://host/api/v1/ws?ticket=<ticket>
4. The server validates the ticket on connect and immediately deletes it from Redis (single-use).

An expired ticket, an already-used ticket, or a missing ticket all result in immediate connection rejection. The 30-second window is narrow enough to prevent replay attacks.

Two independent limits protect the WebSocket layer:

Additionally, the server re-validates each connection's session JTI against Redis every 60 seconds during the connection lifetime. If the JTI has been revoked (e.g., the user changed their password or an admin force-logged-out the user on a different device), the connection is immediately closed.

When a user is banned, the server publishes a FORCE_LOGOUT message to the user's Redis Pub/Sub channel. All Uvicorn workers receive the message and push it to any connected WebSocket belonging to that user, regardless of which worker holds the connection. This ensures bans take effect in real time across all active sessions and all workers.

Services are isolated across two Docker bridge networks (frontend-net and backend-net). Only Nginx is exposed to the host. The database, cache, and object storage are unreachable from the frontend tier.

Internet --> Nginx (:3000 / :3443)
                |
         [frontend-net]
                |-- FastAPI     :8000  (bridges both networks)
                |
         [backend-net]
                |-- FastAPI     :8000  (bridges both networks)
                |-- PostgreSQL  :5432  (internal only)
                |-- Redis       :6379  (internal only)
                `-- MinIO       :9000  (internal only)

TLS is terminated at Nginx. The Let's Encrypt certificate workflow (scripts/init-letsencrypt.sh) and automated renewal (scripts/renew-certs.sh) are included in the repository. In production, HTTP is redirected to HTTPS at the Nginx level.

All responses include X-Robots-Tag: noindex, nofollow. A robots.txt with Disallow: / is served. This prevents academic content (which may include unpublished research or restricted discussions) from being indexed by search engines.

Redis is configured with:

Development:

• maxmemory 256mb — hard cap to prevent unbounded memory growth
• maxmemory-policy allkeys-lru — evicts least-recently-used keys when the cap is reached
• AOF disabled — Redis is used for ephemeral state in development

Production:

• maxmemory 512mb — larger cap for production workload
• maxmemory-policy volatile-lru — only evicts keys that have a TTL set; keys without TTL (e.g., permanent ban entries) are never evicted
• AOF enabled (appendfsync everysec) — provides crash recovery; at most one second of data loss
• Dangerous commands disabled: FLUSHALL, FLUSHDB, KEYS, DEBUG are removed at startup. CONFIG is renamed to an unpublished token to prevent live reconfiguration.

All application containers run with the principle of least privilege:

Celery workers are started with --max-memory-per-child=256000 (KB). A worker that exceeds 256 MB is automatically recycled by Celery, preventing slow memory leaks in long-running task handlers from accumulating indefinitely.

Account deletion does not hard-delete rows. Instead, all personally identifiable information is overwritten:

Foreign keys (post author references, comment author references) are preserved, so the database remains consistent. The content itself may be separately moderated or removed, but the user's PII is gone.

A privacy consent modal is shown at:

• Registration
• First login
• Every new guest session

Consent is recorded in the privacy_consents table (for members) or a Redis key (for guests). The timestamp and IP address are stored with each consent record.

The platform discloses its data residency location (single-server, Hong Kong) in the privacy consent modal. Users must acknowledge this before proceeding.

Every sensitive action is written to the audit_logs table with:

The audit log is paginated and accessible only to Super Admins at GET /admin/audit-logs. It is append-only — no update or delete endpoint exists for audit records.

All POST and PUT requests support the Idempotency-Key header. When a client includes this header, the server caches the response in Redis and replays it for any identical re-submission, preventing duplicate side-effects from network retries.

The user ID is extracted from the JWT sub claim and prepended to the Redis key, ensuring that two users who accidentally submit the same key string never receive each other's responses.