Foundation / checks (deploy) (push) Successful in 3m29s
Foundation / checks (ecs) (push) Successful in 2m0s
Foundation / checks (client) (push) Successful in 12m51s
Foundation / checks (network) (push) Successful in 13m0s
Foundation / checks (tsan) (push) Successful in 7m50s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 32m4s
Foundation / checks (postgres) (push) Canceled after 19m13s
ADR-0096. Session protocol v4 (v3 is deployed and frozen) adds HandoffOffer, SessionRedirect, close reasons handed_off and moved, and ghost marker records. Sessions use the durable probe record: logins open it where it was saved (redirected when it lives elsewhere), and session ends save it. A marker crossing into a neighbour's area is frozen, prepared, its control released and a signed ticket offered; uncommitted transfers are aborted after the ticket's lifetime. The destination shows arriving probes as ghosts (schema v13 incoming_probe_transfers) and opens the marker where it crossed. Refreshes the dev session window. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
157 lines
7.0 KiB
C++
157 lines
7.0 KiB
C++
#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.
|
|
};
|
|
// What the destination now owns: the account's control lease and the probe's state after
|
|
// the committed switch (its generation and position, in micrometres).
|
|
struct HandoffAdmission {
|
|
ControlLease lease;
|
|
std::uint64_t generation{};
|
|
std::int64_t x{}, y{};
|
|
};
|
|
class HandoffLedger {
|
|
public:
|
|
HandoffLedger() = default;
|
|
HandoffLedger(const HandoffLedger&) = delete;
|
|
HandoffLedger& operator=(const HandoffLedger&) = delete;
|
|
virtual ~HandoffLedger() = default;
|
|
[[nodiscard]] virtual std::expected<HandoffAdmission, HandoffLedgerError>
|
|
admit(const TicketClaims& ticket, std::uint64_t session) = 0;
|
|
|
|
protected:
|
|
HandoffLedger(HandoffLedger&&) = default;
|
|
HandoffLedger& operator=(HandoffLedger&&) = default;
|
|
};
|
|
} // namespace evo::network
|