Files
aevolution/docs/adr/0091-m10-session-identity-and-control.md
2026-10-08 12:08:53 -04:00

10 KiB

[Reviewed]

ADR-0091: M10 session identity, grants and control authority

Status

Accepted for M10.3 (2026-10-03). Decisions confirmed with the maintainer on 2026-10-03: ECDSA P-256 grants through Mbed TLS PSA; an identity adapter and grant issuer as a library (no service, no Steam yet); a newer grant replaces an account's existing session; unique control backed by a durable per-world control lease. Delivery: 10.3a grants, identity adapter and region session control (this text); 10.3b the QUIC session handshake; 10.3c the durable control lease. Each segment amends this ADR. The M9 dev path (ADR-0082/0083, protocol v1) is unchanged.

Context

ADR-0017 and NETWORK_ARCHITECTURE require short-lived world/region/account-scoped grants, reconnect that cannot duplicate control, secrets kept out of logs, and an identity provider independent of Steam. ADR-0089 fixed that reconnect is a new grant, a new session and a fresh baseline, and that no session survives an epoch change. M9 has only dev grants: HMAC-SHA256, a u64 subject, refusal of a second session per subject, single use remembered in a file ledger. No account backend exists, and no controllable organism exists yet (organisms arrive with M11).

Decision

Accounts. AccountId is 128 random bits assigned by the account directory and never derived from a provider id. Providers authenticate a credential to a ProviderSubject (provider kind plus opaque subject); the directory maps subjects to accounts. Logs and events may carry only log_label (the first four id bytes).

Grant format v1 (schemas/network/session-grant-v1.md): fixed 160 bytes, EVO-GRANT marker, version, environment byte, issuer key id, grant id, account, per-account serial, world/frame, region, issued/expiry seconds; ECDSA P-256 over SHA-256 of the first 96 bytes (Mbed TLS 4.1.1 PSA, already pinned; no new dependency). Issuers hold private keys (GrantSigningKey, non-exportable PSA keys); regions hold only public keys (GrantVerifier, at most 8 per environment for rotation), so a compromised region cannot mint grants. Verification checks the signature before any claim and then requires the signed environment byte to equal the verifier's.

Dev cannot reach production, by four independent checks: M9 dev grants have another marker and length; a dev-signed session grant carries the dev environment byte and fails in stage/World0 even if a dev public key were misconfigured there; DevTestProvider (credential dev-test:<name>, no secret) cannot be constructed outside dev; GrantIssuer refuses a provider and key from different environments.

Serials order grants; the newest wins. The directory issues per-account serials that strictly increase, with non-decreasing issued_at. A region accepts a grant only if its serial is greater than every serial it accepted for that account. This gives single use (replay is stale_grant) and makes an older unexpired grant, for example a stolen one, useless once a newer grant was presented. A region remembers an account's serial until the newest accepted issued_at plus its maximum lifetime, after which every older grant has expired.

Session control (SessionControl, per region, single owner, transport-neutral): environment, world, region, lifetime (default maximum 300 s), clock skew (30 s), expiry and serial checks; at most one session per account. A valid newer grant for an account that holds a session closes the old session first and reports it as superseded, so control is never shared and a dropped client reconnects without waiting for the 5 s liveness timeout. refresh renews the session in place with a newer grant (no reconnect or new baseline); a session closes when its grant expires. An epoch change closes every session. Bounds: sessions (32), tracked accounts (4,096; full fails closed rather than forgetting serials), and attempt rates: region-wide attempts before signature verification (64 per 60 s) and verified attempts per account (4 per 60 s), counted whether or not accepted. A refused open (capacity) does not consume the grant. These limits are engineering defaults, not game rules.

Identity adapter (evo_identity, library): IdentityProvider, AccountDirectory (bounded in-memory implementation for tests and tools), GrantIssuer (credential to signed grant, lifetime 1..14400 s). Production providers and a running issuer service are later work behind these interfaces.

Alternatives considered

Option Disposition
HMAC grants per environment Every region could forge grants for its environment.
Ed25519 Not in Mbed TLS; would need a new crypto dependency.
Refuse a second login (M9 behaviour) A silently dropped client waits for the liveness timeout; kept for M9 only.
Per-grant single-use set Does not stop an older unused grant (stolen) from taking control; serial ordering subsumes it.
Grant lifetime as session lifetime without refresh Short grants would force reconnects and fresh baselines every few minutes.

