# HyperFlow security model This document lists what HyperFlow defends against, how, and the test that proves each control. A control without a test is not claimed here. Test paths are relative to `tests/flagship/`. ## Assets and trust boundaries | Asset | Where it lives | Boundary | | --- | --- | --- | | Account passwords | `hf_accounts.password` as salted scrypt (`n=16384, r=8, p=1`) | Never stored or logged in plaintext | | HyperFlow sessions | `hf_sessions.token_hash` as SHA-256 of a 48-byte random token, 8-hour expiry | The bearer token exists only in the client | | Swiggy provider credentials | AES-GCM ciphertext bound to the owning account, key from `VAULT_SECRET_KEY` | Decryptable only with the operator key and the owning account ID | | OAuth PKCE verifier | AES-GCM-encrypted in the pending state record, 10-minute expiry | Bound to account, state and exact redirect URI | | Model artifacts | Local registry written by the training job, SHA-256 recorded in the manifest | Files the service wrote; the registry directory is trusted | ## Threats and controls | Threat | Control | Test | | --- | --- | --- | | New endpoint shipped without authentication | Every mounted `/api/v1` and `/api/v2` route is enumerated and must return 401/410 to an anonymous caller, except an explicit public allowlist | `test_phase1_boundary.py::test_every_api_route_rejects_anonymous_callers` | | Anonymous model replacement (found and fixed: unauthenticated `/api/v{1,2}/ml/retrain` promoted a model) | Routes removed; training runs only through authenticated, admin-gated jobs | same test | | Password database leak | scrypt with per-password salt; sessions stored only as hashes | `test_security_hardening.py::test_secrets_are_not_stored_in_plaintext` | | Guessable passwords | 12 to 1024 characters, common long passwords and passwords containing the username rejected | `test_security_hardening.py::test_guessable_passwords_are_rejected` | | Username enumeration through login | Missing users still run a full scrypt; identical status and body for unknown user and wrong password | `test_security_hardening.py::test_unknown_user_and_wrong_password_are_indistinguishable` | | Online guessing against one account from many addresses | At most 5 failures per username per 15 minutes, counted across all addresses | `test_security_hardening.py::test_failed_logins_lock_only_the_targeted_username` | | Rate-limit bypass by forging `X-Forwarded-For` | Forwarded headers are ignored unless `HYPERFLOW_TRUSTED_PROXY_HOPS` is set; then only the proxy-appended right-most hop is used | `test_forwarded_for_is_ignored_without_a_trusted_proxy`, `test_trusted_proxy_hop_is_read_from_the_right` | | One attacker behind a shared proxy locking out every user | Per-client limits use the proxy-observed client address, not the proxy's own address | `test_trusted_proxy_hop_is_read_from_the_right` | | Memory exhaustion through one huge request body (any endpoint, including anonymous login) | ASGI middleware rejects bodies over 1 MiB with 413, counting streamed bytes so a body without `Content-Length` cannot bypass it | `test_security_hardening.py::test_oversized_request_bodies_are_rejected_before_parsing` | | Connection-pool exhaustion through many open event streams (each polls the database every second) | At most 3 streams per account and 50 in total, released on disconnect; sessions re-checked every 15 s | `test_security_hardening.py::test_event_streams_are_capped_per_account` | | Memory exhaustion through address churn | Limiter state is pruned once it exceeds 10,000 keys | covered by code review; not load-tested | | Session reuse after logout | Logout deletes the session row | `test_security_hardening.py::test_logout_revokes_the_session` | | Unbounded anonymous reviewer workspaces | Reviewer creation limited per client; the worker deletes expired sessions and reviewer accounts older than 24 hours with their records and events | `test_prune_removes_expired_sessions_and_stale_reviewer_workspaces`, `test_worker_runs_the_prune` | | Clickjacking, injected scripts, referrer leaks | `Content-Security-Policy` (`default-src 'self'`, `frame-ancestors 'none'`, `object-src 'none'`, `base-uri 'none'`), `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, `Permissions-Policy`, HSTS on HTTPS | `test_security_headers_on_api_and_spa`, `test_hsts_only_over_https`; browser verification records zero CSP console errors | | Cross-origin reads of authenticated data | CORS allows only origins listed in `HYPERFLOW_ORIGINS` | `test_security_hardening.py::test_cors_allows_only_configured_origins` | | OAuth state forgery, cross-account callback, redirect swap, expired state | Encrypted, account-bound PKCE state with exact redirect match and expiry | `test_phase1_boundary.py::test_oauth_state_cross_account_redirect_expiry_and_secret_redaction` | | Provider credentials echoed in errors or responses | Redaction before responses and logs | `test_oauth_provider_error_does_not_echo_credentials`, `test_verify_is_read_only_redacted_and_scoped_to_current_generation` | | One account decrypting another's provider credential | Ciphertext authenticated with the owner's account ID | `test_phase1_identity.py::test_account_ciphertext_cannot_be_used_by_another_account` | | Model or provider text authorizing an order | Mutations require a backend proposal, exact-version approval and a matching receipt; live placements disabled | `test_zero_spend_release_blocks_new_live_placements`, `test_final_boundary.py::test_cart_receipt_must_match_approved_address_and_price` | | Symlink attack on lock files in shared `/tmp` | SQLite lock files live in a `0700` directory beside the database and are opened with `O_NOFOLLOW` | `test_security_hardening.py::test_sqlite_lock_files_are_private_and_refuse_symlinks` | ## Supply chain and secrets (CI `security` job) - `gitleaks` scans the full git history on every push. - `pip-audit -r requirements.txt` and `npm audit --audit-level=high` fail the build on known vulnerabilities. On 23 October 2026 this removed 37 Python advisories (upgrading FastAPI/Starlette, scikit-learn and python-dotenv, and dropping five unused packages, including PyJWT) and 6 high npm advisories. - `bandit -r backend -ll` fails on medium or higher findings. Accepted exceptions are marked inline with their reason: three `pickle.loads` of hash-verified local registry artifacts, and two `urlopen` calls on constant HTTPS URLs. ## Known limits - The rate limiter is in-process. It is correct for the single-container deployment but does not share state across replicas. - Registry artifacts are trusted because only this service writes them. Anyone with write access to the registry directory can replace both an artifact and its recorded hash; signing artifacts would close this. - Registration returns 409 for a taken username, so usernames can be enumerated at the registration rate limit (5 per minute per client). - There is no multi-factor authentication or account recovery flow.