State Machines and Lifecycles

This document provides formal state machine diagrams detailing the operational lifecycles of all subsystems across the LOGAR architecture.

1. High-Level System State Machine

Macroscopic overview of the complete end-to-end system lifecycle from initial PKI bootstrapping to AI provisioning:

stateDiagram-v2
    [*] --> 1_PKI_Licensing: Master Authority generates Bootstrap .lic Package
    1_PKI_Licensing --> 2_Hub_Ready: Server Hub imports .lic & signs Sub-CA over WebSocket
    2_Hub_Ready --> 3_Edge_Enrollment: Edge Forwarders auto-enroll & lease licensed seats
    3_Edge_Enrollment --> 4_mTLS_Streaming: Forwarders stream framed logs over mTLS 1.3 (:9443)
    4_mTLS_Streaming --> 5_Temporal_Aggregation: Server Hub normalizes & correlates logs in 12h window
    5_Temporal_Aggregation --> 6_AI_Provisioning: Logs provisioned to Hermes AI via GET /api/hermes/report
    6_AI_Provisioning --> 4_mTLS_Streaming: Continuous operational loop

2. Master License Authority & Sub-CA Auto-Enrollment

Details how a freshly initialized LOGAR Server Hub imports initial credentials, connects to the Master License Authority (logar.eibl.tech) via WebSocket, and acquires its signed Sub-CA certificate:

stateDiagram-v2
    [*] --> GeneratedBootstrap: Operator generates Bootstrap .lic Package on Authority
    GeneratedBootstrap --> ServerImport: Admin imports .lic package on Server Hub
    ServerImport --> LocalCSR: Server generates local Sub-CA Keypair & CSR
    LocalCSR --> WSConnecting: Opens WebSocket to wss://logar.eibl.tech/ws/license
    WSConnecting --> ValidatedCSR: Authority validates hardware fingerprint & CSR
    ValidatedCSR --> SubCASigned: Authority signs Sub-CA with OID_LOGAR_SEATS (1.3.6.1.4.1.59999.1.1)
    SubCASigned --> QuotaActive: Server parses Seat OID & initializes SQLite seat quota
    QuotaActive --> ServerHubReady: mTLS Listener (Port 9443) & Hermes API (Port 8443) active

3. Live WebSocket Heartbeat, Seat Expansion & In-Flight Reload

Details the continuous synchronization loop, on-demand quota scaling, and hot-reload behavior without dropping client streams:

stateDiagram-v2
    [*] --> ActiveListener: Server Hub actively servicing edge forwarders
    ActiveListener --> WebSocketHeartbeat: Sends periodic check_updates heartbeat
    
    state WebSocketHeartbeat <<choice>>
    WebSocketHeartbeat --> QuotaExpanded: Authority increased seat quota
    WebSocketHeartbeat --> SteadyState: Quota unchanged / heartbeat ack
    WebSocketHeartbeat --> Revoked: Authority revoked license_id
    
    QuotaExpanded --> InFlightReload: Updates SQLite & reloads SSLContext in-flight
    InFlightReload --> ActiveListener: Hot reload complete (Zero downtime)
    SteadyState --> ActiveListener
    Revoked --> DropConnections: Drops all incoming mTLS connections immediately

4. Forwarder Identity Discovery & Zero-Touch Enrollment

Details dynamic machine identity resolution and initial certificate enrollment on Windows and Linux edge forwarders:

stateDiagram-v2
    [*] --> DiscoverIdentity: Edge Client (Win_Client / Linux_Client) launches
    DiscoverIdentity --> QueryFQDN: socket.getfqdn()
    QueryFQDN --> ParseDomain: Resolves Windows AD env / Linux resolv.conf
    ParseDomain --> BuildClientID: Computes FQDN client_id & Site Attribution
    
    BuildClientID --> CheckCertificates: Inspects local certs/client.crt & certs/ca.crt
    state CheckCertificates <<choice>>
    CheckCertificates --> ReadyToStream: Certificates valid & unexpired
    CheckCertificates --> RequestEnrollment: Certificates missing or expired
    
    RequestEnrollment --> ValidateQuota: POST /api/client/enroll with secret
    state ValidateQuota <<choice>>
    ValidateQuota --> StoreCerts: 200 OK (Seats available & secret valid)
    ValidateQuota --> [*]: 403 Forbidden (Seat quota full / bad secret)
    
    StoreCerts --> ReadyToStream

5. mTLS 1.3 Streaming, Proactive Renewal & Reactive Self-Healing

Details the secure streaming loop, proactive certificate lifecycle checks, and automated recovery against CA rotation:

stateDiagram-v2
    [*] --> mTLSHandshake: Initiates TLS 1.3 Handshake (Port 9443)
    mTLSHandshake --> CheckClientCN: Server validates client_id in SQLite clients table
    
    state CheckClientCN <<choice>>
    CheckClientCN --> ActiveStreaming: Client active in DB (Within seat quota)
    CheckClientCN --> DropClient: Client seat revoked in DB
    
    ActiveStreaming --> PeriodicCheck: Checks client.crt validity before each run
    PeriodicCheck --> ProactiveRenew: Expiry < 30 days (Auto-renews via /api/client/enroll)
    ProactiveRenew --> mTLSHandshake
    
    ActiveStreaming --> ReactiveHeal: Handshake error / CA changed (Re-enrolls)
    ReactiveHeal --> mTLSHandshake
    DropClient --> [*]

6. 12-Hour Temporal Window & AI Provisioning

Details log frame extraction, deduplication, temporal correlation across the 12-hour evaluation window, and delivery to Hermes AI:

stateDiagram-v2
    [*] --> EventCaptured: Event captured from Windows Event Log / Linux journalctl
    EventCaptured --> NoiseStripping: Strips DEBUG, trace entries & logs > 24h old
    NoiseStripping --> FrameEncoding: Encodes JSON frame ({site}:{server}:{signature})
    FrameEncoding --> FrameIngested: Streamed over mTLS 1.3 (Port 9443)
    
    FrameIngested --> EvaluateWindow: Compares (now - last_seen) against 12h window
    state EvaluateWindow <<choice>>
    EvaluateWindow --> WithinWindow: (now - last_seen) <= 12 hours
    EvaluateWindow --> WindowExpired: (now - last_seen) > 12 hours
    
    WithinWindow --> UpdateRunCount: Increment consecutive_runs, update last_seen
    WindowExpired --> ResetRunCount: Reset consecutive_runs = 1, update timestamps
    
    UpdateRunCount --> UpsertDB: Upserts active_issues with status="VERIFIED"
    ResetRunCount --> UpsertDB
    
    UpsertDB --> ProvisionReport: Provisioned via GET /api/hermes/report (Port 8443)
    ProvisionReport --> HermesThinking: Hermes AI executes multi-factor reasoning & actions