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 an optional bypass phrase), 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, an optional bypass phrase), and is unwrapped only transiently into server RAM for the duration of an unlock window.

Naming: the memorized unlocker is a bypass phrase everywhere a user sees it (internally passphrase in identifiers and API action names). The name carries its own warning: it bypasses the passkey requirement, it is not the login password, and enrolling one lowers the vault's strength to the strength of the phrase. It is never offered during setup — the ceremony is passkey + recovery codes only — and is added deliberately from the unlocker management panel by users who need to unlock where their passkey is not available (another device, CLI tooling).

One unlock opens everything in that scope. A single passkey tap puts the secret key in the window; 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.

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 - fast; entropy is the defense
$kek     = $box->kekFromPassphrase($passphrase, $salt);// crypto_pwhash Argon2id - slow, low-entropy input
$salt    = $box->generateSalt();                       // one uev_salt serves both KDFs above
$code    = $box->generateRecoveryCode();               // 26 Crockford-base32 chars, >=128 bits, grouped

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

$crypto = new VaultCrypto();
$dek    = $crypto->newItemDek();                        // random 32B, one per content item
$sealed = $crypto->sealItemDek($dek, $public_key);       // store on the consumer's own row
$dek    = $crypto->openItemDek($sealed, $secret_key);
$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'

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.

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 or Guarded 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 bypass phrase instead — the same TYPE_PASSPHRASE wrapping the unlocker panel offers, created at setup time rather than added later, and with no TYPE_PASSKEY wrapping at all.

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.

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):

VaultUnlock::open($user_id, $secret_key, $scope = 'user');
VaultUnlock::isOpen($user_id, $scope = 'user'): bool;
VaultUnlock::secretKey($user_id, $scope = 'user'): ?string;  // 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

Every content read calls secretKey() and treats null as locked — a one-tap unlock prompt, never an error. 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 vault unlock demands device user verification, not merely preferred. The two knowledge-factor unlocks (recovery code, bypass phrase) additionally demand the account's second factor regardless of the 2FA cadence setting: a remote attacker must hold a possession factor, never just stolen strings.

Host hardening

includes/VaultHealth.php checks the three 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), and swap off or encrypted. Best-effort and advisory (a check that can't be verified reports unknown, never a false pass) — surfaced informationally from vault_setup_verify and via php maintenance_scripts/dev_tools/check_vault_health.php (exits non-zero on any unmet check, mirroring check_provisioning.php's convention).

The lock chip

The platform-wide "you're locked" idiom: every signed-in page for a user with a set-up server-custody vault carries a padlock in a fixed place — closed while the vault is locked, open (success-colored) while an unlock window is live. Clicking the closed padlock runs the one-tap passkey unlock ceremony in place; clicking the open padlock opens a small popover with the idle-timeout note and a Lock now button — the walk-away affordance. Users without a vault never see the chip or load its assets.

PublicPageBase drives it: for a signed-in user whose vault exists it emits <meta name="joinery-vault" content="locked|open" data-idle-minutes="N"> and includes assets/js/vault-lock.js + assets/css/vault-lock.css (plus passkeys.js for the ceremony). The chip mounts into the page's [data-vault-lock-slot] element — the core page classes emit one from their header icon cluster via PublicPageBase::render_vault_lock_slot() (which emits nothing for chip-less users, so headers never carry an empty gap) — and falls back to a fixed bottom-right chip on any theme without a slot, so the idiom holds everywhere with zero theme work.

The ceremony surface. window.JoineryVaultLock is the one client-side unlock/lock ceremony: unlock() (resolves true on success), lock(), and state(). Consumer surfaces (the mail reader's unlock banners, a Fortress compose) delegate to it when present rather than calling the vault actions directly, so every ceremony updates the chip and announces itself.

The event contract. Two document-level events keep every surface on the page — chip, presence beacon, consumer UIs — in one state:

• joinery:vault-unlocked — dispatched after any successful unlock. The chip flips open, vault-presence.js starts beating, and consumer surfaces may refresh sealed placeholders in place.
• joinery:vault-locked — dispatched after any explicit lock, and by vault-presence.js when a heartbeat answers alive:false (the window ended elsewhere — another session's lock, a credential event, a cap). The chip flips closed, the beacon stops, and consumer surfaces re-seal their content to placeholders.

File::registerDecryptHook(File::SOURCE_EMAIL_ATTACHMENT, function (string $ciphertext, File $file): string {
    $secret = VaultUnlock::secretKey($file->get('fil_usr_user_id'));
    if ($secret === null) throw new VaultLockedException();
    // ... open the per-item DEK, 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 Fortress 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, string $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. The shared client-custody layer lives in core so every consumer reuses it:

• assets/js/vault-crypto.js — the browser crypto module: WebCrypto AES-GCM/X25519, the vendored hash-pinned Argon2id WASM for the passphrase-fallback KDF, KEK derivation (passkey PRF / recovery / passphrase), wrap/unwrap of the vault secret key, ECIES seal/open of a data key, and the encrypt()→blob / blob→decrypt() content contract.
• assets/js/vault-keyring.js — the scope-parameterized enrollment, unlock, and recovery ceremony, driving the crypto module against the server actions.
• includes/VaultClientCustody.php + the core logic/vault_client_* actions — custody-agnostic opaque-blob storage: create the keypair record, return the keyring view (public key, KDF salt/params, wrapped-secret blobs), 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). The secret key is never unwrapped server-side.

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

A scope a plugin declares is always client custody: user is the only server-custody scope, and VaultScopes refuses a plugin declaring custody: server. A name collision is refused rather than merged — core wins over a plugin, and two plugins claiming one name are both refused — because a shared name means a shared PRF context, which is the isolation failure derivation exists to prevent. A vault row whose scope nothing declares is inert: no card, no unlock, and the rows are never deleted, so reactivating the plugin restores access.

The built consumers are the password manager (scope passwords) and Drive encryption (scope drive, reusing this same layer and adding per-file content encryption and multi-user key sharing on top).