Message Attestation: example with out-of-process policy server

[liustanley]

Overview

Draft for early feedback, tracking the Message Attestation proposal in opamp-spec#333.

Extends the internal/examples/ agent and server to demonstrate Message Attestation end-to-end, following the isolated out-of-process signing architecture.

Depends on: #599

---

What's included

• internal/examples/policysrv/ — new standalone HTTP signing service (the "policy server")
• internal/examples/server/ — --policy-server flag wires a RemoteSigner into Settings.PayloadSigner
• internal/examples/agent/ — --attestation-ca and --attestation-tofu-store flags

---

Architecture

┌─────────────┐   OpAMP (signed)   ┌─────────────┐   sign RPC   ┌──────────────┐
│    Agent    │ ◄────────────────► │ OpAMP Server│ ────────────► │ Policy Server│
│             │                    │  (no key)   │ ◄──────────── │  (holds key) │
└─────────────┘                    └─────────────┘  signature    └──────────────┘

The OpAMP server holds no private key material. Every outbound ServerToAgent is forwarded to the policy server for signing. The policy server can inspect the payload, enforce organisational policies, and delegate to an HSM before returning a signature.

---

Running the example

The examples live in their own Go module, so run all commands from the
internal/examples directory (each in its own terminal):

cd internal/examples

1. Start the policy server

go run ./policysrv/
# Policy server listening on :4322
# CA certificate → /tmp/opamp-policy-ca.pem

The policy server generates a fresh ephemeral CA on every start and writes it to
/tmp/opamp-policy-ca.pem — the agent loads this as its payload trust anchor.

2. Start the OpAMP server

go run ./server/ \
    --policy-server http://localhost:4322
# Server signs every outbound ServerToAgent via the policy server

3. Start the agent

Option A — pre-provisioned CA (recommended for production):

go run ./agent/ \
    --attestation-ca /tmp/opamp-policy-ca.pem

Option B — TOFU enrollment (first connection accepts and pins the CA):

go run ./agent/ \
    --attestation-tofu-store /tmp/my-trust-anchor.pem
# On first run: enrolls and saves the CA to the file.
# On subsequent runs: uses the saved CA as a pre-configured trust anchor.

--attestation-ca and --attestation-tofu-store are mutually exclusive.

What to observe

• The agent logs Message Attestation enabled on startup.
• The server logs each signing request forwarded to the policy server.
• Stop the policy server mid-session and restart the agent — attestation fails, the agent applies exponential backoff, and reconnects once the policy server is back.
• Replace the policy server with a new CA, delete the TOFU store file, and restart the agent — it re-enrolls against the new CA.
• Rotate the signing leaf live while the agent stays connected — run the policy server with --rotate-interval 30s, or curl -X POST http://localhost:4322/v1/rotate. The root CA (trust anchor) is unchanged, so the agent re-validates the new chain and keeps verifying without reconnecting. (The example server uses a short chain-cache TTL so rotations are picked up promptly.)

---

Key files

File	Purpose
internal/examples/policysrv/main.go	HTTP policy server: /v1/sign, /v1/chain, /v1/ca, /v1/rotate (+ --rotate-interval)
internal/examples/server/main.go	Adds --policy-server flag
internal/examples/server/opampsrv/opampsrv.go	Wires signing.NewRemoteSigner into Settings.PayloadSigner
internal/examples/agent/main.go	Adds --attestation-ca / --attestation-tofu-store flags
internal/examples/agent/agent/agent.go	Passes PayloadVerifier / PayloadTOFUStore into StartSettings