Encryption at rest
FACE encrypts what it persists before it is written. It does this with one envelope scheme, from Runink’s shared envelope-encryption library, under one key-encryption key (KEK) that the platform supplies. FACE does not start without that key.
The envelope scheme
Every sealed value is an independent envelope:
- A fresh random 32-byte data-encryption key (DEK) is generated for each seal.
- The plaintext is encrypted with AES-256-GCM under that DEK.
- The DEK is wrapped with AES-GCM under a key derived from the KEK.
- The wrapped DEK, the nonces and the ciphertext are stored together, so one envelope is self-describing.
FACE writes the scheme’s version 2 format everywhere it seals. That covers the encrypted application root (and the metadata tables inside it) and the object store. Each of those writers opts in to version 2 in code, not through a setting.
Version 2 adds the following:
- A per-envelope wrap key. The KEK never keys AES-GCM directly. Each
envelope wraps its DEK under
HKDF-SHA256(KEK, salt, "runink/envelope/v2/wrap")with a fresh 256-bit salt. No GCM key ever encrypts more than one message, so no per-key message budget needs tracking. - A key identifier. Each envelope carries an 8-byte key ID derived from the KEK by HMAC. Opening selects the right key directly, and a blob sealed under an unknown key says so. The ID reveals nothing about the key.
- An authenticated header. The version, key ID, salt and nonces are all covered by the GCM tag, so they cannot be edited or spliced between envelopes.
- Context binding (AAD). The caller’s additional authenticated data is bound in last. FACE uses it to tie each ciphertext to where it lives, so a sealed blob copied to another key, table or path fails to open. It is not merely hidden there.
Key rotation
The KEK is read from the secret TIDE_ENVELOPE_KEK, a base64-encoded 32-byte
value. To rotate it, publish the new key as TIDE_ENVELOPE_KEK and move the old
one into TIDE_ENVELOPE_KEK_RETIRED. Existing envelopes still open because
the key ID selects the retired key. Because only DEKs are wrapped by the KEK,
rotation never requires re-encrypting bulk data. A retired key stays in
TIDE_ENVELOPE_KEK_RETIRED until the shared store’s reseal tool has rewritten
everything sealed under it.
In the cluster, TIDE delivers the key as the tide-envelope-kek Secret in
FACE’s namespace.
A required KEK
- Mounting the encrypted application root needs the KEK. Without it FACE stops, because that root holds the session store and a process without it could authenticate nobody.
- The backend exits specifically on
envelope.ErrKEKUnavailable, and its log line names thetide-envelope-kekSecret to check. Opening a legacyface.dbwithout the KEK is fatal for the same reason.
No code path runs FACE with sealing switched off, and there is no setting that switches it off.
Where sealing applies
The encrypted application root
FACE’s sessions and application metadata live in its own appfs root, from
Runink’s appfs library, mounted at the backend’s application root:
- An app-specific key. The root’s key is
HKDF-SHA256(KEK, info="runink/appfs/face"). A key or blob leaked from another Runink application opens nothing of FACE’s, even on a shared object store. - Path-bound blocks. The AAD of every block includes the application and the block’s full path, tenant segment included. A block moved to another path, tenant or application fails to open.
- Two backends. With
OBJECTSTORE_ENDPOINTset, the root is a scoped view of the object store. Without it, the root is appfs’s encrypted local backend, inFACE_APPFS_DIR. FACE has no in-memory mode.
The root holds sessions, user accounts, the compute-budget ledger and, under
tenants/<FACE_TENANT>/, everything the customer configured or produced:
connections and their credentials, application metadata, fetch snapshots,
briefs and personas, remediation overlays and routes, rule policies, and call
transcripts.
Application metadata tables
FACE keeps no database of its own. Its application metadata (accounts, schedules, operator overlays, fetch snapshots, compute budgets and the application-metadata record) is a set of append-only tables inside the appfs root above, so every object they write is sealed in the version 2 format under FACE’s derived key and bound to its full path. There is no plaintext mode.
A runner keeps its own state the same way, in its own tables under the tenant
(tenants/<FACE_TENANT>/var/lib/runners.<id>.*), not on its image layer.
FACE moved off SQLite on the owner’s decision of 2026-10-08. An
instance upgraded from an older build may still have its old face.db file. At
startup FACE imports its rows once into the appfs tables, opens it only if it
exists, and never writes to it again.
The object store
The object-store client from the shared store library seals every object it
writes with the same envelope scheme (version 2), bound to its bucket and key.
FACE’s durable records go through it: the appfs root itself when
OBJECTSTORE_ENDPOINT is set, the observed lineage records, the fetch run
history, and (when an object store is configured) the tenant’s DCI knowledge
corpus.
Credentials
Connector credentials get stricter handling than any other data FACE holds:
- A connection record cannot hold a secret. The connection type in the connection record has no field a secret would fit in. When a connection arrives over the wire, the connection translator lifts every secret-named field (password, client secret, API key, token, service-account JSON) into a separate credential bundle. The secret-bearing fields in the wire schema are read on the way in and never written on the way out. A client that reads a connection back gets them empty.
- Credentials are sealed rows, not files. Each credential bundle is a row in FACE’s appfs connections table, sealed under FACE’s derived key and bound to its path.
- Credentials are not replicated through consensus. Only connection metadata goes through the raft log. Credential bundles do not.
- Credentials never come from the server’s environment. A connector reads
its credentials only from its own connection’s sealed bundle, never from the
backend’s process environment. A person enters them in Settings ›
Integrations › Systems in the FACE app. The shared data sources in
data-systemsare registered from a partner connection manifest (deploy/data-systems/connections.toml) that cannot carry a credential: each password is read from a named variable at registration time and stored sealed, without being printed. - Local files are owner-only. Where FACE writes local files (credential
compatibility paths, and the knowledge corpus when no object store is
configured), directories are created
0700and files0600.TestKnowledgeCorpusIsNotWorldReadablewrites real corpus content through the real code path, then checks every file and directory mode. - The inference service token is never invented.
INFERENCE_API_KEYis the only source of the token FACE presents to the inference plane. FACE never generates a fallback, andTestFaceNeverInventsAServiceTokenguards that.
Scope of these controls
- Sealing at rest and encryption in transit are separate layers. Sealing happens before a write. Where a sealed payload crosses a network, it is ciphertext because it was sealed for storage, not because of any transport decision. Transport confidentiality comes from TLS (see Defence in depth).
- Key custody belongs to the platform. Whoever holds
TIDE_ENVELOPE_KEKcan open everything sealed under it. Generating, storing, distributing and rotating that key happens outside FACE. - Re-sealing does not reach old copies. The
resealtool rewrites live objects. It does not rewrite copies that already exist in older backups, or a legacyface.dban upgraded instance still keeps. Removing those is an operator step. - File modes are not encryption.
0600/0700protects local files from other users on the host. It does not protect them from the host’s administrator or from someone who has the disk.