Skip to content

Self-improving AI Employees for everyone

docs(auth): correct stale statements in credentials and auth docs

trohitgf593c9165fab
diff --git a/docs-internal/authentication.md b/docs-internal/authentication.md
index 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.md
index 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>)
|
v
AuthService caches decrypted credentials in memory-only dicts
@@ -74,7 +74,8 @@ AuthService caches decrypted credentials in memory-only dicts
Routers 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 container
auth = 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.
```python
class CredentialBackend(ABC):
@@ -170,13 +173,13 @@ aws = ["boto3>=1.34.0"] # AWS Secrets Manager
# Required for Fernet backend
API_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 file
CREDENTIALS_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 Truth
diff --git a/server/services/user_auth.py b/server/services/user_auth.py
index 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 logging
import uuid