Skip to content

Security

Wijanarko Putra Rajeb edited this page Nov 15, 2026 · 3 revisions

Security

Off by default. A plain bun run dev requires no password, and no file on disk can change that: the password is supplied per run and hashed in memory. Only a session signing secret is persisted (~/.kabmo/auth.json, mode 0600), so bun run --hot does not sign you out on every save while nothing durable can enable authentication on its own.

kabmo serve --ui-password my-secret    # or KABMO_UI_PASSWORD
kabmo serve --ui-password              # generates one and prints it once
kabmo serve --tls --ui-password …      # HTTPS, cookie gains Secure
  • Password — argon2id, verified in constant time. Login is throttled per socket address (10 per 5 minutes, then a 15-minute lockout). x-forwarded-for is read only when the socket itself is loopback — the case a tunnel creates, where every client would otherwise share one budget and ten failures from an attacker would lock the owner out. A direct remote connection still keys on its own socket address, which a caller cannot forge. See Connect, tunnels and pairing.
  • Sessions — a stateless HMAC token in a cookie named per port (omp_session_<port>), because browsers key a cookie jar by host and ignore the port. HttpOnly, SameSite=Lax, and Secure whenever the request arrived over https — including through a proxy that sets x-forwarded-proto. Changing the password or calling POST /api/auth/revoke rotates the signing secret and ends every session everywhere. The token binds to a key derived from the password, so a restart with the same password keeps your session and a different one kills it.
  • TLS — --tls generates a self-signed certificate (SAN covering localhost, 127.0.0.1 and the machine's LAN addresses) into ~/.kabmo/tls/. Your browser warns once, then the connection is encrypted. Without it, a password and the session cookie cross the network in cleartext, which is what --lan warns about.
  • No TLS locally? A tunnel terminates TLS at the edge and needs no certificate. Prefer Tailscale Serve, which terminates TLS on this machine with a certificate the platform already trusts — so every shell accepts it, the origin becomes a secure context (dictation, clipboard, service worker), and Tailscale never sees the traffic. A named Cloudflare tunnel also works, but its edge reads the plaintext; quick tunnels are not supported because they buffer SSE. See Connect, tunnels and pairing.
  • Local sockets are origin-checked. The terminal PTY and dictation WebSockets verify the upgrade's origin with the same predicate, because both trigger real work on this machine.

Bind to loopback (the default) and reach it over SSH port-forwarding, a VPN, or a tunnel. Exposing the port directly is the option with the least margin for error.

Implementation notes

UI Authentication (the login screen)

  • The login screen is the app shell, not a page of its own. App renders <LoginScreen/> whenever the client's auth store says required, at whatever URL the document was served from, and the shell is reachable without a session on purpose (it is the way in). authGate (src/server/lib/auth/guard.ts) is the one authority: a single onBeforeHandle that covers every Elysia route, with isPublicPath naming what an unauthenticated visitor may still fetch (the bundle, the fonts, /api/auth/state, /login).
  • The login screen paints the STORED theme, and only the published settings map is gated. The shell is rendered for both audiences, so src/server/plugins/ssr.ts reads app_settings either way: the palette, the surface material, the icon tone and the manifest's colours are presentation, not secrets. splitShellSettings (src/server/lib/assets/shell-settings.server.ts) is the one place that separates them — presentation feeds the first-frame style, the <html> attributes and <meta name="theme-color">, while published feeds window.__OMP_BOOTSTRAP__.appSettings and is {} until the request carries a session. Gating BOTH on authenticated is what shipped, and it drew a dark install's login screen in the default paper palette while the workspace behind it used the chosen one; measured on the smoke probe after the split: unauthenticated GET / answers data-theme="one-dark-pro-soft", data-theme-variant="dark", data-surface="glass", theme-color #21252b, authenticated: false, appSettings: {}.
  • The native shells' update check is on that list, and it has to be. /api/updates/android and /api/updates/ios are asked from NATIVE code (AppUpdateCheck.kt, SettingsViewController.fetchRelease) over a plain HTTP client that carries no cookie — and the button exists precisely for a shell too stale to load the console, so it cannot depend on a session either. Gating them answered 401 to every installed shell on a password-protected console, and the settings screen could only report "Could not ask the server. The check needs a reachable console." (measured against a real authEnabled: true install; the same console's unauthenticated /api/updates/android was 401 while /api/health was 200). What they expose is a version and a public GitHub URL — the same data an unauthenticated browser reads off github.com. /api/updates/desktop deliberately STAYS gated: only the CONSOLE asks it (the desktop shells report their version over __kabmoDesktop and the sidebar compares it), and the console is behind the login. guard.test.ts pins all three directions.
  • A signed-in visitor asking for /login is answered 302 → /, and that check sits BEFORE the public-path shortcut. /login must stay public (it is the only way in), and that is exactly what used to let the shell render the workspace at a URL that says /login — a bookmark, a stale tab or the back button kept landing there. The redirect also fires when authentication is off entirely, where there is nothing to log into. Verified end to end against a real server: GET /login with the session cookie answers 302 location: / on every boot, and 200 text/html without one.
  • A session's fingerprint binds to a DETERMINISTIC key, never to the argon2 hash. issueSessionToken/verifySessionToken take a credentialKey, and credentialFingerprint is HMAC(sessionSecret, credentialKey) where the key is deriveCredentialKey(password, sessionSecret) — scrypt, salted with the persisted secret. The argon2 hash cannot serve: its salt is random per boot, so a restart minted a new hash, changed the fingerprint, and silently killed every session on every restart and every bun --hot save — measured: a token valid before a second initAuth call was rejected after it, with the secret correctly read back from disk. That defeated the documented reason the secret is persisted at all ("a restart keeps its sessions"), and it is what a user reported as being bounced back to the login screen. argon2's own salt option is not an alternative (verified on Bun 1.4.2: two hashes with the same salt still differ). The revocation properties are unchanged and pinned by tests: a different password derives a different key, and revokeAllSessions rotates the secret — both kill every existing token, while a restart with the same password does not. auth.json still holds only the secret: nothing on disk can enable authentication or reveal the password. Verified end to end: log in, SIGKILL the server, boot it again with the same KABMO_DATA_DIR and password, and the same cookie still reports authenticated: true.
  • The client store flips on a 401 only OUTSIDE /api/auth/ (AUTH_PREFIX, src/client/hooks/ui/auth.ts). The bridge wraps window.fetch once so 128 call sites need no auth awareness, but the auth endpoints answer 401 about the credential the caller just supplied — POST /api/auth/password does for a mistyped CURRENT password — and treating that as a lost session threw a signed-in user's whole workspace behind the login screen over an ordinary typo. A gate rejection of the same path is indistinguishable and costs nothing: any other gated request flips the store on its own. Pinned by src/client/hooks/ui/auth.test.ts (happy-dom).
  • The login screen re-checks the session instead of trusting what put it there, on mount and whenever the tab becomes visible: a sign-in in another tab, or a document restored from the back/forward cache, would otherwise leave a form asking for a password the browser already has. probeSession() is deliberately read-only — using the store-aware checkAuthState() would mount the workspace with the settings an unauthenticated shell never injected (the same reason login() reloads instead of flipping a flag) — and it answers null rather than false when the server cannot be asked, so a dropped request neither signs a user out nor sends them somewhere unverified.
  • /api/auth/password and /api/auth/revoke are implemented server-side but have no UI caller yet; the sign-out surface is likewise not wired.

Clone this wiki locally