Where the keys live — the confidential tier, split keys and vault mode

By default a room's key is made in your page and kept there — in its link, and in whatever you save. Three choices change that: the confidential tier seals the key to a verified enclave for the room's turns, a split-key room leaves half of the key with your own server, and vault mode keeps every key out of your page.

Part of the SDK · every call: the reference.

The confidential tier

A confidential room's turns run inside an attested AWS Nitro enclave, and the room key is sealed to that enclave rather than handed to Witbitz's server:

const space = await wb.createSpace({ agent: { name: 'Vault' }, tier: 'enclave' })

• What the create does. It checks the live enclave's attestation first, makes the room, waits for the enclave, and gives it the room's sealed settings before any turn may run — so the first message already reaches the assistant you asked for. It takes longer than a plain create: it is waiting on real hardware.
• The build is checked, not advisory. If the enclave that answers is not a build Witbitz publishes, the SDK refuses to seal the room key to it and throws enclave_not_accepted rather than falling back. Treat that as "send nothing", not as a passing error.
• The published build is read from the viewer's origin (/enclave-claim.json); enclave_claim_unavailable means it could not be read, and a viewer of your own must serve it (or set enclaveClaim).
• The tier is chosen when a room is made; an existing room cannot be moved into it. How the tier works: the confidential tier.

What a room can prove

• await space.certificates() → { verified, failed, unchecked, before, builds, calls, tools }. In a confidential room every reply is signed inside the enclave with the build's measurement, each model call's verified receipt and each tool call. This checks the history loaded on the device: the attestation, the published audit verdict, each signature, and each reply's text. failed lists { id, reason }; unchecked counts replies whose attestation rides an earlier reply this handle has not loaded, which is not a failure. A standard room has none.
• await space.sealedProof(), in any room: what the server actually stores for it — the opaque, sealed history, its size and hash, and who can open it (never the operator). null before the first message. The Confidential Room example shows it live.

Checking an enclave with a standard token (EAT)

Witbitz's enclaves can prove themselves with an Entity Attestation Token (RFC 9711): a JWT signed by a key the enclave made, carrying the AWS Nitro attestation that binds that key to the enclave's measured build, for a nonce you choose.

import { fetchAndVerifyEat } from 'https://witbitz-spaces.pages.dev/sdk/3.10.0/witbitz-sdk.js'
const r = await fetchAndVerifyEat('https://agents.witbitz.chat/eat', { expectedPCRs: { 0: [/* the build you trust */] } })
// r.ok, r.claims (eat_profile, swname, …), r.doc.pcrs, r.userData.siri: the door's TLS key pin

• A token you already hold — one a peer gave you: await verifyEat(token, { expectedPCRs, nonce }) runs the same checks without the fetch. EAT_PROFILE is the profile the token must name.
• Where tokens appear. Every A2A lane's Agent Card names this endpoint (capabilities.extensions, uri https://witbitz.chat/eat/nitro-v1), so an outside agent can check it is talking to the measured enclave rather than take our word. A confidential reply's turn certificate is itself an EAT (certToEat), and the audit's verdicts are published as attestation results at /audit/<subject>.results.json.
• Without the SDK: node tools/eat-verify.mjs https://agents.witbitz.chat.
• The profile: an ES256 JWT; measurements: [[18, <the Nitro document, base64url>]] (COSE_Sign1); the document's nonce is eat_nonce, and its public_key signed the token; user_data carries the door's TLS key pin.

Split-key rooms

const wb = new Witbitz({ appShare: '/api/appshare' })   // your function, on your origin
const room = await wb.createSpace({ key: 'split', admission: { emails: [...] } })
room.shareLink   // …#us=<half a key>&spc=<commitment>: the link alone does not open the room

A split room's key is two halves. The link carries one; your function holds the other. The function seals its half under a key only you have (K_eco) before Witbitz stores it, and unseals it only for a page on your own origin. openSpace(link) fetches that half, combines the two, and checks them against the commitment in the link before using the key.

• Witbitz stores a half it cannot open: it never sees K_eco.
• A leaked link pasted into another website opens nothing, because a browser cannot fake its origin. A script can, so for an open room this is a policy gate; a gated room still needs an allowed sign-in on every operation.
• Deleting the room ends every link at once: the stored half goes with it.
• It does not hide the room from your own page, which puts the key together to use the room.
• The account backup keeps the whole key for split rooms, so a restore never depends on the stored half. A split room's lanes are split too, through your function.
• Limits: standard tier only for now (tier_mismatch otherwise). It is chosen per room; rooms without key: 'split' are unaffected.

Your function. Copy the template — appshare.js (a plain Request → Response handler), e2ee.js beside it, and the wrapper for your host (cloudflare-pages.js or node-express.js) — and give it two secrets:

