The app as an operating system — the vault, the Kernel and Atlas

A Witbitz app is a static page, but inside the browser it is built the way an operating system is: separate realms, each holding one kind of thing, with walls the browser enforces — different origins, separate worker heaps — rather than the app's good behaviour. A bug or a malicious script in the part that draws the screen cannot reach the keys, because they are not in its realm.

The principle is least authority by information class: keys, the room graph, and what is on screen live apart, so a compromise of one exposes only its own class.

How anyone checks that the code in each realm is the published code: verifying the client.

The realms

Why origins, not discipline. One origin can intend to keep its keys away from its drawing code, but nothing enforces it — any script on that origin can read its storage. Putting the vault on its own origin makes the boundary the browser's same-origin policy: the app frame cannot read the vault's storage, and the vault cannot be framed by anyone.

Easier to audit

The structure also shrinks what a reviewer has to read closely. In an ordinary web app any of its code can read the keys, so an audit has to cover all of it, on every release. In the hosted app only the vault and the Kernel touch keys — the trusted core, kept small and changed rarely. The app frame, which is most of the code and changes most often, is checked for what it shows, not for what it could leak: the browser does not let it reach a key.

It is the same reason an operating system's kernel gets audited instead of every program: the guarantees rest on the small part. And because every file in every realm is pinned and logged (verifying the client), the audit applies to exactly the code that runs.

The vault

The vault is the top frame. It holds the account and its room keys, runs every ceremony that touches them — sign-in, recovery, the device lock — and frames the app with no key in the URL and none in the app's storage.

The two talk over a small postMessage protocol, pinned to each other's exact origin in both directions. The app asks for what it needs — open this room, run this turn — and the vault answers; it never hands over the account.

The vault also keeps what the app frame cannot: on iPhone the system drops a framed page's storage on every relaunch, so the app's settings are mirrored up to the vault and handed back at launch.

The Kernel

The Kernel is a Web Worker — a separate JavaScript heap with no access to the page's objects — that holds the keys in use and does all the room cryptography. The app sends it requests, not keys: poll this room, send this turn, read this state, seal this record. The Kernel opens what comes back, signs what goes out, and makes the request itself.

In the hosted app the Kernel runs inside the vault's origin: the app frame has no Kernel and no keys at all, only a channel to ask. (In the regular app, which has no vault, the Kernel runs in the app's own origin.)

The Kernel hands a key out only where the action is about the key: the share link of a room you just created, and a new key after you change a room's members.

Atlas — the room graph

The account's own records — which rooms you are in, their names, which private assistant belongs to which Space — are the room graph. They are stored in sealed account rooms whose entries also carry each room's key.

Atlas keeps those apart. When the account's index is read, the Kernel takes the keys out and the app receives a keyless graph; when the app writes the index, the Kernel puts the keys back. The app can list your rooms — it is the file browser, and may see the directory listing — but it never holds the keys that open them.

The account

The vault is where the account lives: the master secret every account key comes from, the sealed room list, and the recovery code and passkey that bring the account back on a new device. How an account is made, synced across devices, backed up and recovered — and what Witbitz can and cannot see of it: accounts and recovery.

Storage on the device

Each realm's storage can be sealed on the device: with device protection on, every key and every cached message is ciphertext at rest under a key the device's passkey derives, opened into memory only after an unlock and dropped at the next lock. Off by default; see privacy tiers.

Notifications get their own one-way key, derived from the room key, so the service worker can show a short preview without holding the room key itself.

Network

Each realm reaches the network only under its own Content Security Policy: the app frame, the vault and the Kernel can each reach only the hosts their published policy lists. There is no single gateway; the limit is per realm, enforced by the browser.

Build your own

The SDK's vault mode gives your app the same structure with your own vault: you host the vault and the page, Witbitz hosts neither, and secrets stay in the vault's screens — vault mode in the SDK.

Limits

• A worker is a separate heap, not separate memory. The Kernel's wall is as strong as what crosses it: no shared memory, no key returned except for the actions above.
• The app sees your room list. Names and structure are visible to the app frame; only the keys are confined. A separate Atlas worker that would hide the graph from the app too is designed, not built.
• The regular app has no vault. Its Kernel and screen share one origin, and the page itself also holds room keys. The hosted app is the one where the screen never holds a key.
• The regular app's service worker can still fall back to a room key on the device to show a notification; the hosted app's never holds one.

Next

• Verifying the client — the code in each realm is the published code
• Vault mode in the SDK · Privacy tiers · Trust model

Machine-readable source: app-os.md · Generated 2026-10-27T07:05:42Z · build f301388c · every doc in one fetch: llms-full.txt (HTML)