Files
aevolution/include/evo/network/protocol.hpp
T
dingoandClaude Opus 5.5 8fbe093cc8 Implement M9.6 narrow secure dev-session protocol
Add protocol v1: versioned, bounded frames (Hello, Welcome, Intent,
IntentResult, environment/organism views, Close) carrying session, epoch
and commit watermark, with an explicit little-endian canonical codec, a
header-first FrameReader, seeded mutation tests and a libFuzzer target.
SessionAdmission enforces world/region scope, grant lifetime and skew,
single-use grants, one session per subject, epoch, replay, tick window
and per-session rate.

Dev identity is a 108-byte HMAC-SHA256 grant (PSA) that cannot be
created or verified outside the dev environment. Transport security is
TLS 1.3 only via pinned Mbed TLS 4.1.1 LTS with TLS 1.2, DTLS, tickets
and PSK compiled out, AEAD suites, ECDHE groups and a pinned dev CA.
Opt-in EVO_BUILD_NETWORK, new network CI suite. Sockets and region
integration follow in M9.7. ADR-0082 records the decision.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:53:55 -04:00

150 lines
5.7 KiB
C++

#pragma once
#include "evo/client/environment_view.hpp"
#include "evo/client/input.hpp"
#include "evo/client/organism_view.hpp"
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <optional>
#include <span>
#include <utility>
#include <vector>
// M9.6 dev session protocol v1 (schemas/view/dev-session-v1.md, ADR-0082).
// Explicit little-endian fields only: no native struct is ever copied to or from
// the wire. Transport-neutral; the M9 channel carries frames inside TLS 1.3.
namespace evo::network {
inline constexpr std::uint32_t frame_magic = 0x53445645; // Bytes "EVDS".
inline constexpr std::uint16_t protocol_version = 1;
inline constexpr std::size_t frame_header_bytes = 12;
inline constexpr std::size_t max_frame_payload = std::size_t{256} * 1024;
inline constexpr std::size_t max_grant_bytes = 512;
enum class MessageType : std::uint8_t {
hello = 1,
welcome,
intent,
intent_result,
environment_view,
organism_view,
close
};
enum class ProtocolError : std::uint8_t {
truncated,
bad_magic,
unsupported_version,
unknown_type,
reserved_flags,
oversized,
malformed,
invalid_value,
trailing_bytes,
unsupported_feature,
wrong_type
};
// A decoded frame borrows its payload from the input bytes.
struct FrameView {
MessageType type;
std::span<const std::uint8_t> payload;
};
struct OwnedFrame {
MessageType type;
std::vector<std::uint8_t> payload;
};
// Exactly one complete frame; trailing bytes reject.
[[nodiscard]] std::expected<FrameView, ProtocolError>
decode_frame(std::span<const std::uint8_t> bytes);
[[nodiscard]] std::vector<std::uint8_t> encode_frame(MessageType type,
std::span<const std::uint8_t> payload);
// Accumulates a byte stream into frames. The header is validated as soon as it is
// buffered, so an oversized or foreign frame is rejected before its payload is read.
// Holds at most one frame (header + max payload). Errors latch.
class FrameReader {
public:
// Consumes bytes up to the end of the current frame; returns how many were taken.
[[nodiscard]] std::expected<std::size_t, ProtocolError>
feed(std::span<const std::uint8_t> bytes);
// The completed frame, if any; reading it resets the reader for the next frame.
[[nodiscard]] std::optional<OwnedFrame> take();
private:
std::vector<std::uint8_t> buffer_;
std::size_t expected_{frame_header_bytes};
std::optional<ProtocolError> error_;
};
// Client -> server. `required_features` must be zero in v1; the grant is opaque here.
struct Hello {
std::uint32_t required_features{};
std::vector<std::uint8_t> grant;
};
// Server -> client. Session ids identify, they do not authenticate (the channel does).
struct Welcome {
std::uint64_t session{}, world{}, frame{}, region{}, epoch{};
std::uint64_t server_tick{}, commit_watermark{}, grant_expires_at{};
std::uint32_t intent_window{}, window_ticks{}, max_intents_per_window{};
};
// Client -> server: one bounded movement intention (client::Intention on the wire).
struct IntentMessage {
std::uint64_t session{}, epoch{}, sequence{}, tick{};
std::int16_t move_x{}, move_y{};
};
enum class IntentStatus : std::uint8_t {
admitted,
unknown_session,
stale_epoch,
expired,
invalid_vector,
replayed,
outside_window,
rate_limited
};
// "admitted" means accepted for scheduling at `tick`, not simulated or durable.
struct IntentResult {
std::uint64_t sequence{};
IntentStatus status{};
std::uint64_t server_tick{};
};
// Every view names the session/epoch it belongs to and the durable commit watermark.
struct ViewHeader {
std::uint64_t session{}, epoch{}, server_tick{}, commit_watermark{}, baseline{};
};
enum class CloseReason : std::uint8_t {
normal,
unsupported_version,
malformed,
unauthenticated,
expired,
duplicate_session,
stale_epoch,
rate_limited,
server_shutdown
};
[[nodiscard]] std::expected<std::vector<std::uint8_t>, ProtocolError> encode(const Hello& m);
[[nodiscard]] std::vector<std::uint8_t> encode(const Welcome& m);
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentMessage& m);
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentResult& m);
[[nodiscard]] std::vector<std::uint8_t> encode(CloseReason reason);
[[nodiscard]] std::vector<std::uint8_t> encode(const ViewHeader& header,
const client::EnvironmentPresentation& view);
[[nodiscard]] std::vector<std::uint8_t> encode(const ViewHeader& header,
const client::OrganismPresentation& view);
// Decoders take a complete frame and check its type. Views are rebuilt through the
// validated presentation constructors, never trusted as decoded.
[[nodiscard]] std::expected<Hello, ProtocolError> decode_hello(FrameView frame);
[[nodiscard]] std::expected<Welcome, ProtocolError> decode_welcome(FrameView frame);
[[nodiscard]] std::expected<IntentMessage, ProtocolError> decode_intent(FrameView frame);
[[nodiscard]] std::expected<IntentResult, ProtocolError> decode_intent_result(FrameView frame);
[[nodiscard]] std::expected<CloseReason, ProtocolError> decode_close(FrameView frame);
[[nodiscard]] std::expected<std::pair<ViewHeader, client::EnvironmentPresentation>, ProtocolError>
decode_environment_view(FrameView frame);
[[nodiscard]] std::expected<std::pair<ViewHeader, client::OrganismPresentation>, ProtocolError>
decode_organism_view(FrameView frame);
[[nodiscard]] IntentMessage make_intent(std::uint64_t session, std::uint64_t epoch,
const client::Intention& intention) noexcept;
} // namespace evo::network