Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(auth): correct stale statements in credentials and auth docs
trohitgf593c9165fab
diff --git a/docs-internal/authentication.md b/docs-internal/authentication.mdindex 5fcfc59c..4ec675bc 100644--- a/docs-internal/authentication.md+++ b/docs-internal/authentication.md@@ -72,13 +72,17 @@ class User(SQLModel, table=True):- `get_auth_status()` - Returns `auth_mode` and `registration_enabled`- `logout()` - A no-op log line. See Known Limitations.-**`UserAuthService` does not touch the encryption service.** Earlier revisions-of this document described `login()` calling `_initialize_encryption(password)`-and `logout()` calling `self.encryption.clear()`. Neither method has ever-existed. The Fernet key is **server-scoped**: initialised once during startup-in `main.py` from `API_KEY_ENCRYPTION_KEY`, never derived from a user password-and never cleared on logout. See-[Credentials Encryption](./credentials_encryption.md) for the real pipeline.+**`UserAuthService` never initialises, derives or clears the encryption key.**+The container injects `EncryptionService` and `CredentialsDatabase` into it,+but the only use of either is the read-only `is_encryption_initialized()`+(a pass-through to `EncryptionService.is_initialized()`); `credentials_db` is+held and unused. Earlier revisions of this document described `login()`+calling `_initialize_encryption(password)` and `logout()` calling+`self.encryption.clear()`. Neither method has ever existed. The Fernet key is+**server-scoped**: initialised once during startup in `main.py` from+`API_KEY_ENCRYPTION_KEY`, never derived from a user password and never+cleared on logout. See [Credentials Encryption](./credentials_encryption.md)+for the real pipeline.### Auth Router (`server/routers/auth.py`)| Endpoint | Method | Description |@@ -312,14 +316,33 @@ fetch(url, { credentials: 'include' })```## WebSocket Authentication-WebSocket checks the cookie before accepting the connection:+Every handshake is admitted by a helper in `services/authz/ws_session.py`+before `accept()`. `/ws/status` (and `/ws/browser`) call `authenticate_ws`:```python-# In websocket.py-token = websocket.cookies.get(settings.jwt_cookie_name)-if not token:- await websocket.close(code=4001, reason="Not authenticated")- return+# In routers/websocket.py+authenticated_user_id = await authenticate_ws(+ websocket,+ settings=container.settings(),+ user_auth_service=container.user_auth_service,+)+if authenticated_user_id is None:+ return # already closed+websocket.state.user_id = authenticated_user_id```+`authenticate_ws` runs, in order:+1. The `Origin` check: a foreign origin closes with `4003` ("Origin not+ allowed"). See Known Limitations for which origins are admitted.+2. With login disabled (`VITE_AUTH_ENABLED=false`), every same-origin caller+ is the owner principal.+3. Otherwise `core.auth_cookies.get_session_token` reads the session cookie+ (`JWT_COOKIE_NAME`, falling back to the legacy `machina_token`), and+ `UserAuthService.verify_token` checks it. A missing, invalid or subject-less+ token closes with `4001`.++`/ws/internal` uses `admit_internal_ws` instead: the same `Origin` check+(`4003`), then the `X-OpenCompany-Internal-Token` header, an HMAC of+`SECRET_KEY` (`internal_socket_token` / `is_internal_caller` in+`services/authz/ws_surface.py`); a missing or wrong token closes with `4001`.`WebSocketProvider` only connects when authenticated:```typescript@@ -344,7 +367,7 @@ useEffect(() => {| `client/src/components/auth/LoginPage.tsx` | Login UI || `client/src/components/auth/ProtectedRoute.tsx` | Route guard || `server/models/auth.py` | User SQLModel with bcrypt |-| `server/services/user_auth.py` | `UserAuthService`: register / login / JWT mint + verify / `get_current_user`. No encryption-service coupling (see the note under Auth Service) |+| `server/services/user_auth.py` | `UserAuthService`: register / login / JWT mint + verify / `get_current_user`. Holds the encryption service only for the read-only `is_encryption_initialized()` check (see the note under Auth Service) || `server/routers/auth.py` | REST endpoints || `server/middleware/auth.py` | Route protection (`PUBLIC_PATHS` / `PUBLIC_PREFIXES`) || `server/core/config.py` | Settings with `vite_auth_enabled` field |diff --git a/docs-internal/credentials_encryption.md b/docs-internal/credentials_encryption.mdindex 3ea8578a..f0876ce2 100644--- a/docs-internal/credentials_encryption.md+++ b/docs-internal/credentials_encryption.md@@ -10,7 +10,7 @@ Credentials are isolated from the main `workflow.db` for three reasons:1. **Blast radius**: a dump of `workflow.db` for debugging never contains secrets.2. **Independent backups**: `credentials.db` can be excluded from snapshots and SQLite dumps.-3. **Backend pluggability**: the file-backed SQLite can be swapped for OS keyring or AWS Secrets Manager without touching workflow storage.+3. **Backend pluggability**: the file-backed SQLite is designed to be swappable for OS keyring or AWS Secrets Manager without touching workflow storage (the abstraction exists but is not wired in yet; see [Multi-Backend Abstraction](#multi-backend-abstraction)).## Files@@ -18,8 +18,8 @@ Credentials are isolated from the main `workflow.db` for three reasons:server/core/|-- encryption.py EncryptionService (Fernet + PBKDF2)|-- credentials_database.py CredentialsDatabase (async SQLite, salt storage)-|-- credential_backends.py Multi-backend abstraction (Fernet / Keyring / AWS)-`-- config.py credential_backend, aws_secret_arn settings+|-- credential_backends.py Multi-backend abstraction (Fernet / Keyring / AWS; not wired in)+`-- config.py credential_backend, aws_secret_arn settings (read only by the uncalled create_backend)server/services/`-- auth.py AuthService (single access point, caching)@@ -54,7 +54,7 @@ API_KEY_ENCRYPTION_KEY (from .env)The derived Fernet key lives only in `EncryptionService._fernet` in process memory. It is never written to disk or to Redis.-`EncryptionService` (`server/core/encryption.py`) exposes `initialize(password, salt)` (derive + store the Fernet cipher), `encrypt(plaintext) -> str` (base64 ciphertext), `decrypt(ciphertext) -> str`, `clear()` (drop the in-memory key), `is_initialized() -> bool`, the lower-level `derive_key_from_password(password, salt) -> bytes` that `initialize` calls, and a static `generate_salt() -> bytes`. `CredentialsDatabase` (`server/core/credentials_database.py`) backs both systems with `initialize() -> bytes` (creates tables, returns the salt), `save_api_key` / `get_api_key` / `delete_api_key`, and `save_oauth_tokens` / `get_oauth_tokens` / `delete_oauth_tokens(provider, customer_id="owner")`.+`EncryptionService` (`server/core/encryption.py`) exposes `initialize(password, salt)` (derive + store the Fernet cipher), `encrypt(plaintext) -> str` (base64 ciphertext), `decrypt(ciphertext) -> str`, `clear()` (drop the in-memory key; only tests call it), `is_initialized() -> bool`, the lower-level `derive_key_from_password(password, salt) -> bytes` that `initialize` calls, and a static `generate_salt() -> bytes`. `CredentialsDatabase` (`server/core/credentials_database.py`) backs both systems with `initialize() -> bytes` (creates tables, returns the salt), `save_api_key` / `get_api_key` / `delete_api_key`, and `save_oauth_tokens` / `get_oauth_tokens` / `delete_oauth_tokens(provider, customer_id="owner")`.## Lifecycle@@ -65,7 +65,7 @@ Server startup (main.py lifespan)CredentialsDatabase.initialize() -> creates tables, returns existing or new salt|v-EncryptionService.initialize(password=API_KEY_ENCRYPTION_KEY, salt=<bytes>)+container.encryption_service().initialize(password=API_KEY_ENCRYPTION_KEY, salt=<bytes>)|vAuthService caches decrypted credentials in memory-only dicts@@ -74,7 +74,8 @@ AuthService caches decrypted credentials in memory-only dictsRouters call AuthService.get_api_key() / get_oauth_tokens() ...|v-(on shutdown) EncryptionService.clear() wipes the in-memory key+(process exit) the key is held for the process lifetime; shutdown does not call+ EncryptionService.clear()````EncryptionService.is_initialized()` is checked before any encrypt/decrypt call. If the server key is misconfigured, the service raises at startup rather than returning unusable ciphertext later.@@ -116,22 +117,24 @@ from core.container import containerauth = container.auth_service()tokens = await auth.get_oauth_tokens("google")-# Wrong (will not go through cache, will not respect backend abstraction):+# Wrong (bypasses the AuthService cache):credentials_db = get_credentials_db()row = await credentials_db.query(...)```-Enforcement:+How the pieces are wired:-- `AuthService` owns the Fernet cipher initialization.+- The Fernet cipher is initialized in the `main.py` lifespan, not by `AuthService`: `container.credentials_database().initialize()` returns the salt, then `container.encryption_service().initialize(settings.api_key_encryption_key, salt)` derives the key. `CredentialsDatabase` receives that same `EncryptionService` singleton through DI and performs the encrypt/decrypt.- `AuthService` maintains the memory-only decryption cache.-- `CredentialsDatabase` is injected into `AuthService` and not exposed via DI to other services.+- `CredentialsDatabase` is a DI singleton (`container.credentials_database()`). The container injects it into `AuthService` and into `UserAuthService` (which holds it but never uses it), and `main.py` resolves it at startup to create tables and read the salt. The container does not stop anything else from resolving it, so "routers and services go through `AuthService`" is a rule to follow, not something DI enforces.The in-memory cache is important: decrypting on every request would be slow, and writing decrypted values to Redis would defeat the encryption. Each `AuthService` instance caches decrypted credentials in process memory only, and `AuthService.clear_cache()` flushes them on demand (used by the logout handler).## Multi-Backend Abstraction-For deployment flexibility, `credential_backends.py` defines an abstract interface that can be swapped via the `CREDENTIAL_BACKEND` env var.+For deployment flexibility, `credential_backends.py` defines an abstract interface intended to be selected via the `CREDENTIAL_BACKEND` env var.++**Status: not wired in.** Nothing in the server calls `create_backend()`, and `Settings.credential_backend` / `aws_secret_arn` / `aws_region` are read only inside it. `AuthService` always talks to `CredentialsDatabase` directly, so every install uses Fernet-encrypted SQLite and setting `CREDENTIAL_BACKEND` currently has no effect. The rest of this section describes the abstraction as written.```pythonclass CredentialBackend(ABC):@@ -170,13 +173,13 @@ aws = ["boto3>=1.34.0"] # AWS Secrets Manager# Required for Fernet backendAPI_KEY_ENCRYPTION_KEY=<any string, at least 32 chars for good entropy>-# Which backend to use+# Which backend to use -- currently has no effect (see Multi-Backend Abstraction)CREDENTIAL_BACKEND=fernet # fernet | keyring | aws# Path to credentials SQLite fileCREDENTIALS_DB_PATH=credentials.db-# AWS backend only+# AWS backend only (also unused until the backend layer is wired in)AWS_SECRET_ARN=arn:aws:secretsmanager:...AWS_REGION=us-east-1```@@ -191,7 +194,7 @@ When `company build` scaffolds `.env` from `.env.template` (step `[0/6]`), it ge- **No plaintext on disk**: credentials are only decrypted in memory.- **No plaintext in Redis**: even in Redis mode, only encrypted envelopes cross the wire (the cache layer never stores decrypted credentials).- **Salt per install**: different OpenCompany installs have different salts, so ciphertext is not portable across installs even with the same server key.-- **Wipes on shutdown**: `EncryptionService.clear()` zeroes the Fernet reference, preventing cold-boot recovery of the derived key.+- **Held for the process lifetime**: the derived key is never written to disk, but it is not wiped at shutdown either. `EncryptionService.clear()` (which drops the Fernet reference) is called only by tests; the `main.py` lifespan shutdown does not call it, so the key leaves memory when the process exits.## Source of Truthdiff --git a/server/services/user_auth.py b/server/services/user_auth.pyindex cf6755ff..6c1a7dd0 100644--- a/server/services/user_auth.py+++ b/server/services/user_auth.py@@ -1,4 +1,10 @@-"""User authentication service with JWT handling and encryption initialization."""+"""User authentication service: registration, login and JWT handling.++It does not initialise, derive or clear the credential encryption key. That+key is server-scoped and initialised once in the ``main.py`` lifespan from+``API_KEY_ENCRYPTION_KEY``. ``UserAuthService`` only exposes the read-only+``is_encryption_initialized()`` check.+"""import loggingimport uuid