Architecture Flows

Auto-generated

Rendered from docs/architecture/calm/architecture.json by the CALM CLI (calm template). Do not edit this file by hand — edit the architecture JSON or the Handlebars template at docs/architecture/calm/templates/mermaid/flows.md.hbs and regenerate with make calm-diagrams.

Each business flow defined in the CALM architecture is rendered below as its own Mermaid flowchart TD — one diagram per flow, linking the transitions in sequence order. Three flows are modelled today:

• sceau startup: recreate the SRK — the deterministic primary key is recreated at boot and the stable key_id is derived.
• Encrypt a Secret write — the happy path from apiserver DEK to sealed envelope in etcd.
• Decrypt a Secret read — envelope back to plaintext DEK, in memory only.

sceau startup: recreate the SRK

At boot (before the apiserver starts) sceau connects to the TPM and recreates the deterministic SRK primary from the standard template — identical key material on every boot of the same TPM — then derives the stable key_id from the SRK Name.

flowchart TD t1["1. TPM2_CreatePrimary(Owner, SRK template) recreates the same RSA-2048 restricted decryption primary; the SRK handle is kept resident for the daemon's lifetime."] t2["2. TPM2_ReadPublic yields the SRK Name; its hash becomes the KMS key_id reported by Status, stable across reboots of this TPM."] t1 --> t2

_{Source: flow flow-startup-srk in architecture.json.}

Encrypt a Secret write

The apiserver generates a DEK for a write, sceau seals it under the SRK, and the envelope is persisted in etcd.

flowchart TD t1["1. Encrypt RPC: the apiserver sends the freshly generated DEK over the unix socket."] t2["2. TPM2_Create builds a fixedTpm+fixedParent sealed keyed-hash object under the SRK containing the DEK; the private+public blobs never expose the DEK."] t3["3. sceau returns the sealed envelope (version || public || private) as the KMS ciphertext with the current key_id."] t4["4. The apiserver wraps the Secret payload with the DEK (AES-GCM) and stores the KMS envelope in etcd."] t1 --> t2 --> t3 --> t4

_{Source: flow flow-encrypt-secret in architecture.json.}

Decrypt a Secret read

On a read, the apiserver hands the stored envelope back to sceau, which unseals the DEK inside the TPM; plaintext crosses only the host-local socket.

flowchart TD t1["1. The apiserver reads the KMS envelope (sealed DEK + ciphertext) for the requested object."] t2["2. Decrypt RPC: the envelope is sent to sceau with its key_id; a mismatched key_id is rejected without touching the TPM."] t3["3. TPM2_Load + TPM2_Unseal recover the DEK inside the TPM; the object handle is flushed immediately after."] t4["4. The DEK returns over the unix socket and lives only in apiserver memory for the duration of the request."] t1 --> t2 --> t3 --> t4

_{Source: flow flow-decrypt-secret in architecture.json.}