ADR-007: mTLS Full Chain Verification

Status: Accepted Date: 2026-03 Deciders: Platform team (platform-0043, T560)

Context

The Arbitex Platform exposes internal API routes (/v1/internal/) that accept inbound connections from Hybrid Outposts and other internal services authenticated via mTLS (mutual TLS). The server validates the client certificate against a configured CA.

The original configuration accepted a single root CA certificate path (CLOUD_CA_CERT_PATH) and an optional separate intermediate CA path (CLOUD_CA_INTERMEDIATE_PATH). This two-field configuration model has limitations in practice:

Multi-level intermediate chains — some PKI hierarchies use two intermediate CA levels (root → intermediate-1 → intermediate-2 → leaf). The two-field model cannot express this.
Operational friction — rotating a CA requires updating two separate configuration fields and redeploying, with risk of misconfiguration if only one field is updated.
Inconsistency with standard tooling — most PKI tooling (step-ca, Let’s Encrypt, internal CAs) produces a single PEM bundle containing the full chain as concatenated certificates.

Decision

Introduce MTLS_CA_BUNDLE — a single PEM file that may contain one or more CA certificates (root + optional intermediates) concatenated. When set, this takes precedence over the legacy CLOUD_CA_CERT_PATH + CLOUD_CA_INTERMEDIATE_PATH configuration.

The bundle is parsed into a trusted CA pool, and incoming leaf certificates are verified against that pool using standard chain verification. Any number of intermediate CA levels is supported.

The legacy two-field configuration remains supported for backward compatibility and is used when MTLS_CA_BUNDLE is not set.

Consequences

Positive:

Supports arbitrarily deep PKI hierarchies (multi-level intermediate chains).
Simplifies CA rotation: replace one file, no configuration field changes needed.
Consistent with how most PKI tooling exports CA chains (concatenated PEM format).
New deployments can use a single environment variable for the complete trust anchor.

Negative / trade-offs:

Operators who currently use CLOUD_CA_CERT_PATH + CLOUD_CA_INTERMEDIATE_PATH do not need to migrate — the legacy configuration continues to work. However, new documentation emphasises MTLS_CA_BUNDLE as the recommended configuration.
A malformed bundle (invalid PEM, wrong certificate type) will cause mTLS verification to fail for all connections — the fail-closed behaviour means internal routes become unavailable rather than silently allowing unauthenticated connections.
The bundle file must be kept up to date when the CA chain changes. An expired CA certificate in the bundle causes all outpost heartbeats and policy syncs to fail.

Configuration:

MTLS_CA_BUNDLE — path to PEM bundle (recommended).
CLOUD_CA_CERT_PATH — root CA path (legacy fallback).
CLOUD_CA_INTERMEDIATE_PATH — intermediate CA path (legacy, optional).