--- status: building created: 2026-07-24 amended: 2026-07-31 owner: tbd --- # Opt-in Authentication & Multi-User Segregation ## Why Kandev ships as a single-user local tool with zero authentication: the backend binds `0.0.0.0` by default and anyone who can reach the port owns the instance and every agent credential on it. Teams who share a Kandev server (VPS, homelab, office box) need user accounts and privacy between users — without burdening the local single-user install with a login screen it never asked for. ## What - **Opt-in.** Authentication is OFF by default. A disabled instance behaves byte-identically to pre-auth Kandev — no login, no auth UI. - **Enablement is a runtime feature toggle.** Authentication is turned on/off through the `features.auth` runtime flag ("Authentication & users" in `Settings > System > Feature Toggles`, or `KANDEV_FEATURES_AUTH=true`) — a restart-required flag like the other feature toggles, with no separate Authentication settings page. Turning it on (and restarting) enters **setup mode**: the first visitor completes a wizard (email + password) and becomes the admin. The wizard promotes the existing single-user profile — settings, workspaces, and secrets carry over to the admin account. The effective mode is derived: `flag off → disabled`, `flag on + no admin → setup`, `flag on + admin exists → enabled`. - **Accounts.** Local email + password (argon2id). The identity schema is provider-based so OIDC/SSO can be added later without migration. Roles: `admin` (user management, auth settings, destructive system operations, feature toggles) and `member`. Users can be disabled (revokes all sessions and tokens); the last active admin cannot be demoted or disabled. - **Sessions & tokens.** Browser sessions are opaque cookies (`kandev_session`, HttpOnly, SameSite=Lax, sliding 30-day expiry, DB-backed and revocable from `Settings > Account`). Programmatic clients (external MCP, scripts, CI) use personal access tokens (`kandev_pat_…`, shown once, revocable). - **Invites.** Admins mint tokenized invite URLs (`/invite?token=…`, optional pinned email, member/admin role, 7-day default expiry, single use). No email server required. Admins can also create accounts directly. - **Segregation: per-user workspaces.** Every workspace has one owner. Users see and touch only their own workspaces — tasks, sessions, repositories, workflows, plans, walkthroughs, terminals, VS Code, port previews, git snapshots, session turns/context, secrets, **third-party integration settings (GitHub/GitLab/Jira/Linear/Sentry/Slack/Azure), automations**, and WebSocket events included. Cross-user access returns 404 — knowing an ID from another user's workspace does not grant access. Admins do NOT see other users' workspaces (hard privacy; admin is a management role, not a visibility role). Pre-auth data is claimed by the admin at setup. - **Shared surfaces (instance-global by design).** Executors, executor profiles, environment definitions, agent profiles/agents, editors, prompts, sprites, voice, notification providers, and system pages remain shared across the instance; mutation of system settings and feature toggles is admin-only when auth is enabled. **Note:** a shared agent profile means all users share the agent's provider credentials — see the OS-level limit below. - **Public endpoints.** `/health`, the SPA shell/static assets, the boot payload (`/api/v1/app-state` — returns only `{features, auth}` for anonymous visitors), `/api/v1/features`, credential endpoints (login/setup/invite-accept), and self-authenticating webhooks (automation `X-Webhook-Secret`, office channel HMAC, plugin webhooks). - **Session challenges are distinct from provider authentication failures.** The browser clears its Kandev identity and opens `/login` only when a 401 is a Kandev session challenge. A third-party integration may also return 401 when GitHub, GitLab, Jira, or Linear rejects its own credential; that failure remains on the current page and is rendered by the integration surface. - **Disable.** An admin can turn auth off again (unless env-forced). Ownership data is retained; everyone reaching the instance has full access again. ## API surface `/api/v1/auth/*`: `setup`, `login`, `logout`, `me`, `password`, `sessions`, `tokens`, `invites` (+ `preview`, `accept`), `settings`. `/api/v1/users` (admin CRUD: list, create, role/status). WS: cookie on same-origin upgrade or `?token=`; subscriptions and RPC actions are scoped to the caller. ## Failure modes - Wrong credentials and unknown emails return the same generic 401; login is rate-limited (10 attempts / 5 min per IP+email). - Foreign workspaces/tasks read as 404 — existence is not leaked. - A server bound to non-loopback interfaces with auth disabled logs a prominent startup warning. - Sessions/PATs of disabled users fail closed immediately. - Third-party provider authentication failures do not clear the authenticated Kandev user, replace the current route, or trigger a login redirect. ## Scenarios - **GIVEN** an authenticated Kandev browser session, **WHEN** a protected API request receives a Kandev session challenge, **THEN** the browser clears the stale Kandev identity and navigates to `/login`. - **GIVEN** an authenticated Kandev browser session and an expired or invalid third-party integration credential, **WHEN** GitHub, GitLab, Jira, or Linear data loading returns 401 without a Kandev session challenge, **THEN** the browser stays on the integration route and displays the provider loading error. ## Known v1 limits - **Filesystem / agent-credential isolation is NOT enforced.** Worktrees and repos live under one `~/.kandev` tree readable by the OS user running the backend, and agent CLI logins (`gh auth`, `claude login`, provider API keys) authenticate as that OS user — so all app-users share the same on-disk agent credentials. Application-layer isolation (DB + the checks above) is the boundary between users' *kandev data*; it does NOT sandbox the filesystem or per-user agent auth. For hard isolation of agent credentials, run separate kandev instances per user or use per-user OS accounts / sandboxed executors (future work). - No workspace sharing/membership — one owner per workspace. - No first-party OIDC/SSO. The host supports **plugin-provided** external login (an `auth`-capable plugin asserts a validated OIDC/SAML identity and the host mints the session — see ADR 0050); the pre-auth login-page SSO buttons and anonymous provider discovery (`auth.ssoProviders` in the boot payload) ship here too. What remains is a published IdP plugin (e.g. Google OIDC, developed in its own repo) and setup-mode first-admin bootstrap via SSO (SSO requires enforced auth today). - Office workspace-scoped HTTP routes (those carrying a `:wsId`) are ownership-checked when auth is enabled; office run *subscriptions* are not yet ownership-checked (run events carry no workspace context at the subscription layer).