Security Model¶
Numi Chat enforces authentication and resource ownership at the HTTP/WebSocket boundary, scopes tools per instance, tier, and chat, and runs model-generated Python inside a sandbox by default.
For reverse-proxy and TLS setup, see Run with Docker. For data storage and external network flows, see Privacy and Self-Hosting.
Trust Boundaries¶
| Boundary | Enforcement Mechanism |
|---|---|
| Anonymous -> Authenticated | Short-lived JWT access cookies backed by active refreshtoken session rows in SQLite |
| User -> User | Every chat, upload, generated file, share management route, and memory query filters by current_user.id (returning 404 on mismatches) |
| User -> Administrator | /api/v1/admin/* routes require current_user.is_admin == True; admin status does not grant access to other users' private chats through chat routes |
| Model -> Tools | Startup TOOLS_ALLOWLIST / TOOLS_DENYLIST, user tier policy, per-chat optional group activation, and server-injected user_id / chat_id / chat_uuid |
| Generated Python -> Host | Monty / Deno + Pyodide WebAssembly sandbox with allowlisted imports and networking disabled by default |
Authentication and Session Lifecycle¶
Authentication is implemented in src/numi_chat/services/auth/
(credentials.py, flow.py, access.py):
- Session-backed JWTs: Access tokens carry the user's stable subject ID and
a session ID, and expire after
AUTH_ACCESS_TOKEN_EXPIRE_MINUTES(default30minutes). Every authenticated check verifies both the JWT signature (AUTH_SECRET_KEY) and that the session'srefreshtokenrow in SQLite is unexpired and unrevoked. - Single-use refresh token rotation: Refresh tokens expire after
AUTH_REFRESH_TOKEN_EXPIRE_DAYS(default7days) and are stored as SHA-256 hashes. Refreshing claims the token handle atomically (so each token can rotate at most once) and issues a new pair for the same session. - Immediate revocation: Signing out revokes all token rows belonging to that
session and clears the
HttpOnly,SameSite=Laxcookies (SecurewhenENVIRONMENT!=development). Changing a password or resetting a user as an admin revokes all of that user's sessions immediately. Active WebSocket connections periodically re-verify their session (WEBSOCKET_AUTH_CHECK_SECONDS=30). - Password hashing: Passwords are pre-hashed with SHA-256 (base64-encoded)
and hashed with bcrypt (
AUTH_BCRYPT_ROUNDS=13by default). By default, passwords must be at least 12 characters (AUTH_PASSWORD_MIN_LENGTH=12) and include uppercase, lowercase, a digit, and a symbol (AUTH_PASSWORD_REQUIRE_COMPLEXITY=true). - Login throttling: Failed login attempts are tracked in the database
(
auththrottlebucket) using keyed HMAC-SHA256 hashes of the username and client IP, applying progressive delays and temporary lockouts (AUTH_MAX_FAILED_LOGIN_ATTEMPTS=5,AUTH_ACCOUNT_LOCKOUT_MINUTES=15,AUTH_IP_LOGIN_ATTEMPTS_PER_MINUTE=20,AUTH_MAX_LOGIN_DELAY_SECONDS=60). - First-admin bootstrap: On an empty database with zero users, the first
registered account becomes an administrator (
is_admin=True), and open registration closes automatically afterward unless an administrator enables it in Admin settings (appsetting).
Tool and Code Execution Boundaries¶
Allowlist, Denylist, and Per-Chat Activation¶
- At startup,
ToolRegistryloads a tool only if it is inTOOLS_ALLOWLISTand not inTOOLS_DENYLIST(TOOLS_DENYLISTalways wins).request_tool_activationis exempt from the allowlist so the model can ask to enable optional groups, unless explicitly listed inTOOLS_DENYLIST. - Optional tool groups stay out of a chat's active tool schemas until the user enables them for that chat.
- At execution time,
ToolExecutorServicerejects any tool call not in the chat's active set and overwriteschat_id,chat_uuid, anduser_idwith server-verified values so a model cannot spoof another user's or chat's context.
Code Interpreter Sandboxing¶
code_interpreter executes dependency-free scripts with Monty and runs
package-dependent scripts in a fresh Deno + Pyodide WebAssembly environment
(mcp-run-python):
- Only modules in
TOOLS_CODE_INTERPRETER_IMPORT_ALLOWLISTand packages inTOOLS_CODE_INTERPRETER_DEPS_ALLOWLISTare permitted; modules inTOOLS_CODE_INTERPRETER_IMPORT_DENYLISTare blocked. - User code runs with networking disabled by default
(
TOOLS_CODE_INTERPRETER_ALLOW_NETWORKING=false), bounded memory (TOOLS_CODE_INTERPRETER_MAX_MEMORY_MB=1024), bounded concurrency (TOOLS_CODE_INTERPRETER_MAX_CONCURRENT=2), and an execution timeout (TOOLS_CODE_INTERPRETER_TIMEOUT=90). - Only validated uploads and generated files belonging to the current chat (plus enabled skill helper files when authorized) are provisioned into the sandbox workspace.
- Keeping
TOOLS_CODE_INTERPRETER_UNSANDBOXED=falseis essential on any shared or internet-facing deployment; setting it totrueruns Python directly on the host as the server OS user.
See Secure Tool Access and Tool System Design.
Rate Limiting, Security Headers, and CORS¶
- Rate limiting: HTTP endpoints use
SlowAPI(RATE_LIMIT_DEFAULT="200/hour",RATE_LIMIT_AUTH="20/minute",RATE_LIMIT_UPLOAD="10/hour"), while WebSocket connections and active turns enforce per-user and per-IP caps viaWEBSOCKET_*settings. - HTTP security headers (
web/middleware.py): Responses includeX-Content-Type-Options: nosniff,X-Frame-Options: DENY,Referrer-Policy,Permissions-Policy, Content Security Policy, and (in production)Strict-Transport-Security(HSTS). Interactive OpenAPI docs (/docs,/redoc) are disabled outside development. - CORS and WebSocket Origin checks: Set
CORS_ALLOW_ORIGINSto your exact public origin(s). WebSocket handshakes verify that any suppliedOriginheader matchesCORS_ALLOW_ORIGINSor the request's host (*is never accepted as a trusted WebSocket origin).
Production Security Checklist¶
Before exposing a Numi Chat instance to a network or the internet:
- Generate a strong 32+ byte
AUTH_SECRET_KEY(openssl rand -hex 32) and keep it backed up securely. - Register the initial administrator account before opening network access, and verify whether public signup should remain off.
- Terminate HTTPS at a reverse proxy, bind the container port to
127.0.0.1, and setENVIRONMENT=production,CORS_ALLOW_ORIGINS="https://your-domain.example", andFORWARDED_ALLOW_IPSto your proxy's IP. - Keep
TOOLS_CODE_INTERPRETER_UNSANDBOXED=falseand trimTOOLS_ALLOWLIST/TOOLS_DENYLISTto the tools your users need. - Restrict host filesystem permissions on
chats.db,.env,state/, and backups.