Skip to content

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:

  1. A fresh random 32-byte data-encryption key (DEK) is generated for each seal.
  2. The plaintext is encrypted with AES-256-GCM under that DEK.
  3. The DEK is wrapped with AES-GCM under a key derived from the KEK.
  4. 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 the tide-envelope-kek Secret to check. Opening a legacy face.db without 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_ENDPOINT set, the root is a scoped view of the object store. Without it, the root is appfs’s encrypted local backend, in FACE_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-systems are 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 0700 and files 0600. TestKnowledgeCorpusIsNotWorldReadable writes real corpus content through the real code path, then checks every file and directory mode.
  • The inference service token is never invented. INFERENCE_API_KEY is the only source of the token FACE presents to the inference plane. FACE never generates a fallback, and TestFaceNeverInventsAServiceToken guards 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_KEK can open everything sealed under it. Generating, storing, distributing and rotating that key happens outside FACE.
  • Re-sealing does not reach old copies. The reseal tool rewrites live objects. It does not rewrite copies that already exist in older backups, or a legacy face.db an upgraded instance still keeps. Removing those is an operator step.
  • File modes are not encryption. 0600/0700 protects 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.