Trust Model

KnowledgeFlowDB takes an honest disclosure approach to security. Rather than making unverifiable claims, we document exactly what each deployment mode protects against and where operator access remains possible.

Trust Postures

The system supports three trust postures, controlled by the TEE_TRUST_POSTURE environment variable:

Posture	Behavior	Use Case
Permissive	No TEE checks. Any environment allowed.	Development, testing, public datasets
Audit	Logs warnings when TEE is missing but allows operation.	Staging, migration periods
Enforced	Refuses to start without TEE platform detected.	Production with confidential data

Startup Behavior

TEE_TRUST_POSTURE=Enforced + TEE_PLATFORM=GCE_AMD_SEV  -->  Server starts normally
TEE_TRUST_POSTURE=Enforced + TEE_PLATFORM not set       -->  Server refuses to start
TEE_TRUST_POSTURE=Audit    + TEE_PLATFORM not set       -->  Server starts with warning
TEE_TRUST_POSTURE=Permissive                            -->  Server always starts

Access Path Comparison

This table honestly discloses what an operator (someone with infrastructure access) can and cannot see in each mode:

Access Path	TEE Pod (Enforced)	Standard Pod (Permissive)
kubectl exec -- read environment	AMD SEV blocks memory inspection	Master key visible in env
kubectl get secret -- read K8s secrets	Readable (K8s limitation)	Readable
cqlsh on ScyllaDB -- direct query	__enc_* ciphertext only	Plaintext values
ClickHouse query -- direct query	__enc_* ciphertext only	Plaintext values
API response -- authenticated request	Decrypted for authorized user only	Plaintext for any authenticated user
Network sniffing	TLS encrypted	TLS encrypted
Memory dump via hypervisor	AMD SEV encrypted memory	Plaintext in memory

What TEE Protects

In TEE Enforced mode with encryption active:

• Database contents are encrypted ciphertext -- a database administrator with direct ScyllaDB or ClickHouse access sees only __enc_str:..., __enc_int:... etc.
• VM memory is encrypted by AMD SEV -- the hypervisor and host OS cannot read process memory
• API responses are decrypted only for the authenticated tenant who owns the data
• Cross-tenant isolation is cryptographic -- each wallet derives a unique encryption key

What TEE Does Not Protect

Being honest about limitations:

• Kubernetes secrets are readable by cluster administrators (kubectl get secret). The encryption master key is stored as a K8s secret.
• Network metadata (which endpoints are called, request sizes, timing) is visible to network operators even with TLS.
• Graph structure (labels, IDs, edges) is not encrypted -- an operator can see that nodes of type "File" exist and how they connect, but not their property values.
• Property names (keys) are not encrypted -- an operator can see that a node has properties named "path" and "content", but not their values.

tip

For the highest security, combine TEE Enforced mode with sign-to-derive key management. This way, the encryption root key never exists on the server -- it is derived from the user's wallet signature on each request.

Encryption Activation

Encryption is gated on the KFDB_TEE_MODE environment variable:

KFDB_TEE_MODE	ENCRYPTION_MASTER_KEY	Result
encrypted	Set	Per-wallet keys derived, properties encrypted
encrypted	Not set	No encryption (key material unavailable)
Not set / other	Any	No encryption (standard mode)

This design prevents standard pods from accidentally encrypting public data. Only TEE-configured pods set KFDB_TEE_MODE=encrypted.

Per-Wallet Key Derivation

Each tenant's encryption key is derived from:

HKDF-SHA256(
  ikm:  ENCRYPTION_MASTER_KEY,
  salt: ENCRYPTION_SALT + wallet_address,
  info: "kfdb-tenant-encryption-v1"
)

This means:

• Different wallets get different keys (cryptographic tenant isolation)
• Same wallet always gets the same key (deterministic, no key storage needed)
• Master key compromise affects all tenants on that pod (mitigated by TEE memory protection)

Deployment Architecture

                    Internet
                       |
                       v
              +------------------+
              |   Load Balancer  |
              |   (TLS termination)
              +--------+---------+
                       |
         +-------------+-------------+
         |                           |
    +----v--------+           +------v------+
    | TEE Pod     |           | Standard Pod|
    | AMD SEV-SNP |           | (Permissive)|
    | Encrypted   |           | Plaintext   |
    +----+--------+           +------+------+
         |                           |
    +----v---------------------------v----+
    |          ScyllaDB Cluster           |
    |  TEE tenant data: __enc_* cipher    |
    |  Standard data: plaintext           |
    +-------------------------------------+

TEE and standard pods share the same database cluster. TEE tenant data is stored as ciphertext; standard tenant data remains plaintext. They coexist safely because encryption is per-tenant, not per-cluster.

Comparison with Other Approaches

Approach	Data at Rest	Operator Access	Key Management
KFDB TEE Enforced	Encrypted per-tenant	Ciphertext only (DB), encrypted memory (VM)	HKDF from master or wallet signature
KFDB Permissive	Plaintext	Full access	N/A
Database-level TDE	Encrypted on disk	Plaintext in memory and queries	Single key for entire database
Application-level encryption	Encrypted per-field	Ciphertext in DB, plaintext in app memory	Application-managed keys
Confidential Space	Encrypted + attested	Cryptographic attestation JWT	Workload identity

KnowledgeFlowDB's approach combines application-level property encryption with TEE memory protection, providing defense in depth beyond what database-level TDE offers alone.

Source Code

• Release guard: crates/kfdb-api/src/release_guard.rs
• Tenant middleware (key derivation): crates/kfdb-api/src/tenant/middleware.rs
• Health/security posture: crates/kfdb-api/src/health.rs