Repository navigation
Security
Wijanarko Putra Rajeb edited this page Nov 15, 2026
·
3 revisions
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-foris 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, andSecurewhenever the request arrived over https — including through a proxy that setsx-forwarded-proto. Changing the password or callingPOST /api/auth/revokerotates 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 —
--tlsgenerates a self-signed certificate (SAN coveringlocalhost,127.0.0.1and 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--lanwarns 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.
-
The login screen is the app shell, not a page of its own.
Apprenders<LoginScreen/>whenever the client's auth store saysrequired, 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 singleonBeforeHandlethat covers every Elysia route, withisPublicPathnaming 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.tsreadsapp_settingseither 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 —presentationfeeds the first-frame style, the<html>attributes and<meta name="theme-color">, whilepublishedfeedswindow.__OMP_BOOTSTRAP__.appSettingsand is{}until the request carries a session. Gating BOTH onauthenticatedis 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: unauthenticatedGET /answersdata-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/androidand/api/updates/iosare 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 answered401to 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 realauthEnabled: trueinstall; the same console's unauthenticated/api/updates/androidwas401while/api/healthwas200). What they expose is a version and a public GitHub URL — the same data an unauthenticated browser reads off github.com./api/updates/desktopdeliberately STAYS gated: only the CONSOLE asks it (the desktop shells report their version over__kabmoDesktopand the sidebar compares it), and the console is behind the login.guard.test.tspins all three directions. -
A signed-in visitor asking for
/loginis answered302 → /, and that check sits BEFORE the public-path shortcut./loginmust 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 /loginwith the session cookie answers302 location: /on every boot, and200 text/htmlwithout one. -
A session's fingerprint binds to a DETERMINISTIC key, never to the argon2 hash.
issueSessionToken/verifySessionTokentake acredentialKey, andcredentialFingerprintisHMAC(sessionSecret, credentialKey)where the key isderiveCredentialKey(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 everybun --hotsave — measured: a token valid before a secondinitAuthcall 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 ownsaltoption 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, andrevokeAllSessionsrotates the secret — both kill every existing token, while a restart with the same password does not.auth.jsonstill holds only the secret: nothing on disk can enable authentication or reveal the password. Verified end to end: log in,SIGKILLthe server, boot it again with the sameKABMO_DATA_DIRand password, and the same cookie still reportsauthenticated: true. -
The client store flips on a 401 only OUTSIDE
/api/auth/(AUTH_PREFIX,src/client/hooks/ui/auth.ts). The bridge wrapswindow.fetchonce so 128 call sites need no auth awareness, but the auth endpoints answer 401 about the credential the caller just supplied —POST /api/auth/passworddoes 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 bysrc/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-awarecheckAuthState()would mount the workspace with the settings an unauthenticated shell never injected (the same reasonlogin()reloads instead of flipping a flag) — and it answersnullrather thanfalsewhen the server cannot be asked, so a dropped request neither signs a user out nor sends them somewhere unverified. -
/api/auth/passwordand/api/auth/revokeare implemented server-side but have no UI caller yet; the sign-out surface is likewise not wired.
Using Kabmo
How it is built
- Architecture
- Runtime and toolchain
- App shell and layout
- Chat stream and tools
- omp engine and settings
- Plugins, skills and automation
- Desktop integration
- Workspace panels
- Providers
- Harnesses
- Tool panels
Shipping it
History