Files
aevolution/docs/adr/0082-dev-session-transport.md
T
2026-10-08 12:08:53 -04:00

5.8 KiB

[Reviewed]

ADR-0082: Narrow secure dev-session protocol and transport security

Status

Accepted for M9.6/M9.7 engineering development sessions only. It is a scoped application of ADR-0017; the M10 realtime transport (QUIC/DATAGRAM vs DTLS plus owned reliability) remains open. The dev identity is never valid outside dev.

Context

M9 must connect a desktop client to one authoritative dev region. NETWORK_ARCHITECTURE locks server authority, untrusted clients, no custom cryptography, explicit wire decoding, short-lived scoped grants, replay windows and rate/byte caps, and requires the maintained implementation, exact version, license, cipher configuration and threat review to be named. Production identity (M10.3) does not exist yet; a test identity must not be able to escape into stage or World0.

Decision

Transport security. TLS 1.3 over a reliable byte stream (TCP in M9.7) with Mbed TLS 4.1.1 (LTS branch supported until March 2029; upstream BRANCHES.md and release notes checked 2026-10-01), used under the Apache-2.0 option of its dual license. The release tarball (bundling TF-PSA-Crypto) is pinned by SHA-256 3359a349…375c98c, matching upstream's published checksum file (same GitHub release origin, so this proves integrity of what was reviewed, not independent provenance). tools/prepare-mbedtls.cmake prepares it explicitly; EVO_BUILD_NETWORK opts in; static libraries only; headless/server/client builds never evaluate it otherwise.

Owned build restriction (third_party/mbedtls/evo_mbedtls_config.h, enforced by a compile-time check): TLS 1.2, DTLS, renegotiation, session tickets and TLS 1.3 PSK modes are compiled out. Runtime profile: TLS 1.3 only; suites TLS_AES_128_GCM_SHA256 and TLS_CHACHA20_POLY1305_SHA256; groups X25519 and secp256r1; ephemeral key exchange only; no early data or resumption. The client requires a server certificate chaining to a pinned dev CA and matching the configured server name; the system trust store is not used. Clients present no certificate: identity is the dev grant inside the channel.

Dev identity. A fixed 108-byte grant: EVO-DEV-ONLY marker, version, a dev environment byte, grant id, subject, world/frame, region, issued/expiry seconds, and an HMAC-SHA256 tag computed and checked (constant time) by PSA with a 32-byte non-exportable key. DevGrantKey::import refuses any environment but dev. VerifiedGrant is constructible only by verification. Admission enforces world/region scope, maximum lifetime (default one hour), clock skew, single use (remembered until expiry; fail closed when full) and one session per subject. Reconnect needs a fresh grant. This is not an account system.

Protocol v1 (schemas/view/dev-session-v1.md, include/evo/network/protocol.hpp): 12-byte header (magic, version, type, zero flags, length <= 256 KiB) and seven messages: Hello, Welcome (session, world/frame, region, epoch, server tick, commit watermark, limits), Intent (session, epoch, sequence, tick, bounded vector), IntentResult, EnvironmentView and OrganismView (session, epoch, server tick, commit watermark, baseline plus the M9.4/9.5 presentations), Close. Fields are explicit little-endian; decoders are bounds-checked and views are rebuilt through validated presentation constructors. Unknown versions, types, flags, required features and enum values reject. A streaming FrameReader validates headers before buffering payloads. Admission orders checks: rate (every attempt counts), epoch, expiry, vector norm <= 1000, strictly increasing sequence, tick window. "Admitted" means eligible for scheduling, never simulated or durable.

Alternatives considered

Option Disposition
System OpenSSL 3 (already linked by the Linux persistence adapter) Strong option for Linux servers; no equivalent on the Windows client without a separate Perl/NASM build or a second TLS stack (Schannel). One stack on both ends is simpler for this scope.
Mbed TLS 3.6.7 LTS Support ends March 2027, within the expected M9-M10 lifetime.
QUIC library (e.g. msquic) Fits M10's datagram questions; large dependency and its own TLS integration before any realtime measurements exist. Deferred to M10.1.
libsodium primitives with an owned handshake Requires designing key exchange/authentication: rejected by ADR-0017.
Plain TCP for dev Unauthenticated protocol could escape into production; rejected.
Protobuf/FlatBuffers codec Codegen dependency for seven small messages; explicit codec is reviewable and fuzzed.

No performance comparison was measured; the choice rests on maintenance window, platform build (CMake, no Perl/Python needed for release tarballs), license and attack-surface reduction.

Benefits

Maintained AEAD/ECDHE implementation with a reduced compiled surface; explicit, fuzzed, canonical codec; replay/rate/epoch admission testable without sockets; dev identity unusable outside dev by construction.

Costs

Static crypto library build (~2.7 MB of static archives on MSVC), certificate/key management for the dev region, TCP head-of-line behaviour (acceptable for one dev engineering client, not measured for M10).

Risks

Dev CA/HMAC key leakage allows dev impersonation (dev only; rotate by redeploying secrets). Session ids identify but do not authenticate; M9.7 must bind a session to its TLS connection. Rate limits are per message, not per byte; M9.7 adds connection byte/time limits. Upstream advisories require prompt pin updates (the July 2026 releases fixed several TLS issues, some in code compiled out here).

Consequences

Amended by ADR-0083 before deployment: v1 also carries IntentOutcome (type 8) and close reason capacity. M9.7 adds sockets, server/client session adapters, dev secret provisioning and reconnect semantics. Pin upgrades change version, hash and this ADR together and rerun the network suite. M10 reopens transport selection with measurements.