Consequences and limits (10.3a)

  • Serials and sessions are in memory: a restarted region process would accept an already-used, still-unexpired grant again (bounded by the 300 s lifetime), and two regions of one world could each admit the same account. The durable control lease (10.3c) closes both. Until then nothing deploys M10 sessions.
  • If a newer grant is stolen before its owner presents it, the thief can take control until the owner presents a still newer grant. Grants travel only inside TLS and are never logged; revocation (bans) and channel binding are not designed yet.
  • Private-key provisioning: GrantSigningKey::import takes a raw 32-byte P-256 scalar; a provisioning tool and secret handling come with the issuer service.

M10.3b implementation (2026-10-03)

Session protocol v1 session messages (session-v1): Hello (grant), Welcome, Refresh, RefreshResult and Close with a reason, each a fixed-size message with an EVSN header on the QUIC reliable stream.

  • Region side (RegionSessions, src/server/session): owns the QUIC endpoint, the verifier and SessionControl on the region host's thread. Hello deadline 5 s; region attempts counted before signature work; a takeover closes the previous connection with superseded before Welcome; grant expiry and epoch advances close sessions; every close sends Close and then closes the connection after a flush of at most 1 s. A peer that closes its own connection is reported as client_closed (the client's Close can be discarded by its own immediate close). Connections are bounded by the transport limit (at least the session limit; the rest is headroom for logins and closes still flushing). Events carry account log labels only.
  • Client side (RegionSessionClient, src/client/session): sends Hello when the pinned connection is up and then zeroes its copy of the grant; Welcome deadline 5 s; refresh in place; any Close, malformed message, deadline or transport loss ends the session.
  • Not yet wired into evo-server or the engineering client: they keep the M9 dev path until the durable control lease (10.3c) exists, so nothing deploys M10 sessions.

M10.3c durable account control (2026-10-03)

Schema v10 (migrations/0010_account_control.sql) keeps one row per world and account: the highest grant serial any region of the world accepted, and the region session holding control, with a fencing generation and a database-time expiry. The runtime reaches it only through claim_account_control, renew_account_control and release_account_control; each first requires the caller's exact unexpired region lease (lock order: upgrade lock, region lease row, account control row).

  • Serials are durable and world-wide. A claim with a serial not above the stored one is stale_grant, so a replayed or older grant fails after a region restart and in every other region of the world. This closes the 10.3a limits.
  • Newest grant wins across regions without overlap. A claim may take control from an unexpired holder in another region; it then returns that holder's remaining database time as a wait, and the region delays Welcome until the wait has passed (the old holder stops before its own expiry, as with region leases, and its next renewal is fenced). Control held by the claimant's own region needs no wait: under the current epoch the region closes its own session, and an older epoch's holder stopped before the current region lease could be acquired.
  • Session layer: ControlLedger (transport-neutral interface) with a PostgreSQL implementation (PostgresControlLedger, Linux). RegionSessions with a ledger runs check() (no side effects), then the durable claim, then local admission; renews every 5 s; closes with superseded when its control is fenced (another region accepted a newer grant) without releasing it, and with shutdown when renewals cannot be confirmed before its local deadline (send time plus granted duration minus a 2 s margin). Refresh records the newer serial for the same session. Close and transport loss release control. Durations: 20 s control, 5 s renewal, 2 s margin (as for region leases).
  • Organism binding is not part of v10: no controllable organism exists yet. It is added by a later migration when organisms arrive, under the same row and fencing.
  • Not yet wired into evo-server or the engineering client (both keep the M9 dev path); that integration comes with 10.4, so nothing deploys M10 sessions yet.

Amendment (M10.5c, 2026-10-06): grant bundles and a dev grant lifetime

  • Bundles. evo-session-probe grants signs 1-64 grants for one account in one file (concatenated 160-byte grants, created new, owner-only), all issued now with consecutive serials. Without --serial the first serial is 64 x the issue time in seconds, so a later bundle for the account supersedes an earlier one without bookkeeping. The issuer key stays with the operator; testers receive only the bundle and the dev CA. Grants cannot be dated ahead (clock skew 30 s), so a bundle expires as a whole.
  • Lifetime. The 300 s maximum would make a bundle unusable after five minutes. The evo-server flag --m10-max-grant-lifetime 60..14400 raises the region's maximum, refused at startup outside dev; without it the 300 s default stands. A session ends when its grant expires; the client then reconnects with the next grant of the bundle, which succeeds only while that grant is still valid.
  • Not changed: World0/stage issuance (no production identity provider yet), refresh within a session, durable serial rules.