Mercury

Architecture Overview

Mercury is a secure agent-based architecture that bridges cloud (STREAM SaaS) and on-premise systems through encrypted tunnels and persistent connections. The system operates on three core principles:

Security Model: When agents enroll, they perform an ECDH key exchange. Mercury stores all data in an encrypted database file. The Solaris private key is stored securely in a KMS and only retrieved when an agent tries to open a tunnel connection.

Session Lifecycle: Mercury maintains a persistent, authenticated tunnel connection to Nexus (the cloud gateway). This tunnel enables bidirectional message flow and is recovered automatically on disconnection. Nexus manages session state and validates all inbound/outbound messages.

Resilience: The Message Broker (NATS) provides durable message delivery, ensuring no updates are lost even if the tunnel is temporarily disconnected. When Mercury reconnects, it retrieves pending messages from NATS.

Enrollment

Enrollment establishes a cryptographic identity for the agent. The agent generates a Curve25519 key pair locally and sends the public key along with the enrollment token in the enrollment request. Nexus only proxies the enrollment request to Solaris. After performing the ECDH key exchange, Solaris stores it's own private key in Vault KMS. The enrollment token is single-use and establishes the initial trust relationship between Mercury and the cloud system.

Start Tunnel

A tunnel connection is always initiated by Mercury. Mercury adds an authorization Header to the StartTunnel RPC to prove possesion of the Identity key. Then, Mercury initiates the session handshake to perform a key exchange with Nexus.

Configuration Update

Configuration updates flow through the Message Broker (NATS) to ensure reliable delivery even if the tunnel is temporarily down. Solaris encrypts plugin configs (which may contain secrets) before storing them in the database, but sends them in plaintext within the Kubernetes cluster to NATS. Nexus retrieves the message from NATS and encrypts it with the agent's session key before sending it through the tunnel. Mercury decrypts and applies changes. Encryption boundaries are: at-rest in the database (Solaris), and in-transit through the tunnel (Nexus → Mercury).

Normal Operation

Use case: Push data from cloud to on-premise

Use case: Pull data from on-premise to cloud

Bidirectional Data Flow

The tunnel enables two distinct data paths:

Cloud → On-Premise (Push): Solaris fetches data, publishes to NATS, Nexus retrieves and encrypts with the agent's session key, then sends through the persistent tunnel. Mercury decrypts, formats for the external system, and delivers it. If the tunnel is down, Nexus buffers the message in NATS until Mercury reconnects.

On-Premise → Cloud (Pull): External systems send data to Mercury, which encrypts it and sends through the tunnel. Nexus decrypts, verifies, and publishes to NATS. Solaris (and other cloud services) consumer the message, validate it, and store it in the database. This maintains the same security and reliability model in both directions.