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>
This commit is contained in:
@@ -0,0 +1,95 @@
|
||||
#pragma once
|
||||
#include "evo/network/protocol.hpp"
|
||||
#include "evo/world/chunks.hpp"
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <vector>
|
||||
|
||||
// Server-side session admission for the M9.6 dev session (ADR-0082). Transport-
|
||||
// neutral and single-owner: the host serializes calls. It admits intentions for
|
||||
// scheduling only; the simulation still validates and decides every outcome.
|
||||
namespace evo::network {
|
||||
enum class DeploymentEnvironment : std::uint8_t { dev, stage, world0 };
|
||||
// Claims a dev grant carries; meaningful only once verified.
|
||||
struct DevGrantClaims {
|
||||
std::uint64_t grant_id{}, subject{};
|
||||
world::WorldIdentity world;
|
||||
std::uint64_t region{}, issued_at{}, expires_at{}; // Server clock, seconds.
|
||||
};
|
||||
class DevGrantKey;
|
||||
// Only DevGrantKey::verify constructs this, so admission cannot be handed
|
||||
// unauthenticated claims by accident.
|
||||
class VerifiedGrant {
|
||||
public:
|
||||
[[nodiscard]] const DevGrantClaims& claims() const noexcept {
|
||||
return claims_;
|
||||
}
|
||||
|
||||
private:
|
||||
friend class DevGrantKey;
|
||||
explicit VerifiedGrant(DevGrantClaims claims) : claims_{claims} {}
|
||||
DevGrantClaims claims_;
|
||||
};
|
||||
struct AdmissionConfig {
|
||||
world::WorldIdentity world;
|
||||
std::uint64_t region{}, epoch{};
|
||||
std::size_t max_sessions{16};
|
||||
std::size_t max_remembered_grants{4096};
|
||||
std::uint32_t intent_window{8}; // Ticks ahead of the server tick.
|
||||
std::uint32_t window_ticks{8}; // Rate window length.
|
||||
std::uint32_t max_intents_per_window{16}; // Counts every attempt by a session.
|
||||
std::uint64_t max_grant_lifetime{3600}; // Seconds.
|
||||
std::uint64_t clock_skew{30}; // Seconds tolerated before issued_at.
|
||||
};
|
||||
enum class AdmissionError : std::uint8_t {
|
||||
invalid_config,
|
||||
wrong_world,
|
||||
wrong_region,
|
||||
invalid_lifetime,
|
||||
not_yet_valid,
|
||||
expired,
|
||||
grant_reused,
|
||||
duplicate_subject,
|
||||
sessions_full,
|
||||
grants_full,
|
||||
unknown_session
|
||||
};
|
||||
class SessionAdmission {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<SessionAdmission, AdmissionError>
|
||||
create(AdmissionConfig config);
|
||||
// Single-use grants: a grant id is remembered until it expires. A subject may hold
|
||||
// one session; a second open is refused (control is never duplicated).
|
||||
[[nodiscard]] std::expected<Welcome, AdmissionError> open(const VerifiedGrant& grant,
|
||||
std::uint64_t now_seconds,
|
||||
std::uint64_t server_tick,
|
||||
std::uint64_t commit_watermark);
|
||||
[[nodiscard]] IntentResult admit(const IntentMessage& intent, std::uint64_t server_tick,
|
||||
std::uint64_t now_seconds);
|
||||
[[nodiscard]] std::expected<void, AdmissionError> close(std::uint64_t session);
|
||||
// New ownership epoch: existing sessions become stale and must reconnect.
|
||||
[[nodiscard]] std::expected<void, AdmissionError> advance_epoch(std::uint64_t epoch);
|
||||
[[nodiscard]] std::size_t sessions() const noexcept {
|
||||
return sessions_.size();
|
||||
}
|
||||
[[nodiscard]] std::uint64_t epoch() const noexcept {
|
||||
return config_.epoch;
|
||||
}
|
||||
|
||||
private:
|
||||
struct Session {
|
||||
std::uint64_t id{}, subject{}, epoch{}, expires_at{}, last_sequence{};
|
||||
std::uint64_t window_start{};
|
||||
std::uint32_t attempts{};
|
||||
};
|
||||
struct Remembered {
|
||||
std::uint64_t grant_id{}, expires_at{};
|
||||
};
|
||||
explicit SessionAdmission(AdmissionConfig config) : config_{config} {}
|
||||
AdmissionConfig config_;
|
||||
std::uint64_t next_session_{1};
|
||||
std::vector<Session> sessions_;
|
||||
std::vector<Remembered> grants_;
|
||||
};
|
||||
} // namespace evo::network
|
||||
@@ -0,0 +1,50 @@
|
||||
#pragma once
|
||||
#include "evo/network/admission.hpp"
|
||||
#include <array>
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <span>
|
||||
|
||||
// Dev-only session grants for the M9 engineering client (ADR-0082). A grant is a
|
||||
// fixed 108-byte record ("EVO-DEV-ONLY" marker, version, environment byte, claims)
|
||||
// authenticated with HMAC-SHA256 from Mbed TLS PSA. It is not an account system,
|
||||
// cannot be created or verified outside DeploymentEnvironment::dev, and never
|
||||
// appears in logs. Production identity remains the M10.3 identity-provider adapter.
|
||||
namespace evo::network {
|
||||
inline constexpr std::size_t dev_grant_bytes = 108;
|
||||
inline constexpr std::size_t dev_key_bytes = 32;
|
||||
using DevGrant = std::array<std::uint8_t, dev_grant_bytes>;
|
||||
enum class GrantError : std::uint8_t {
|
||||
not_dev_environment,
|
||||
invalid_key,
|
||||
invalid_claims,
|
||||
malformed,
|
||||
wrong_marker,
|
||||
unsupported_version,
|
||||
wrong_environment,
|
||||
bad_tag,
|
||||
crypto
|
||||
};
|
||||
// Owns an imported PSA HMAC key (non-exportable). Move-only; destroys the key.
|
||||
class DevGrantKey {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<DevGrantKey, GrantError>
|
||||
import(DeploymentEnvironment environment, std::span<const std::uint8_t> secret);
|
||||
DevGrantKey(DevGrantKey&& other) noexcept;
|
||||
DevGrantKey& operator=(DevGrantKey&& other) noexcept;
|
||||
DevGrantKey(const DevGrantKey&) = delete;
|
||||
DevGrantKey& operator=(const DevGrantKey&) = delete;
|
||||
~DevGrantKey();
|
||||
// Structural claim checks only (nonzero ids/scope, ordered times); admission
|
||||
// applies the clock, lifetime, world/region and single-use rules.
|
||||
[[nodiscard]] std::expected<DevGrant, GrantError> issue(const DevGrantClaims& claims) const;
|
||||
// Constant-time tag check before any claim is trusted.
|
||||
[[nodiscard]] std::expected<VerifiedGrant, GrantError>
|
||||
verify(std::span<const std::uint8_t> grant) const;
|
||||
|
||||
private:
|
||||
explicit DevGrantKey(std::uint32_t key) : key_{key} {}
|
||||
std::uint32_t key_; // PSA key id; zero when moved-from.
|
||||
};
|
||||
} // namespace evo::network
|
||||
@@ -0,0 +1,149 @@
|
||||
#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
|
||||
@@ -0,0 +1,66 @@
|
||||
#pragma once
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <memory>
|
||||
#include <span>
|
||||
#include <string>
|
||||
#include <string_view>
|
||||
|
||||
// TLS 1.3 channel over caller-owned non-blocking byte transport (ADR-0082). The
|
||||
// M9.7 socket adapter supplies the transport; tests use in-memory pipes. No Mbed TLS
|
||||
// type crosses this header. One owner thread per channel.
|
||||
namespace evo::network {
|
||||
enum class TransportError : std::uint8_t { closed, failed };
|
||||
class ByteTransport {
|
||||
public:
|
||||
virtual ~ByteTransport() = default;
|
||||
// Bytes moved; zero means "would block". Errors end the channel.
|
||||
[[nodiscard]] virtual std::expected<std::size_t, TransportError>
|
||||
write(std::span<const std::uint8_t> bytes) = 0;
|
||||
[[nodiscard]] virtual std::expected<std::size_t, TransportError>
|
||||
read(std::span<std::uint8_t> bytes) = 0;
|
||||
};
|
||||
// PEM inputs are secrets (key) or trust anchors; never logged or retained as text.
|
||||
struct ServerCredentials {
|
||||
std::string certificate_chain_pem;
|
||||
std::string private_key_pem;
|
||||
};
|
||||
struct ClientTrust {
|
||||
std::string authority_pem; // Pinned dev CA; the system trust store is not used.
|
||||
std::string server_name; // Checked against the certificate.
|
||||
};
|
||||
enum class TlsError : std::uint8_t {
|
||||
credentials,
|
||||
configuration,
|
||||
handshake,
|
||||
peer_verification,
|
||||
transport,
|
||||
closed,
|
||||
record
|
||||
};
|
||||
enum class TlsProgress : std::uint8_t { done, want_io };
|
||||
class TlsChannel {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<std::unique_ptr<TlsChannel>, TlsError>
|
||||
server(const ServerCredentials& credentials, ByteTransport& transport);
|
||||
[[nodiscard]] static std::expected<std::unique_ptr<TlsChannel>, TlsError>
|
||||
client(const ClientTrust& trust, ByteTransport& transport);
|
||||
TlsChannel(const TlsChannel&) = delete;
|
||||
TlsChannel& operator=(const TlsChannel&) = delete;
|
||||
~TlsChannel();
|
||||
[[nodiscard]] std::expected<TlsProgress, TlsError> handshake();
|
||||
// Zero means "would block". Errors latch until destruction.
|
||||
[[nodiscard]] std::expected<std::size_t, TlsError> send(std::span<const std::uint8_t> bytes);
|
||||
[[nodiscard]] std::expected<std::size_t, TlsError> receive(std::span<std::uint8_t> bytes);
|
||||
[[nodiscard]] std::expected<TlsProgress, TlsError> close();
|
||||
// Negotiated "TLSv1.3" and suite name after a completed handshake.
|
||||
[[nodiscard]] std::string_view version() const noexcept;
|
||||
[[nodiscard]] std::string_view suite() const noexcept;
|
||||
|
||||
private:
|
||||
struct Impl;
|
||||
explicit TlsChannel(std::unique_ptr<Impl> impl);
|
||||
std::unique_ptr<Impl> impl_;
|
||||
};
|
||||
} // namespace evo::network
|
||||
Reference in New Issue
Block a user