• Back up K_eco. If it is lost, a split room opens only from a member's account backup.
• The function answers its own origin only, with no CORS header; rate-limit the route in your host. It answers { op: 'create', room, commit, appShare, … }, which seals the half and registers the room, and { op: 'get', room } → { appShare, commit }, which the SDK sends on open.
• Errors reach your code by name: cross_origin, no_appshare, appshare_unconfigured, unwrap_failed, and split_mismatch when the halves do not match the commitment. On the page, openSpace throws origin_not_declared, split_unopenable or split_mismatch.

If you cannot host a function, leave appShare out and name your tenant (new Witbitz({ tenant })). Witbitz then holds K_eco for your tenant — ask us to turn it on — and serves the half to your declared origins. Everything above holds except the first point: Witbitz could open the half. With neither, the create is refused (tenant_required, split_unavailable or seal_unconfigured) rather than making a room that cannot open.

Vault mode: no key in your page

In vault mode the room keys live in a vault: a small site you host on a second origin of your own (say vault.acme.com), which shows your app (app.acme.com) inside it. Your app uses the SDK as usual and never holds a key.

// your app page, served on app.acme.com and opened inside the vault
import { Witbitz } from 'https://witbitz-spaces.pages.dev/sdk/3.10.0/witbitz-sdk.js'

const wb = await Witbitz.inVault({ vault: 'https://vault.acme.com' })   // not_in_vault when not framed by it
const space = await wb.createSpace({ agent: { name: 'Assistant' } })    // the key is made in the vault and stays there
space.on('message', (m) => show(m))
await space.send('Hello')

await wb.vault.share(space)            // the vault shows the invite link, which carries the key
const rooms = await wb.vault.rooms()   // [{ room, title, at }]: no links
const again = await wb.vault.openRoom(rooms[0].room)
await wb.vault.signIn()                // the vault's sign-in screen; your page learns the email, never the token

wb.vault is a VaultSession: the vault's origin, what it said when the page connected (info), and these calls — also whoami(), signOut(), forget(space), showSiriKey() and on('rooms' | 'joined' | 'signedIn' | 'signedOut' | 'account', cb).

Building the vault

The vault is a kit you build once and host yourself; Witbitz hosts nothing for it:

curl -O https://witbitz-spaces.pages.dev/sdk/3.10.0/vault-kit.mjs     # Node 18+, no packages
node vault-kit.mjs ./vault --page https://app.acme.com/chat --vault https://vault.acme.com --tenant t_… --brand Acme

• It is checked. The kit builds from the release it came with and checks every file against that release's manifest.json. To check the manifest itself, pass its published hash, --manifest-sha <sha384-…> (the kit prints the one it read):

• What is yours, and what is not. The folder holds vault.js (your settings) and screens.js (sign-in, share and "didn't load" — restyle them or write your own; each is a plain function that resolves when the person is done), plus core/, everything that touches a key. Do not edit core/: a new run of the kit replaces only that folder, so your screens survive an upgrade.
• Serving it. HEADERS.md lists the headers to serve it with (nginx, Caddy, Apache) — among them Cross-Origin-Opener-Policy: same-origin, so a page that opens your vault in a window gets no handle on it — and your app page must allow the vault to frame it (frame-ancestors https://vault.acme.com). Declare both origins on your tenant (admin.origins): the vault makes the requests, so the server sees the vault's origin, and a room it creates is your tenant's.
• Invite links point at the vault (https://vault.acme.com/space?room=…#mk=…). The vault keeps the link, takes the key out of the address bar, and tells your page (wb.vault.on('joined', ({ room }) => …)).

What it protects, and what it doesn't

• Your page cannot read a key or keep one for later. The keys are in a worker on the vault's origin, and the browser keeps one origin out of another's memory and storage. A bug in your page, a compromised package or an injected script gets no key, no invite link and no sign-in token. Once a room is removed from the vault, the page cannot reach it. Signing out ends the page's access to gated rooms; an open room stays usable on that device until it is removed.
• What only the person can do, in the vault's own screens: remove a room (wb.vault.forget), sign out, join a room from an invite link, change a room's members or rotate its key, remove a room from the account, take or release a username, remove a connection, let a room's assistant use one, and make a new Siri key or turn the Siri inbox off. Your page can ask; the vault asks the person. The page learns the signed-in email (whoami, the signedIn event), and nothing else about the sign-in.
• Your page sees the conversation it shows. Vault mode keeps keys out, not content.
• You host the vault too, so it protects keys from your page's code, not from you.
• The settings the page reads carry no connection key or funding grant, and the page's settings writes cannot grant either: those go through the vault's own calls, after the person says yes.
• The vault answers only what an app needs: the room operations of a room it holds (read, send, rows, settings, approvals, reactions); creating a room (only the fields createSpace sends, at most 20 in 10 minutes); the room list; sharing; sign-in. A raw key operation, a destructive one, a key or identity passed in, or a room it does not hold is refused (vault_refused, not_in_vault, vault_unsupported, rate_limited). It answers only the page it framed, on its own origin, and the page cannot navigate the vault's window away (the frame is sandboxed without top navigation).

The SDK inside a vault

Everything the SDK offers works in a vault, except cloud computers. What differs:

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