# signalapp/securevaluerecovery2 architecture

> Architecture diagram of the GitHub repository signalapp/securevaluerecovery2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/signalapp/securevaluerecovery2
- Repository: https://github.com/signalapp/securevaluerecovery2

## Overview

##### Project Type and Purpose
- This is a security-critical, full-stack service that combines:
–  A host-side Go microservice (the “host” process) exposing APIs to clients.
–  A trusted-execution enclave (C++ code) running inside hardware TEEs (SGX, Nitro, SEV-SNP).
–  A lightweight in-memory Raft consensus layer for replication and state durability.
–  A build/deploy toolchain (Docker, Packer) and trusted VM image builder for SEV.
- Its purpose is to securely store low-entropy client secrets behind a rate-limited recovery protocol, using TEEs to guard keys and state.

a.  Clients
- Mobile/desktop applications or CLI tools that call the host over HTTP/gRPC/REST/WebSocket.
- Responsible for pin input, OPRF flows, attestation verification.
b.  Host Service (Go)
- HTTP/gRPC server with sub-modules:
–  Web handlers (host/web/handlers)
–  Control CLI (host/cmd/control, svr2client, svr3client)
–  Configuration loader (host/config)
–  Dispatch layer that serializes requests into protobufs and routes them to the enclave (host/dispatch)
–  Health, metrics, rate-limiting middleware
- Manages enclave lifecycle: initialization, remote attestation, secure channel
- Integrates a Rust client (host/rustclient) and communicates via protobufs over a UNIX or TCP socket.
c.  Enclave (C++)
- Entry-point modules (ecalls/ecalls.cc) for incoming host requests.
- Core logic modules:
–  Secret storage & Raft consensus (enclave/core, enclave/raft)
–  Cryptography (enclave/hmac, enclave/noise, enclave/ristretto)
–  Storage layer abstractions (enclave/db, enclave/fs)
–  Attestation adapters (SGX in enclave/attestation/oe, Nitro in enclave/attestation/nitro, TPM2/SEV modules)
–  Utilities and metrics (enclave/util, enclave/metrics)
- Shared interface definitions (in enclave/proto and shared/proto for protobuf, shared/svr2.edl for ocall/ecall).
d.  Consensus & Replication
- In-memory Raft ring of enclave instances across nodes
- Host processes open peer-to-peer channels to run Raft (uses protobuf messages over network).
e.  Build & Deployment Tooling
- Docker build image (docker/Dockerfile) that compiles both host and enclave
- Packer configurations and scripts in trustedimage/ to build VMs for SEV-SNP
- CI workflows (.github/workflows) to run tests and builds on PRs/pushes

##### Component Relationships & Data Flows
- Client → Host API: Over TLS/HTTP, passes user PIN or OPRF request.
- Host → Enclave: Via a secure channel (OE enclave socket, Nitro CLI socket, SEV VM agent) using protobuf messages defined in shared/proto.
- Enclave internal:
–  ecall handlers deserialize requests → core modules
–  Core invokes Raft replication to update state on peer enclaves
–  Crypto modules perform OPRF or encrypt/decrypt secrets
–  ecall returns result → host
- Enclave → Host ocalls: For filesystem access, logging, metrics
- Raft peer traffic: Enclave-to-enclave messages on TCP ports for consensus
- Build pipeline: Developers run make → Docker container → produce enclave.signed, host binary, trusted VM image

