Authentication & Authorization (AuthNZ)
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication and Authorization (AuthNZ) module provides enterprise-grade security for the tldw_server platform. It is designed to facilitate secure access control for both personal local deployments and hosted multi-tenant environments. The module manages user identities, session lifecycles, and fine-grained permission checks to ensure data isolation and resource governance across the system.
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:14-18, Docs/Architecture.md:244-247
The system operates in two primary modes: single_user, which utilizes a static API key for simple local setups, and multi_user, which implements a robust JWT-based (JSON Web Token) authentication flow including registration, login, and session management. AuthNZ integrates deeply with the project's data storage architecture, mapping authenticated identities to specific per-user databases to maintain logical multi-tenancy.
Sources: Docs/Architecture.md:237-243, tldw_Server_API/app/core/AuthNZ/README.md:11-20
Architecture and Components
The AuthNZ module is structured as a collection of specialized services and managers that handle different aspects of the security lifecycle. It utilizes a centralized database for user credentials and global permissions while delegating actual data storage to isolated per-user environments.
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:32-51, tldw_Server_API/app/core/AuthNZ/README.md:25-33
Component Relationship
The following diagram illustrates how core components interact within the AuthNZ module.
Core Components Table
| Component | Description | Primary File |
|---|---|---|
| Settings Management | Centralized configuration using Pydantic and env variables. | settings.py |
| JWT Service | Handles creation, decoding, and validation of Access and Refresh tokens. | jwt_service.py |
| Password Service | Implements Argon2id hashing and password strength validation. | password_service.py |
| Session Manager | Manages encrypted session storage with support for Redis caching. | session_manager.py |
| API Key Manager | Manages the lifecycle of user API keys (creation, rotation, revocation). | api_key_manager.py |
| Rate Limiter | Implements token-bucket algorithms for per-user and per-endpoint limits. | rate_limiter.py |
| Auth Governor | Orchestrates global auth policies and guardrails. | auth_governor.py |
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:77-133, tldw_Server_API/app/core/AuthNZ/README.md:46-56
Authentication Flows
The system switches logic based on the AUTH_MODE environment variable.
Sources: Docs/Architecture.md:237-243
Single-User Mode
In single-user mode, authentication is simplified to a single static key validation. The server checks the X-API-KEY header against the configured SINGLE_USER_API_KEY.
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:144-152
Multi-User Mode (JWT)
Multi-user mode uses a stateful login process followed by stateless token verification for subsequent requests. It involves both Access Tokens (short-lived) and Refresh Tokens (long-lived).
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:154-173
Data Models and Schema
AuthNZ relies on a centralized database, typically SQLite (users.db) for development or PostgreSQL for production multi-user environments.
Sources: Docs/Architecture.md:218-223, tldw_Server_API/app/core/AuthNZ/README.md:65-75
Core Tables Summary
| Table | Purpose | Key Fields |
|---|---|---|
| users | Stores user identity and credentials. | id, username, email, password_hash, role, is_active |
| sessions | Tracks active logins and device info. | id, user_id, token_hash, encrypted_token, expires_at |
| api_keys | Manages persistent user API keys. | id, user_id, key_hash, key_prefix, scope, expires_at |
| token_blacklist | Stores revoked tokens (logout/rotation). | jti, expires_at |
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:175-227, tldw_Server_API/app/core/AuthNZ/README.md:65-75
Security Implementation Details
Password Security
Passwords are never stored in plaintext. The system uses Argon2id hashing via the PasswordService. This includes configurable salt, memory cost, and parallelism parameters. The system also supports password history to prevent immediate reuse during resets.
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:102-108, tldw_Server_API/app/core/AuthNZ/README.md:50
Session and Token Security
- JWT tokens: Signed using a
JWT_SECRET_KEY. - Encryption at Rest: Sessions stored in the database contain
encrypted_tokenandencrypted_refreshfields, encrypted using the Fernet (AES-128) algorithm. - Revocation: Supports immediate token revocation via a blacklist (stored in DB or Redis) and the ability for admins to "revoke all" sessions for a specific user.
- Fernet Key Management: The
SESSION_ENCRYPTION_KEYis required for decrypting session data. If not provided in environment variables, the system attempts to persist/load it fromtldw_Server_API/Config_Files/session_encryption.key.
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:110-120, tldw_Server_API/app/core/AuthNZ/README.md:86-97
Guardrails and Rate Limiting
The module provides protection against abuse through several mechanisms:
- Token Bucket Rate Limiting: Enforced via
rate_limiter.pyper user identifier and endpoint. - Lockout Tracker: Tracks failed login attempts and imposes a cooldown period after
MAX_LOGIN_ATTEMPTSis exceeded. - LLM Budgets: Specific to "Virtual Keys," allowing admins to set token or USD limits for LLM provider usage.
- CSRF Protection: Implements a double-submit cookie pattern for WebUI interactions.
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:239-258, tldw_Server_API/app/core/AuthNZ/README.md:52-56
Configuration Options
| Variable | Type | Default | Description |
|---|---|---|---|
AUTH_MODE | String | single_user | Either single_user or multi_user. |
DATABASE_URL | String | sqlite:///./Databases/users.db | URL for the central AuthNZ database. |
JWT_SECRET_KEY | String | None | Secret used to sign JWT tokens (Multi-user only). |
SINGLE_USER_API_KEY | String | None | Static key used for single_user mode. |
SESSION_ENCRYPTION_KEY | String | None | Fernet key for session data encryption. |
ACCESS_TOKEN_EXPIRE_MINUTES | Integer | 30 | Duration before an access token expires. |
ENABLE_REGISTRATION | Boolean | true | Allows new users to create accounts. |
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:83-91, tldw_Server_API/app/core/AuthNZ/README.md:77-85, Docs/User_Guides/WebUI_Extension/Household_Multi_User_Walkthrough.md:126-140
Conclusion
The AuthNZ module is a critical infrastructure component of tldw_server, providing the necessary security layers to transition from a single-user tool to a multi-tenant platform. By abstracting authentication into single_user and multi_user modes and enforcing strict authorization via RBAC and per-user database isolation, it ensures that user data remains secure and private while offering administrators the tools needed for system governance and resource management.
Sources: Docs/Published/Code_Documentation/AuthNZ-Developer-Guide.md:368-372, Docs/Architecture.md:244-256