Sealed Vault

A per-user encryption identity shared by every feature that seals content the server should only read while the user has proven presence. One lock (a passkey, a recovery code, or — only where no passkey can hold a key — a passphrase), one touch that opens every vault the person holds (see One vault), one bounded unlock window, and any number of consumers behind it — mail, AI chat, protected conversations and Drive's Private files seal server-custody content; the password manager and Drive's Fortress folders are client-custody consumers (their keys are unwrapped only in the browser). The vault owns the identity and the lock; each consumer owns what it seals and how it presents locked state.

Consumers register their hooks from a bootstrap file the vault loads lazily. Who consumes the vault is instance configuration, not a list in core: a plugin declares itself under vaultConsumer in its plugin.json, and a core consumer — Drive is one, since it has no plugin — in vault_consumers.json at the public_html/ root. See Registering a consumer, and Building a vault consumer for the developer-facing walkthrough.

The shape of it

Each user gets an X25519 keypair per scope (uev_scope). user is the server-custody scope, shared by mail, chat and every other consumer the server reads for while the member is present; every other scope is client custody. The public key is cleartext at rest — anything can seal to it, even while the user is offline. The secret key never touches disk unwrapped: it exists only as wrappings, one per enrolled unlocker (a passkey's WebAuthn PRF output, a recovery code, a passphrase), and is unwrapped only transiently into server RAM for the duration of an unlock window.

A passphrase only where no passkey can hold the key. A phrase can be guessed and phished where a tapped passkey cannot, so an account holds one only when Passkey::userNeedsPassphraseFallback() says every passkey it has is provably unable to derive a key (see When a passkey cannot hold the key). An account with a working passkey has no passphrase: a lost device is what the recovery codes are for. vault_passphrase_enroll, vault_client_setup and VaultCeremonies::setup()/rotate() refuse one otherwise, and a passkey unlock removes any phrase an account no longer qualifies for, telling the person why.

One unlock opens everything. A single passkey tap puts the account secret key in the window and, from the same touch, opens the root vault in the browser, which opens every browser-held vault (One vault); every server-custody consumer's VaultUnlock::secretKey() call sees it open at once. That is the UX win and the accepted cost: an attacker resident during an active window reads every consumer's in-window content, not just one — bounded by the idle timeout, seal-after-use, and key rotation. A consumer that needs genuine isolation declares a client-custody scope of its own and accepts that no server-side feature can ever read it; isolation with server readability is the one combination the platform does not offer.

One vault

(Design and decisions: specs/one_vault_experience.md.)

Two kinds of key stay two — the account vault (user, server custody, opened in server RAM) and the browser-held vaults (client custody) — but a person has one thing to unlock, one set of recovery codes, and at most one passphrase.

The root vault. root is a client-custody scope (vault_scopes.json) that every unlocker opens: each passkey's second PRF output from the same touch (prf.eval.second, context vault-root-kek), each recovery code's root half, and the passphrase's root half where one exists. A content vault (mail, drive, passwords, …; VaultScopes::contentScopes()) holds one root wrapping: its secret under `HKDF(root secret, 'joinery-vault:scope:v1:' + scope)`, derived only inside the root's keyring session (session.scopeKek(scope)), so each content vault has its own key and the root's secret never leaves its closure. VaultClientCustody::persistWrappings() enforces the split: the root takes only unlockers, and a content vault that opens through the root takes only its root wrapping. A content vault made before the root keeps its own unlockers (its rotation still writes them); it opens once by its own ceremony and is then given its root wrapping.

One touch. vault_unlock_options {with_root} asks for both PRF outputs. JoineryPasskeys.derive() takes the second out of the response it hands back, so the posted credential carries the first only, exactly as the server has always verified it; VaultCeremonies::assertNoSecondPrfOutput() refuses a response that still carries the second. The browser opens the root with the second output and every content vault through the root (JoinerySealed.openAllThroughRoot()). An authenticator that returns only the first output gets a second touch for the root alone (vault_client_prf_options {scope: root} — the same salt). A passkey that opens the account vault but has no root wrapping yet (it was enrolled before the root existed, or its wrapping is bad) asks once for another way in: a recovery code, the passphrase where one exists, or a passkey the root knows. The root was made on one device under that device's passkey, so on any other device the code is the way that is always there. The browser opens the root from its keyring view alone (VaultKeyring.openRootWith); nothing is posted, so the code is not used up and the recovery kill-switch does not fire. The root then learns the passkey from the output already in hand (vault_client_add_wrapping, no step-up for a passkey the account vault already has). A content vault set up before the root has no root wrapping, so the root cannot open it: the one unlock finishes by running that vault's own ceremony once more, with a line saying why, and JoinerySealed.session() then gives it a root wrapping, so the next unlock is one touch.

One set of recovery codes, never seen by the server. The browser makes the codes (VaultKeyring.makeCodeSet) and derives two halves from each, both salted by the root vault's salt: the account half `HKDF-SHA256(code, salt, 'joinery-vault:recovery:account:v1'), posted as code_set: {id, entries: [{index, kek}]}, and the root half SHA-256(salt ‖ code)`, which wraps the root's secret in the browser. Every wrapping from a set carries its id and the code's index (uew_code_set, uew_code_index) on both vaults. vault_unlock_recovery {code_kek} finds the account wrapping the posted half opens and, in one transaction, spends it and its root twin, returning the twin (root_wrapping) for the browser to open. A use also ends every window, stamps uev_recovery_time on every vault the person holds (a reload's resume half kept before it is refused — VaultClientResume::get()), and clears the vault keys of every linked device (VaultClientCustody::forgetDevices()). Setup, rotation, regeneration and the code-set adoption below always change both halves in one transaction: the root is created with the account vault (VaultClientCustody::createVault() inside VaultCeremonies::setup()), and its twins are replaced with the account's codes (VaultClientCustody::replaceRootRecovery()). The key file names the code salt and derivation (code_kdf), so a code plus the file still rebuilds the account key offline.

