Add M10.8b signed handoff tickets and ticket admission
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m55s
Foundation / checks (client) (push) Successful in 12m40s
Foundation / checks (postgres) (push) Canceled after 4s
Foundation / checks (network) (push) Successful in 12m53s
Foundation / checks (tsan) (push) Successful in 7m55s
Foundation / checks (checks) (push) Successful in 31m47s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m55s
Foundation / checks (client) (push) Successful in 12m40s
Foundation / checks (postgres) (push) Canceled after 4s
Foundation / checks (network) (push) Successful in 12m53s
Foundation / checks (tsan) (push) Successful in 7m55s
Foundation / checks (checks) (push) Successful in 31m47s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
ADR-0096. A source region's handoff key signs a 160-byte ticket for one probe transfer, account and destination; it rides the Hello grant slot and is verified against neighbour keys bound to their regions. SessionControl admits a ticket once per region, superseding like a grant, with the session ending at the client's original grant expiry. RegionSessions makes the destination's durable step first: PostgresHandoffLedger stages and commits the transfer and moves the account's control, idempotently. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,149 @@
|
||||
#pragma once
|
||||
#include "evo/network/session_control.hpp"
|
||||
#include "evo/network/session_grant.hpp"
|
||||
#include <array>
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <span>
|
||||
#include <vector>
|
||||
|
||||
// M10.8b handoff tickets v1 (ADR-0096, schemas/network/handoff-ticket-v1.md): a fixed
|
||||
// 160-byte record ("EVO-HANDOFF" marker, version, environment, key id, claims) signed by the
|
||||
// SOURCE region with its own handoff key (ECDSA P-256/SHA-256, Mbed TLS PSA), naming one
|
||||
// committed-to-be transfer, its account and its one destination. It travels in the Hello
|
||||
// grant slot: the marker only routes it to this verifier, and nothing in it is trusted
|
||||
// before its signature verifies against a key registered for the claimed source region.
|
||||
// Region handoff keys never sign grants and the grant issuer never signs tickets (distinct
|
||||
// markers). Ticket bytes and keys have no log form.
|
||||
namespace evo::network {
|
||||
inline constexpr std::size_t handoff_ticket_bytes = 160;
|
||||
inline constexpr std::uint64_t max_ticket_lifetime = 120; // Seconds a ticket may be valid.
|
||||
using HandoffTicket = std::array<std::uint8_t, handoff_ticket_bytes>;
|
||||
using TransferId = std::array<std::uint8_t, 16>;
|
||||
struct TicketClaims {
|
||||
TransferId transfer{};
|
||||
AccountId account;
|
||||
world::WorldIdentity world;
|
||||
std::uint64_t source{}, destination{};
|
||||
// Server clock, seconds (u32 on the wire, valid to 2106): when the ticket stops being
|
||||
// accepted, and when the session it opens must end (the client's grant expiry at the
|
||||
// source, so a crossing never extends a session).
|
||||
std::uint32_t expires_at{}, session_expires_at{};
|
||||
};
|
||||
enum class HandoffTicketError : std::uint8_t {
|
||||
invalid_key,
|
||||
duplicate_key,
|
||||
too_many_keys,
|
||||
invalid_claims,
|
||||
malformed,
|
||||
wrong_marker,
|
||||
unsupported_version,
|
||||
wrong_environment,
|
||||
unknown_key,
|
||||
wrong_source, // Signed by a key registered for another region than the claimed source.
|
||||
wrong_scope, // Another world or another destination than this region.
|
||||
expired, // Ticket or session expiry passed, or a lifetime beyond the maximum.
|
||||
bad_signature,
|
||||
crypto
|
||||
};
|
||||
// Marker check only (unauthenticated): routes a Hello to ticket verification.
|
||||
[[nodiscard]] bool looks_like_handoff_ticket(std::span<const std::uint8_t> bytes) noexcept;
|
||||
|
||||
// A region's handoff signing key (PSA, non-exportable private part). Move-only.
|
||||
class HandoffSigningKey {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<HandoffSigningKey, HandoffTicketError>
|
||||
generate(DeploymentEnvironment environment, std::uint32_t key_id);
|
||||
[[nodiscard]] static std::expected<HandoffSigningKey, HandoffTicketError>
|
||||
import(DeploymentEnvironment environment, std::uint32_t key_id,
|
||||
std::span<const std::uint8_t> private_key);
|
||||
HandoffSigningKey(HandoffSigningKey&& other) noexcept;
|
||||
HandoffSigningKey& operator=(HandoffSigningKey&& other) noexcept;
|
||||
HandoffSigningKey(const HandoffSigningKey&) = delete;
|
||||
HandoffSigningKey& operator=(const HandoffSigningKey&) = delete;
|
||||
~HandoffSigningKey();
|
||||
// Structural checks only (nonzero ids and scope, source != destination, ordered times).
|
||||
[[nodiscard]] std::expected<HandoffTicket, HandoffTicketError>
|
||||
sign(const TicketClaims& claims) const;
|
||||
[[nodiscard]] std::expected<GrantPublicKey, HandoffTicketError> public_key() const;
|
||||
|
||||
private:
|
||||
HandoffSigningKey(DeploymentEnvironment environment, std::uint32_t key_id, std::uint32_t key)
|
||||
: environment_{environment}, key_id_{key_id}, key_{key} {}
|
||||
DeploymentEnvironment environment_;
|
||||
std::uint32_t key_id_;
|
||||
std::uint32_t key_; // PSA key id; zero when moved-from.
|
||||
};
|
||||
|
||||
class HandoffVerifier;
|
||||
// Only HandoffVerifier::verify constructs this, after signature, source, scope and times.
|
||||
class VerifiedHandoffTicket {
|
||||
public:
|
||||
[[nodiscard]] const TicketClaims& claims() const noexcept {
|
||||
return claims_;
|
||||
}
|
||||
|
||||
private:
|
||||
friend class HandoffVerifier;
|
||||
explicit VerifiedHandoffTicket(const TicketClaims& claims) : claims_{claims} {}
|
||||
TicketClaims claims_;
|
||||
};
|
||||
|
||||
// Destination-side verifier: this region's world and id, and the handoff public keys of the
|
||||
// regions it may receive from (up to 32, each bound to one source region).
|
||||
class HandoffVerifier {
|
||||
public:
|
||||
static constexpr std::size_t max_keys = 32;
|
||||
[[nodiscard]] static std::expected<HandoffVerifier, HandoffTicketError>
|
||||
create(DeploymentEnvironment environment, world::WorldIdentity world, std::uint64_t region);
|
||||
HandoffVerifier(HandoffVerifier&& other) noexcept;
|
||||
HandoffVerifier& operator=(HandoffVerifier&& other) noexcept;
|
||||
HandoffVerifier(const HandoffVerifier&) = delete;
|
||||
HandoffVerifier& operator=(const HandoffVerifier&) = delete;
|
||||
~HandoffVerifier();
|
||||
[[nodiscard]] std::expected<void, HandoffTicketError>
|
||||
add_key(std::uint64_t source_region, std::uint32_t key_id,
|
||||
std::span<const std::uint8_t> public_key);
|
||||
// Signature first; then marker, version, environment, the key's region equal to the
|
||||
// claimed source, this world and region as destination, and the times at `now_seconds`.
|
||||
[[nodiscard]] std::expected<VerifiedHandoffTicket, HandoffTicketError>
|
||||
verify(std::span<const std::uint8_t> ticket, std::uint64_t now_seconds) const;
|
||||
|
||||
private:
|
||||
struct Key {
|
||||
std::uint64_t region{};
|
||||
std::uint32_t key_id{}, key{};
|
||||
};
|
||||
HandoffVerifier(DeploymentEnvironment environment, world::WorldIdentity world,
|
||||
std::uint64_t region)
|
||||
: environment_{environment}, world_{world}, region_{region} {}
|
||||
void destroy() noexcept;
|
||||
DeploymentEnvironment environment_;
|
||||
world::WorldIdentity world_;
|
||||
std::uint64_t region_;
|
||||
std::vector<Key> keys_;
|
||||
};
|
||||
// The destination's durable side of a ticket login (ADR-0096): stage and commit the ticket's
|
||||
// transfer under this region's lease, then take the account's durable control for
|
||||
// `session` (handoff_account_control). The region host implements it over PostgreSQL;
|
||||
// tests use fakes. Renewal and release then go through the ControlLedger.
|
||||
enum class HandoffLedgerError : std::uint8_t {
|
||||
refused, // The transfer is unknown, aborted, or not this region's: never admit.
|
||||
fenced, // This region's lease is not current.
|
||||
unavailable // Not decided (database unreachable, timeout, unknown outcome): retry later.
|
||||
};
|
||||
class HandoffLedger {
|
||||
public:
|
||||
HandoffLedger() = default;
|
||||
HandoffLedger(const HandoffLedger&) = delete;
|
||||
HandoffLedger& operator=(const HandoffLedger&) = delete;
|
||||
virtual ~HandoffLedger() = default;
|
||||
[[nodiscard]] virtual std::expected<ControlLease, HandoffLedgerError>
|
||||
admit(const TicketClaims& ticket, std::uint64_t session) = 0;
|
||||
|
||||
protected:
|
||||
HandoffLedger(HandoffLedger&&) = default;
|
||||
HandoffLedger& operator=(HandoffLedger&&) = default;
|
||||
};
|
||||
} // namespace evo::network
|
||||
@@ -37,6 +37,7 @@ struct GrantClaims {
|
||||
std::uint64_t region{}, issued_at{}, expires_at{}; // Server clock, seconds.
|
||||
};
|
||||
class GrantVerifier;
|
||||
class VerifiedHandoffTicket; // M10.8b, handoff_ticket.hpp.
|
||||
// Only GrantVerifier::verify constructs this, after the signature and environment checked.
|
||||
class VerifiedSessionGrant {
|
||||
public:
|
||||
@@ -107,6 +108,15 @@ class SessionControl {
|
||||
// session is closed first and reported as superseded. Control is never shared.
|
||||
[[nodiscard]] std::expected<OpenedSession, ControlError> open(const VerifiedSessionGrant& grant,
|
||||
std::uint64_t now_seconds);
|
||||
// M10.8b (ADR-0096): a verified handoff ticket opens a session here, the destination,
|
||||
// for its account. A ticket is single-use per region (its transfer is remembered until
|
||||
// the ticket expires), counts as an attempt like a grant, supersedes like a grant, and
|
||||
// the session ends at the ticket's session expiry, capped at the maximum grant lifetime
|
||||
// from now: a crossing never extends a session. Serials are unchanged.
|
||||
[[nodiscard]] std::expected<void, ControlError>
|
||||
check_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds) const;
|
||||
[[nodiscard]] std::expected<OpenedSession, ControlError>
|
||||
open_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds);
|
||||
// In-session renewal with a newer grant for the same account: extends the expiry
|
||||
// without a reconnect or new baseline.
|
||||
[[nodiscard]] std::expected<std::uint64_t, ControlError>
|
||||
@@ -139,6 +149,12 @@ class SessionControl {
|
||||
[[nodiscard]] bool forgettable(const Account& account, std::uint64_t now_seconds) const;
|
||||
[[nodiscard]] std::expected<Account*, ControlError> admit(const VerifiedSessionGrant& grant,
|
||||
std::uint64_t now_seconds);
|
||||
[[nodiscard]] std::optional<ControlError> ticket_error(const VerifiedHandoffTicket& ticket,
|
||||
std::uint64_t now_seconds) const;
|
||||
struct UsedTicket {
|
||||
std::array<std::uint8_t, 16> transfer{};
|
||||
std::uint64_t until{};
|
||||
};
|
||||
void accept(Account& account, const GrantClaims& claims);
|
||||
void forget_idle(std::uint64_t now_seconds);
|
||||
ControlConfig config_;
|
||||
@@ -146,6 +162,7 @@ class SessionControl {
|
||||
std::uint64_t region_window_start_{};
|
||||
std::uint32_t region_attempts_{};
|
||||
std::vector<Account> accounts_;
|
||||
std::vector<UsedTicket> used_tickets_; // At most max_accounts, pruned at expiry.
|
||||
};
|
||||
|
||||
// Durable per-world account control (10.3c, schema v10). The region host implements it
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
#pragma once
|
||||
#include "evo/network/handoff_ticket.hpp"
|
||||
#include "evo/persistence/probe_store.hpp"
|
||||
#include "evo/server/pg_slot.hpp"
|
||||
#include <chrono>
|
||||
#include <functional>
|
||||
#include <optional>
|
||||
#include <utility>
|
||||
|
||||
// M10.8b destination side of a ticket login over PostgreSQL (ADR-0096, schema v12). Linux
|
||||
// only; owned by the region host's thread, on its own connection slot. For a verified ticket:
|
||||
// stage its transfer under the host's current lease (again after a restart), commit it (the
|
||||
// authority switch), then take the account's durable control for the session. Every step is
|
||||
// idempotent, so a retried ticket login after an undecided outcome converges. A transfer that
|
||||
// is unknown, aborted, for another account or another region is refused.
|
||||
namespace evo::server {
|
||||
class PostgresHandoffLedger final : public network::HandoffLedger {
|
||||
public:
|
||||
using LeaseSource = std::function<std::optional<persistence::LeaseGrant>()>;
|
||||
PostgresHandoffLedger(PgSlot& db, persistence::RegionKey key, LeaseSource lease,
|
||||
std::chrono::milliseconds duration = std::chrono::milliseconds{20000},
|
||||
std::chrono::milliseconds timeout = std::chrono::milliseconds{2000})
|
||||
: db_{&db}, key_{key}, lease_{std::move(lease)}, duration_{duration}, timeout_{timeout} {}
|
||||
[[nodiscard]] std::expected<network::ControlLease, network::HandoffLedgerError>
|
||||
admit(const network::TicketClaims& ticket, std::uint64_t session) override;
|
||||
|
||||
private:
|
||||
PgSlot* db_;
|
||||
persistence::RegionKey key_;
|
||||
LeaseSource lease_;
|
||||
std::chrono::milliseconds duration_, timeout_;
|
||||
};
|
||||
} // namespace evo::server
|
||||
@@ -1,4 +1,5 @@
|
||||
#pragma once
|
||||
#include "evo/network/handoff_ticket.hpp"
|
||||
#include "evo/network/intent_admission.hpp"
|
||||
#include "evo/network/probe_motion.hpp"
|
||||
#include "evo/network/quic_transport.hpp"
|
||||
@@ -33,6 +34,10 @@
|
||||
// M10.6 (ADR-0094, EXPERIMENT): once the host sets a motion area, every established session
|
||||
// has a probe marker; admitted intentions schedule its movement, each poll advances markers
|
||||
// to the simulated tick, and snapshots carry them. A new epoch starts without markers.
|
||||
// M10.8b (ADR-0096): a Hello may carry a handoff ticket instead of a grant (same slot,
|
||||
// another marker). A ticket verified against a neighbour's key for this region opens a
|
||||
// session for its account after the HandoffLedger durably staged and committed its transfer
|
||||
// and moved the account's control here.
|
||||
// With a ControlLedger, control is durable and unique per world: a session that loses its
|
||||
// durable control (another region accepted a newer grant) closes with `superseded`, and
|
||||
// one whose control cannot be renewed in time closes with `shutdown`.
|
||||
@@ -41,6 +46,12 @@ struct IssuerKey {
|
||||
std::uint32_t key_id{};
|
||||
network::GrantPublicKey public_key{};
|
||||
};
|
||||
// A neighbouring region's handoff public key (ADR-0096): tickets it signs are accepted here.
|
||||
struct HandoffKey {
|
||||
std::uint64_t source_region{};
|
||||
std::uint32_t key_id{};
|
||||
network::GrantPublicKey public_key{};
|
||||
};
|
||||
struct RegionSessionsConfig {
|
||||
network::quic::ServerConfig transport;
|
||||
network::ControlConfig control; // `epoch` is the initial ownership epoch.
|
||||
@@ -57,6 +68,11 @@ struct RegionSessionsConfig {
|
||||
// Durable action records (10.4b), owned by the host; null keeps outcomes in memory only.
|
||||
network::ActionLedger* actions{};
|
||||
network::ReplicationLimits replication{}; // max_sessions follows control.max_sessions.
|
||||
// M10.8b handoff tickets (ADR-0096): neighbours' keys, and the durable side owned by the
|
||||
// host. Without keys every ticket is refused (unauthenticated). With a ControlLedger a
|
||||
// ticket also needs a HandoffLedger (control must move durably with the transfer).
|
||||
std::vector<HandoffKey> handoff_keys;
|
||||
network::HandoffLedger* handoff{};
|
||||
};
|
||||
// The region host's authority, read once per poll.
|
||||
struct HostFacts {
|
||||
|
||||
Reference in New Issue
Block a user