Skip to content

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 (default 30 minutes). Every authenticated check verifies both the JWT signature (AUTH_SECRET_KEY) and that the session's refreshtoken row in SQLite is unexpired and unrevoked.
  • Single-use refresh token rotation: Refresh tokens expire after AUTH_REFRESH_TOKEN_EXPIRE_DAYS (default 7 days) 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=Lax cookies (Secure when ENVIRONMENT!=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=13 by 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

  1. At startup, ToolRegistry loads a tool only if it is in TOOLS_ALLOWLIST and not in TOOLS_DENYLIST (TOOLS_DENYLIST always wins). request_tool_activation is exempt from the allowlist so the model can ask to enable optional groups, unless explicitly listed in TOOLS_DENYLIST.
  2. Optional tool groups stay out of a chat's active tool schemas until the user enables them for that chat.
  3. At execution time, ToolExecutorService rejects any tool call not in the chat's active set and overwrites chat_id, chat_uuid, and user_id with 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_ALLOWLIST and packages in TOOLS_CODE_INTERPRETER_DEPS_ALLOWLIST are permitted; modules in TOOLS_CODE_INTERPRETER_IMPORT_DENYLIST are 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=false is essential on any shared or internet-facing deployment; setting it to true runs 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 via WEBSOCKET_* settings.
  • HTTP security headers (web/middleware.py): Responses include X-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_ORIGINS to your exact public origin(s). WebSocket handshakes verify that any supplied Origin header matches CORS_ALLOW_ORIGINS or 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 set ENVIRONMENT=production, CORS_ALLOW_ORIGINS="https://your-domain.example", and FORWARDED_ALLOW_IPS to your proxy's IP.
  • Keep TOOLS_CODE_INTERPRETER_UNSANDBOXED=false and trim TOOLS_ALLOWLIST / TOOLS_DENYLIST to the tools your users need.
  • Restrict host filesystem permissions on chats.db, .env, state/, and backups.