Self-improving AI Employees for everyone
Authentication System
Overview
n8n-inspired authentication system with JWT tokens stored in HttpOnly cookies. Authentication can be completely disabled for development or supports two deployment modes for different use cases.
Authentication Toggle
| Setting | Environment Variable | Description |
|---|---|---|
| Enabled | VITE_AUTH_ENABLED=true |
Require login (company deploy sets this on cloud VMs) |
| Disabled | VITE_AUTH_ENABLED=false |
Bypass authentication, anonymous access (default in .env.template) |
When VITE_AUTH_ENABLED=false:
- Frontend skips login page entirely
- User is set to anonymous with owner privileges
- The client still asks
GET /api/auth/statusonce at boot; it answersauth_enabled: false, and that is how the client knows to skip login - Useful for local development and testing
Deployment Modes (when auth enabled)
| Mode | Environment Variable | Description |
|---|---|---|
| Single Owner | AUTH_MODE=single |
First user becomes owner, registration disabled after |
| Multi User | AUTH_MODE=multi |
Open registration for cloud deployments |
Architecture
Frontend (LoginPage.tsx) → AuthContext → Backend (/api/auth/*) → JWT Cookie
↓
AuthMiddleware
↓
Protected Routes
Backend Implementation
User Model (server/models/auth.py)
class User(SQLModel, table=True):
__tablename__ = "users"
id: Optional[int] = Field(default=None, primary_key=True)
email: str = Field(unique=True, index=True)
password_hash: str
display_name: str
is_owner: bool = Field(default=False)
is_active: bool = Field(default=True)
created_at: datetime
last_login: Optional[datetime]
def set_password(self, password: str) -> None:
# Uses bcrypt for secure hashing
def verify_password(self, password: str) -> bool:
# Verifies against bcrypt hash
Auth Service (server/services/user_auth.py)
register()- Creates a new user; setsis_ownerif first user in single mode. Eligibility checks and the INSERT share ONE session (they used to span four, so two concurrent first-registrations could both be granted ownership), and aIntegrityErroron the email UNIQUE index returns a 400-shaped error rather than surfacing as a 500.login()- Validates credentials, returns(user, error). Every rejection returns the same"Invalid email or password", and the unknown-email path still runs a bcrypt comparison against a dummy hash — distinct messages and an early return were both account-enumeration oracles on a public endpoint.create_access_token()- Mints the JWT (HS256,sub/email/display_name/is_owner/exp/iat/nbf/jti). Noiss/aud: enforcing them would invalidate every token already held by a browser for negligible benefit in a single-audience app with a per-deployment secret.verify_token()- Validates JWT tokenget_current_user()- Resolves the token's subject to aUser, rejecting a non-numericsuband any account withis_active = Falseget_auth_status()- Returnsauth_modeandregistration_enabledlogout()- A no-op log line. See Known Limitations.
UserAuthService never initialises, derives or clears the encryption key.
The container injects EncryptionService and CredentialsDatabase into it,
and neither is used: the only reference to the encryption service is
is_encryption_initialized() (a pass-through to
EncryptionService.is_initialized()), which nothing calls, and
credentials_db is held and never read. 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
for the real pipeline.
Auth Router (server/routers/auth.py)
| Endpoint | Method | Description |
|---|---|---|
/api/auth/status |
GET | Get auth mode and registration status |
/api/auth/register |
POST | Register new user |
/api/auth/login |
POST | Login and set cookie |
/api/auth/logout |
POST | Clear auth cookie |
/api/auth/me |
GET | Get current user info |
routers/auth.py defines its own local get_auth_service() helper
(return container.auth_service()) — get_auth_service is NOT exported from
services/auth.py. routers/websocket.py repeats the same local helper.
The OAuth callback routers moved into their plugin folders
(nodes/twitter/_router.py, nodes/google/_router.py, built by
services.events.oauth_lifecycle.make_oauth_callback_router) and resolve the
service through services.plugin.deps.get_auth_service — the same call-time
container lookup, deliberately not memoised. In handlers/services use
from core.container import container; auth = container.auth_service().
Auth Middleware (server/middleware/auth.py)
Protects all routes except public paths:
PUBLIC_PATHS = frozenset(
[
"/health",
"/health/ready", # readiness probe for the desktop shell splash / CI
"/api/desktop/shutdown", # desktop shell; gated by X-Desktop-Token, not the cookie
"/docs",
"/openapi.json",
"/redoc",
"/api/auth/status",
"/api/auth/login",
"/api/auth/register",
"/api/auth/logout",
"/ws/internal", # Internal WebSocket for Temporal workers
]
)
# Path prefixes that are public. ``/mcp/`` is the CLI-agent MCP server, which
# enforces its own per-batch bearer-token auth (cookies don't apply to it), so
# it bypasses this cookie gate.
PUBLIC_PREFIXES = ("/webhook/", "/mcp/")
The middleware also lets the static SPA shell, built assets, and client-side routes load BEFORE login (the SPA renders the login page itself) when the container serves the client on a single port.
Frontend Implementation
Auth Context (client/src/contexts/AuthContext.tsx)
interface AuthContextValue {
user: User | null;
isAuthenticated: boolean;
isLoading: boolean;
error: string | null;
authMode: 'single' | 'multi';
canRegister: boolean;
login: (email: string, password: string) => Promise<boolean>;
register: (email: string, password: string, displayName: string) => Promise<boolean>;
logout: () => Promise<void>;
/** Check the session again; true when the server answered. */
checkAuth: () => Promise<boolean>;
/** A login/register request is in flight, or succeeded and its welcome
* is still showing. */
signingIn: boolean;
/** End the welcome: the requests go back to idle and the app shows. */
finishSignIn: () => void;
}
Protected Route (client/src/components/auth/ProtectedRoute.tsx)
The sign-in gate (onboarding handoff R4), in front of the whole app:
| State | Shows |
|---|---|
the session is being checked (isLoading) |
a loading screen |
the server can't be reached (error, not signed in) |
Connecting (ConnectingPanel): a countdown to each check, Try now, "Attempt n", and from the third attempt "Still nothing? Make sure OpenCompany is running." |
| the server answered | "Connected", held CONNECT_RETRY.CONNECTED_HOLD_MS (1.5 s, useHold) |
| then | sign-in, or the app when the session is good or login is off |
a sign-in from the form in flight or just done (signingIn) |
sign-in, then its welcome (SignedIn) until finishSignIn |
signed in, the WebSocket down (reconnecting from useWebSocketActions) |
Connecting over the app (role="dialog", z-60); the app stays mounted, inert |
Connecting, sign-in and the welcome render inside one ConnectScreen (the
whole window, the orb filling it, the logo and the theme button on top), so
the orb glides from one's slot to the other's. The schedule is useRetrySchedule:
CONNECT_RETRY.DELAYS_S (2, 3, 5, 8, 8 s), each check being checkAuth;
over the app the checks are HTTP session checks too, so a session that
expired while the server was away goes to sign-in, and the overlay goes
once the WebSocket is back. A ConnectScreen shows the chosen theme like the
rest of the app, and its theme button is the one in both modes' headers
(components/ui/ThemeButton.tsx).
Login Page (client/src/components/auth/LoginPage.tsx)
Inside the gate's ConnectScreen (onboarding handoff R5): the orb's login
slot above a card that rises in. "Welcome back" or "Create your account", the
fields ("Your name" when registering, "Email", "Password" with a show/hide
toggle), Sign in or Create account, and, while canRegister, the way to the
other mode.
- shadcn
Formcomposition (react-hook-form + zod), matchingEmailPanel— schema and the field messages incomponents/auth/schemas/login.ts.FormControlsuppliesaria-invalid+aria-describedbyper field; the form isnoValidateso zod is the single validation authority rather than native browser bubbles. canRegistergates the footer link only; the mode itself is local state.- The card shows one error: what the server said.
submitErroris the server's own rejection text, shown as it is:UserAuthServicewords it for the owner ("An account with this email already exists.", "This OpenCompany already has its owner. Sign in instead.", a wrong password, a 429). When the request got no answer it isAUTH_UNREACHABLE("Can't reach OpenCompany. Make sure it's running, then try again."). The bootstraperror(the server can't be reached at all) is the gate's Connecting screen, so this page never shows it. - Inputs and the submit button gate on
isSubmitting(per-request), notisLoading(bootstrap query). The latter has always settled by the time this page renders, so using it disabled nothing and the form accepted unlimited concurrent submits. - The card shakes (
shakeinlib/motion.ts) when a field is wrong or the server refuses. The orb follows the form: livelier while a field has focus (ENERGY.focus), more with text in it (ENERGY.typing), most while the request is out (ENERGY.generating). - After signing in the card gives way to
SignedIn: "Signed in" or "Account created", "Welcome back, {first name}" (or "Welcome, …" for a new account) and "Opening your team…", and the orb spikes. The gate keeps the screen up whilesigningInis true, which is the login and register mutations' own state: in flight, or succeeded and not yet finished. The welcome hands over the way a mode switch does (app/useShellActions.ts): the screen the app opens on (Home or the editor) loads while the welcome rises in, thenfinishSignInreturns the mutations to idle and the app shows. A session that was already good never sees it.
Configuration
Environment variables in .env:
# Authentication Toggle (frontend - Vite)
VITE_AUTH_ENABLED=false # 'false' (template default) bypasses login; 'true' requires it
# Authentication Mode (backend)
AUTH_MODE=single # 'single' or 'multi'
JWT_SECRET_KEY=your-secret-key-32 # Min 32 chars
JWT_EXPIRE_MINUTES=10080 # 7 days
JWT_COOKIE_NAME=opencompany_token
JWT_COOKIE_SECURE=false # true for HTTPS
JWT_COOKIE_SAMESITE=lax # 'none' REQUIRES SECURE=true (enforced)
# Login/registration throttling (core/rate_limit.py)
AUTH_RATE_LIMIT_ENABLED=true
AUTH_RATE_LIMIT_ATTEMPTS=10 # per window, per (client IP, email)
AUTH_RATE_LIMIT_WINDOW=300 # seconds
cookie_posture_warnings(settings) (in core/config.py, beside
dev_secret_offenders) logs a non-fatal banner at startup for an insecure
cookie outside DEPLOYMENT_MODE=local, and for "*" in CORS_ORIGINS while
credentialed CORS is on. Warnings rather than failures on purpose: company deploy intentionally sets JWT_COOKIE_SECURE=false because the VM is reached
over plain HTTP on its IP, so raising would break every LAN/IP deployment with
the worst possible symptom — login appearing to succeed, then immediately
logging out. The one combination that does hard-fail is
JWT_COOKIE_SAMESITE=none with JWT_COOKIE_SECURE=false, which no browser
accepts.
Known Limitations
Recorded explicitly because each of these is easy to assume is handled.
AUTH_MODE=multiprovides authentication, not isolation. The identity is now resolved —services/authz/ws_surface.py(execution_principal) reads the handshake identity and decides what a given execution runs as, and cron/deploy carry the deployer'suser_idthrough to every spawned run. What is still missing is enforcement: there is no ownership check on workflow get / list / delete, and the checks that exist on the Context and Memory panels are fail-open (if stored_owner and stored_owner != caller), so a row with an emptyowner_id— every legacy row, and every row written through the REST path — authorizes everyone.get_all_workflowsreturns every tenant's rows unfiltered.is_owneris still decorative. Until ownership moves to an indexed column with scoped accessors, treatmultias "several people who fully trust each other"./ws/internalskips the cookie gate and must stay narrow. It is inPUBLIC_PATHSbecause a Temporal worker has no session cookie. It used to accept any peer, and itsexecute_noderuns whatever node type and parameters the message names, so anyone who could reach the app port (published by Docker and bycompany deploy), or any web page open on the same machine, could run ashellnode. The handshake now requires theX-OpenCompany-Internal-Tokenheader, an HMAC ofSECRET_KEY(internal_socket_tokeninservices/authz/ws_surface.py); the worker clients (services/temporal/activities.py,ws_client.py, and a standalone worker's chat relay,services/chat/relay.py) send it, and any new internal client must too. A loopback-address check would not do: a reverse proxy on the same host makes public traffic arrive from 127.0.0.1, and a page's socket tolocalhostis itself loopback. Even with the token the socket reaches only the deny-by-default allowlist (INTERNAL_SOCKET_HANDLERS), which exists because the socket once dispatched through the same registry as the authenticated one —save_workflow,delete_workflowand all six Memory handlers were reachable. Refusal is deliberately indistinguishable from an unknown message type so the socket cannot be probed, and the allowlist test is generated from the live registry, so a newly added handler is closed by default.- Every WebSocket handshake checks
Origin. A browser lets any page open a socket to any host,localhostincluded, and with login off (the local default) there is no cookie to check, so any page open on the machine could drive/ws/status.services/authz/ws_session.pyadmits a handshake only whenOriginis absent (not a browser), matches the request'sHost, or is listed inCORS_ORIGINS(*there allows every origin, as it already does for HTTP CORS); anything else closes with4003beforeaccept().authenticate_ws(Origin, then the session cookie) serves every browser-facing socket;admit_internal_ws(Origin, then the worker token) serves/ws/internal. A reverse proxy that rewritesHostmust list the public origin inCORS_ORIGINS. Locked bytests/test_internal_socket_surface.py, which runs real handshakes. - No CSRF token. The API is cookie-authenticated and
SameSiteis the only defence. Mitigated by every mutating endpoint beingPOSTunder/api/and bySameSite=none+ insecure being rejected at startup. A real double-submit scheme would touch everyfetchand the WebSocket handshake. - No token revocation.
logoutclears the cookie; there is nojtidenylist, so a token captured beforehand stays valid untilexp(default 7 days). The practical lever isUser.is_active, enforced inget_current_user. - Rate-limit counters are per-process — see
core/rate_limit.py. /docs,/redoc,/openapi.jsonare served only when auth is disabled orDEPLOYMENT_MODE=local. They were previously public on every deployment becauseAuthMiddlewaregates by exclusion: any GET/HEAD outside/api/and/ws/is unauthenticated so the SPA shell can load pre-login. That rule is safe only while every router lives under/api/; the invariant test intests/auth/test_auth_middleware.pyfails if a new router breaks it.
core/config.py carries the vite_auth_enabled field (required because
Settings reads it to gate the auth middleware in middleware/auth.py;
model_config uses extra="ignore", so stale .env vars do not raise). It also exposes DEV_SECRET_LITERALS
and dev_secret_offenders(): server startup (lifespan) logs a non-fatal error
banner when SECRET_KEY / JWT_SECRET_KEY / API_KEY_ENCRYPTION_KEY still
carry the dev template placeholders while auth is enabled or DEPLOYMENT_MODE
is not local. Only a .env that company build creates itself gets fresh
secrets.token_hex(24) values; bun install in a checkout and
company provision copy the template as-is, and with login off in a local
install nothing warns. See
Credentials Encryption → Placeholder secrets.
Race Condition Handling (the bootstrap check)
The frontend starts before the backend is ready during cold launch, so the auth-status check must tolerate the server not being there yet.
The AuthContext runs the check through TanStack Query
(useQuery({ queryKey: AUTH_STATUS_QUERY_KEY, queryFn: fetchAuthStatus, retry: false, networkMode: 'always' })):
- No hidden retries. A failed check (no answer, a 5xx, a 401/403 or a
non-JSON 200) sets
errorat once, and the sign-in gate shows Connecting, which checks again throughcheckAuthon a schedule the owner can see (CONNECT_RETRYinclient/src/lib/connectionConfig.ts).checkAuthrefetches and says whether the server answered; a failed check keeps the last answer, so a signed-in owner stays signed in while the server is away. Nothing ever writes a failure into the status cache. networkMode: 'always': the browser's idea of being offline never pauses a check of a server on this computer.- AbortController
signalis plumbed throughqueryFnso unmount + React Strict Mode cleanup cancel in-flight requests automatically. login/register/logoutinvalidate the cache viaqueryClient.invalidateQueries({ queryKey: AUTH_STATUS_QUERY_KEY })(AUTH_STATUS_QUERY_KEY = ['auth', 'status']).
Historical note: the check used to retry on its own, first through a recursive
setTimeoutchain (1, 2, 4, 8, 16 s), then through TanStack Query's full-jitter backoff (AUTH_RETRY, about 10 s in all), after which the login page showed "Failed to connect to server" and nothing checked again. The visible Connecting screen replaced both.
Cookie-Based Auth for API Calls
All API calls must include credentials: 'include' for the HttpOnly cookie:
// In workflowApi.ts, all fetch calls include:
fetch(url, { credentials: 'include' })
WebSocket Authentication
Every handshake is admitted by a helper in services/authz/ws_session.py
before accept(). /ws/status (and /ws/browser) call authenticate_ws:
# 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:
- The
Origincheck: a foreign origin closes with4003("Origin not allowed"). See Known Limitations for which origins are admitted. - With login disabled (
VITE_AUTH_ENABLED=false), every same-origin caller is the owner principal. - Otherwise
core.auth_cookies.get_session_tokenreads the session cookie (JWT_COOKIE_NAME, falling back to the legacymachina_token), andUserAuthService.verify_tokenchecks it. A missing, invalid or subject-less token closes with4001.
/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:
// In WebSocketContext.tsx
const { isAuthenticated, isLoading: authLoading } = useAuth();
useEffect(() => {
if (authLoading || !isAuthenticated) {
// Disconnect if logged out
return;
}
connect();
}, [isAuthenticated, authLoading]);
Key Files
| File | Description |
|---|---|
client/src/config/api.ts |
The backend's base URL (same origin unless VITE_PYTHON_SERVICE_URL) |
client/src/contexts/AuthContext.tsx |
React auth state: the TanStack Query bootstrap check, checkAuth |
client/src/lib/connectionConfig.ts |
CONNECT_RETRY (the Connecting screen's schedule) and the WebSocket envelope |
client/src/components/auth/LoginPage.tsx, schemas/login.ts |
Sign in and register, and their messages |
client/src/components/auth/SignedIn.tsx |
The welcome after signing in, until the app is ready |
client/src/components/auth/ProtectedRoute.tsx |
The sign-in gate (states above) |
client/src/components/auth/ConnectScreen.tsx, ConnectingPanel.tsx |
The screen around Connecting and sign-in, and Connecting itself |
client/src/components/auth/useRetrySchedule.ts, useHold.ts |
The countdown to each check; "Connected" held a moment |
server/models/auth.py |
User SQLModel with bcrypt |
server/services/user_auth.py |
UserAuthService: register / login / JWT mint + verify / get_current_user. Holds the encryption service and credentials database but uses neither; its is_encryption_initialized() has no callers (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 |
Dependencies
# server/pyproject.toml
bcrypt>=4.2.0
pyjwt>=2.13.0
email-validator>=2.0.0
JWT handling uses PyJWT (import jwt, jwt.encode / jwt.decode, catch
jwt.PyJWTError) — HS256 with Settings.jwt_secret_key. Do not reintroduce
python-jose: it drags in pure-Python ecdsa, which carries an unpatchable
Minerva timing-attack advisory (GHSA-wj6h-64fc-37mp).