##### Architectural Patterns & Principles
- Trust boundary: clearly separate “host” untrusted process from “enclave” trusted process.
- Modular attestation adapters: one per TEE backend (SGX, Nitro, SEV, TPM2).
- Pluggable crypto stack: Noise protocol for secure channel, Ristretto OPRF for SVR3.
- High-availability via in-memory Raft: sacrificing liveness for security is a conscious choice.
- Shared IDLs (protobuf + EDL) enforce schema consistency across host/enclave.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        ClientApp["Mobile/Desktop/CLI"]:::untrusted
    end

    %% Host Service
    subgraph "Host Service (Go)" 
        direction TB
        HostMain["host/main.go"]:::untrusted
        Config["Configuration Loader"]:::untrusted
        Dispatch["Dispatch Layer"]:::untrusted
        Middleware["Rate-Limiting & Metrics"]:::untrusted
        Logger["Logging"]:::untrusted
        HostCLI["Control CLI"]:::untrusted
        RustClient["Rust Client"]:::untrusted
    end

    %% Enclave
    subgraph "Enclave (C++)" 
        direction TB
        ECalls["ECalls Entry-Points"]:::trusted
        Core["Core Logic"]:::trusted
        RaftImpl["Raft Implementation"]:::trusted
        Crypto["Crypto Modules"]:::trusted
        Storage["Storage Abstractions"]:::trusted
        Attestation["Attestation Adapters"]:::trusted
        Utils["Utilities & Metrics"]:::trusted
        SharedSchema["Shared Proto & EDL"]:::trusted
    end

    %% Consensus & Replication
    subgraph "Consensus & Replication"
        direction TB
        RaftPeers["Raft Peers"]:::trusted
    end

    %% Build & Deployment
    subgraph "Build & Deployment" 
        direction TB
        Docker["Docker Build"]:::infra
        Packer["Packer VM Image"]:::infra
        CI["CI Workflows"]:::infra
    end

    %% Data Flows
    ClientApp -->|"HTTP/gRPC/TLS"| HostMain
    HostMain -->|"secure channel\n(Protobuf over socket)"| ECalls
    ECalls -->|"deserialize & dispatch"| Core
    Core -->|"invoke replication"| RaftImpl
    RaftImpl <-->|"Raft RPC"| RaftPeers
    Core -->|"crypto ops"| Crypto
    Crypto --> Core
    ECalls -->|"ocalls (fs, logs, metrics)"| Storage
    ECalls -->|"ocalls"| Utils
    SharedSchema --> HostMain
    SharedSchema --> ECalls

    %% Build flows
    Docker -->|build host & enclave| HostMain
    Docker -->|build host & enclave| ECalls
    Packer -->|produce VM image| Enclave
    CI --> Docker
    CI --> Packer

    %% Click events
    click ClientApp "https://github.com/signalapp/securevaluerecovery2/blob/main/host/cmd/control/main.go"
    click HostMain "https://github.com/signalapp/securevaluerecovery2/blob/main/host/main.go"
    click Config "https://github.com/signalapp/securevaluerecovery2/blob/main/host/config/config.go"
    click Dispatch "https://github.com/signalapp/securevaluerecovery2/blob/main/host/dispatch/dispatcher.go"
    click Middleware "https://github.com/signalapp/securevaluerecovery2/blob/main/host/web/middleware/*.go"
    click Logger "https://github.com/signalapp/securevaluerecovery2/blob/main/host/logger/logger.go"
    click HostCLI "https://github.com/signalapp/securevaluerecovery2/blob/main/host/cmd/control/main.go"
    click RustClient "https://github.com/signalapp/securevaluerecovery2/blob/main/host/rustclient/src/main.rs"
    click ECalls "https://github.com/signalapp/securevaluerecovery2/blob/main/enclave/ecalls/ecalls.cc"
    click Core "https://github.com/signalapp/securevaluerecovery2/blob/main/enclave/core/core.cc"
    click RaftImpl "https://github.com/signalapp/securevaluerecovery2/blob/main/enclave/raft/raft.cc"
    click Crypto "https://github.com/signalapp/securevaluerecovery2/blob/main/enclave/hmac/hmac.cc"
    click Storage "https://github.com/signalapp/securevaluerecovery2/blob/main/enclave/fs/fs.cc"
    click Attestation "https://github.com/signalapp/securevaluerecovery2/blob/main/enclave/attestation/oe/attestation.cc"
    click Utils "https://github.com/signalapp/securevaluerecovery2/blob/main/enclave/util/util.cc"
    click SharedSchema "https://github.com/signalapp/securevaluerecovery2/blob/main/shared/proto/*.proto"
    click Docker "https://github.com/signalapp/securevaluerecovery2/tree/main/docker/Dockerfile"
    click Packer "https://github.com/signalapp/securevaluerecovery2/tree/main/trustedimage/"
    click CI "https://github.com/signalapp/securevaluerecovery2/blob/main/.github/workflows/push.yml"

    %% Styles
    classDef untrusted fill:#f9d,stroke:#333,stroke-width:1px
    classDef trusted fill:#def,stroke:#333,stroke-width:1px
    classDef infra fill:#dfd,stroke:#333,stroke-width:1px
```
