Rocket Telemetry Project Docs
ADR Master Index

ADR-001: TLS Mutual Authentication

Decision record for TLS mutual authentication between node and central, covering bootstrap, rotation, and fallback.

Metadata

Problem / Context

The node and central aggregator communicate over HTTP(S) on port 8080 for API queries. The original architecture specified mutual TLS to prevent impersonation, but left open:

  1. Certificate management: How are certificates issued, renewed, and revoked?
  2. API key strategy: Do we layer API keys on top of mTLS, or is mTLS sufficient?
  3. Credential bootstrap: How does a new node obtain its certificate on first deployment?
  4. Rotation cadence: What is the certificate lifetime and rotation frequency?
  5. Fallback authentication: If mTLS fails during GNSS-degraded operations, how do we detect and respond?

Current State

  • Endpoint specs in System-APIs-Contracts assume authenticated requests but do not mandate mTLS
  • Central aggregator auth model is undefined
  • API is currently unauthenticated in prototypes

Why This Matters

  • Security: Prevents unauthorized nodes from connecting to the central aggregator
  • Trust: Establishes mutual identity between node and server
  • Auditability: Credential rotation and revocation create audit trails for compliance

Deferred Decision Options

Option A: Mutual TLS + API Keys (Defense in Depth)

Approach: Install mTLS certificates on node and central; additionally require per-request API keys.

Pros:

  • Strong double-layer authentication (certificate + key)
  • API keys can be easier to rotate than certificates
  • Compliant with zero-trust architecture patterns
  • Incident response: revoke key without reissuing certificate

Cons:

  • Operational complexity: manage two credential types
  • API keys typically live in config files → secret management dependency
  • Higher latency (validation of both cert and key)
  • Overkill for internal network (node and central on same physical system or adjacent servers)

Implementation:

  • Use certifi + requests with client certificates on node
  • FastAPI middleware validates certificate + extracts key from header
  • Annual certificate rotation; quarterly key rotation

Option B: Mutual TLS Only (Simpler)

Approach: Client and server both require valid TLS certificates; no additional API key layer.

Pros:

  • Simpler to operate: single credential type
  • Faster (no extra header parsing)
  • Standard practice for service-to-service comms
  • Certificate-only rotation has established tooling (let's encrypt automation, cert-manager in Kubernetes)

Cons:

  • Lost key = lost access (no secondary credential to fall back to)
  • If node private key is compromised, all impersonation until certificate revoked
  • API key layer useful for fine-grained per-user access control (backend team prefers this)

Implementation:

  • Python ssl module on node for client cert
  • FastAPI ssl_context for server-side enforcement
  • Automated certificate renewal (systemd timer on node)

ADR Master Index

This is the canonical registry for all unresolved and resolved architecture decisions across the rocket telemetry system.

ADR-002: Schema Governance & Compatibility Policy

Decision record for payload schema versioning, compatibility, and registry policy for mission payloads.

On this page

MetadataProblem / ContextCurrent StateWhy This MattersDeferred Decision OptionsOption A: Mutual TLS + API Keys (Defense in Depth)Option B: Mutual TLS Only (Simpler)