One passphrase. One Argon2id run over the phrase with the root salt and KDF params; HKDF splits the result into the account half (joinery-vault:passphrase:account:v1, posted as passphrase_kek) and the root half (…:root:v1, kept). What it costs, said plainly: a server that has been broken into holds the account half from the next passphrase unlock and can guess phrases offline; the same guess yields the end-to-end keys. For a passphrase account, end-to-end content is as strong as the phrase against a compromised server, and the passphrase form says so.

One setup. The Security page and the setup wizard make the account vault, the root vault and the codes in one step (VaultKeyring.setupVault(), over vault_setup_verify / vault_setup_passphrase with code_set and root). A content vault is created silently the first time a feature needs it while the root is open (VaultKeyring.contentSession()): a keypair in the browser and its root wrapping, nothing to set up and nothing to remember. A root vault is never created on its own beside an account vault (a second set of codes): createVault() refuses it.

An account vault whose codes carry no set id (codes the server made) gets a browser-made set, and the root vault, at its next passkey unlock: vault_unlock_passkey {adopt_code_set, root} opens under the tapped passkey with the new wrappings in its wrap list and creates the root in the same transaction (UserEncryptionWrapping::adoptCodeSet()); the padlock then shows the new codes once.

One name. Everything a person reads says "vault". The registry labels (vault_scopes.json, a plugin's vaultScopes) name each scope on the Security page's detail list and in logs.

Crypto core

includes/SealedBox.php — the asymmetric sibling of SecretBox, hard-requiring ext-sodium (no OpenSSL fallback; crypto_box_seal has none). Versioned, self-describing base64url blobs, same philosophy as SecretBox: fail closed, never return half-verified plaintext.

$box = new SealedBox();
$keypair = $box->generateKeypair();               // ['public'=>b64, 'secret'=>b64] X25519
$sealed  = $box->sealDek($bytes, $public_key);     // crypto_box_seal - anyone can seal
$bytes   = $box->openDek($sealed, $secret_key);       // public key derived from the secret
$blob    = $box->aeadEncrypt($plaintext, $key, $ad);   // xchacha20poly1305_ietf
$plain   = $box->aeadDecrypt($blob, $key, $ad);        // throws on tamper or AD mismatch
$wrapped = $box->wrapKey($secret_key, $kek, $ad);      // same AEAD primitive, wrapping a key
$secret  = $box->unwrapKey($wrapped, $kek, $ad);
$kek     = $box->kekFromRecoveryCode($code, $salt);    // crypto_generichash; the readiness dry run of a vault with no root vault
$salt    = $box->generateSalt();                       // a vault row's uev_salt
$code    = $box->generateRecoveryCode();               // 26 Crockford-base32 chars, >=128 bits, grouped

The server derives no KEK from a code or a phrase a person holds: the browser does, and posts only the account half (see One vault). includes/VaultUnlockerKdf.php writes those derivations out in PHP for the tests to build exactly what a browser sends; nothing in production calls it.

$account = VaultUnlockerKdf::codeKekAccount($code, $root_salt_b64);  // HKDF-SHA256, info joinery-vault:recovery:account:v1
$root    = VaultUnlockerKdf::codeKekRoot($code, $root_salt_b64);     // SHA-256(salt ‖ code) = VaultCrypto.kekFromRecoveryCode
[$a, $r] = VaultUnlockerKdf::passphraseSplit($argon2id_output);     // HKDF per half
$kek     = VaultUnlockerKdf::scopeKek($root_secret, 'mail');         // a content vault's key from the root

includes/VaultCrypto.php names the per-item envelope-encryption dance every consumer repeats, thin over SealedBox:

$crypto = new VaultCrypto();
$key    = VaultUnlock::secretKey($user_id);              // ?VaultKey — null means locked
$dek    = $crypto->newItemDek();                        // random 32B, one per content item
$sealed = $crypto->sealItemDek($dek, $key->publicKey()); // store on the consumer's own row
$dek    = $crypto->openItemDek($sealed, $key);           // one row; memoized per key id + blob
$deks   = $crypto->openItemDeks($sealed_list, $key);     // a page of rows in ONE VaultKey::unseal()
$blob   = $crypto->sealField($plaintext, $dek, $ad);     // $ad is the CONSUMER's row-binding string
$plain  = $crypto->openField($blob, $dek, $ad);          // e.g. 'mail:{message_id}:body_plain'
$crypto->sealFieldFile($src, $dst, $dek, $ad);           // whole FILE, path-to-path, memory bounded
$crypto->openFieldFile($src, $dst, $dek, $ad);           //   by a chunk (SealedBox v1.stream. format)

The AD (additional data) is entirely the consumer's convention — a stable per-item identity string. Binding it means a ciphertext can never be spliced onto a different row and still decrypt.

A vault key is used, never read. VaultUnlock::secretKey() returns a VaultKey (includes/VaultKey.php): unseal(array $sealed) opens crypto_box_seal ciphertexts sealed to its public half, publicKey() is that half, and id() is a stable non-secret identity the DEK memo keys on. There is no getter for the bytes and no wrap method. PoolVaultKey is the implementation that holds the bytes in PHP; the SealedBox primitives that take or produce a vault secret (openDek, openBinary, unwrapKey, wrapKey, generateKeypair) are pinned to that one file by tests/vault/sealed_read_paths_test.php, so a consumer cannot reach the raw secret by any path the tree contains. Wrapping the secret under a new unlocker happens only inside VaultUnlock::open()/openKey(), in the request that presented an unlocker for it.

Key hierarchy

• uev_user_encryption_vaults (UserEncryptionVault) — one row per (user, scope): uev_public_key (cleartext), uev_salt (the current generation's KDF salt for the recovery/passphrase unlockers), uev_custody (server for mail/chat; client for the browser-only password/Drive scopes), uev_key_generation.
• uew_user_encryption_wrappings (UserEncryptionWrapping) — one row per enrolled unlocker: uew_unlocker_type (passkey/recovery/passphrase), uew_wrapped_secret_key (AEAD-wrapped, AD = vault:{vault_id}:{wrapping_id} via UserEncryptionWrapping::adFor()), uew_salt (the KDF salt this wrapping's KEK was derived under — recovery/passphrase only, null for passkeys — so a rotation replacing uev_salt never strands a live wrapping), uew_key_generation (which generation's secret it wraps), uew_is_used (recovery codes are one-time), uew_delete_time (soft delete retires a wrapping).

Neither table is an API resource; consumers never touch them directly.

Every account holds one; using it is optional

Holding a vault and using a vault are separate things. A vault that seals nothing costs its holder nothing, so the setup wizard's encryption_key step is mandatory and offers no decline — an estate where every account already holds a key needs no capability check before offering a private folder, a sealed mailbox, or a protected conversation.

Two conditions stand between an account and a vault, and code that assumes universal vaults must still handle them:

• No PRF-capable passkey. Passkey::vault_capability() answers incapable for an authenticator that cannot derive a secret. See the fallback below.
• No account password. vault_setup_options refuses with requires_password, because a vault holder keeps password sign-in as the second door.

• Mail is stored unsealed — readable to anyone who can reach the database or a backup archive.
• No private Drive folders (logic/drive_folder_create_logic.php refuses) and no saved passwords (the keyring is sealed under this key).
• No encrypted chat. A conversation cannot be raised to Private while any member holds no vault — Conversation::members_without_vault() names them, so one member without a key caps the whole conversation.

When a passkey cannot hold the key

(Rationale and the rejected alternatives: specs/vault_passphrase_fallback.md.)

PRF is a narrower requirement than passkey support: iPhones before iOS 18, Windows 10, older Firefox, older Android and most security keys enrol a passkey happily and then cannot derive a secret from it. For those accounts a vault is bootstrapped under a passphrase instead, with no TYPE_PASSKEY wrapping at all; the same phrase opens the root vault (One vault).

This is a compatibility fallback, never a preference. A phrase can be guessed and phished where a tapped passkey cannot, so an account that could use a passkey must:

• Passkey::userNeedsPassphraseFallback() is the single gate: the account holds at least one credential *and every one of them is provably incapable. The count requirement closes the owning-nothing route: an account with no credentials at all is not eligible, so deleting your passkeys is not a way to opt into weaker crypto.
• The failure stamp comes only from a verified ceremony. PasskeyService::verifyDerivation() stamps pkc_prf_failed_time after the assertion checks out, never before, so a forged request cannot mark someone else's credential incapable. A later success clears the stamp — a firmware or OS update can make a credential capable. The stamp is one of two evidence sets: registration-time signals alone can also prove a credential incapable, and must, since a U2F-only key cannot pass a UV-required assertion and so could never earn a stamp.
• The trust boundary of that evidence is the client. The assertion signature covers the authenticator data and the client data hash; clientExtensionResults — where the PRF output travels — is assembled by the browser and unsigned, and registration-time signals are client-reported too. Remote proof that a credential cannot derive does not exist in WebAuthn, so capability evidence is best-effort against accident, not against a client that lies about its own account. Where signed corroboration exists it is used: a CTAP authenticator that evaluated PRF carries the hmac-secret output inside the signed authenticator data, and a missing client result is not stamped when that shows an evaluation happened. The backstops for a wrong stamp are the ceremony gate, the step-up on minting, and the clear-on-success rule.
• VaultCeremonies::setup() re-asks the same question before writing a passkeyless vault, and requires a phrase when it does. The gate is in the ceremony, not in the page that hides the button, so no other caller can route around it.
• logic/vault_setup_passphrase_logic.php is the only action that reaches this path.

Which passkeys a vault prompt offers is one rule, shared by every ceremony above and by unlock and rotation: VaultUnlock::offerableCredentialIds($user_id, $scope) returns the credentials holding a wrapping for that scope's vault; if none do, this is an enrollment, so it returns everything except the credentials known to be incapable of ever deriving a secret. The two halves answer different questions and the first is much the stronger: which credentials hold a wrapping is a stored fact about this vault, so unlock and rotation — the paths where a wrong answer means someone cannot reach their own sealed content — never consult capability at all. A partially-rotated vault holds wrappings across generations and the offer is their union. Client- custody scopes need no special case: the server cannot read those KEKs, but it does store each scope's wrapping rows tagged with the credential id, so it knows which credentials unlock a scope without knowing what they unlock. An empty result means "no opinion" and offers every live credential — never nothing, since an empty allowCredentials on the unlock path is a lockout.

Adding an unlocker is the exception: vault_add_passkey_options takes a credential_id and scopes the ceremony to that one passkey, because the browser otherwise decides which credential answers — pick the security key's row, tap Touch ID at the prompt, and Touch ID would get the wrapping while the row that was clicked still read Not activated. vault_add_passkey_verify echoes the credential id and label it actually activated, so a caller that forgets to scope cannot activate one silently.

The unlock window

includes/VaultUnlock.php — the secret key lives in APCu, keyed vault:{session_id}:{user_id}:{scope}, TTL = vault_unlock_idle_minutes (default 30), re-stored on every read (activity extension). What callers hold is a VaultKey, never the bytes:

// $unlocker = $wrapping->unlocker($kek) — the row's wrapping, the KEK the
// credential derived, the row's AD; null mints a fresh keypair (setup, rotation).
// $wrap_under = [$row->wrapEntry($kek), ...] — the wrappings to produce.
VaultUnlock::open($user_id, $unlocker, $wrap_under = [], $scope = 'user', $caps = null, $via)
    : array{key: VaultKey, wrappings: string[]};          // opens AND arms the session's window
VaultUnlock::openKey($user_id, $unlocker, $wrap_under = [], $scope = 'user'): array;  // the key, no window
VaultUnlock::arm($user_id, VaultKey $key, $scope = 'user', $caps = null, $via): void;  // make it the window
VaultUnlock::isOpen($user_id, $scope = 'user'): bool;
VaultUnlock::secretKey($user_id, $scope = 'user'): ?VaultKey;  // null = locked
VaultUnlock::close($user_id, $scope = 'user'): void;         // current session
VaultUnlock::lock($user_id, $session_id, $scope = 'user'): void;  // a specific session
VaultUnlock::lockAll($user_id): void;                        // every scope, every session
VaultUnlock::hasAnyOpenWindow($user_id, $scope = 'user'): bool;  // ANY session, any SAPI

openKey() exists for the two callers that need a key without a window: the rotation ceremony, whose old-generation key every resealer uses and which must never become the window, and the recovery-code / passphrase probes (and the recovery-readiness dry run), which try each wrapping until one opens. A wrong unlocker throws and yields nothing.

Every content read calls secretKey() and treats null as locked — a one-tap unlock prompt, never an error; code that only asks whether the window is open calls isOpen(). lock()/lockAll() are the generic wipe surface; when to call them (explicit lock, a credential event, a heartbeat/IP-change policy, a permission cap) is entirely consumer-defined.

hasAnyOpenWindow() answers "does any session hold a window for this user" for a consumer's passive-close sweep (e.g. reclaiming /dev/shm working copies from cron). Its signal is a secret-free marker file (/dev/shm/vault_window_{user_id}_{scope}, mtime = the window's current expiry, stamped by open()/secretKey()), NOT APCu — a CLI cron process has its own APCu segment and can never see the web workers' entries, but every process on the host sees /dev/shm. A single-session lock() leaves the marker (another session may still hold a window); it expires with the idle TTL, so a sweep is at worst delayed one interval, never wrong about an open window. lockAll() removes the user's markers outright.

Unlock endpoints (logic/vault_unlock_options_logic.php and its vault_unlock_passkey / vault_unlock_recovery / vault_unlock_passphrase siblings, plus vault_lock) mint the WebAuthn PRF assertion options with userVerification: required (PasskeyService::getDerivationOptions()) — every passkey unlock demands device user verification, not merely preferred. The recovery code and the passphrase each open the vault on their own, from the account half the browser derived (code_kek, passphrase_kek). The account's sign-in second factor never takes part in opening a vault: an authenticator code confirms sign-ins and sensitive changes, and opens nothing.

Host hardening

includes/VaultHealth.php checks the four facts that keep an unwrapped secret key off disk even during a live window:

• APCu backed by anonymous shared memory (apc.mmap_file_mask unset).
• The PHP worker's core dumps disabled. rlimit_core = 0 in the pool is the whole answer only when kernel.core_pattern names a file. When it pipes to a handler the kernel ignores the rlimit: Ubuntu's apport reads the entire core into its /var/crash report, so the check is unmet while apport is enabled (sudo systemctl disable --now apport, and enabled=0 in /etc/default/apport — on the host, since core_pattern is not namespaced and a container reads the host's). systemd-coredump honours the rlimit; any other handler reports unknown, naming it.
• Exception traces omit their arguments (zend.exception_ignore_args = On). The secret key is a string argument on the VaultCrypto open methods, and with it off a logged uncaught exception carries the key's leading bytes.
• Swap off, or every active swap device encrypted. The device-mapper type is read from /sys/block/dm-N/dm/uuid: CRYPT- is dm-crypt and verified, LVM- is a plain volume and unmet. zram is accepted (compressed RAM, no disk without its writeback feature). The installer's housekeeping creates 1 GB of swap as dm-crypt with a per-boot random key.

File::registerDecryptHook(File::SOURCE_EMAIL_ATTACHMENT, function (string $ciphertext, File $file): string {
    $key = VaultUnlock::secretKey($file->get('fil_usr_user_id'));
    if ($key === null) throw new VaultLockedException();
    // ... $crypto->openItemDek($sealed_key, $key), then the AEAD blob, return plaintext bytes
});

File::registerStreamingDecryptHook('drive', function (File $file, $size_key = null) {
    return $file->is_sealed() ? new DriveSealedStream($file, $size_key) : null;  // null = stream unchanged
});

The opener is handed the size key being served — 'original' or an image variant — because a consumer's integrity checks differ between the two: a file's row records the plaintext size of its original and knows nothing about a variant's. A caller that cannot say passes null, which means unknown, never original.

The decryptor answers three questions: prepare($path) acquires the in-window key (and throws VaultLockedException if there is none), plainSize($path) reports the plaintext length, and stream($path, $sink, $offset, $length) decrypts a span. serve_from_path() resolves the key before writing any header — so a locked vault is a clean 423 — then advertises `Accept-Ranges: bytes` and serves 206 against plaintext offsets. Whole-file content should use this shape; the whole-bytes hook above suits small sealed attachments.

Blob-only sealing — a consumer whose ciphertext lives entirely outside the database declares no $sealed_fields at all. It still needs the four sealing columns, and records its key with `SystemBase::recordSealedKey($row_id, $vault, $dek)`, which wraps a key the consumer already minted (a file's bytes have to be sealed before the row that will point at them exists) rather than minting its own the way sealColumns() must. Such a row is still sealed: save() protects its key wrapping exactly as it does for a column-sealing model.

Sealed-field model hook — a model declares which columns hold protected content and adds four columns. That is the whole integration: no crypto code, no key handling, no AD string of its own.

class MailboxContact extends SystemBase {
    public static $sealed_fields = ['imc_address', 'imc_display_name'];

    public static $field_specifications = [
        // ... the content columns above, declared 'text' (base64 + AEAD
        // overhead outgrows any varchar cap), plus:
        'imc_content_sealed'       => ['type'=>'bool', 'is_nullable'=>false, 'default'=>false],
        'imc_sealed_key'           => ['type'=>'text', 'is_nullable'=>true],
        'imc_sealed_owner_user_id' => ['type'=>'int8', 'is_nullable'=>true],
        'imc_key_generation'       => ['type'=>'int4', 'is_nullable'=>false, 'default'=>0],
    ];
}

Sealing is per row, not per model

The flag lives on the row because sensitivity does. The same table holds sealed and plaintext rows side by side — a Private domain's mail and a Standard domain's mail are the same model — and only the row knows which it is. A row with {prefix}_content_sealed false reads and writes as ordinary plaintext and costs nothing.

Many readers: the one variation on the shape

Every model above seals to a single owner, whose wrapping lives on the row. A conversation has many readers, so the messenger varies exactly that one part and nothing else (docs/social_features.md § Protection levels): the key is wrapped once per participant in ckg_conversation_key_grants, Message overrides decryptSealedFieldStatic() to resolve it through whichever present participant's grant opens, and the row's own wrapping columns stay null. Everything else is the shipped machinery — sealColumns() with a supplied key writes the ciphertext, save() leaves a sealed row's content columns alone, a closed window is VaultLockedException, and rotation re-wraps grants without rewriting a single message.

A consumer with the same shape (several people reading one item) should copy that arrangement rather than inventing a third. A consumer with one owner should not: the generic path is less code and less to get wrong.

Reading

SystemBase::get() decrypts automatically whenever the requested key is in $sealed_fields, which covers ordinary field access and everything built on it (export_as_array(), export_for_api()). ModelQueryExecutor (the AI query_model tool's raw-row reader) calls decryptSealedFieldStatic() on a raw associative row instead, since it never instantiates the model. Both paths run the same implementation, so they cannot drift apart.

A locked vault raises VaultLockedException — never a return of ciphertext, which would look like data. At the edges that becomes a 423 Locked response (File hook) or a [locked - unlock your vault to view] placeholder (the raw-row path, so an LLM sees a legible state rather than a stack trace).

Writing

save() seals. A consumer writes its content the way it writes anything else:

$note = new AcmeNote(NULL);
$note->set('acn_usr_user_id', $user_id);
$note->set('acn_body', $body);
$note->save();          // sealed

set() records which sealed columns the caller supplied, and save() lifts exactly those out of the ordinary column build and seals them once the row id exists. Everything that can fail — resolving the owner, finding their vault, recovering an existing row's key — happens before any SQL runs, and the insert and its seal share one transaction, so a save either seals or changes nothing.

Whether a row seals is a per-row policy decision. The default is seal when this row's owner has an active vault, which is right for a consumer whose premise is that its content is private and needs no declaration. A consumer whose policy is dynamic — a per-domain security level, a per-conversation setting — overrides one method:

protected static function shouldSeal(array $row): bool {
    return $row['acn_visibility'] === 'private';
}

Ownership resolves through sealedOwnerUserIdFor(), falling back to the conventional {prefix}_usr_user_id column — which the consumer sets on the row anyway, and is why the write path needs no vault lookup of its own.

Create works offline; updating sealed content needs the window. That asymmetry is the crypto, not the API: sealing needs only the owner's public key, so any process can seal to a member at any time — an ingest path writes into a locked vault and there is never a reason to store protected content in the clear because "the window might close". Reusing an existing row's key means unwrapping it, which needs the secret, so a sealed-column update against a closed window raises VaultLockedException, exactly as get() does.

That asymmetry is what lets an unattended job add protected content to something that already exists. Mail attachment adoption is the worked example: a message ingested over IMAP holds only references to its attachments, and an archive import that later turns up the real bytes stores them — sealed, in cron, with nobody signed in. It can only do that because the bytes go into a self-sealed File carrying its own key wrapped to the owner's vault, the same shape Drive uses, rather than borrowing the message's DEK (which would mean opening it, and so needing a window). Per-file keys also mean the existing Drive reseal sweep re-wraps them on rotation with no new code — the sweep selects on fil_content_sealed and the generation, deliberately not on fil_source.

An update reuses the row's existing key rather than minting a fresh one. Minting would rewrite the wrapping and orphan every sealed column the update did not itself rewrite. Whether the row is sealed is the database's answer, not the instance's: sealColumns() writes with a targeted UPDATE that never touches an already-loaded instance, so "loaded before the row sealed" is an ordinary state (a deferred ingest, another request), and a save that trusted its own stale flag would mint over the live wrapping. For the same reason save() treats the seal flag and wrapping columns as owned by the sealing path on a sealed row — a stale instance's false/NULL copies are never written back.

A first-time seal of an existing row seals the whole row, not just the columns the edit touched. A row created plaintext (its owner had no vault yet, or the policy declined) and sealed later must not end up half-and-half: plaintext in a sealed column of a sealed row is leaked at rest and an exception on every later read, so every populated $sealed_fields column is lifted into that first seal.

Null clears; non-scalars are refused. Setting a sealed column to null (or '') stores the empty value bare — never an AEAD blob of nothing — so `IS NULL` queries stay honest and reads return the same shape a plaintext model would. An array or object value throws: a silent string cast would durably seal the literal "Array". Encode structured values to a string before set(). The write path also honors sealedFieldIsActive(), the same per-row predicate the read path checks: a column that is metadata on this row travels the ordinary column build in the clear, because sealing it would hand later readers the raw blob as data.

$seal_on_save = false opts a model out, for a consumer that owns its own sealing path — one that seals blobs under the same key, or decides in code that predates this. Those call sealColumns() directly:

MailboxContact::sealColumns($contact_id, $owner_vault, [
    'imc_address'      => $address,
    'imc_display_name' => $name,
]);

It mints the row's DEK, wraps it to the owner's vault public key, seals each value, sets the flag and writes one UPDATE — returning the raw DEK so the caller can seal related blobs (attachments, raw messages) under the same key. Pass a DEK as the fourth argument to re-seal under an existing one, which leaves the key wrapping untouched and keeps anything already sealed beside it readable. The row must exist first: the AD binds every value to the primary key. On such a model save() skips the $sealed_fields columns entirely on a sealed row, so an ordinary metadata edit cannot write decrypted content back into them.

The override surface

Two hooks, for the cases the defaults cannot answer:

• sealedOwnerUserIdFor($row) — whose vault this row opens against. The default is the owner recorded at seal time, which is immune to later membership changes. Override for an indirect owner (chat resolves through the conversation) or a fallback for rows sealed before the column existed.
• sealedFieldIsActive($field, $row) — whether a column holds content on this particular row. Override where a column is content on some rows and metadata on others: an inbound message's recipient is the routing alias, written in the clear, while an outbound message's recipient is a real address list.

"bootstrap": "includes/bootstrap.php",
"vaultConsumer": {
  "order": 20,
  "reseals": true,
  "caches": true
}

   VaultUnlock::onReseal(VaultUnlock::modelReseal([
       MailboxContact::class,
       MailboxMessage::class,
   ]));

1. Register a wipe callback if you keep any disposable in-window cache (VaultUnlock::onWipe()), e.g. a plaintext search index, and declare caches: true.
2. Own your own levels, scope, and locked-state surfaces (list placeholders, a content-action unlock prompt, a native locked flag) — the vault provides everything below the content. Run web unlock/lock ceremonies through JoineryVaultLock and listen for the two lock-chip events (see The lock chip) so your surface and the chip stay in one state.

VaultUnlock::onWindowCaps(
    function (int $user_id): array {
        return ['idle' => 7200, 'absolute' => 86400];
    },
    ['idle' => 7200, 'absolute' => 86400]   // contributed instead if the provider throws
);

VaultDeferredWork::register(
    'mailbox_parse',
    fn(int $user_id) => bool,                                   // cheap, indexed, no decrypt
    fn(int $user_id, VaultKey $key, float $deadline) => int      // work until the deadline
);

A client-custody scope (uev_custody = 'client') is unwrapped only in the browser — the server never holds the secret key and never sees plaintext. Everything a consumer needs lives in core, so a consumer writes no crypto, no ceremony and no session code:

• assets/js/vault-crypto.js — the browser crypto module: WebCrypto AES-GCM/X25519, the vendored hash-pinned Argon2id WASM for the passphrase KDF, KEK derivation (passkey PRF / recovery / passphrase), wrap/unwrap of the vault secret key, ECIES seal/open of a data key, and encrypt(str, key, ad?) / decrypt(blob, key, ad?). selfCheck() proves this engine and the server agree on the bytes (the shared vector in tests/vault/fixtures/edge_vector.json).
• assets/js/vault-keyring.js — VaultKeyring.ensureUnlocked(scope, opts), the one ceremony: setup (then the recovery codes), unlock, or nothing.
• assets/js/joinery-sealed.js — JoinerySealed: opening and sealing rows, the per-scope session and its lock, and key rotation.
• includes/VaultClientCustody.php + the core logic/vault_client_* actions — opaque-blob storage: the keypair record, the keyring view, add/remove/replace unlocker wrappings, consume a one-time recovery key (which emails the account — the server can't verify code knowledge, so visibility is the defense against a session-rider burning codes).

"vaultScopes": {
  "passwords": { "custody": "client", "label": "Password vault" }
}

protected static function sealScopeForWrite(array $row): string {
    return $row['acn_end_to_end'] ? 'acme_notes' : 'user';
}

A second, narrower door adds fields to a row the browser already holds the key to*: SystemBase::acceptBrowserSealedFields($row_id, $fields), for content the browser derives from a row it opened (an AI verdict on Fortress mail). It takes column => v1.edge. ciphertext sealed with the row's own DEK under the row's AD, and only for columns the model lists in $browser_appendable_fields (mail: iem_ai_summary, iem_ai_scan), which must also be $sealed_fields. It requires the row's stored key to be v1.edgeseal.{scope}. for a client-custody scope (a row lowered to a server scope is the server's to write), lets the model refuse for a reason of its own (browserAppendRefusal(): a mail row still awaiting its browser parse), and writes those columns and nothing else. The row's key, generation and owner stay as they are, so a value appended during a pending rotation still opens after the rotation commits. Authorization is the caller's, as above.

Moving rows between custodies

A row changes custody when its sealScopeForWrite() answer changes (a mailbox raised to Fortress, or lowered from it). The DEK never changes, so anything else sealed under it (a consumer's files) stays addressable; only the fields' format and whose key wraps the DEK move.

• The raise is the server's, row by row in the owner's window: SystemBase::convertRowToClientCustody($row_id, $old_key, $scope_vault) opens the DEK with the server key, re-encrypts every populated sealed field into v1.edge. under the same DEK and AD, seals the DEK to the client vault's key (the pending one during a rotation), and writes fields, key, generation and owner in one UPDATE. It refuses a row not sealed, one already under a client-custody vault, a vault that is not client custody or not the owner's, and a scope the row's hook does not name, and returns the DEK so the consumer can re-encrypt its own blobs.
• The lowering is the browser's, since only it opens the DEK. JoinerySealed.changeCustody(scope, {progress, reason}) walks vault_custody_rows (VaultCustodyChange::page(): the caller's rows of the models clientReseal() registered for the scope, whose hook now names another vault, each with that vault's public key), opens each DEK with the scope's session, seals it to the target key and posts vault_row_custody. SystemBase::acceptBrowserCustodyChange() checks the row is the caller's, under a client-custody key, that its hook names another vault and that the key is sealed to exactly that one; with the owner's server window open it also opens a field with the key first, so a wrong key never replaces a good one. The UPDATE is conditional on the key it read. A moved row is not listed again, so the walk resumes wherever it stopped. The row is left with a v1.edgeseal.user. key and its v1.edge. fields (see Reading on the server). browserCustodyPage() asks the hook of every row the scope holds. Its count, browserCustodyBacklog(), is null unless a model overrides it: a model with many rows overrides both with SQL that states the hook's rule (mail does), and the walk's first page carries remaining only when every model can count.
• Rotation. A server rotation re-seals a lowered row's key into v1.seal.; resealRows() leaves a row under a client-custody key to the browser's rotation.

The browser side

const note = await JoinerySealed.open(rowFromApi, refetch);   // plaintext fields, or an unlock prompt
await JoinerySealed.save('acme/note_save', values, { scope: 'acme_notes', sealedFields: ['acn_title', 'acn_body'] });

• open(row, refetch, opts) — a plain row resolves as is; a server-custody row with content_locked runs JoineryVaultLock.unlock() then resolves refetch(); a row with sealed_scope opens sealed_dek with the scope's session and decrypts every v1.edge. field. Opened values are cached per scope session and dropped on lock.
• seal(scope, id, adPrefix, values) — mints a DEK, seals it to the scope's public key (no unlock needed; a scope not set up runs setup) and each field under its AD. Empty values stay bare.
• save(action, values, opts) — the two-step write as one call: posts values minus opts.sealedFields to action, reads id and sealed_ad_prefix from the reply, seals, and posts {id, sealed_dek, fields} to the same action.

The ceremony

JoinerySealed.session(scope) opens a content vault through the root (One vault): with the root shut it runs the one unlock (JoineryVaultLock.unlock()), then opens the vault with its root wrapping, or creates it silently when it does not exist yet. There is no separate setup and no separate prompt per vault. A person with no vault is sent to their Security page, where the account vault, the root and the codes are made together.

VaultKeyring.ensureUnlocked(scope, opts) remains for a content vault that holds unlockers of its own and no root wrapping: it reads vault_client_status and runs the unlock inside one JoineryModal, offering only what that keyring has; the session is then given its root wrapping, so it is the last time. opts.reason reads in the prompt ("You need it to open this file").

Sessions and the lock

JoinerySealed holds one session per scope per tab, the root's among them (session(scope) runs the ceremony on a miss; adopt(scope, session) holds one the lock chip's unlock opened) and never hands out key bytes: a session opens and seals, it cannot reveal. Every open scope locks together after vault_client_autolock_minutes without keyboard or pointer activity (a person's own choice for this browser overrides it).

Reloads reopen. A scope stays open across a reload, or a move to another page, in the same tab. When it opens, its secret is wrapped (`AD vault:{scope}:resume) under HKDF-SHA256(server half ‖ tab half, info 'joinery-vault-resume:v1:{scope}')`, two random 32-byte halves. The tab keeps the wrapped secret and its half in sessionStorage; the server keeps the other half in the sign-in's PHP session (vault_client_resume, includes/VaultClientResume.php, keyed by scope and a random per-tab id). Neither half opens anything alone, and shares are never logged. At load JoinerySealed.ready settles once every scope the tab had open has reopened (joinery:vault-scope-unlocked with detail.resumed) or been given up — a stored public key a rotation retired, a tab idle past its limit, a session that ended. session() waits for ready, so a page never runs a ceremony for a scope that is about to reopen; a consumer deciding a scope is shut waits for it too.

pagehide drops only the in-memory key, and a back/forward-cache restore (pageshow with persisted) drops it and reopens through the halves — a restored page never shows plaintext with a key it did not re-derive. Every other lock is real and forgets both halves. Closing the tab loses the tab's half; signing out loses the server's. A new tab asks once.

JoinerySealed.lock(scope) / lockAll() are the explicit entries; onLock(scope, fn) registers a callback and document receives joinery:vault-scope-locked. Core drops the session and its cache of opened values. The consumer owns wiping its own DOM and caches: decrypted names written into elements, raw key bytes it kept, inputs and detail panes, object URLs.

Rotating a client-custody key

Only the browser holds the secret, so only the browser can rotate it (JoinerySealed.resealScope(scope)). Every linked device must re-link afterwards (it holds the old secret). What else it costs depends on how the vault opens:

• A content vault that opens through the root (every one made since the root exists; VaultClientCustody::opensThroughRoot()) costs nothing more than the root being open. The new key takes one root wrapping, made with the root's scopeKek(scope), and nothing else; the root's passkeys, phrase and codes are its way back in and do not change. The Security page lists these vaults under Vault Keys (VaultClientCustody::throughRootVaults()), since they have no recovery card of their own. A vault made before the root and since given its root wrapping rotates the same way: the passkeys and codes it kept of its own open only the old key and retire with it. The browser proves the new wrapping before it is sent, and again from the stored copy (opened through the root, as the next page will) before anything moves onto the new key. A committed rotation leaves the new key open in the tab.
• A vault with unlockers of its own costs new recovery codes (the browser never held the old ones), the passphrase again if there is one, and one passkey tap per enrolled passkey. Its recovery card offers it.

1. vault_client_rotate_begin stores the new public key and its wrappings as generation N+1, pending. The key in use and all its unlockers keep working; changing its unlockers is refused meanwhile. It needs a recent step-up; the browser asks first with dry_run, before collecting any passkey tap or the passphrase.
2. The batch moves every sealed DEK onto the new key: rows of the models a consumer registered through vault_client_reseal_rows (only rows still on generation N) and vault_row_reseal (key column and generation only, the caller's own rows, the blob's scope must be the row's), then each consumer's JoinerySealed.onReseal(scope, fn) hook for keys kept elsewhere.
3. vault_client_rotate_commit — refused while any registered row is left on generation N — retires generation N's wrappings, makes the pending key the key, and takes the scope off every linked device (sde_vault_scopes). Any key a hook skipped is named in the result.

VaultUnlock::clientReseal('acme_notes', array(AcmeNote::class));                  // models
VaultUnlock::clientReseal('passwords', array(), array('plugins/vault/assets/js/vault-reseal.js'));  // a hook

and declares "client_reseals": ["acme_notes"] in its vaultConsumer block. A hook script registers JoinerySealed.onReseal(scope, async ctx => …), receiving {oldSession, newSession, newPublicKey, progress, skip}; it must be safe to run twice (a key the new session opens was moved already), and a key neither session opens — unreadable before the rotation too — is left and reported with ctx.skip() rather than holding the rotation back. Drive re-seals its FileKeyGrant rows through drive_key_grants_reseal (the member's own grants only, only while a rotation is pending); the password manager its store key through vault/keyring_replace (accepted only while a rotation is pending; keyring_save stays create-only).

A consumer that publishes a scope's sealing key somewhere else hears the rotation through `VaultUnlock::onClientRotation($scope, fn(int $user_id, string $phase)), called with 'begin' and 'commit'` once each is stored; a listener that throws is logged and changes nothing. The mailbox uses it to push the relay routing map for mail.

A consumer whose published key something may still be sealing to can hold the commit back: `VaultUnlock::onClientRotationCommit($scope, fn(int $user_id): ?string)` returns null to allow it, or the sentence the person sees; a guard that throws refuses. The commit asks every guard before it retires anything. The mailbox's guard waits until the relay has accepted the map that names the new key and a pull has since read the relay's whole listing, so no mail sealed to the old key is still on the relay when that key retires.

While a rotation is pending, new material seals to the pending key (UserEncryptionVault::sealingPublicKey()): the server sealer, the keys drive_public_keys hands out, and JoinerySealed.seal() all use it, and a browser write names the key it sealed to (acceptBrowserSealed(..., $public_key)) so the row is stamped with that key's generation. Nothing sealed during the rotation is left on the key the commit retires.

The one rotation an operator may discard is a through-root one whose stored wrapping failed the browser's proof: the browser moved nothing onto that key, so once no row carries the pending generation, clearing the vault's uev_pending_public_key and uev_pending_key_generation and soft-deleting the pending generation's wrappings returns it to the key in use.

A rotation that stops part way is finished, never discarded: what it moved opens only with the new key, and keys a consumer's hook moved (Drive's grants, the password store key) carry no generation the server could count, so there is no telling "nothing moved" from "everything moved". The card then says that what moved will not open until the rotation is finished and offers "Finish rotating", which unlocks both keys (the new one with the unlockers it was given, or through the root) and runs the batch again — everything in it resumes. A new begin is refused while one is pending. The status payload lists the key in use's wrappings in wrappings and the pending ones apart in pending_wrappings.

Handing a vault to a device

The device-link page (/profile/devices/link) offers a checkbox for each browser-held vault the user has set up: Drive's (enable_vault, its key in sealed_vault_key, the field the shipped sync client reads) and one per other scope (its key in sealed_vault_keys, {scope: blob}). Each chosen vault is unlocked and its secret sealed to the device's public key in the browser (session.sealSecretKeyTo()), one unlock per vault. The device collects both fields once on its claim, and sde_vault_scopes records what it holds. A native client learns a scope's public key and key generation — and so notices a rotation — from vault_client_probe (any registered client scope, session-key reachable, no unlock material).