feat(client): add rendezvous traversal coordinators (#12)

Closes #11

.gitea/workflows/ci.yml

@@ -30,5 +30,8 @@ jobs:
       - name: Build
         run: dotnet build Rendezvous.slnx --configuration Release --no-restore
 
+      - name: Verify generated API contract
+        run: git diff --exit-code -- docs/api
+
       - name: Test
         run: dotnet test Rendezvous.slnx --configuration Release --no-build

Directory.Packages.props

@@ -5,7 +5,11 @@
   </PropertyGroup>
   <ItemGroup>
     <PackageVersion Include="LiteNetLib" Version="2.1.4" />
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.ApiDescription.Server" Version="10.0.9" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.4.0" />
+    <PackageVersion Include="Microsoft.OpenApi" Version="2.7.5" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.10" />
     <PackageVersion Include="xunit" Version="2.9.3" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
   </ItemGroup>

README.md

@@ -79,6 +79,10 @@ Rendezvous is currently in its initial design and bootstrap stage. The first imp
 
 The ratified v1 boundaries, trust decisions, privacy rules, safety budgets, and
 threat model are indexed in [the architecture documentation](docs/architecture/README.md).
+The frozen v1 wire surface is documented in the
+[HTTP, UDP, and generated OpenAPI contracts](docs/contracts/README.md).
+Tenant policy, publisher/operator principals, and production key custody are
+defined in [game provisioning and signing-key lifecycle](docs/security/provisioning.md).
 
 ## Development
 
@@ -95,5 +99,9 @@ dotnet test Rendezvous.slnx --configuration Release --no-build
 Run the bootstrap server with
 `dotnet run --project src/FinalFactory.Rendezvous.Server`. It serves HTTP health endpoints and binds
 the configured UDP mediator port; both stop through normal host cancellation.
+The launch profile uses an ephemeral development-only signing key. Production
+startup fails closed until externally supplied game policies and `env:` signing
+key references resolve to valid key material; no reusable game secret is stored
+in this repository or the public Client package.
 The project dependency rules and supported runtime choices are documented in
 [project and dependency boundaries](docs/architecture/project-boundaries.md).

docs/architecture/0003-state-privacy-availability-and-budgets.md

@@ -64,7 +64,7 @@ them but must not raise them without security review.
 | Browser page | 100 listings and 256 KiB encoded response; opaque cursor; stable bounded sort |
 | UDP datagram accepted | 1,200 bytes; oversized or fragmented application payloads are dropped without response |
 | Opaque HTTP credential | 1,024 bytes encoded |
-| UDP capability or ticket | 768 bytes encoded, with the complete datagram still at most 1,200 bytes |
+| UDP capability or connection ticket | 192 base64url characters; NAT punch capabilities also remain below LiteNetLib's 256-character token ceiling; complete datagram at most 1,200 bytes |
 | Clock skew | 30 seconds maximum when validating issued/not-before/expiry times |
 | Lease lifetime | 60 seconds; renewal accepted from 30 seconds; no client-selected extension |
 | Host presence freshness | 20 seconds |

docs/architecture/0004-atomic-ephemeral-state.md

@@ -0,0 +1,101 @@
+# ADR 0004: atomic ephemeral state and single-active availability
+
+- Status: Accepted
+- Date: 2026-07-16
+- Tracking: #6
+
+## Context
+
+Listings, leases, endpoint observations, join attempts, and replay decisions must
+move together. A partially committed authorization can expose an expired listing,
+reuse a capability, or introduce an endpoint that was never authorized. V1 is a
+single-active service, so it needs honest bounded in-memory behavior rather than
+a database-shaped abstraction that implies unavailable durability or scale.
+
+## Decision
+
+`IEphemeralRendezvousStore` is the atomic boundary for directory, lease, presence,
+attempt, endpoint, replay, revocation, and drain transitions. The v1 implementation
+serializes each transition under one process-local lock. This deliberately favors
+simple, auditable correctness at the initial 25,000-listing/10,000-attempt ceiling.
+It retains only immutable listing data, opaque credential fingerprints, observed
+endpoints, monotonic deadlines, and bounded idempotency/replay records.
+
+Every collection has an independent configured ceiling. An operation checks all
+of the capacity it needs before changing any collection. Exhaustion returns
+`CapacityExceeded`; it does not evict live state, partially insert an operation,
+or grow a fallback queue. Policy-provided per-owner listing and per-tenant active
+attempt quotas are evaluated inside the same creation transition, so concurrent
+requests cannot pass a check performed outside the store. New join authorization returns `ServiceUnavailable`
+when the atomic store is unavailable and `Draining` once drain starts.
+
+### Time and cleanup
+
+Expiry uses an injected monotonic clock. Wall time is used only to return an
+informational `ExpiresAt` value. Moving the wall clock forward or backward cannot
+expire or prolong authority. Cleanup runs deterministically at the start of every
+store operation and removes presence, attempts, listings, replay entries,
+idempotency records, and revocations at their deadline. Removal of a listing also
+removes its presence handle and every linked attempt before another caller can
+observe the store.
+
+### Concurrency and idempotency
+
+- Listing registration and join-attempt creation use a tenant-and-owner-scoped idempotency
+  key plus a canonical request fingerprint. An exact duplicate returns the
+  original live result; reuse with different input returns `Conflict`; replay
+  after the resource has expired returns `Expired` until the bounded idempotency
+  record itself expires. Configuration requires idempotency retention to cover
+  every listing and attempt lifetime, preventing a live duplicate after eviction.
+- Lease renewal is compare-and-swap by version. A stale renewal returns the latest
+  version as `Conflict`. Renew/delete races are serialized: renewal either commits
+  before deletion or observes the listing as absent.
+- Host presence refresh is an atomic whole-endpoint replacement because NAT
+  mappings can legitimately change. Attempt capabilities are different: the
+  first endpoint bound for each role wins, an identical datagram is idempotent,
+  and a different replay is rejected. Introduction is consumed once atomically.
+- Cancellation is checked before waiting for the lock and again after acquiring
+  it. A cancellation observed at either point makes no change. Once a synchronous
+  transition starts, it completes atomically and does not expose partial state.
+
+### Visibility and revocation
+
+A listing is visible or joinable only when its lease and authenticated UDP host
+presence are both fresh. Public browsing is tenant/protocol scoped, excludes
+unlisted sessions, and uses a stable listing-ID order with the contract page
+ceiling. Revoking a listing or principal removes every listing, presence, and
+attempt path in the same transition. A revocation is inserted before removal;
+if the bounded revocation pool is full, the operation rejects without deleting
+anything.
+
+### Restart and graceful drain
+
+A process restart creates a new store instance ID and starts empty. Old listing,
+lease, attempt, endpoint, idempotency, and consumption state is not recovered.
+Publishers must re-register; old callers receive typed `NotFound`, `Expired`, or
+`ServiceUnavailable` outcomes rather than an ambiguous success. No database is
+required or supported for the single-active MVP.
+
+Drain is idempotent. It immediately rejects new registrations, attempts, and
+lease extensions, while already-created attempts may bind endpoints and consume
+their introduction during the configured window (at most 30 seconds). At the
+deadline all active state is cleared atomically. Readiness is false while draining
+or unavailable, and application shutdown starts drain before teardown.
+
+## Future shared-store mapping
+
+The interface uses explicit typed outcomes, TTLs, compare-and-swap versions,
+idempotency records, and all-or-nothing multi-record transitions. A future Redis
+implementation therefore requires authenticated transport, tenant-prefixed keys,
+server-side scripts or transactions for each transition, TTLs based on the store's
+authoritative time, and deterministic mediator routing. It must preserve these
+semantics and pass the same contract tests before issue #18 may enable more than
+one active instance.
+
+## Consequences
+
+- V1 has deterministic failure and restart behavior without durable gameplay state.
+- A single lock is a measured capacity constraint, not a claim of horizontal scale.
+- Transport and HTTP modules cannot bypass the store for authorization decisions.
+- Operational code must treat `CapacityExceeded`, `Draining`, and
+  `ServiceUnavailable` as normal typed overload/availability outcomes.

docs/architecture/0005-session-lease-lifecycle.md

@@ -0,0 +1,93 @@
+# ADR 0005: authenticated session lease and presence lifecycle
+
+- Status: Accepted
+- Date: 2026-07-16
+- Tracking: #7
+
+## Context
+
+A host needs to publish a player-facing session without letting an HTTP request
+claim a public endpoint or remain visible after the gameplay socket disappears.
+Registration retries must be safe, credentials must remain opaque, and policy or
+ownership checks cannot race state mutation.
+
+## Decision
+
+The four host HTTP operations require `Authorization: Bearer <publisher credential>`.
+The signed principal supplies the authoritative game, environment, publisher trust
+mode, subject, and allowed regions. Request fields never widen that scope. Creation
+and update apply the enabled `GamePolicy` to exact protocol, region, visibility,
+bounded display/build/capacity values, and the allowlisted metadata schema.
+
+Capacity reported by a host is advisory directory information. Rendezvous bounds
+and publishes it but never treats it as final admission authority; the game host
+still decides identity, bans, reserved slots, and whether a connection may join.
+
+```mermaid
+stateDiagram-v2
+    [*] --> AwaitingPresence: authorized register
+    AwaitingPresence --> Listed: valid host UDP presence
+    Listed --> AwaitingPresence: presence deadline passes
+    AwaitingPresence --> AwaitingPresence: lease renew or data update
+    Listed --> Listed: lease renew, data update, or presence refresh
+    AwaitingPresence --> Removed: lease expiry or delete
+    Listed --> Removed: lease expiry or delete
+    Removed --> [*]
+```
+
+Registration returns a listing ID, lease ID/token, host-presence handle/capability,
+lease expiry, a 30-second renewal suggestion, and a 10-second presence-refresh
+suggestion. The authoritative ceilings remain 60 seconds for the lease and 20
+seconds for presence. Timing suggestions are server-controlled, not client-selected.
+
+The lease token and presence capability are 256-bit opaque values derived with
+HMAC-SHA256 from an in-memory per-process secret, a purpose label, the publisher
+subject, the idempotency key, a canonical request fingerprint, and a random
+per-registration derivation salt. Opaque IDs use separate purpose labels. Exact
+retries read the retained non-secret salt and therefore reproduce the original
+response without retaining plaintext credentials. Once the bounded idempotency
+record expires, a new salt rotates IDs and capabilities so an old token cannot
+regain authority. Metadata order is canonicalized before fingerprinting. The store
+retains the salt and only a second keyed fingerprint of each token. Restart rotates
+the derivation secret while the matching ephemeral state disappears.
+
+Renew, update, and delete require both the same publisher subject and the lease
+capability. Cross-owner or wrong-capability access returns the same not-found shape.
+Update may change display name, build label, advisory capacity, and metadata only;
+game, environment, region, protocol, visibility, trust mode, and opaque IDs remain
+canonical. Delete is idempotent and does not reveal whether another publisher owns
+the supplied ID.
+
+### UDP presence
+
+Only a structurally valid frozen `HostPresence` envelope or native LiteNetLib
+host-presence request with the issued capability can refresh presence. The public
+endpoint is the UDP packet's observed source on the host's gameplay socket; the
+HTTP API never accepts one. The bounded local candidate comes from the authenticated
+packet. Invalid or unknown inputs receive no response. ADR 0009 defines the later
+attempt-role use of frozen `ClientPresence` and native host/client requests.
+Presence expiry demotes public visibility but keeps the lease, so the same handle
+can restore visibility without changing session identity.
+
+Public listing responses contain bounded listing data only. They never contain
+public/local endpoints, lease tokens, presence capabilities, fingerprints, store
+keys, or canonical player identity.
+
+## Failure semantics
+
+- malformed or policy-invalid fields return a stable typed `InvalidRequest`;
+- an unsupported gameplay protocol returns `IncompatibleProtocol`;
+- missing/invalid publisher authentication returns `AuthenticationRequired`;
+- cross-scope authorization returns `Forbidden` without resource disclosure;
+- wrong owner/capability or expired state returns the tenant-hidden `NotFound`;
+- idempotency reuse with changed input returns `Conflict`;
+- publisher/global exhaustion returns `CapacityExceeded`; and
+- drain or loss of atomic state returns `ServiceUnavailable` and authorizes no join.
+
+## Consequences
+
+- HTTP registration alone can never make a public session browseable.
+- Plaintext session capabilities are returned to the intended host but are not
+  retained, logged, included in public listing DTOs, or exported as metrics.
+- Re-registration after restart is the recovery path; there is no durable session
+  identity or gameplay state in Rendezvous.

docs/architecture/0006-compatible-session-browser.md

@@ -0,0 +1,51 @@
+# ADR 0006: bounded compatible session browser
+
+- Status: Accepted
+- Date: 2026-07-16
+- Tracking: #8
+
+## Decision
+
+The public list endpoint requires game, environment, and exact gameplay protocol.
+Region is optional, page size is 1–100, and callers may exclude sessions whose
+advisory current-player count has reached the advertised maximum. Lists contain
+public sessions only and only while both lease and authenticated host presence are
+fresh. Unlisted sessions never appear in a list; they may be retrieved directly by
+their 128-bit unguessable listing ID only when the caller also supplies the exact
+game, environment, and protocol scope.
+
+Results use ascending opaque listing ID as a deterministic keyset. A cursor carries
+the last ID plus every compatibility/filter field, a five-minute expiry, and an
+HMAC-SHA256 signature under a per-process key. Tampering, expiry, or reuse with a
+different tenant/protocol/region/full filter returns `InvalidRequest`. Restart
+rotates the key, matching the loss of ephemeral listings.
+
+Pagination is a bounded live view, not a database snapshot. A record that remains
+eligible and whose ID is greater than the cursor is returned exactly once. Records
+removed or made stale disappear immediately. A record created after a page whose ID
+sorts before that page's cursor is outside that traversal; callers refresh from the
+first page to discover new sessions. This avoids skips or duplicates among stable
+eligible records without retaining per-browser snapshot state.
+
+The store reads at most page size plus one record. The service serializes against
+the 256 KiB response ceiling and shortens a page before returning it when metadata
+makes the requested count too large. A continuation cursor is emitted whenever an
+extra or byte-trimmed record remains. All cursor, page, metadata, property, scalar,
+and collection sizes are bounded before untrusted allocation can grow without a
+ceiling.
+
+Browser DTOs are fresh copies containing only opaque listing ID, exact compatibility,
+region, visibility/trust presentation, advisory capacity, build/display labels, and
+policy-validated string metadata. They contain no observed endpoint, lease,
+capability, ticket, credential fingerprint, derivation salt, principal subject, or
+store key. Metadata is display text: JSON encoding escapes markup, but game UI must
+still render values as text and must never execute markup, interpret endpoints, or
+use metadata for authorization.
+
+## Consequences
+
+- Cross-game, cross-environment, incompatible, stale, revoked, expired, unlisted,
+  and optionally full sessions are removed before response construction.
+- Direct unlisted lookup is suitable for an out-of-band invite carrying the opaque
+  ID; human join codes remain future work and require their own bounded abuse model.
+- Host capacity remains advisory. The host makes the final admission decision.

docs/architecture/0007-caller-owned-dotnet-client-sdk.md

@@ -0,0 +1,53 @@
+# ADR 0007: caller-owned .NET publisher and browser SDK
+
+- Status: Accepted
+- Date: 2026-07-16
+- Tracking: #9
+
+## Decision
+
+The .NET client package exposes separate publisher and browser interfaces plus
+concrete clients over a caller-supplied `HttpClient`. The caller owns that client,
+its handler, base address, connection pool, proxy, and lifetime. SDK operations
+dispose every request, response, and response body they create, but never dispose
+the supplied client. The package targets `netstandard2.1`, depends only on the
+wire-contract package and LiteNetLib, and contains no Godot types, global client,
+service URL, publisher secret, or embedded game credential.
+
+Every operation returns `RendezvousClientResult<T>` with a stable error code,
+message, and optional retry guidance. Cancellation remains exceptional through
+the caller's `CancellationToken`; transport failures become `ServiceUnavailable`.
+Response bodies are streamed under the contract's 256 KiB browser ceiling before
+deserialization. Invalid or oversized success bodies become `InternalError` and
+never escape as partially trusted contract objects.
+
+The SDK retries only operations whose duplicate execution is safe: scoped reads,
+idempotency-keyed registration, lease renewal with the same lease token, complete
+resource update, and lease-token deregistration. It honors bounded server retry
+guidance and otherwise uses capped exponential backoff with jitter. Each retry
+creates a fresh HTTP request while preserving the caller's registration
+idempotency key. Configuration is copied on construction so later option mutation
+cannot change an in-flight client's behavior.
+
+`PublishedSession` holds the server-issued lease and presence capabilities needed
+by the host. Its string representation always redacts them. Update requests are
+copied before the lease token is attached, so the SDK never mutates caller-owned
+DTOs. The browser exposes one-page calls and bounded cursor traversal; cursor
+values remain opaque and caller requests remain unchanged.
+
+Lease maintenance is explicit. Creating a `SessionLeaseMaintainer` starts no task;
+the game chooses when to call `RunAsync`, owns cancellation, and awaits
+`DisposeAsync`. The loop uses the latest server-provided renewal interval and
+returns a distinct cancelled, disposed, lost-lease, or failed result. Terminal
+authorization, expiry, and missing-lease responses also raise `LeaseLost` so the
+host can stop advertising or re-register deliberately.
+
+## Consequences
+
+- SpaceGame and Unscouted can inject the publisher/browser interfaces in tests
+  without an engine runtime or real network.
+- Games must configure an absolute `HttpClient.BaseAddress` (or equivalent
+  handler routing), obtain publisher credentials from their deployment boundary,
+  and explicitly run and dispose lease maintenance.
+- The versioned client public-API snapshot and live-server integration tests fail
+  together when SDK and HTTP contracts drift.

docs/architecture/0008-scoped-join-attempts-and-tickets.md

@@ -0,0 +1,78 @@
+# ADR 0008: scoped join attempts and one-time connection tickets
+
+- Status: Accepted
+- Date: 2026-07-16
+- Tracking: #10
+
+## Decision
+
+Join creation is an unauthenticated public operation because v1 does not treat a
+Rendezvous caller as game identity. The HTTP source address is normalized and
+converted to a process-keyed opaque subject for idempotency and bounded policy
+accounting; raw addresses and the derived subject are never returned or logged.
+A successful request means only that this network client may try to connect to
+this active session. It does not reserve capacity or grant gameplay admission.
+
+Creation validates the v1 contract, caller idempotency key, enabled tenant policy,
+exact gameplay protocol, listing scope, live lease, and fresh authenticated host
+presence in one atomic store operation. A listing advertised as full remains
+joinable because its player count is advisory and the game host owns the final
+capacity, identity, ban, and admission decision.
+
+Each attempt derives independent host-punch, client-punch, and connection-ticket
+credentials plus opaque attempt and mediation IDs from a process-ephemeral HMAC
+key, the client subject, the complete canonical request fingerprint, a fresh salt,
+and a purpose/role label. Credentials are 32-byte base64url values (43 characters),
+below both the 192-character Rendezvous capability ceiling and LiteNetLib's
+256-character NAT token ceiling. The connection ticket uses half of that payload
+for its attempt ID and half for an independently derived 128-bit authenticator, so
+the SDK can correlate concurrent introductions without increasing UDP response
+size. State retains keyed credential fingerprints, derivation inputs, and salt—not
+issued plaintext. All diagnostic string representations redact credentials and
+derivation material.
+
+The client receives only its punch capability. A host polls its own listing with
+the lease token in `X-Rendezvous-Lease-Token` and receives only host-role
+capabilities through a signed, listing-bound, five-minute cursor. Replaying an
+identical join request returns the same live attempt; changing the request under
+the same owner/key conflicts. A client may cancel with its punch capability in
+`X-Rendezvous-Client-Punch-Capability`; cancellation atomically marks the attempt
+and retains a bounded tombstone until its original expiry. Host polling returns
+that tombstone so a coordinator can revoke any local ticket authorization, while
+endpoint binding, introduction, ticket issuance, and ticket consumption all
+reject the cancelled attempt. Listing deletion, expiry, revocation, or process
+restart removes every associated attempt and credential fingerprint.
+
+Endpoint binding remains role- and capability-specific. The first endpoint
+observed for a role wins atomically; an exact UDP duplicate is idempotent, while
+endpoint or role substitution is rejected. An introduction is consumable once
+only after both roles bind, so concurrent attempts for the same listing cannot
+cross-wire.
+
+The connection ticket is distinct from both punch capabilities and is reproduced
+only after introduction succeeds. Its window begins at that moment and lasts at
+most 20 seconds without outliving the 30-second attempt. The server has an atomic
+fingerprint-consumption seam for mediator tests and revocation. On the game host,
+the SDK's bounded `ConnectionTicketValidator` stores a process-keyed digest,
+accepts an exact ticket once under a lock, rejects altered/cross-attempt/expired/
+revoked/replayed tickets, and zeroes retained digests and key material on disposal.
+Issue #11 carries the fixed-size ticket in the authenticated introduction. Issue
+#12 extracts its embedded attempt ID, bounds the host's local authorization window
+by both the host-polled attempt expiry and the configured ticket lifetime, then
+wires one-time consumption into the caller-owned coordinator. Both peers receive
+a digest of the exact expected ticket over HTTP and reject any syntactically valid
+but unauthenticated introduction token. Embedding the ID prevents concurrent or
+late introductions from cross-binding a valid ticket while preserving the
+mediator's 2.0 response-byte amplification ceiling.
+
+## Consequences
+
+- A join attempt is transport authorization, never proof of player identity or a
+  game slot.
+- Network-address-derived subjects are process-local abuse/idempotency scopes,
+  not stable user identifiers; stronger authenticated player scopes require a
+  future game-owned identity contract.
+- Cancellation after a ticket has reached a host must also revoke that host's
+  local validator entry; coordinator wiring owns that race in issue #12.
+- Capability and ticket plaintext never enter browser results, state snapshots,
+  logs, metrics, or generated string representations.

docs/architecture/0009-authenticated-litenet-nat-mediator.md

@@ -0,0 +1,68 @@
+# ADR 0009: authenticated bounded LiteNetLib NAT mediator
+
+- Status: Accepted
+- Date: 2026-07-16
+- Tracking: #11
+
+## Decision
+
+The server owns one LiteNetLib `NetManager` and its `NatPunchModule` on the
+configured UDP endpoint. It runs in manual mode with a configured maximum number
+of datagrams per poll and a short caller-owned poll interval. LiteNetLib events
+are unsynchronized so authenticated requests are processed immediately on that
+single polling path rather than accumulated in an unbounded event queue. The
+mediator never accepts a LiteNetLib gameplay connection or handles application
+payloads.
+
+The packet layer also consumes the frozen v1 presence envelope on the same
+socket. Native NAT requests use a canonical fixed-size 192-character token that
+binds a role (`HostPresence`, attempt `Host`, or attempt `Client`), mediation
+handle, and the already-issued capability. Both transports enter one processor
+and the same atomic store operations. No transport-supplied public address is
+trusted; the socket source is authoritative.
+
+LiteNetLib's native NAT packet family also contains introduction-response and
+punch frames that are appropriate for peers but unsafe on a public mediator: a
+forged response can name arbitrary destinations. The packet layer therefore
+decodes only the pinned `NatIntroduceRequest` wire shape and consumes every
+inbound packet before `NatPunchModule` sees it. The module is outbound-only and
+may send introductions solely from a completed authorized plan.
+
+Listing presence refreshes authorize no response. Attempt contributions bind the
+first observed endpoint for exactly one capability role. Exact duplicates are
+idempotent; a different endpoint, the opposite role, an expired/cancelled
+attempt, or a stale listing presence cannot replace it. The introduction is
+consumed atomically only after both roles bind and their observed address
+families match, preventing concurrent attempts for one listing from cross-wiring.
+
+A reported local candidate is eligible only when it is RFC 1918 IPv4 or IPv6
+unique-local unicast, matches the observed family, and both peers have the same
+observed public address. Otherwise `NatIntroduce` receives the observed public
+endpoint in the local slot. Loopback, link-local, multicast, unspecified,
+documentation IPv6, global-address claims, and cross-family claims are never
+disclosed as local targets. IPv4 is required; observed global IPv6 can be used
+when both peers contribute IPv6, without claiming guaranteed IPv6 NAT traversal.
+
+The introduction carries only the distinct connection ticket and is emitted at
+most once to each verified observed endpoint. The fixed authenticated native
+request and bounded frozen envelope keep the combined response bytes within the
+2.0 verified amplification budget; unauthenticated inputs receive zero bytes.
+Malformed, truncated, oversized, spoofed, or unrelated LiteNetLib packets do not
+grow Rendezvous state. Raw endpoints and credentials are never logged or exposed
+through diagnostic string representations.
+
+Frozen IPv6 listing-presence refresh remains valid because it emits no response.
+IPv6 attempt roles require the fixed-size native LiteNetLib request; accepting the
+short frozen envelope would exceed the 2.0 byte budget for two IPv6 introduction
+frames. The required IPv4 listen address and optional IPv6 listen address are
+configured separately so enabling one family never widens the other family to a
+wildcard bind.
+
+## Consequences
+
+- Hosts refresh listing presence and answer invitations from their actual
+  gameplay socket; a separate mediator socket would observe the wrong mapping.
+- Caller-owned SDK coordination in #12 must poll the host invitation endpoint,
+  send the corresponding native role token, and consume the returned ticket.
+- UDP loss can prevent traversal, but it cannot cause an arbitrary destination,
+  replay, role substitution, or cross-attempt introduction.

docs/architecture/README.md

@@ -6,8 +6,16 @@ decision requires a superseding ADR and corresponding contract/test updates.
 - [ADR 0001: v1 control-plane boundaries and domain](0001-v1-control-plane-boundaries.md)
 - [ADR 0002: publisher trust, discovery, compatibility, and fallback](0002-publisher-trust-and-connection-policy.md)
 - [ADR 0003: state, privacy, availability, and safety budgets](0003-state-privacy-availability-and-budgets.md)
+- [ADR 0004: atomic ephemeral state and single-active availability](0004-atomic-ephemeral-state.md)
+- [ADR 0005: authenticated session lease and presence lifecycle](0005-session-lease-lifecycle.md)
+- [ADR 0006: bounded compatible session browser](0006-compatible-session-browser.md)
+- [ADR 0007: caller-owned .NET publisher and browser SDK](0007-caller-owned-dotnet-client-sdk.md)
+- [ADR 0008: scoped join attempts and one-time connection tickets](0008-scoped-join-attempts-and-tickets.md)
+- [ADR 0009: authenticated bounded LiteNetLib NAT mediator](0009-authenticated-litenet-nat-mediator.md)
 - [Threat model](../security/threat-model.md)
 - [Security promise and test matrix](../security/control-matrix.md)
+- [Versioned HTTP and UDP contracts](../contracts/README.md)
+- [Game provisioning and signing-key lifecycle](../security/provisioning.md)
 
 These decisions intentionally leave gameplay authority, player identity,
 simulation, persistence, social features, skill matchmaking, and gameplay

docs/architecture/project-boundaries.md

@@ -11,11 +11,13 @@ FinalFactory.Rendezvous.Server     FinalFactory.Rendezvous.TestClient
 
 - `Contracts` targets `netstandard2.1` and contains only versioned,
   transport-neutral IDs and wire contracts. It cannot reference Server,
-  LiteNetLib, or Godot.
+  LiteNetLib, or Godot. Its only package is `System.Text.Json`, used for the
+  canonical cross-runtime JSON contract.
 - `Client` targets `netstandard2.1`, references Contracts and the pinned
   LiteNetLib package, and contains no Godot or Server dependency.
-- `Server` targets .NET 10 LTS, references Contracts and LiteNetLib, and owns
-  HTTP hosting, UDP mediation, application policy, and ephemeral state.
+- `Server` targets .NET 10 LTS, references Contracts, LiteNetLib, and the
+  first-party ASP.NET Core OpenAPI generator, and owns HTTP hosting, UDP
+  mediation, application policy, and ephemeral state.
 - `TestClient` targets .NET 8, references only the public Client/Contracts seams
   and LiteNetLib, and must never reach into Server internals.
 - `Tests` target .NET 10 and may reference every project solely to verify public
@@ -32,6 +34,8 @@ engine, transport, or server dependency therefore fails the normal test gate.
   .NET 8-or-later runtime used by current Godot 4 C# projects.
 - TestClient runtime: .NET 8.
 - LiteNetLib: 2.1.4, pinned centrally and restored from the lock files.
+- Microsoft.OpenApi: patched 2.7.5 line, centrally pinned because the version
+  originally pulled by the .NET 10 generator is affected by CVE-2026-49451.
 
 The repository uses central package versions, per-project lock files,
 deterministic compilation, nullable reference types, warnings as errors, current
@@ -43,3 +47,5 @@ Primary compatibility references:
 - [.NET support policy](https://dotnet.microsoft.com/en-us/platform/support/policy)
 - [Godot stable C# prerequisites](https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_basics.html)
 - [LiteNetLib 2.1.4 on NuGet](https://www.nuget.org/packages/LiteNetLib/2.1.4)
+- [ASP.NET Core OpenAPI generation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview?view=aspnetcore-10.0)
+- [Microsoft.OpenApi security advisory](https://github.com/advisories/GHSA-v5pm-xwqc-g5wc)

docs/contracts/README.md

@@ -0,0 +1,18 @@
+# Versioned contracts
+
+Tracking: #4
+
+The v1 contract is defined by three artifacts that are reviewed and versioned
+together:
+
+- [HTTP v1 semantics](http-v1.md)
+- [UDP v1 wire format](udp-v1.md)
+- [Generated OpenAPI 3.1 document](../api/rendezvous-v1.json)
+
+The public .NET types live in `FinalFactory.Rendezvous.Contracts`, target
+`netstandard2.1`, and contain no Server, Godot, or LiteNetLib dependency. Golden
+vectors and a public-API snapshot make accidental wire or source compatibility
+changes fail the normal test gate.
+
+Any incompatible change requires a new contract version. Additive JSON fields
+may be introduced within v1 because v1 readers ignore unknown object members.

docs/contracts/http-v1.md

@@ -0,0 +1,111 @@
+# HTTP contract v1
+
+Tracking: #4
+
+All production endpoints require HTTPS. JSON uses UTF-8, camel-case property
+names, compact output, string-valued camel-case enums, and ISO 8601 timestamps.
+Every request that contains a body carries `contractVersion: 1`; browse carries
+the same value as a required query parameter.
+
+## Compatibility and parsing
+
+- Contract version matching is exact. Any value other than `1` fails with
+  `unsupportedContractVersion`; it is never guessed or downgraded.
+- Gameplay protocol matching is exact. `buildVersion` is display and diagnostic
+  text only and never decides compatibility.
+- Unknown JSON object properties are ignored so additive v1 responses remain
+  readable. Unknown enum names, numeric enum values, comments, trailing commas,
+  invalid identifier strings, and excessive nesting are rejected.
+- Game, environment, and region IDs are lowercase URL-safe slugs. Listing,
+  lease, join-attempt, and mediation IDs are non-empty UUIDs serialized as JSON
+  strings.
+- Clients must honor request cancellation. A disconnected or cancelled request
+  does not promise a response body; the server should stop work where safe.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/v1/sessions` | Register a session and create its renewable lease. |
+| `POST` | `/v1/sessions/{listingId}/renew` | Renew the listing lease. |
+| `PUT` | `/v1/sessions/{listingId}` | Replace mutable browser fields and capacity. |
+| `DELETE` | `/v1/sessions/{listingId}` | Withdraw a listing. |
+| `GET` | `/v1/sessions` | Browse compatible public sessions. |
+| `GET` | `/v1/sessions/{listingId}` | Resolve a public or explicitly shared unlisted listing. |
+| `POST` | `/v1/join-attempts` | Authorize and create a short-lived join attempt. |
+| `DELETE` | `/v1/join-attempts/{attemptId}` | Cancel an attempt using its client punch capability. |
+| `GET` | `/v1/sessions/{listingId}/join-attempts` | Let an authenticated host poll pending attempts. |
+| `POST` | `/v1/join-attempts/{attemptId}/outcome` | Report a bounded connection outcome. |
+| `GET` | `/health/live` | Report that the HTTP process is alive. |
+| `GET` | `/health/ready` | Report whether the UDP mediator is bound and ready. |
+
+The generated [OpenAPI document](../api/rendezvous-v1.json) is the normative
+shape reference for parameters, bodies, and responses. Contract-only endpoints
+return `501` until their behavior is implemented by the subsequent directory,
+lease, and join-orchestration issues.
+
+Host polling sends its reusable lease credential in
+`X-Rendezvous-Lease-Token`; it must never be placed in a URL. Lease credentials
+for mutation operations are carried in their request bodies. Public browser
+responses contain no IP endpoints, lease tokens, punch capabilities, connection
+tickets, player identifiers, or gameplay state.
+
+Attempt cancellation sends the short-lived client punch capability in
+`X-Rendezvous-Client-Punch-Capability`. Join creation uses the observed HTTP
+source only for a process-keyed, short-lived idempotency/abuse scope; this is not
+player authentication and is never returned to callers.
+
+## Idempotency, cursors, and retries
+
+Registration and join creation require a caller-generated visible-ASCII
+`idempotencyKey`. A repeat in the same authorization scope returns the original
+result while the key is retained; reusing a key with a different payload fails
+with `conflict`. Keys are opaque and must not contain credentials.
+
+Cursors are opaque, endpoint-specific, short-lived values. A client may echo a
+cursor only to the endpoint and filters that produced it. Invalid or expired
+cursors fail with `invalidRequest`; clients restart browsing from the first page.
+Renew, update, delete, and outcome reporting are safe to retry with the same
+lease/attempt identity after a transport-level failure.
+
+## Limits
+
+Limits are measured after UTF-8 encoding where stated. Servers reject the
+entire request rather than truncate values.
+
+| Item | v1 limit |
+| --- | ---: |
+| HTTP request body | 16 KiB |
+| Browser response body | 256 KiB |
+| Browser page | 100 listings |
+| Metadata document | 4 KiB, 32 keys |
+| Metadata key / value | 64 / 256 UTF-8 bytes |
+| Game / environment / region ID | 64 / 32 / 32 characters |
+| Display name / build version | 128 / 64 UTF-8 bytes |
+| Idempotency key | 64 visible ASCII characters |
+| Cursor | 512 visible ASCII characters |
+| Diagnostic code | 64 visible ASCII characters |
+| Error message | 256 UTF-8 bytes |
+| Reusable HTTP credential | 1,024 characters |
+| Session capacity | 1–10,000 players |
+
+## Error mapping
+
+Errors use `ApiError` with a stable `code`, bounded safe `message`, optional
+`correlationId`, and optional `retryAfterSeconds`. Messages are diagnostic and
+must not be parsed. Secrets and raw credentials are never echoed.
+
+| HTTP | Codes |
+| ---: | --- |
+| 400 | `invalidRequest`, `unsupportedContractVersion` |
+| 401 | `authenticationRequired` |
+| 403 | `forbidden` |
+| 404 | `notFound` |
+| 409 | `conflict`, `incompatibleProtocol`, `replayRejected`, `capacityExceeded` |
+| 410 | `expired`, `staleHost` |
+| 429 | `rateLimited` (with retry guidance when known) |
+| 503 | `serviceUnavailable` (with retry guidance when known) |
+| 500 | `internalError` |
+
+Malformed input must receive the same bounded error family regardless of which
+parser or validation stage rejected it.

docs/contracts/udp-v1.md

@@ -0,0 +1,96 @@
+# UDP presence and NAT-punch contract v1
+
+Tracking: #4, #11
+
+The UDP mediator accepts the frozen bounded presence envelope below and native
+LiteNetLib NAT-introduction requests. Both forms associate an authenticated
+mediation handle with the packet's observed public source endpoint and the
+sender's reported local endpoint. Neither form carries gameplay packets.
+
+All multi-byte integers use network byte order. UUID bytes use the canonical
+RFC 4122 textual order (the byte pairs from the 32 hexadecimal digits), not the
+mixed-endian layout returned by `Guid.ToByteArray()`.
+
+## Datagram layout
+
+| Offset | Size | Field |
+| ---: | ---: | --- |
+| 0 | 2 | Magic bytes `52 56` (`RV`). |
+| 2 | 1 | Contract version, exactly `01`. |
+| 3 | 1 | Message type: host presence `01`, client presence `02`. |
+| 4 | 1 | Flags, exactly `00` in v1. |
+| 5 | 16 | Non-empty mediation-handle UUID. |
+| 21 | 1 | Address family: IPv4 `04`, IPv6 `06`. |
+| 22 | 1 | Address length: `04` for IPv4, `10` for IPv6. |
+| 23 | 4 or 16 | Raw local IP address bytes. |
+| next | 2 | Local UDP port, 1–65535. |
+| next | 1 | Capability length, 1–192. |
+| next | variable | ASCII base64url capability, without padding. |
+
+No trailing bytes are permitted. The whole datagram is limited to 1,200 bytes,
+well below common Internet path MTUs. The v1 capability limit is 192 characters,
+which also keeps any value passed through LiteNetLib's 256-character NAT token
+surface safely below that library boundary.
+
+## Validation and failure behavior
+
+Decoders return one stable failure category: oversized, truncated, invalid
+magic, unsupported version, unknown message type, non-zero flags, invalid
+handle, invalid address family, invalid address, invalid port, invalid
+capability, or trailing data. Unknown versions and message types are rejected;
+they are never interpreted as v1.
+
+The address-family byte, encoded address length, and parsed address must agree.
+The service derives the public endpoint from the UDP packet source and never
+trusts a client-supplied public address. Reported local endpoints are candidates
+only and grant no authority.
+
+Capabilities are short-lived, single-purpose, scoped to one mediation handle,
+and compared without exposing them in logs. A valid-looking packet does not
+prove authorization until the capability is checked. Invalid packets receive
+no UDP response, preventing the mediator from becoming an amplification oracle.
+For the frozen envelope, `HostPresence` is resolved against either the listing's
+host-presence capability or an attempt's host-role capability. `ClientPresence`
+is resolved only against the attempt's client-role capability. Handles are
+globally distinct in the active store, so this does not permit role confusion.
+
+## Native LiteNetLib request token
+
+A game using LiteNetLib sends `NatPunchModule.SendNatIntroduceRequest` from its
+gameplay `NetManager`. The `additionalInfo` value is produced by
+`NatPunchRequestTokenCodec` and is exactly 192 ASCII characters:
+
+```text
+rv1:<role>:<32 lowercase handle hex>:<43-character capability><dot padding>
+```
+
+`role` is `p` for listing host-presence refresh, `h` for the host side of a join
+attempt, or `c` for its client side. Padding is canonical and leaves the token
+below LiteNetLib's 256-character ceiling. Its fixed size also ensures that the
+two authenticated introduction responses remain within the 2.0 response-byte
+budget. Tokens with a wrong length, role, handle, capability, or padding receive
+no response.
+
+The mediator runs LiteNetLib in bounded manual-poll mode. Its packet layer admits
+only the pinned native `NatIntroduceRequest` frame, consumes every inbound frame
+before LiteNetLib can act on it, and uses `NatPunchModule` only to emit authorized
+introductions. Native and frozen v1 inputs reach the same atomic role/capability
+checks. Only the packet source is
+used as the public endpoint. A claimed private candidate is retained only when
+it is private unicast, matches the observed address family, and both authorized
+peers were observed behind the same public address; otherwise the observed
+public endpoint is substituted. IPv4 punching is required. IPv6 sources must be
+observed global unicast and both roles must use IPv6; IPv6 NAT traversal remains
+best-effort rather than a v1 release requirement.
+
+The second valid contribution atomically consumes the introduction and starts
+the connection-ticket lifetime. `NatIntroduce` is called once with the distinct
+43-character connection ticket. Reordered and exact duplicate requests are
+idempotent. Endpoint substitution, cross-role use, stale host presence, expired
+or cancelled attempts, malformed packets, and gameplay payloads produce no
+introduction and create no mediator queue or endpoint state.
+
+Frozen envelopes may refresh listing presence over IPv6 because that operation
+has no response. IPv6 attempt contributions must use the fixed-size native token;
+the shorter frozen IPv6 envelope cannot fund two IPv6 introduction frames within
+the 2.0 response-byte ceiling and is therefore dropped without response.

docs/security/provisioning.md

@@ -0,0 +1,84 @@
+# Game provisioning and signing-key lifecycle
+
+Tracking: #5
+
+Rendezvous treats game and environment scope as provisioned policy, not caller
+input. Production starts only when it can build an enabled policy registry and
+load at least one currently active signing key from an external secret provider.
+Unknown and disabled scopes fail closed.
+
+## Policy boundary
+
+Each `GamePolicy` fixes the allowed:
+
+- game/environment pair and regions;
+- exact gameplay protocol versions;
+- publisher trust and listing visibility modes;
+- metadata keys, required keys, per-value limits, total bytes, and key count;
+- listing, anonymous-host, and active-attempt quotas; and
+- dedicated fallback feature policy.
+
+Publisher authorization first authenticates a typed principal, then derives the
+authoritative game/environment from that principal. Request fields are compared
+for mismatch detection but never replace the authenticated scope. Dedicated
+workloads, short-lived player-host grants, anonymous unlisted publishers, and
+operators are distinct principal types. Operator credentials cannot be used as
+publisher credentials, and anonymous publishers cannot escalate to public
+visibility.
+
+## Signed credentials
+
+Signed principal credentials use the compact form
+`rv1.<key-id>.<base64url-payload>.<base64url-HMAC-SHA256>`. The signed payload
+contains version, issuer, audience, subject, principal kind, bounded scope,
+issued/not-before/expiry times, and a random nonce. It contains no signing key,
+reusable publisher secret, player identity, or gameplay state.
+
+Validation is deliberately ordered and bounded:
+
+1. enforce the v1 opaque-credential length and four-segment grammar;
+2. resolve a known, non-revoked key in its verification window;
+3. compare the HMAC in fixed time;
+4. parse canonical bounded JSON;
+5. require exact version, issuer, and audience;
+6. enforce clock skew, expiry, key lifetime, principal kind, and scope shape.
+
+Failures return typed internal reasons without echoing the credential. Logs and
+metrics must record only allowlisted tenant/principal/result dimensions; token,
+key, secret-reference value, and raw key material are excluded.
+
+## Rotation and revocation
+
+A key is bound either to operator credentials only or to allowed publisher
+credential kinds for exactly one game/environment. The verifier checks this
+authority after the signature, so even a compromised game grant issuer cannot
+mint a valid cross-game or operator credential.
+
+A key also has three times: `NotBefore`, `SignUntil`, and `VerifyUntil`. Issuance
+picks the newest authorized non-revoked key inside its signing window. Older credentials continue
+to verify until the old key's verification window ends, providing an explicit
+overlap. After `VerifyUntil` they fail as retired. Configuration revocation and
+runtime revocation both reject immediately. A configured revoked key retains
+only its public key ID/lifecycle metadata and does not require retired secret
+material to remain available.
+
+Key IDs are non-secret base64url identifiers. Secret references are resolved
+through `ISecretProvider`; production supports `env:<VARIABLE>` references and
+the interface is replaceable by a deployment-specific vault/KMS adapter. The
+committed development profile uses an in-memory random key identified by a
+`development:ephemeral/...` reference. It never writes key material to disk and
+all credentials become invalid when the process exits.
+
+## Production configuration
+
+`Rendezvous:Provisioning` supplies issuer, audience, clock skew, signing-key
+descriptors, and game policies. A production key reference such as
+`env:RENDEZVOUS_SIGNING_KEY_2026_01` expects that environment variable to hold at
+least 32 random bytes encoded as base64. Missing, malformed, short, inactive, or
+duplicate keys stop startup with a key-ID-only diagnostic. No game-wide secret
+belongs in `appsettings`, source control, examples, the Client package, URLs,
+responses, logs, metrics, exceptions, or diagnostic dumps.
+
+Readiness becomes true only after provisioning and UDP startup both succeed.
+OpenAPI generation uses a pinned build-only host and does not start listeners or
+bypass provisioning in a deployed server process.

src/FinalFactory.Rendezvous.Client/ConnectionTickets/ConnectionTicketValidator.cs

@@ -0,0 +1,232 @@
+using System.Security.Cryptography;
+using System.Text;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public enum ConnectionTicketConsumptionResult
+{
+    Accepted = 1,
+    NotFound = 2,
+    Expired = 3,
+    Rejected = 4,
+    AlreadyConsumed = 5,
+    Revoked = 6,
+}
+
+public sealed class ConnectionTicketValidator : IDisposable
+{
+    private readonly object _gate = new();
+    private readonly Dictionary<JoinAttemptId, TicketEntry> _tickets = [];
+    private readonly int _maximumAuthorizedTickets;
+    private readonly IConnectionTicketClock _clock;
+    private readonly byte[] _fingerprintKey = new byte[32];
+    private bool _disposed;
+
+    public ConnectionTicketValidator(int maximumAuthorizedTickets = 1_024)
+        : this(maximumAuthorizedTickets, new SystemConnectionTicketClock())
+    {
+    }
+
+    internal ConnectionTicketValidator(
+        int maximumAuthorizedTickets,
+        IConnectionTicketClock clock)
+    {
+        if (maximumAuthorizedTickets is < 1 or > 10_000)
+        {
+            throw new ArgumentOutOfRangeException(nameof(maximumAuthorizedTickets));
+        }
+
+        _maximumAuthorizedTickets = maximumAuthorizedTickets;
+        _clock = clock ?? throw new ArgumentNullException(nameof(clock));
+        RandomNumberGenerator.Fill(_fingerprintKey);
+    }
+
+    public bool TryAuthorize(
+        JoinAttemptId attemptId,
+        string connectionTicket,
+        DateTimeOffset expiresAt)
+    {
+        lock (_gate)
+        {
+            ThrowIfDisposed();
+            DateTimeOffset now = _clock.UtcNow;
+            if (attemptId.Value == Guid.Empty
+                || !ContractValidation.IsConnectionTicketValid(connectionTicket)
+                || expiresAt <= now)
+            {
+                return false;
+            }
+
+            RemoveExpired(now);
+            byte[] fingerprint = Fingerprint(connectionTicket);
+            if (_tickets.TryGetValue(attemptId, out TicketEntry? current))
+            {
+                bool idempotent = current.State == TicketState.Active
+                    && current.ExpiresAt == expiresAt
+                    && CryptographicOperations.FixedTimeEquals(current.Fingerprint, fingerprint);
+                CryptographicOperations.ZeroMemory(fingerprint);
+                return idempotent;
+            }
+
+            if (_tickets.Count >= _maximumAuthorizedTickets)
+            {
+                CryptographicOperations.ZeroMemory(fingerprint);
+                return false;
+            }
+
+            _tickets.Add(attemptId, new(fingerprint, expiresAt));
+            return true;
+        }
+    }
+
+    public ConnectionTicketConsumptionResult Consume(
+        JoinAttemptId attemptId,
+        string connectionTicket)
+    {
+        lock (_gate)
+        {
+            ThrowIfDisposed();
+            DateTimeOffset now = _clock.UtcNow;
+            if (attemptId.Value == Guid.Empty
+                || !ContractValidation.IsConnectionTicketValid(connectionTicket))
+            {
+                return ConnectionTicketConsumptionResult.Rejected;
+            }
+
+            if (!_tickets.TryGetValue(attemptId, out TicketEntry? entry))
+            {
+                RemoveExpired(now);
+                return ConnectionTicketConsumptionResult.NotFound;
+            }
+
+            if (entry.ExpiresAt <= now)
+            {
+                Remove(attemptId, entry);
+                return ConnectionTicketConsumptionResult.Expired;
+            }
+
+            if (entry.State == TicketState.Revoked)
+            {
+                return ConnectionTicketConsumptionResult.Revoked;
+            }
+
+            if (entry.State == TicketState.Consumed)
+            {
+                return ConnectionTicketConsumptionResult.AlreadyConsumed;
+            }
+
+            byte[] supplied = Fingerprint(connectionTicket);
+            bool matches = CryptographicOperations.FixedTimeEquals(entry.Fingerprint, supplied);
+            CryptographicOperations.ZeroMemory(supplied);
+            if (!matches)
+            {
+                return ConnectionTicketConsumptionResult.Rejected;
+            }
+
+            entry.State = TicketState.Consumed;
+            return ConnectionTicketConsumptionResult.Accepted;
+        }
+    }
+
+    public bool Revoke(JoinAttemptId attemptId)
+    {
+        lock (_gate)
+        {
+            ThrowIfDisposed();
+            RemoveExpired(_clock.UtcNow);
+            if (!_tickets.TryGetValue(attemptId, out TicketEntry? entry))
+            {
+                return false;
+            }
+
+            entry.State = TicketState.Revoked;
+            CryptographicOperations.ZeroMemory(entry.Fingerprint);
+            return true;
+        }
+    }
+
+    public void Dispose()
+    {
+        lock (_gate)
+        {
+            if (_disposed)
+            {
+                return;
+            }
+
+            foreach (TicketEntry entry in _tickets.Values)
+            {
+                CryptographicOperations.ZeroMemory(entry.Fingerprint);
+            }
+
+            _tickets.Clear();
+            CryptographicOperations.ZeroMemory(_fingerprintKey);
+            _disposed = true;
+        }
+    }
+
+    public override string ToString() => "[ConnectionTicketValidator: tickets and key redacted]";
+
+    private byte[] Fingerprint(string ticket)
+    {
+        byte[] encoded = Encoding.ASCII.GetBytes(ticket);
+        try
+        {
+            using HMACSHA256 hmac = new(_fingerprintKey);
+            return hmac.ComputeHash(encoded);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(encoded);
+        }
+    }
+
+    private void RemoveExpired(DateTimeOffset now)
+    {
+        foreach (KeyValuePair<JoinAttemptId, TicketEntry> item in _tickets
+                     .Where(item => item.Value.ExpiresAt <= now)
+                     .ToArray())
+        {
+            Remove(item.Key, item.Value);
+        }
+    }
+
+    private void Remove(JoinAttemptId attemptId, TicketEntry entry)
+    {
+        CryptographicOperations.ZeroMemory(entry.Fingerprint);
+        _tickets.Remove(attemptId);
+    }
+
+    private void ThrowIfDisposed()
+    {
+        if (_disposed)
+        {
+            throw new ObjectDisposedException(nameof(ConnectionTicketValidator));
+        }
+    }
+
+    private sealed class TicketEntry(byte[] fingerprint, DateTimeOffset expiresAt)
+    {
+        public byte[] Fingerprint { get; } = fingerprint;
+        public DateTimeOffset ExpiresAt { get; } = expiresAt;
+        public TicketState State { get; set; }
+    }
+
+    private enum TicketState
+    {
+        Active = 0,
+        Consumed = 1,
+        Revoked = 2,
+    }
+}
+
+internal interface IConnectionTicketClock
+{
+    DateTimeOffset UtcNow { get; }
+}
+
+internal sealed class SystemConnectionTicketClock : IConnectionTicketClock
+{
+    public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
+}

src/FinalFactory.Rendezvous.Client/FinalFactory.Rendezvous.Client.csproj

@@ -5,10 +5,12 @@
     <RootNamespace>FinalFactory.Rendezvous.Client</RootNamespace>
     <IsPackable>true</IsPackable>
     <PackageId>FinalFactory.Rendezvous.Client</PackageId>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <Description>Godot-independent client SDK for Final Factory Rendezvous.</Description>
   </PropertyGroup>
   <ItemGroup>
     <ProjectReference Include="../FinalFactory.Rendezvous.Contracts/FinalFactory.Rendezvous.Contracts.csproj" />
     <PackageReference Include="LiteNetLib" />
+    <None Update="README.md" Pack="true" PackagePath="\" />
   </ItemGroup>
 </Project>

src/FinalFactory.Rendezvous.Client/JoinAttempts/RendezvousJoinClient.cs

@@ -0,0 +1,148 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class RendezvousJoinClient : IRendezvousJoinClient
+{
+    private const string LeaseTokenHeader = "X-Rendezvous-Lease-Token";
+    private const string ClientPunchCapabilityHeader = "X-Rendezvous-Client-Punch-Capability";
+
+    private readonly RendezvousHttpTransport _transport;
+
+    public RendezvousJoinClient(
+        HttpClient httpClient,
+        RendezvousClientOptions? options = null,
+        IRendezvousDelay? delay = null)
+    {
+        _transport = new(httpClient, options, delay);
+    }
+
+    public Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
+        CreateJoinAttemptRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+        CreateJoinAttemptRequest body = new()
+        {
+            ContractVersion = request.ContractVersion,
+            IdempotencyKey = request.IdempotencyKey,
+            GameId = request.GameId,
+            EnvironmentId = request.EnvironmentId,
+            ListingId = request.ListingId,
+            ProtocolVersion = request.ProtocolVersion,
+        };
+        return _transport.SendSafeAsync<CreateJoinAttemptResponse>(
+            () => RendezvousHttpTransport.JsonRequest(HttpMethod.Post, "v1/join-attempts", body),
+            cancellationToken);
+    }
+
+    public Task<RendezvousClientResult<bool>> CancelAsync(
+        CreateJoinAttemptResponse attempt,
+        CancellationToken cancellationToken = default)
+    {
+        if (attempt is null)
+        {
+            throw new ArgumentNullException(nameof(attempt));
+        }
+        return _transport.SendSafeAsync<bool>(
+            () => HeaderRequest(
+                HttpMethod.Delete,
+                $"v1/join-attempts/{attempt.AttemptId}",
+                ClientPunchCapabilityHeader,
+                RequireHeaderValue(attempt.ClientPunchCapability, nameof(attempt))),
+            cancellationToken);
+    }
+
+    public Task<RendezvousClientResult<BrowseHostJoinAttemptsResponse>> BrowseForHostAsync(
+        PublishedSession session,
+        int pageSize = ContractLimits.BrowserPageMaxItems,
+        string? cursor = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new ArgumentNullException(nameof(session));
+        }
+        if (pageSize is < 1 or > ContractLimits.BrowserPageMaxItems)
+        {
+            throw new ArgumentOutOfRangeException(nameof(pageSize));
+        }
+
+        string query = $"v1/sessions/{session.ListingId}/join-attempts"
+            + $"?contractVersion={ContractLimits.ContractVersion}"
+            + $"&pageSize={pageSize}"
+            + (cursor is null ? string.Empty : $"&cursor={Uri.EscapeDataString(cursor)}");
+        return _transport.SendSafeAsync<BrowseHostJoinAttemptsResponse>(
+            () => HeaderRequest(
+                HttpMethod.Get,
+                query,
+                LeaseTokenHeader,
+                RequireHeaderValue(session.LeaseToken, nameof(session))),
+            cancellationToken);
+    }
+
+    public async Task<RendezvousClientResult<IReadOnlyList<HostJoinAttempt>>> BrowseAllForHostAsync(
+        PublishedSession session,
+        int maximumPages = 100,
+        CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new ArgumentNullException(nameof(session));
+        }
+        if (maximumPages is < 1 or > 1_000)
+        {
+            throw new ArgumentOutOfRangeException(nameof(maximumPages));
+        }
+
+        List<HostJoinAttempt> attempts = [];
+        string? cursor = null;
+        for (int page = 0; page < maximumPages; page++)
+        {
+            RendezvousClientResult<BrowseHostJoinAttemptsResponse> result =
+                await BrowseForHostAsync(
+                    session,
+                    ContractLimits.BrowserPageMaxItems,
+                    cursor,
+                    cancellationToken).ConfigureAwait(false);
+            if (!result.IsSuccess || result.Value is null)
+            {
+                return RendezvousClientResult.Failure<IReadOnlyList<HostJoinAttempt>>(
+                    result.Error,
+                    result.Message,
+                    result.RetryAfterSeconds);
+            }
+
+            attempts.AddRange(result.Value.Items);
+            cursor = result.Value.NextCursor;
+            if (string.IsNullOrEmpty(cursor))
+            {
+                return RendezvousClientResult.Success<IReadOnlyList<HostJoinAttempt>>(
+                    attempts.AsReadOnly());
+            }
+        }
+
+        return RendezvousClientResult.Failure<IReadOnlyList<HostJoinAttempt>>(
+            RendezvousErrorCode.CapacityExceeded,
+            $"Host invitation polling exceeded the configured {maximumPages}-page limit.");
+    }
+
+    private static HttpRequestMessage HeaderRequest(
+        HttpMethod method,
+        string uri,
+        string header,
+        string value)
+    {
+        HttpRequestMessage request = new(method, uri);
+        request.Headers.TryAddWithoutValidation(header, value);
+        return request;
+    }
+
+    private static string RequireHeaderValue(string value, string parameterName) =>
+        !string.IsNullOrWhiteSpace(value)
+            ? value
+            : throw new ArgumentException("The required capability is missing.", parameterName);
+}

src/FinalFactory.Rendezvous.Client/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("FinalFactory.Rendezvous.Tests")]

src/FinalFactory.Rendezvous.Client/README.md

@@ -0,0 +1,159 @@
+# FinalFactory.Rendezvous.Client
+
+Godot-independent .NET publisher, browser, join, and LiteNetLib traversal SDK for Rendezvous v1.
+The package targets `netstandard2.1` and uses a caller-owned `HttpClient`.
+
+```csharp
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+
+using HttpClient http = new()
+{
+    BaseAddress = new Uri("https://rendezvous.example/"),
+};
+
+string publisherCredential = Environment.GetEnvironmentVariable(
+    "RENDEZVOUS_PUBLISHER_CREDENTIAL")
+    ?? throw new InvalidOperationException("Publisher credential is not configured.");
+CancellationToken cancellationToken = default;
+RendezvousPublisherClient publisher = new(http);
+RendezvousClientResult<PublishedSession> registered = await publisher.RegisterAsync(
+    new RegisterSessionRequest
+    {
+        IdempotencyKey = Guid.NewGuid().ToString("N"),
+        GameId = new("space-game"),
+        EnvironmentId = new("production"),
+        RegionId = new("eu-central"),
+        ProtocolVersion = 7,
+        BuildVersion = "1.0.0",
+        DisplayName = "My server",
+        Visibility = ListingVisibility.Public,
+        Capacity = new() { CurrentPlayers = 1, MaximumPlayers = 8 },
+    },
+    publisherCredential,
+    cancellationToken);
+if (!registered.IsSuccess || registered.Value is null)
+{
+    throw new InvalidOperationException(
+        $"Registration failed: {registered.Error} ({registered.Message})");
+}
+```
+
+Load `publisherCredential` from the game's deployment secret boundary; never
+embed it in a client build or source control. A successful registration returns a
+`PublishedSession` containing the lease and host-presence capabilities.
+Send a periodic presence request from the host's gameplay `NetManager` using the
+server-controlled refresh interval and the fixed-size native token:
+
+```csharp
+string presenceToken = NatPunchRequestTokenCodec.Encode(
+    NatPunchPeerRole.HostPresence,
+    session.HostPresenceHandle,
+    session.HostPresenceCapability);
+gameplayNetManager.NatPunchModule.SendNatIntroduceRequest(mediator, presenceToken);
+```
+
+For direct connections, let the SDK drive those tokens from the same caller-owned
+LiteNetLib socket that carries gameplay. Ask the routing listener to create the
+bound manager, then configure and start that caller-owned manager yourself. The
+factory does not open a socket, and synchronized events must remain enabled:
+
+```csharp
+RendezvousNetListener networkEvents = new();
+NetManager gameplayNetManager = networkEvents.CreateManager();
+if (!gameplayNetManager.Start(0))
+{
+    throw new InvalidOperationException("The gameplay UDP socket could not start.");
+}
+```
+
+The host polls join invitations asynchronously; that method only queues a
+snapshot and never calls the manager. `Poll()` is the sole SDK path that invokes
+LiteNetLib and dispatches its synchronized callbacks. Call it once per game
+frame on the thread that owns the manager:
+
+```csharp
+RendezvousJoinClient joins = new(http);
+using RendezvousHostCoordinator host = new(
+    gameplayNetManager,
+    networkEvents,
+    mediatorEndPoint,
+    session,
+    joins);
+
+// Run periodically from the game's normal async scheduling path.
+await host.RefreshJoinAttemptsAsync(cancellationToken);
+
+// Godot _Process, Update, or the equivalent main-thread frame callback.
+host.Poll();
+```
+
+Do not also call `gameplayNetManager.PollEvents()` or
+`gameplayNetManager.NatPunchModule.PollEvents()` when a coordinator owns polling.
+The host coordinator refreshes host presence, punches for queued invitations,
+validates the introduction ticket, and accepts the direct request. Subscribe to
+`AttemptCompleted`; a `Connected` result is raised only after LiteNetLib reports
+the accepted peer as connected. Register ordinary gameplay callbacks on
+`networkEvents.GameplayEvents`; the routing listener reserves Rendezvous direct
+requests for ticket validation and forwards every other callback normally.
+
+The joining game first creates the HTTP attempt, then uses its own already-started
+gameplay manager in the same frame loop:
+
+```csharp
+CreateJoinAttemptResponse attempt = (await joins.CreateAsync(
+    createJoinRequest,
+    cancellationToken)).Value
+    ?? throw new InvalidOperationException("Join issuance failed.");
+using RendezvousClientCoordinator client = new(
+    gameplayNetManager,
+    networkEvents,
+    mediatorEndPoint,
+    attempt);
+
+// Godot _Process, Update, or the equivalent main-thread frame callback.
+client.Poll();
+```
+
+NAT introduction changes the client state to `Connecting`; it is not success.
+Only `Connected` supplies `ConnectedPeer`. Call `Cancel()` and then `Poll()` for
+local cancellation, or `CancelAsync(joins, cancellationToken)` to also revoke the
+service attempt. Terminal client paths release all event subscriptions. Disposing
+a coordinator never stops or disposes the caller-owned manager and does not touch
+an in-flight peer; call `Cancel()` followed by `Poll()` first when that peer must
+also be disconnected.
+
+Lease renewal is explicit and caller-controlled:
+
+```csharp
+PublishedSession session = registered.Value;
+await using SessionLeaseMaintainer maintainer = publisher.CreateLeaseMaintainer(
+    session,
+    publisherCredential);
+LeaseMaintenanceResult stopped = await maintainer.RunAsync(cancellationToken);
+```
+
+Creating the maintainer does not start background work. Await its run and dispose
+it when hosting stops. Use `IRendezvousPublisherClient` and
+`IRendezvousSessionBrowserClient` as injection seams in game tests. The SDK disposes
+the requests and responses it creates but never disposes the supplied `HttpClient`.
+
+The host-side `ConnectionTicketValidator` is a bounded, thread-safe one-time gate.
+Authorize only tickets delivered by the authenticated Rendezvous introduction,
+then consume the exact ticket presented by the direct LiteNetLib connection:
+
+```csharp
+using ConnectionTicketValidator tickets = new();
+tickets.TryAuthorize(attemptId, expectedTicket, expiresAt);
+ConnectionTicketConsumptionResult admission = tickets.Consume(
+    attemptId,
+    presentedTicket);
+```
+
+An `Accepted` ticket authorizes only this connection attempt. The game must still
+apply its own player identity, capacity, ban, and gameplay admission rules. Revoke
+the attempt on cancellation and dispose the validator during host shutdown so its
+keyed ticket digests are zeroed.
+
+See the repository's ADR 0007 for HTTP ownership/retry semantics and ADR 0008 for
+join-capability and connection-ticket security semantics.

src/FinalFactory.Rendezvous.Client/RendezvousClientAbstractions.cs

@@ -0,0 +1,200 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class RendezvousClientResult<T>
+{
+    internal RendezvousClientResult(
+        RendezvousErrorCode error,
+        T? value,
+        string message,
+        int? retryAfterSeconds)
+    {
+        Error = error;
+        Value = value;
+        Message = message;
+        RetryAfterSeconds = retryAfterSeconds;
+    }
+
+    public bool IsSuccess => Error == RendezvousErrorCode.None;
+    public RendezvousErrorCode Error { get; }
+    public T? Value { get; }
+    public string Message { get; }
+    public int? RetryAfterSeconds { get; }
+
+}
+
+public static class RendezvousClientResult
+{
+    public static RendezvousClientResult<T> Success<T>(T value) =>
+        value is null
+            ? throw new ArgumentNullException(nameof(value))
+            : new(RendezvousErrorCode.None, value, string.Empty, null);
+
+    public static RendezvousClientResult<T> Failure<T>(
+        RendezvousErrorCode error,
+        string message,
+        int? retryAfterSeconds = null) =>
+        error == RendezvousErrorCode.None
+            ? throw new ArgumentException("A failure requires a non-success error.", nameof(error))
+            : new(error, default, message ?? string.Empty, retryAfterSeconds);
+}
+
+public sealed class PublishedSession
+{
+    private readonly object _timingGate = new();
+    private DateTimeOffset _expiresAt;
+    private int _leaseRenewAfterSeconds;
+
+    internal PublishedSession(RegisterSessionResponse response)
+    {
+        ListingId = response.ListingId;
+        LeaseId = response.LeaseId;
+        LeaseToken = response.LeaseToken;
+        HostPresenceHandle = response.HostPresenceHandle;
+        HostPresenceCapability = response.HostPresenceCapability;
+        _expiresAt = response.ExpiresAt;
+        _leaseRenewAfterSeconds = response.LeaseRenewAfterSeconds;
+        HostPresenceRefreshAfterSeconds = response.HostPresenceRefreshAfterSeconds;
+    }
+
+    public SessionListingId ListingId { get; }
+    public LeaseId LeaseId { get; }
+    public string LeaseToken { get; }
+    public MediationHandle HostPresenceHandle { get; }
+    public string HostPresenceCapability { get; }
+    public DateTimeOffset ExpiresAt
+    {
+        get
+        {
+            lock (_timingGate)
+            {
+                return _expiresAt;
+            }
+        }
+        internal set
+        {
+            lock (_timingGate)
+            {
+                _expiresAt = value;
+            }
+        }
+    }
+
+    public int LeaseRenewAfterSeconds
+    {
+        get
+        {
+            lock (_timingGate)
+            {
+                return _leaseRenewAfterSeconds;
+            }
+        }
+        internal set
+        {
+            lock (_timingGate)
+            {
+                _leaseRenewAfterSeconds = value;
+            }
+        }
+    }
+    public int HostPresenceRefreshAfterSeconds { get; }
+
+    public override string ToString() => $"[PublishedSession {ListingId}; credentials redacted]";
+}
+
+public interface IRendezvousPublisherClient
+{
+    Task<RendezvousClientResult<PublishedSession>> RegisterAsync(
+        RegisterSessionRequest request,
+        string publisherCredential,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<RenewLeaseResponse>> RenewAsync(
+        PublishedSession session,
+        string publisherCredential,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<bool>> UpdateAsync(
+        PublishedSession session,
+        UpdateSessionRequest request,
+        string publisherCredential,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<bool>> DeregisterAsync(
+        PublishedSession session,
+        string publisherCredential,
+        CancellationToken cancellationToken = default);
+}
+
+public interface IRendezvousSessionBrowserClient
+{
+    Task<RendezvousClientResult<BrowseSessionsResponse>> BrowseAsync(
+        BrowseSessionsRequest request,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<IReadOnlyList<SessionListing>>> BrowseAllAsync(
+        BrowseSessionsRequest request,
+        int maximumPages = 100,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<GetSessionResponse>> GetAsync(
+        SessionListingId listingId,
+        GameId gameId,
+        EnvironmentId environmentId,
+        uint protocolVersion,
+        CancellationToken cancellationToken = default);
+}
+
+public interface IRendezvousJoinClient
+{
+    Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
+        CreateJoinAttemptRequest request,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<bool>> CancelAsync(
+        CreateJoinAttemptResponse attempt,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<BrowseHostJoinAttemptsResponse>> BrowseForHostAsync(
+        PublishedSession session,
+        int pageSize = ContractLimits.BrowserPageMaxItems,
+        string? cursor = null,
+        CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<IReadOnlyList<HostJoinAttempt>>> BrowseAllForHostAsync(
+        PublishedSession session,
+        int maximumPages = 100,
+        CancellationToken cancellationToken = default);
+}
+
+public interface IRendezvousDelay
+{
+    Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken);
+}
+
+public sealed class RendezvousClientOptions
+{
+    public int MaximumSafeRetries { get; set; } = 2;
+    public TimeSpan InitialRetryDelay { get; set; } = TimeSpan.FromMilliseconds(200);
+    public TimeSpan MaximumRetryDelay { get; set; } = TimeSpan.FromSeconds(2);
+    public double JitterRatio { get; set; } = 0.2;
+
+    internal void Validate()
+    {
+        if (MaximumSafeRetries is < 0 or > 5
+            || InitialRetryDelay < TimeSpan.Zero
+            || MaximumRetryDelay < InitialRetryDelay
+            || MaximumRetryDelay > TimeSpan.FromSeconds(30)
+            || JitterRatio is < 0 or > 1)
+        {
+            throw new ArgumentOutOfRangeException(nameof(RendezvousClientOptions));
+        }
+    }
+}
+
+internal sealed class SystemRendezvousDelay : IRendezvousDelay
+{
+    public Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken) =>
+        Task.Delay(delay, cancellationToken);
+}

src/FinalFactory.Rendezvous.Client/RendezvousHttpTransport.cs

@@ -0,0 +1,242 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+internal sealed class RendezvousHttpTransport
+{
+    private readonly HttpClient _httpClient;
+    private readonly RendezvousClientOptions _options;
+    private readonly IRendezvousDelay _delay;
+
+    internal RendezvousHttpTransport(
+        HttpClient httpClient,
+        RendezvousClientOptions? options,
+        IRendezvousDelay? delay)
+    {
+        _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
+        RendezvousClientOptions suppliedOptions = options ?? new RendezvousClientOptions();
+        suppliedOptions.Validate();
+        _options = new RendezvousClientOptions
+        {
+            MaximumSafeRetries = suppliedOptions.MaximumSafeRetries,
+            InitialRetryDelay = suppliedOptions.InitialRetryDelay,
+            MaximumRetryDelay = suppliedOptions.MaximumRetryDelay,
+            JitterRatio = suppliedOptions.JitterRatio,
+        };
+        _delay = delay ?? new SystemRendezvousDelay();
+    }
+
+    internal async Task<RendezvousClientResult<T>> SendSafeAsync<T>(
+        Func<HttpRequestMessage> requestFactory,
+        CancellationToken cancellationToken)
+    {
+        for (int attempt = 0; ; attempt++)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            try
+            {
+                using HttpRequestMessage request = requestFactory();
+                using HttpResponseMessage response = await _httpClient
+                    .SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken)
+                    .ConfigureAwait(false);
+                if (response.IsSuccessStatusCode)
+                {
+                    if (typeof(T) == typeof(bool) && response.StatusCode == HttpStatusCode.NoContent)
+                    {
+                        return RendezvousClientResult.Success((T)(object)true);
+                    }
+
+                    byte[] payload;
+                    try
+                    {
+                        payload = await ReadBoundedAsync(response.Content, cancellationToken)
+                            .ConfigureAwait(false);
+                    }
+                    catch (InvalidDataException)
+                    {
+                        return RendezvousClientResult.Failure<T>(
+                            RendezvousErrorCode.InternalError,
+                            "The service returned an oversized success response.");
+                    }
+
+                    T? value;
+                    try
+                    {
+                        value = JsonSerializer.Deserialize<T>(payload, ContractJson.Options);
+                    }
+                    catch (JsonException)
+                    {
+                        value = default;
+                    }
+
+                    return value is null
+                        ? RendezvousClientResult.Failure<T>(
+                            RendezvousErrorCode.InternalError,
+                            "The service returned an invalid success response.")
+                        : RendezvousClientResult.Success(value);
+                }
+
+                ApiError error = await ReadErrorAsync(response, cancellationToken).ConfigureAwait(false);
+                int? retryAfter = error.RetryAfterSeconds ?? GetRetryAfterSeconds(response.Headers.RetryAfter);
+                if (attempt < _options.MaximumSafeRetries && IsTransient(error.Code))
+                {
+                    await _delay.DelayAsync(
+                        GetRetryDelay(attempt, retryAfter),
+                        cancellationToken).ConfigureAwait(false);
+                    continue;
+                }
+
+                return RendezvousClientResult.Failure<T>(error.Code, error.Message, retryAfter);
+            }
+            catch (Exception exception) when (
+                IsTransientTransportFailure(exception, cancellationToken)
+                && attempt < _options.MaximumSafeRetries)
+            {
+                await _delay.DelayAsync(GetRetryDelay(attempt, null), cancellationToken)
+                    .ConfigureAwait(false);
+            }
+            catch (Exception exception) when (IsTransientTransportFailure(exception, cancellationToken))
+            {
+                return RendezvousClientResult.Failure<T>(
+                    RendezvousErrorCode.ServiceUnavailable,
+                    "The Rendezvous service did not return a valid response.");
+            }
+        }
+    }
+
+    internal static HttpRequestMessage JsonRequest<T>(
+        HttpMethod method,
+        string uri,
+        T body,
+        string? publisherCredential = null)
+    {
+        HttpRequestMessage request = new(method, uri)
+        {
+            Content = new StringContent(
+                JsonSerializer.Serialize(body, ContractJson.Options),
+                Encoding.UTF8,
+                "application/json"),
+        };
+        if (publisherCredential is not null)
+        {
+            request.Headers.Authorization = new AuthenticationHeaderValue(
+                "Bearer",
+                RequireCredential(publisherCredential));
+        }
+
+        return request;
+    }
+
+    internal static string RequireCredential(string credential) =>
+        !string.IsNullOrWhiteSpace(credential)
+            ? credential
+            : throw new ArgumentException("A publisher credential is required.", nameof(credential));
+
+    private static async Task<ApiError> ReadErrorAsync(
+        HttpResponseMessage response,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            byte[] payload = await ReadBoundedAsync(response.Content, cancellationToken)
+                .ConfigureAwait(false);
+            ApiError? error = JsonSerializer.Deserialize<ApiError>(payload, ContractJson.Options);
+            return error is not null && error.Code != RendezvousErrorCode.None
+                ? error
+                : FallbackError(response.StatusCode);
+        }
+        catch (Exception exception) when (exception is JsonException or InvalidDataException)
+        {
+            return FallbackError(response.StatusCode);
+        }
+    }
+
+    private static async Task<byte[]> ReadBoundedAsync(
+        HttpContent content,
+        CancellationToken cancellationToken)
+    {
+        using Stream source = await content.ReadAsStreamAsync().ConfigureAwait(false);
+        using MemoryStream destination = new();
+        byte[] buffer = new byte[8192];
+        while (true)
+        {
+            int read = await source.ReadAsync(buffer.AsMemory(), cancellationToken)
+                .ConfigureAwait(false);
+            if (read == 0)
+            {
+                return destination.ToArray();
+            }
+
+            if (destination.Length + read > ContractLimits.BrowserResponseMaxBytes)
+            {
+                throw new InvalidDataException("The service response exceeded the SDK limit.");
+            }
+
+            await destination.WriteAsync(buffer.AsMemory(0, read), cancellationToken)
+                .ConfigureAwait(false);
+        }
+    }
+
+    private TimeSpan GetRetryDelay(int attempt, int? retryAfterSeconds)
+    {
+        TimeSpan basis = retryAfterSeconds.HasValue
+            ? TimeSpan.FromSeconds(Math.Max(0, retryAfterSeconds.Value))
+            : TimeSpan.FromMilliseconds(
+                _options.InitialRetryDelay.TotalMilliseconds * Math.Pow(2, attempt));
+        double bounded = Math.Min(basis.TotalMilliseconds, _options.MaximumRetryDelay.TotalMilliseconds);
+        if (_options.JitterRatio == 0 || bounded == 0)
+        {
+            return TimeSpan.FromMilliseconds(bounded);
+        }
+
+        byte[] random = new byte[1];
+        RandomNumberGenerator.Fill(random);
+        double unit = random[0] / 255d;
+        double multiplier = 1 - _options.JitterRatio + (2 * _options.JitterRatio * unit);
+        return TimeSpan.FromMilliseconds(Math.Min(
+            bounded * multiplier,
+            _options.MaximumRetryDelay.TotalMilliseconds));
+    }
+
+    private static bool IsTransient(RendezvousErrorCode code) => code is
+        RendezvousErrorCode.RateLimited
+        or RendezvousErrorCode.CapacityExceeded
+        or RendezvousErrorCode.ServiceUnavailable;
+
+    private static bool IsTransientTransportFailure(
+        Exception exception,
+        CancellationToken callerCancellation) =>
+        exception is HttpRequestException
+        or IOException
+        || exception is OperationCanceledException && !callerCancellation.IsCancellationRequested;
+
+    private static int? GetRetryAfterSeconds(RetryConditionHeaderValue? retryAfter) =>
+        retryAfter?.Delta is TimeSpan delta
+            ? Math.Max(0, (int)Math.Ceiling(delta.TotalSeconds))
+            : null;
+
+    private static ApiError FallbackError(HttpStatusCode statusCode) => new()
+    {
+        Code = statusCode switch
+        {
+            HttpStatusCode.BadRequest => RendezvousErrorCode.InvalidRequest,
+            HttpStatusCode.Unauthorized => RendezvousErrorCode.AuthenticationRequired,
+            HttpStatusCode.Forbidden => RendezvousErrorCode.Forbidden,
+            HttpStatusCode.NotFound => RendezvousErrorCode.NotFound,
+            HttpStatusCode.Conflict => RendezvousErrorCode.Conflict,
+            HttpStatusCode.Gone => RendezvousErrorCode.Expired,
+            HttpStatusCode.TooManyRequests => RendezvousErrorCode.RateLimited,
+            HttpStatusCode.RequestTimeout => RendezvousErrorCode.ServiceUnavailable,
+            HttpStatusCode.BadGateway => RendezvousErrorCode.ServiceUnavailable,
+            HttpStatusCode.ServiceUnavailable => RendezvousErrorCode.ServiceUnavailable,
+            HttpStatusCode.GatewayTimeout => RendezvousErrorCode.ServiceUnavailable,
+            _ => RendezvousErrorCode.InternalError,
+        },
+        Message = "The service returned an error without a valid Rendezvous envelope.",
+    };
+}

src/FinalFactory.Rendezvous.Client/RendezvousPublisherClient.cs

@@ -0,0 +1,151 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class RendezvousPublisherClient : IRendezvousPublisherClient
+{
+    private readonly RendezvousHttpTransport _transport;
+    private readonly IRendezvousDelay _delay;
+
+    public RendezvousPublisherClient(
+        HttpClient httpClient,
+        RendezvousClientOptions? options = null,
+        IRendezvousDelay? delay = null)
+    {
+        _delay = delay ?? new SystemRendezvousDelay();
+        _transport = new(httpClient, options, _delay);
+    }
+
+    public async Task<RendezvousClientResult<PublishedSession>> RegisterAsync(
+        RegisterSessionRequest request,
+        string publisherCredential,
+        CancellationToken cancellationToken = default)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        RegisterSessionRequest body = CopyRegistration(request);
+        RendezvousClientResult<RegisterSessionResponse> result = await _transport.SendSafeAsync<RegisterSessionResponse>(
+            () => RendezvousHttpTransport.JsonRequest(HttpMethod.Post, "v1/sessions", body, publisherCredential),
+            cancellationToken).ConfigureAwait(false);
+        return result.IsSuccess && result.Value is not null
+            ? RendezvousClientResult.Success(new PublishedSession(result.Value))
+            : RendezvousClientResult.Failure<PublishedSession>(
+                result.Error,
+                result.Message,
+                result.RetryAfterSeconds);
+    }
+
+    public async Task<RendezvousClientResult<RenewLeaseResponse>> RenewAsync(
+        PublishedSession session,
+        string publisherCredential,
+        CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new ArgumentNullException(nameof(session));
+        }
+
+        RendezvousClientResult<RenewLeaseResponse> result = await _transport.SendSafeAsync<RenewLeaseResponse>(
+            () => RendezvousHttpTransport.JsonRequest(
+                HttpMethod.Post,
+                $"v1/sessions/{session.ListingId}/renew",
+                new RenewLeaseRequest { LeaseToken = session.LeaseToken },
+                publisherCredential),
+            cancellationToken).ConfigureAwait(false);
+        if (result.IsSuccess && result.Value is not null)
+        {
+            session.ExpiresAt = result.Value.ExpiresAt;
+            session.LeaseRenewAfterSeconds = result.Value.RenewAfterSeconds;
+        }
+
+        return result;
+    }
+
+    public Task<RendezvousClientResult<bool>> UpdateAsync(
+        PublishedSession session,
+        UpdateSessionRequest request,
+        string publisherCredential,
+        CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new ArgumentNullException(nameof(session));
+        }
+
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        UpdateSessionRequest body = new()
+        {
+            ContractVersion = request.ContractVersion,
+            LeaseToken = session.LeaseToken,
+            BuildVersion = request.BuildVersion,
+            DisplayName = request.DisplayName,
+            Capacity = CopyCapacity(request.Capacity),
+            Metadata = CopyMetadata(request.Metadata),
+        };
+        return _transport.SendSafeAsync<bool>(
+            () => RendezvousHttpTransport.JsonRequest(
+                HttpMethod.Put,
+                $"v1/sessions/{session.ListingId}",
+                body,
+                publisherCredential),
+            cancellationToken);
+    }
+
+    public Task<RendezvousClientResult<bool>> DeregisterAsync(
+        PublishedSession session,
+        string publisherCredential,
+        CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new ArgumentNullException(nameof(session));
+        }
+
+        return _transport.SendSafeAsync<bool>(
+            () => RendezvousHttpTransport.JsonRequest(
+                HttpMethod.Delete,
+                $"v1/sessions/{session.ListingId}",
+                new DeleteSessionRequest { LeaseToken = session.LeaseToken },
+                publisherCredential),
+            cancellationToken);
+    }
+
+    public SessionLeaseMaintainer CreateLeaseMaintainer(
+        PublishedSession session,
+        string publisherCredential) => new(
+            this,
+            session ?? throw new ArgumentNullException(nameof(session)),
+            RendezvousHttpTransport.RequireCredential(publisherCredential),
+            _delay);
+
+    private static RegisterSessionRequest CopyRegistration(RegisterSessionRequest request) => new()
+    {
+        ContractVersion = request.ContractVersion,
+        IdempotencyKey = request.IdempotencyKey,
+        GameId = request.GameId,
+        EnvironmentId = request.EnvironmentId,
+        RegionId = request.RegionId,
+        ProtocolVersion = request.ProtocolVersion,
+        BuildVersion = request.BuildVersion,
+        DisplayName = request.DisplayName,
+        Visibility = request.Visibility,
+        Capacity = CopyCapacity(request.Capacity),
+        Metadata = CopyMetadata(request.Metadata),
+    };
+
+    private static SessionCapacity CopyCapacity(SessionCapacity capacity) => new()
+    {
+        CurrentPlayers = capacity.CurrentPlayers,
+        MaximumPlayers = capacity.MaximumPlayers,
+    };
+
+    private static Dictionary<string, string> CopyMetadata(Dictionary<string, string> metadata) =>
+        new(metadata, StringComparer.Ordinal);
+}

src/FinalFactory.Rendezvous.Client/RendezvousSessionBrowserClient.cs

@@ -0,0 +1,110 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class RendezvousSessionBrowserClient : IRendezvousSessionBrowserClient
+{
+    private readonly RendezvousHttpTransport _transport;
+
+    public RendezvousSessionBrowserClient(
+        HttpClient httpClient,
+        RendezvousClientOptions? options = null,
+        IRendezvousDelay? delay = null)
+    {
+        _transport = new(httpClient, options, delay);
+    }
+
+    public Task<RendezvousClientResult<BrowseSessionsResponse>> BrowseAsync(
+        BrowseSessionsRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        string query = $"v1/sessions?contractVersion={request.ContractVersion}"
+            + $"&gameId={Escape(request.GameId.Value)}"
+            + $"&environmentId={Escape(request.EnvironmentId.Value)}"
+            + $"&protocolVersion={request.ProtocolVersion}"
+            + $"&pageSize={request.PageSize}"
+            + $"&excludeFull={request.ExcludeFull.ToString().ToLowerInvariant()}"
+            + (request.RegionId.HasValue ? $"&regionId={Escape(request.RegionId.Value.Value)}" : string.Empty)
+            + (request.Cursor is not null ? $"&cursor={Escape(request.Cursor)}" : string.Empty);
+        return _transport.SendSafeAsync<BrowseSessionsResponse>(
+            () => new HttpRequestMessage(HttpMethod.Get, query),
+            cancellationToken);
+    }
+
+    public async Task<RendezvousClientResult<IReadOnlyList<SessionListing>>> BrowseAllAsync(
+        BrowseSessionsRequest request,
+        int maximumPages = 100,
+        CancellationToken cancellationToken = default)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        if (maximumPages is < 1 or > 1000)
+        {
+            throw new ArgumentOutOfRangeException(nameof(maximumPages));
+        }
+
+        List<SessionListing> items = [];
+        string? cursor = request.Cursor;
+        for (int page = 0; page < maximumPages; page++)
+        {
+            BrowseSessionsRequest pageRequest = new()
+            {
+                ContractVersion = request.ContractVersion,
+                GameId = request.GameId,
+                EnvironmentId = request.EnvironmentId,
+                ProtocolVersion = request.ProtocolVersion,
+                RegionId = request.RegionId,
+                PageSize = request.PageSize,
+                ExcludeFull = request.ExcludeFull,
+                Cursor = cursor,
+            };
+            RendezvousClientResult<BrowseSessionsResponse> result = await BrowseAsync(
+                pageRequest,
+                cancellationToken).ConfigureAwait(false);
+            if (!result.IsSuccess || result.Value is null)
+            {
+                return RendezvousClientResult.Failure<IReadOnlyList<SessionListing>>(
+                    result.Error,
+                    result.Message,
+                    result.RetryAfterSeconds);
+            }
+
+            items.AddRange(result.Value.Items);
+            cursor = result.Value.NextCursor;
+            if (string.IsNullOrEmpty(cursor))
+            {
+                return RendezvousClientResult.Success<IReadOnlyList<SessionListing>>(items.AsReadOnly());
+            }
+        }
+
+        return RendezvousClientResult.Failure<IReadOnlyList<SessionListing>>(
+            RendezvousErrorCode.CapacityExceeded,
+            $"Browsing exceeded the configured {maximumPages}-page limit.");
+    }
+
+    public Task<RendezvousClientResult<GetSessionResponse>> GetAsync(
+        SessionListingId listingId,
+        GameId gameId,
+        EnvironmentId environmentId,
+        uint protocolVersion,
+        CancellationToken cancellationToken = default)
+    {
+        string query = $"v1/sessions/{listingId}?contractVersion={ContractLimits.ContractVersion}"
+            + $"&gameId={Escape(gameId.Value)}"
+            + $"&environmentId={Escape(environmentId.Value)}"
+            + $"&protocolVersion={protocolVersion}";
+        return _transport.SendSafeAsync<GetSessionResponse>(
+            () => new HttpRequestMessage(HttpMethod.Get, query),
+            cancellationToken);
+    }
+
+    private static string Escape(string value) => Uri.EscapeDataString(value ?? string.Empty);
+}

src/FinalFactory.Rendezvous.Client/SessionLeaseMaintainer.cs

@@ -0,0 +1,150 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public enum LeaseMaintenanceStopReason
+{
+    Cancelled = 1,
+    Disposed = 2,
+    LeaseLost = 3,
+    Failed = 4,
+}
+
+public sealed class LeaseMaintenanceResult
+{
+    internal LeaseMaintenanceResult(LeaseMaintenanceStopReason reason, RendezvousErrorCode error)
+    {
+        Reason = reason;
+        Error = error;
+    }
+
+    public LeaseMaintenanceStopReason Reason { get; }
+    public RendezvousErrorCode Error { get; }
+}
+
+public sealed class SessionLeaseMaintainer : IAsyncDisposable
+{
+    private readonly object _gate = new();
+    private readonly IRendezvousPublisherClient _publisher;
+    private readonly PublishedSession _session;
+    private readonly string _publisherCredential;
+    private readonly IRendezvousDelay _delay;
+    private readonly CancellationTokenSource _disposeCancellation = new();
+    private Task<LeaseMaintenanceResult>? _activeRun;
+    private Task? _disposeTask;
+    private bool _disposed;
+
+    internal SessionLeaseMaintainer(
+        IRendezvousPublisherClient publisher,
+        PublishedSession session,
+        string publisherCredential,
+        IRendezvousDelay? delay = null)
+    {
+        _publisher = publisher;
+        _session = session;
+        _publisherCredential = publisherCredential;
+        _delay = delay ?? new SystemRendezvousDelay();
+    }
+
+    public event EventHandler? LeaseLost;
+
+    public Task<LeaseMaintenanceResult> RunAsync(CancellationToken cancellationToken = default)
+    {
+        lock (_gate)
+        {
+            if (_disposed)
+            {
+                throw new ObjectDisposedException(nameof(SessionLeaseMaintainer));
+            }
+            if (_activeRun is not null)
+            {
+                throw new InvalidOperationException("Lease maintenance is already running.");
+            }
+
+            _activeRun = RunCoreAsync(cancellationToken);
+            return _activeRun;
+        }
+    }
+
+    public ValueTask DisposeAsync()
+    {
+        lock (_gate)
+        {
+            if (_disposeTask is not null)
+            {
+                return new(_disposeTask);
+            }
+
+            _disposed = true;
+            _disposeCancellation.Cancel();
+            _disposeTask = FinishDisposeAsync(_activeRun);
+            return new(_disposeTask);
+        }
+    }
+
+    private async Task FinishDisposeAsync(Task<LeaseMaintenanceResult>? active)
+    {
+        try
+        {
+            if (active is not null)
+            {
+                await active.ConfigureAwait(false);
+            }
+        }
+        finally
+        {
+            _disposeCancellation.Dispose();
+        }
+    }
+
+    private async Task<LeaseMaintenanceResult> RunCoreAsync(CancellationToken cancellationToken)
+    {
+        await Task.Yield();
+        using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(
+            cancellationToken,
+            _disposeCancellation.Token);
+        try
+        {
+            while (true)
+            {
+                await _delay.DelayAsync(
+                    TimeSpan.FromSeconds(Math.Max(1, _session.LeaseRenewAfterSeconds)),
+                    linked.Token).ConfigureAwait(false);
+                RendezvousClientResult<RenewLeaseResponse> renewed = await _publisher.RenewAsync(
+                    _session,
+                    _publisherCredential,
+                    linked.Token).ConfigureAwait(false);
+                if (renewed.IsSuccess)
+                {
+                    continue;
+                }
+
+                if (renewed.Error is RendezvousErrorCode.NotFound
+                    or RendezvousErrorCode.Expired
+                    or RendezvousErrorCode.Forbidden
+                    or RendezvousErrorCode.AuthenticationRequired)
+                {
+                    LeaseLost?.Invoke(this, EventArgs.Empty);
+                    return new(LeaseMaintenanceStopReason.LeaseLost, renewed.Error);
+                }
+
+                return new(LeaseMaintenanceStopReason.Failed, renewed.Error);
+            }
+        }
+        catch (OperationCanceledException) when (linked.IsCancellationRequested)
+        {
+            return new(
+                _disposeCancellation.IsCancellationRequested
+                    ? LeaseMaintenanceStopReason.Disposed
+                    : LeaseMaintenanceStopReason.Cancelled,
+                RendezvousErrorCode.None);
+        }
+        finally
+        {
+            lock (_gate)
+            {
+                _activeRun = null;
+            }
+        }
+    }
+}

src/FinalFactory.Rendezvous.Client/Traversal/DirectConnectionRequestCodec.cs

@@ -0,0 +1,83 @@
+using System.Text;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class DirectConnectionRequest
+{
+    public JoinAttemptId AttemptId { get; set; }
+    public string ConnectionTicket { get; set; } = string.Empty;
+
+    public override string ToString() =>
+        $"[DirectConnectionRequest {AttemptId}; ticket redacted]";
+}
+
+public static class DirectConnectionRequestCodec
+{
+    public const int EncodedLength = 63;
+
+    private const int MagicLength = 4;
+    private const int AttemptIdLength = 16;
+    private const int TicketLength = ContractLimits.DerivedCredentialCharacters;
+    private static readonly byte[] Magic = [(byte)'R', (byte)'V', (byte)'D', (byte)'1'];
+
+    public static bool IsRendezvousRequest(ReadOnlySpan<byte> encoded) =>
+        encoded.Length >= MagicLength && encoded[..MagicLength].SequenceEqual(Magic);
+
+    public static byte[] Encode(JoinAttemptId attemptId, string connectionTicket)
+    {
+        if (attemptId.Value == Guid.Empty
+            || connectionTicket is null
+            || connectionTicket.Length != TicketLength
+            || !ContractValidation.IsConnectionTicketValid(connectionTicket))
+        {
+            throw new ArgumentException("The direct connection request fields are invalid.");
+        }
+
+        byte[] encoded = new byte[EncodedLength];
+        Magic.CopyTo(encoded, 0);
+        if (!attemptId.Value.TryWriteBytes(encoded.AsSpan(MagicLength, AttemptIdLength)))
+        {
+            throw new InvalidOperationException("The join attempt identifier could not be encoded.");
+        }
+
+        Encoding.ASCII.GetBytes(
+            connectionTicket,
+            0,
+            connectionTicket.Length,
+            encoded,
+            MagicLength + AttemptIdLength);
+        return encoded;
+    }
+
+    public static bool TryDecode(
+        ReadOnlySpan<byte> encoded,
+        out DirectConnectionRequest? request)
+    {
+        request = null;
+        if (encoded.Length != EncodedLength
+            || !encoded[..MagicLength].SequenceEqual(Magic))
+        {
+            return false;
+        }
+
+        Guid attemptId = new(encoded.Slice(MagicLength, AttemptIdLength));
+        if (attemptId == Guid.Empty)
+        {
+            return false;
+        }
+
+        string ticket = Encoding.ASCII.GetString(encoded[(MagicLength + AttemptIdLength)..]);
+        if (!ContractValidation.IsConnectionTicketValid(ticket))
+        {
+            return false;
+        }
+
+        request = new DirectConnectionRequest
+        {
+            AttemptId = new JoinAttemptId(attemptId),
+            ConnectionTicket = ticket,
+        };
+        return true;
+    }
+}

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousClientCoordinator.cs

@@ -0,0 +1,290 @@
+using System.Net;
+using FinalFactory.Rendezvous.Contracts;
+using LiteNetLib;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class RendezvousClientCoordinator : IDisposable
+{
+    private readonly NetManager _manager;
+    private readonly RendezvousNetListener _networkEvents;
+    private readonly EventBasedNatPunchListener _punchEvents;
+    private readonly IPEndPoint _mediator;
+    private readonly CreateJoinAttemptResponse _attempt;
+    private readonly IRendezvousCoordinatorClock _clock;
+    private readonly RendezvousPunchRetrySchedule _retry;
+    private NetPeer? _connectingPeer;
+    private bool _cancelRequested;
+    private int _polling;
+    private bool _subscriptionsReleased;
+    private bool _disposed;
+
+    public RendezvousClientCoordinator(
+        NetManager manager,
+        RendezvousNetListener networkEvents,
+        IPEndPoint mediator,
+        CreateJoinAttemptResponse attempt,
+        RendezvousCoordinatorOptions? options = null)
+        : this(
+            manager,
+            networkEvents,
+            mediator,
+            attempt,
+            options,
+            new SystemRendezvousCoordinatorClock())
+    {
+    }
+
+    internal RendezvousClientCoordinator(
+        NetManager manager,
+        RendezvousNetListener networkEvents,
+        IPEndPoint mediator,
+        CreateJoinAttemptResponse attempt,
+        RendezvousCoordinatorOptions? options,
+        IRendezvousCoordinatorClock clock)
+    {
+        _manager = manager ?? throw new ArgumentNullException(nameof(manager));
+        _networkEvents = networkEvents ?? throw new ArgumentNullException(nameof(networkEvents));
+        _punchEvents = _networkEvents.PunchEvents;
+        _mediator = mediator ?? throw new ArgumentNullException(nameof(mediator));
+        _attempt = attempt ?? throw new ArgumentNullException(nameof(attempt));
+        _clock = clock ?? throw new ArgumentNullException(nameof(clock));
+        RendezvousCoordinatorOptions validated = (options ?? new RendezvousCoordinatorOptions())
+            .CopyAndValidate();
+        _retry = new(validated, _clock);
+
+        RendezvousManagerGuard.Validate(_manager, _networkEvents);
+        if (_mediator.Port is < 1 or > 65_535
+            || _attempt.AttemptId.Value == Guid.Empty
+            || _attempt.MediationHandle.Value == Guid.Empty
+            || !ContractValidation.IsCapabilityValid(_attempt.ClientPunchCapability)
+            || !ContractValidation.IsConnectionTicketValid(_attempt.ConnectionTicketDigest)
+            || _attempt.ExpiresAt <= _clock.UtcNow)
+        {
+            throw new ArgumentException("The client traversal inputs are invalid.");
+        }
+
+        _networkEvents.RendezvousPeerConnected += OnPeerConnected;
+        _networkEvents.RendezvousPeerDisconnected += OnPeerDisconnected;
+        _punchEvents.NatIntroductionSuccess += OnNatIntroductionSuccess;
+    }
+
+    public event EventHandler<RendezvousConnectionCompletedEventArgs>? Completed;
+
+    public RendezvousConnectionState State { get; private set; } = RendezvousConnectionState.Punching;
+    public NetPeer? ConnectedPeer { get; private set; }
+    public bool IsCompleted => IsTerminal(State);
+
+    public void Cancel() => Volatile.Write(ref _cancelRequested, true);
+
+    public async Task<RendezvousClientResult<bool>> CancelAsync(
+        IRendezvousJoinClient joinClient,
+        CancellationToken cancellationToken = default)
+    {
+        if (joinClient is null)
+        {
+            throw new ArgumentNullException(nameof(joinClient));
+        }
+
+        ThrowIfDisposed();
+        Cancel();
+        return await joinClient.CancelAsync(_attempt, cancellationToken).ConfigureAwait(false);
+    }
+
+    public void Poll()
+    {
+        ThrowIfDisposed();
+        if (IsCompleted)
+        {
+            return;
+        }
+
+        if (Interlocked.Exchange(ref _polling, 1) != 0)
+        {
+            throw new InvalidOperationException("The Rendezvous coordinator cannot be polled concurrently or recursively.");
+        }
+
+        try
+        {
+            if (Volatile.Read(ref _cancelRequested))
+            {
+                DisconnectPendingPeer();
+                Complete(RendezvousConnectionState.Cancelled);
+                return;
+            }
+
+            if (!_manager.IsRunning)
+            {
+                Complete(RendezvousConnectionState.ManagerStopped);
+                return;
+            }
+
+            _manager.PollEvents();
+            _manager.NatPunchModule.PollEvents();
+            if (IsCompleted)
+            {
+                return;
+            }
+
+            DateTimeOffset now = _clock.UtcNow;
+            if (Volatile.Read(ref _cancelRequested))
+            {
+                DisconnectPendingPeer();
+                Complete(RendezvousConnectionState.Cancelled);
+            }
+            else if (!_manager.IsRunning)
+            {
+                Complete(RendezvousConnectionState.ManagerStopped);
+            }
+            else if (now >= _attempt.ExpiresAt)
+            {
+                DisconnectPendingPeer();
+                Complete(RendezvousConnectionState.TimedOut);
+            }
+            else if (State == RendezvousConnectionState.Punching && _retry.IsDue(now))
+            {
+                if (_retry.IsExhausted)
+                {
+                    Complete(RendezvousConnectionState.TimedOut);
+                    return;
+                }
+
+                _manager.NatPunchModule.SendNatIntroduceRequest(
+                    _mediator,
+                    NatPunchRequestTokenCodec.Encode(
+                        NatPunchPeerRole.Client,
+                        _attempt.MediationHandle,
+                        _attempt.ClientPunchCapability));
+                _retry.RecordRequest();
+            }
+        }
+        finally
+        {
+            Volatile.Write(ref _polling, 0);
+        }
+    }
+
+    public void Dispose()
+    {
+        if (_disposed)
+        {
+            return;
+        }
+
+        if (!IsCompleted)
+        {
+            Complete(RendezvousConnectionState.Disposed);
+        }
+
+        ReleaseSubscriptions();
+        _disposed = true;
+    }
+
+    public override string ToString() =>
+        $"[RendezvousClientCoordinator {_attempt.AttemptId}; credentials redacted]";
+
+    private void OnNatIntroductionSuccess(
+        IPEndPoint target,
+        NatAddressType addressType,
+        string encodedIntroduction)
+    {
+        _ = addressType;
+        if (State != RendezvousConnectionState.Punching
+            || !NatIntroductionTokenCodec.TryDecode(
+                encodedIntroduction,
+                out NatIntroductionToken? introduction)
+            || introduction is null
+            || introduction.AttemptId != _attempt.AttemptId
+            || !NatIntroductionTokenCodec.MatchesDigest(
+                introduction.ConnectionTicket,
+                _attempt.ConnectionTicketDigest))
+        {
+            return;
+        }
+
+        byte[] connectionData = DirectConnectionRequestCodec.Encode(
+            introduction.AttemptId,
+            introduction.ConnectionTicket);
+        _connectingPeer = _manager.Connect(target, connectionData);
+        if (_connectingPeer is null
+            || _connectingPeer.ConnectionState != ConnectionState.Outgoing)
+        {
+            _connectingPeer = null;
+            Complete(RendezvousConnectionState.Rejected);
+            return;
+        }
+
+        State = RendezvousConnectionState.Connecting;
+    }
+
+    private void OnPeerConnected(NetPeer peer)
+    {
+        if (State != RendezvousConnectionState.Connecting
+            || !ReferenceEquals(peer, _connectingPeer))
+        {
+            return;
+        }
+
+        ConnectedPeer = peer;
+        Complete(RendezvousConnectionState.Connected, peer);
+    }
+
+    private void OnPeerDisconnected(NetPeer peer, DisconnectInfo disconnectInfo)
+    {
+        _ = disconnectInfo;
+        if (State == RendezvousConnectionState.Connecting
+            && ReferenceEquals(peer, _connectingPeer))
+        {
+            Complete(RendezvousConnectionState.Rejected);
+        }
+    }
+
+    private void DisconnectPendingPeer()
+    {
+        if (_connectingPeer is not null && State == RendezvousConnectionState.Connecting)
+        {
+            _connectingPeer.Disconnect();
+        }
+    }
+
+    private void Complete(RendezvousConnectionState terminalState, NetPeer? peer = null)
+    {
+        if (IsCompleted)
+        {
+            return;
+        }
+
+        State = terminalState;
+        ReleaseSubscriptions();
+        Completed?.Invoke(this, new(terminalState, peer));
+    }
+
+    private void ReleaseSubscriptions()
+    {
+        if (_subscriptionsReleased)
+        {
+            return;
+        }
+
+        _networkEvents.RendezvousPeerConnected -= OnPeerConnected;
+        _networkEvents.RendezvousPeerDisconnected -= OnPeerDisconnected;
+        _punchEvents.NatIntroductionSuccess -= OnNatIntroductionSuccess;
+        _subscriptionsReleased = true;
+    }
+
+    private static bool IsTerminal(RendezvousConnectionState state) => state is
+        RendezvousConnectionState.Connected
+        or RendezvousConnectionState.Cancelled
+        or RendezvousConnectionState.TimedOut
+        or RendezvousConnectionState.Rejected
+        or RendezvousConnectionState.ManagerStopped
+        or RendezvousConnectionState.Disposed;
+
+    private void ThrowIfDisposed()
+    {
+        if (_disposed)
+        {
+            throw new ObjectDisposedException(nameof(RendezvousClientCoordinator));
+        }
+    }
+}

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousCoordinatorAbstractions.cs

@@ -0,0 +1,124 @@
+using System.Security.Cryptography;
+using LiteNetLib;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public enum RendezvousConnectionState
+{
+    Punching = 1,
+    Connecting = 2,
+    Connected = 3,
+    Cancelled = 4,
+    TimedOut = 5,
+    Rejected = 6,
+    ManagerStopped = 7,
+    Disposed = 8,
+}
+
+public sealed class RendezvousConnectionCompletedEventArgs(
+    RendezvousConnectionState state,
+    NetPeer? peer = null) : EventArgs
+{
+    public RendezvousConnectionState State { get; } = state;
+    public NetPeer? Peer { get; } = peer;
+}
+
+public sealed class RendezvousCoordinatorOptions
+{
+    public int MaximumPunchRequests { get; set; } = 5;
+    public int MaximumAttemptChecksPerPoll { get; set; } = 128;
+    public TimeSpan InitialPunchRetryDelay { get; set; } = TimeSpan.FromMilliseconds(200);
+    public TimeSpan MaximumPunchRetryDelay { get; set; } = TimeSpan.FromSeconds(2);
+    public TimeSpan ConnectionTicketLifetime { get; set; } = TimeSpan.FromSeconds(20);
+    public double JitterRatio { get; set; } = 0.2;
+
+    internal RendezvousCoordinatorOptions CopyAndValidate()
+    {
+        if (MaximumPunchRequests is < 1 or > 20
+            || MaximumAttemptChecksPerPoll is < 1 or > 1_024
+            || InitialPunchRetryDelay < TimeSpan.FromMilliseconds(10)
+            || MaximumPunchRetryDelay < InitialPunchRetryDelay
+            || MaximumPunchRetryDelay > TimeSpan.FromSeconds(10)
+            || ConnectionTicketLifetime <= TimeSpan.Zero
+            || ConnectionTicketLifetime > TimeSpan.FromSeconds(20)
+            || JitterRatio is < 0 or > 1)
+        {
+            throw new ArgumentOutOfRangeException(nameof(RendezvousCoordinatorOptions));
+        }
+
+        return new RendezvousCoordinatorOptions
+        {
+            MaximumPunchRequests = MaximumPunchRequests,
+            MaximumAttemptChecksPerPoll = MaximumAttemptChecksPerPoll,
+            InitialPunchRetryDelay = InitialPunchRetryDelay,
+            MaximumPunchRetryDelay = MaximumPunchRetryDelay,
+            ConnectionTicketLifetime = ConnectionTicketLifetime,
+            JitterRatio = JitterRatio,
+        };
+    }
+}
+
+internal interface IRendezvousCoordinatorClock
+{
+    DateTimeOffset UtcNow { get; }
+}
+
+internal sealed class SystemRendezvousCoordinatorClock : IRendezvousCoordinatorClock
+{
+    public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
+}
+
+internal static class RendezvousManagerGuard
+{
+    internal static void Validate(
+        NetManager manager,
+        RendezvousNetListener networkEvents)
+    {
+        networkEvents.ValidateManager(manager);
+        if (!manager.IsRunning)
+        {
+            throw new InvalidOperationException("The caller-owned LiteNetLib manager must be running.");
+        }
+
+        if (!manager.NatPunchEnabled
+            || manager.UnsyncedEvents
+            || manager.NatPunchModule.UnsyncedEvents)
+        {
+            throw new InvalidOperationException(
+                "The caller-owned manager must enable NAT punching and synchronized event dispatch.");
+        }
+    }
+}
+
+internal sealed class RendezvousPunchRetrySchedule(
+    RendezvousCoordinatorOptions options,
+    IRendezvousCoordinatorClock clock)
+{
+    public int RequestsSent { get; private set; }
+    public DateTimeOffset NextRequestAt { get; private set; } = DateTimeOffset.MinValue;
+
+    public bool IsExhausted => RequestsSent >= options.MaximumPunchRequests;
+
+    public bool IsDue(DateTimeOffset now) => now >= NextRequestAt;
+
+    public void RecordRequest()
+    {
+        int exponent = Math.Min(RequestsSent, 30);
+        RequestsSent++;
+        double milliseconds = Math.Min(
+            options.InitialPunchRetryDelay.TotalMilliseconds * Math.Pow(2, exponent),
+            options.MaximumPunchRetryDelay.TotalMilliseconds);
+        if (options.JitterRatio > 0)
+        {
+            Span<byte> random = stackalloc byte[1];
+            RandomNumberGenerator.Fill(random);
+            double unit = random[0] / 255d;
+            double multiplier = 1 - options.JitterRatio + (2 * options.JitterRatio * unit);
+            milliseconds = Math.Min(
+                milliseconds * multiplier,
+                options.MaximumPunchRetryDelay.TotalMilliseconds);
+        }
+
+        NextRequestAt = clock.UtcNow + TimeSpan.FromMilliseconds(milliseconds);
+    }
+}

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousHostCoordinator.cs

@@ -0,0 +1,547 @@
+using System.Net;
+using FinalFactory.Rendezvous.Contracts;
+using LiteNetLib;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public enum RendezvousHostState
+{
+    Active = 1,
+    ManagerStopped = 2,
+    Disposed = 3,
+}
+
+public sealed class RendezvousHostAttemptCompletedEventArgs(
+    JoinAttemptId attemptId,
+    RendezvousConnectionState state,
+    NetPeer? peer = null) : EventArgs
+{
+    public JoinAttemptId AttemptId { get; } = attemptId;
+    public RendezvousConnectionState State { get; } = state;
+    public NetPeer? Peer { get; } = peer;
+}
+
+public sealed class RendezvousHostCoordinator : IDisposable
+{
+    private readonly NetManager _manager;
+    private readonly RendezvousNetListener _networkEvents;
+    private readonly EventBasedNatPunchListener _punchEvents;
+    private readonly IPEndPoint _mediator;
+    private readonly PublishedSession _session;
+    private readonly IRendezvousJoinClient _joinClient;
+    private readonly RendezvousCoordinatorOptions _options;
+    private readonly IRendezvousCoordinatorClock _clock;
+    private readonly ConnectionTicketValidator _tickets;
+    private readonly Dictionary<JoinAttemptId, PendingHostAttempt> _attempts = [];
+    private readonly Dictionary<NetPeer, JoinAttemptId> _acceptedPeers = [];
+    private readonly Dictionary<JoinAttemptId, DeferredConnectionRequest> _deferredRequests = [];
+    private readonly Dictionary<JoinAttemptId, DateTimeOffset> _terminalAttempts = [];
+    private readonly Queue<JoinAttemptId> _attemptSchedule = [];
+    private readonly List<JoinAttemptId> _cleanupScratch = [];
+    private HostJoinAttempt[]? _latestSnapshot;
+    private DateTimeOffset _nextPresenceAt = DateTimeOffset.MinValue;
+    private DateTimeOffset _nextTerminalCleanupAt = DateTimeOffset.MinValue;
+    private int _refreshing;
+    private int _polling;
+    private bool _subscriptionsReleased;
+    private int _disposed;
+
+    public RendezvousHostCoordinator(
+        NetManager manager,
+        RendezvousNetListener networkEvents,
+        IPEndPoint mediator,
+        PublishedSession session,
+        IRendezvousJoinClient joinClient,
+        RendezvousCoordinatorOptions? options = null)
+        : this(
+            manager,
+            networkEvents,
+            mediator,
+            session,
+            joinClient,
+            options,
+            new SystemRendezvousCoordinatorClock(),
+            null)
+    {
+    }
+
+    internal RendezvousHostCoordinator(
+        NetManager manager,
+        RendezvousNetListener networkEvents,
+        IPEndPoint mediator,
+        PublishedSession session,
+        IRendezvousJoinClient joinClient,
+        RendezvousCoordinatorOptions? options,
+        IRendezvousCoordinatorClock clock,
+        ConnectionTicketValidator? tickets)
+    {
+        _manager = manager ?? throw new ArgumentNullException(nameof(manager));
+        _networkEvents = networkEvents ?? throw new ArgumentNullException(nameof(networkEvents));
+        _punchEvents = _networkEvents.PunchEvents;
+        _mediator = mediator ?? throw new ArgumentNullException(nameof(mediator));
+        _session = session ?? throw new ArgumentNullException(nameof(session));
+        _joinClient = joinClient ?? throw new ArgumentNullException(nameof(joinClient));
+        _options = (options ?? new RendezvousCoordinatorOptions()).CopyAndValidate();
+        _clock = clock ?? throw new ArgumentNullException(nameof(clock));
+        _tickets = tickets ?? new ConnectionTicketValidator();
+
+        RendezvousManagerGuard.Validate(_manager, _networkEvents);
+        ValidateInputs();
+        _networkEvents.RendezvousConnectionRequest += OnConnectionRequest;
+        _networkEvents.RendezvousPeerConnected += OnPeerConnected;
+        _networkEvents.RendezvousPeerDisconnected += OnPeerDisconnected;
+        _punchEvents.NatIntroductionSuccess += OnNatIntroductionSuccess;
+    }
+
+    public event EventHandler<RendezvousHostAttemptCompletedEventArgs>? AttemptCompleted;
+
+    public RendezvousHostState State { get; private set; } = RendezvousHostState.Active;
+    public int PendingAttemptCount => _attempts.Count;
+    internal int DeferredRequestCount => _deferredRequests.Count;
+
+    public async Task<RendezvousClientResult<int>> RefreshJoinAttemptsAsync(
+        CancellationToken cancellationToken = default)
+    {
+        ThrowIfDisposed();
+        if (Interlocked.Exchange(ref _refreshing, 1) != 0)
+        {
+            throw new InvalidOperationException("A host invitation refresh is already running.");
+        }
+
+        try
+        {
+            RendezvousClientResult<IReadOnlyList<HostJoinAttempt>> result =
+                await _joinClient.BrowseAllForHostAsync(
+                    _session,
+                    cancellationToken: cancellationToken).ConfigureAwait(false);
+            if (!result.IsSuccess || result.Value is null)
+            {
+                return RendezvousClientResult.Failure<int>(
+                    result.Error,
+                    result.Message,
+                    result.RetryAfterSeconds);
+            }
+
+            HostJoinAttempt[] snapshot = result.Value.Select(CopyAttempt).ToArray();
+            if (Volatile.Read(ref _disposed) != 0)
+            {
+                throw new ObjectDisposedException(nameof(RendezvousHostCoordinator));
+            }
+
+            Interlocked.Exchange(ref _latestSnapshot, snapshot);
+            if (Volatile.Read(ref _disposed) != 0)
+            {
+                Interlocked.Exchange(ref _latestSnapshot, null);
+                throw new ObjectDisposedException(nameof(RendezvousHostCoordinator));
+            }
+
+            return RendezvousClientResult.Success(snapshot.Length);
+        }
+        finally
+        {
+            Volatile.Write(ref _refreshing, 0);
+        }
+    }
+
+    public void Poll()
+    {
+        ThrowIfDisposed();
+        if (State != RendezvousHostState.Active)
+        {
+            return;
+        }
+
+        if (Interlocked.Exchange(ref _polling, 1) != 0)
+        {
+            throw new InvalidOperationException("The Rendezvous coordinator cannot be polled concurrently or recursively.");
+        }
+
+        try
+        {
+            ApplySnapshots();
+            if (!_manager.IsRunning)
+            {
+                Stop(RendezvousHostState.ManagerStopped, RendezvousConnectionState.ManagerStopped);
+                return;
+            }
+
+            _manager.NatPunchModule.PollEvents();
+            _manager.PollEvents();
+            _manager.NatPunchModule.PollEvents();
+            if (State != RendezvousHostState.Active)
+            {
+                return;
+            }
+
+            DateTimeOffset now = _clock.UtcNow;
+            if (!_manager.IsRunning)
+            {
+                Stop(RendezvousHostState.ManagerStopped, RendezvousConnectionState.ManagerStopped);
+                return;
+            }
+
+            RefreshPresence(now);
+            int checks = Math.Min(
+                _attemptSchedule.Count,
+                _options.MaximumAttemptChecksPerPoll);
+            for (int index = 0; index < checks; index++)
+            {
+                JoinAttemptId attemptId = _attemptSchedule.Dequeue();
+                if (!_attempts.TryGetValue(attemptId, out PendingHostAttempt? attempt))
+                {
+                    continue;
+                }
+
+                if (now >= attempt.Invitation.ExpiresAt)
+                {
+                    CompleteAttempt(attemptId, RendezvousConnectionState.TimedOut);
+                    continue;
+                }
+
+                if (attempt.State == RendezvousConnectionState.Punching
+                    && attempt.Retry.IsDue(now))
+                {
+                    if (attempt.Retry.IsExhausted)
+                    {
+                        CompleteAttempt(attemptId, RendezvousConnectionState.TimedOut);
+                        continue;
+                    }
+
+                    _manager.NatPunchModule.SendNatIntroduceRequest(
+                        _mediator,
+                        NatPunchRequestTokenCodec.Encode(
+                            NatPunchPeerRole.Host,
+                            attempt.Invitation.MediationHandle,
+                            attempt.Invitation.HostPunchCapability));
+                    attempt.Retry.RecordRequest();
+                }
+
+                _attemptSchedule.Enqueue(attemptId);
+            }
+
+            if (now >= _nextTerminalCleanupAt)
+            {
+                _cleanupScratch.Clear();
+                foreach (KeyValuePair<JoinAttemptId, DateTimeOffset> terminal in _terminalAttempts)
+                {
+                    if (terminal.Value <= now)
+                    {
+                        _cleanupScratch.Add(terminal.Key);
+                    }
+                }
+
+                foreach (JoinAttemptId attemptId in _cleanupScratch)
+                {
+                    _terminalAttempts.Remove(attemptId);
+                }
+
+                _nextTerminalCleanupAt = now + TimeSpan.FromSeconds(1);
+            }
+        }
+        finally
+        {
+            Volatile.Write(ref _polling, 0);
+        }
+    }
+
+    public void Dispose()
+    {
+        if (Interlocked.Exchange(ref _disposed, 1) != 0)
+        {
+            return;
+        }
+
+        Stop(RendezvousHostState.Disposed, RendezvousConnectionState.Disposed);
+        Interlocked.Exchange(ref _latestSnapshot, null);
+        _attemptSchedule.Clear();
+        _terminalAttempts.Clear();
+        _cleanupScratch.Clear();
+        _tickets.Dispose();
+    }
+
+    public override string ToString() =>
+        $"[RendezvousHostCoordinator {_session.ListingId}; credentials redacted]";
+
+    private void ApplySnapshots()
+    {
+        HostJoinAttempt[]? latest = Interlocked.Exchange(ref _latestSnapshot, null);
+
+        if (latest is null)
+        {
+            return;
+        }
+
+        DateTimeOffset now = _clock.UtcNow;
+        foreach (HostJoinAttempt invitation in latest)
+        {
+            if (invitation.AttemptId.Value == Guid.Empty
+                || invitation.MediationHandle.Value == Guid.Empty
+                || !ContractValidation.IsCapabilityValid(invitation.HostPunchCapability)
+                || !ContractValidation.IsConnectionTicketValid(
+                    invitation.ConnectionTicketDigest))
+            {
+                continue;
+            }
+
+            if (invitation.IsCancelled)
+            {
+                if (_attempts.ContainsKey(invitation.AttemptId))
+                {
+                    CompleteAttempt(
+                        invitation.AttemptId,
+                        RendezvousConnectionState.Cancelled);
+                }
+
+                _terminalAttempts[invitation.AttemptId] = invitation.ExpiresAt;
+                continue;
+            }
+
+            if (invitation.ExpiresAt <= now
+                || _attempts.ContainsKey(invitation.AttemptId)
+                || _terminalAttempts.ContainsKey(invitation.AttemptId))
+            {
+                continue;
+            }
+
+            _attempts.Add(
+                invitation.AttemptId,
+                new PendingHostAttempt(
+                    CopyAttempt(invitation),
+                    new RendezvousPunchRetrySchedule(_options, _clock)));
+            _attemptSchedule.Enqueue(invitation.AttemptId);
+        }
+    }
+
+    private void RefreshPresence(DateTimeOffset now)
+    {
+        if (now < _nextPresenceAt || now >= _session.ExpiresAt)
+        {
+            return;
+        }
+
+        _manager.NatPunchModule.SendNatIntroduceRequest(
+            _mediator,
+            NatPunchRequestTokenCodec.Encode(
+                NatPunchPeerRole.HostPresence,
+                _session.HostPresenceHandle,
+                _session.HostPresenceCapability));
+        _nextPresenceAt = now + TimeSpan.FromSeconds(_session.HostPresenceRefreshAfterSeconds);
+    }
+
+    private void OnNatIntroductionSuccess(
+        IPEndPoint target,
+        NatAddressType addressType,
+        string encodedIntroduction)
+    {
+        _ = target;
+        _ = addressType;
+        if (!NatIntroductionTokenCodec.TryDecode(
+                encodedIntroduction,
+                out NatIntroductionToken? introduction)
+            || introduction is null
+            || !_attempts.TryGetValue(introduction.AttemptId, out PendingHostAttempt? attempt)
+            || !NatIntroductionTokenCodec.MatchesDigest(
+                introduction.ConnectionTicket,
+                attempt.Invitation.ConnectionTicketDigest)
+            || !_tickets.TryAuthorize(
+                introduction.AttemptId,
+                introduction.ConnectionTicket,
+                Min(
+                    attempt.Invitation.ExpiresAt,
+                    _clock.UtcNow + _options.ConnectionTicketLifetime)))
+        {
+            return;
+        }
+
+        attempt.State = RendezvousConnectionState.Connecting;
+        if (_deferredRequests.Remove(
+                introduction.AttemptId,
+                out DeferredConnectionRequest? deferred))
+        {
+            AcceptAuthorizedRequest(
+                introduction.AttemptId,
+                attempt,
+                deferred.Request,
+                deferred.ConnectionTicket);
+        }
+    }
+
+    private void OnConnectionRequest(ConnectionRequest request)
+    {
+        ReadOnlySpan<byte> data = request.Data.GetRemainingBytesSpan();
+        if (!DirectConnectionRequestCodec.IsRendezvousRequest(data))
+        {
+            return;
+        }
+
+        if (!DirectConnectionRequestCodec.TryDecode(data, out DirectConnectionRequest? connection)
+            || connection is null
+            || !_attempts.TryGetValue(connection.AttemptId, out PendingHostAttempt? attempt)
+            || !NatIntroductionTokenCodec.MatchesDigest(
+                connection.ConnectionTicket,
+                attempt.Invitation.ConnectionTicketDigest))
+        {
+            request.RejectForce([]);
+            return;
+        }
+
+        if (attempt.State == RendezvousConnectionState.Punching)
+        {
+            _deferredRequests[connection.AttemptId] = new(
+                request,
+                connection.ConnectionTicket);
+            return;
+        }
+
+        if (attempt.State != RendezvousConnectionState.Connecting)
+        {
+            request.RejectForce([]);
+            return;
+        }
+
+        AcceptAuthorizedRequest(
+            connection.AttemptId,
+            attempt,
+            request,
+            connection.ConnectionTicket);
+    }
+
+    private void OnPeerConnected(NetPeer peer)
+    {
+        if (_acceptedPeers.TryGetValue(peer, out JoinAttemptId attemptId))
+        {
+            CompleteAttempt(attemptId, RendezvousConnectionState.Connected, peer);
+        }
+    }
+
+    private void OnPeerDisconnected(NetPeer peer, DisconnectInfo disconnectInfo)
+    {
+        _ = disconnectInfo;
+        if (_acceptedPeers.TryGetValue(peer, out JoinAttemptId attemptId))
+        {
+            CompleteAttempt(attemptId, RendezvousConnectionState.Rejected);
+        }
+    }
+
+    private void CompleteAttempt(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState state,
+        NetPeer? peer = null)
+    {
+        if (!_attempts.Remove(attemptId, out PendingHostAttempt? attempt))
+        {
+            return;
+        }
+
+        if (attempt.AcceptedPeer is not null)
+        {
+            _acceptedPeers.Remove(attempt.AcceptedPeer);
+        }
+
+        _deferredRequests.Remove(attemptId);
+        _tickets.Revoke(attemptId);
+        _terminalAttempts[attemptId] = attempt.Invitation.ExpiresAt;
+        AttemptCompleted?.Invoke(this, new(attemptId, state, peer));
+    }
+
+    private void Stop(RendezvousHostState hostState, RendezvousConnectionState attemptState)
+    {
+        if (State != RendezvousHostState.Active)
+        {
+            return;
+        }
+
+        State = hostState;
+        foreach (JoinAttemptId attemptId in _attempts.Keys.ToArray())
+        {
+            CompleteAttempt(attemptId, attemptState);
+        }
+
+        ReleaseSubscriptions();
+    }
+
+    private void ReleaseSubscriptions()
+    {
+        if (_subscriptionsReleased)
+        {
+            return;
+        }
+
+        _networkEvents.RendezvousConnectionRequest -= OnConnectionRequest;
+        _networkEvents.RendezvousPeerConnected -= OnPeerConnected;
+        _networkEvents.RendezvousPeerDisconnected -= OnPeerDisconnected;
+        _punchEvents.NatIntroductionSuccess -= OnNatIntroductionSuccess;
+        _subscriptionsReleased = true;
+    }
+
+    private void ValidateInputs()
+    {
+        if (_mediator.Port is < 1 or > 65_535
+            || _session.HostPresenceHandle.Value == Guid.Empty
+            || !ContractValidation.IsCapabilityValid(_session.HostPresenceCapability)
+            || _session.HostPresenceRefreshAfterSeconds < 1
+            || _session.ExpiresAt <= _clock.UtcNow)
+        {
+            throw new ArgumentException("The host traversal inputs are invalid.");
+        }
+    }
+
+    private static HostJoinAttempt CopyAttempt(HostJoinAttempt attempt) => new()
+    {
+        AttemptId = attempt.AttemptId,
+        MediationHandle = attempt.MediationHandle,
+        HostPunchCapability = attempt.HostPunchCapability,
+        ConnectionTicketDigest = attempt.ConnectionTicketDigest,
+        IsCancelled = attempt.IsCancelled,
+        ExpiresAt = attempt.ExpiresAt,
+    };
+
+    private static DateTimeOffset Min(DateTimeOffset left, DateTimeOffset right) =>
+        left <= right ? left : right;
+
+    private void AcceptAuthorizedRequest(
+        JoinAttemptId attemptId,
+        PendingHostAttempt attempt,
+        ConnectionRequest request,
+        string connectionTicket)
+    {
+        ConnectionTicketConsumptionResult consumption = _tickets.Consume(
+            attemptId,
+            connectionTicket);
+        if (consumption != ConnectionTicketConsumptionResult.Accepted)
+        {
+            request.RejectForce([]);
+            return;
+        }
+
+        NetPeer peer = request.Accept();
+        attempt.AcceptedPeer = peer;
+        _acceptedPeers[peer] = attemptId;
+    }
+
+    private void ThrowIfDisposed()
+    {
+        if (Volatile.Read(ref _disposed) != 0)
+        {
+            throw new ObjectDisposedException(nameof(RendezvousHostCoordinator));
+        }
+    }
+
+    private sealed class PendingHostAttempt(
+        HostJoinAttempt invitation,
+        RendezvousPunchRetrySchedule retry)
+    {
+        internal HostJoinAttempt Invitation { get; } = invitation;
+        internal RendezvousPunchRetrySchedule Retry { get; } = retry;
+        internal RendezvousConnectionState State { get; set; } = RendezvousConnectionState.Punching;
+        internal NetPeer? AcceptedPeer { get; set; }
+    }
+
+    private sealed class DeferredConnectionRequest(
+        ConnectionRequest request,
+        string connectionTicket)
+    {
+        internal ConnectionRequest Request { get; } = request;
+        internal string ConnectionTicket { get; } = connectionTicket;
+    }
+}

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousNetListener.cs

@@ -0,0 +1,110 @@
+using System.Net;
+using System.Net.Sockets;
+using LiteNetLib;
+using LiteNetLib.Utils;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class RendezvousNetListener : INetEventListener
+{
+    private NetManager? _manager;
+
+    public EventBasedNetListener GameplayEvents { get; } = new();
+    public EventBasedNatPunchListener PunchEvents { get; } = new();
+
+    public NetManager CreateManager()
+    {
+        if (_manager is not null)
+        {
+            throw new InvalidOperationException(
+                "This Rendezvous listener is already bound to a LiteNetLib manager.");
+        }
+
+        NetManager manager = new(this) { NatPunchEnabled = true };
+        manager.NatPunchModule.Init(PunchEvents);
+        _manager = manager;
+        return manager;
+    }
+
+    internal event Action<NetPeer>? RendezvousPeerConnected;
+    internal event Action<NetPeer, DisconnectInfo>? RendezvousPeerDisconnected;
+    internal event Action<ConnectionRequest>? RendezvousConnectionRequest;
+
+    internal void ValidateManager(NetManager manager)
+    {
+        if (!ReferenceEquals(_manager, manager))
+        {
+            throw new InvalidOperationException(
+                "The LiteNetLib manager must be created by this Rendezvous listener.");
+        }
+    }
+
+    public void OnPeerConnected(NetPeer peer)
+    {
+        RendezvousPeerConnected?.Invoke(peer);
+        ((INetEventListener)GameplayEvents).OnPeerConnected(peer);
+    }
+
+    public void OnPeerDisconnected(NetPeer peer, DisconnectInfo disconnectInfo)
+    {
+        RendezvousPeerDisconnected?.Invoke(peer, disconnectInfo);
+        ((INetEventListener)GameplayEvents).OnPeerDisconnected(peer, disconnectInfo);
+    }
+
+    public void OnNetworkError(IPEndPoint endPoint, SocketError socketError) =>
+        ((INetEventListener)GameplayEvents).OnNetworkError(endPoint, socketError);
+
+    public void OnNetworkReceive(
+        NetPeer peer,
+        NetPacketReader reader,
+        byte channelNumber,
+        DeliveryMethod deliveryMethod) =>
+        ((INetEventListener)GameplayEvents).OnNetworkReceive(
+            peer,
+            reader,
+            channelNumber,
+            deliveryMethod);
+
+    public void OnNetworkReceiveUnconnected(
+        IPEndPoint remoteEndPoint,
+        NetPacketReader reader,
+        UnconnectedMessageType messageType) =>
+        ((INetEventListener)GameplayEvents).OnNetworkReceiveUnconnected(
+            remoteEndPoint,
+            reader,
+            messageType);
+
+    public void OnNetworkLatencyUpdate(NetPeer peer, int latency) =>
+        ((INetEventListener)GameplayEvents).OnNetworkLatencyUpdate(peer, latency);
+
+    public void OnConnectionRequest(ConnectionRequest request)
+    {
+        int position = request.Data.Position;
+        bool isRendezvous = DirectConnectionRequestCodec.IsRendezvousRequest(
+            request.Data.GetRemainingBytesSpan());
+        request.Data.SetPosition(position);
+        if (!isRendezvous)
+        {
+            ((INetEventListener)GameplayEvents).OnConnectionRequest(request);
+            return;
+        }
+
+        Action<ConnectionRequest>? handler = RendezvousConnectionRequest;
+        if (handler is null)
+        {
+            request.RejectForce([]);
+            return;
+        }
+
+        handler(request);
+    }
+
+    public void OnMessageDelivered(NetPeer peer, object userData) =>
+        ((INetEventListener)GameplayEvents).OnMessageDelivered(peer, userData);
+
+    public void OnNtpResponse(NtpPacket packet) =>
+        ((INetEventListener)GameplayEvents).OnNtpResponse(packet);
+
+    public void OnPeerAddressChanged(NetPeer peer, IPEndPoint previousAddress) =>
+        ((INetEventListener)GameplayEvents).OnPeerAddressChanged(peer, previousAddress);
+}

src/FinalFactory.Rendezvous.Client/packages.lock.json

@@ -8,8 +8,71 @@
         "resolved": "2.1.4",
         "contentHash": "KWlxvMw3Urpqj9joD96LRiK+LC62pQNs/zkXRJc+rHnxgkGp+vV703xzDrxRmv+V1YhCFfIGzs5nrVWtREIlyA=="
       },
+      "Microsoft.Bcl.AsyncInterfaces": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "TFI6OKYE1XZz4SGuTSH70c6SBdPpFktXsoa1gCxTr3mKrhmXirnvaS0tKz+J3ZWICEAmMpEGn59nO4ICtUpQXA=="
+      },
+      "System.Buffers": {
+        "type": "Transitive",
+        "resolved": "4.6.1",
+        "contentHash": "N8GXpmiLMtljq7gwvyS+1QvKT/W2J8sNAvx+HVg4NGmsG/H+2k/y9QI23auLJRterrzCiDH+IWAw4V/GPwsMlw=="
+      },
+      "System.IO.Pipelines": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "7WX0W96y3dpQdYG4sEGdh38g3/0lOD4/dKbn2rRVOVzKhzoZUn2gKNIKaFeKWs8RCbpFfmmEWsRhSy95hMpvqA==",
+        "dependencies": {
+          "System.Buffers": "4.6.1",
+          "System.Memory": "4.6.3",
+          "System.Threading.Tasks.Extensions": "4.6.3"
+        }
+      },
+      "System.Memory": {
+        "type": "Transitive",
+        "resolved": "4.6.3",
+        "contentHash": "qdcDOgnFZY40+Q9876JUHnlHu7bosOHX8XISRoH94fwk6hgaeQGSgfZd8srWRZNt5bV9ZW2TljcegDNxsf+96A=="
+      },
+      "System.Runtime.CompilerServices.Unsafe": {
+        "type": "Transitive",
+        "resolved": "6.1.2",
+        "contentHash": "2hBr6zdbIBTDE3EhK7NSVNdX58uTK6iHW/P/Axmm9sl1xoGSLqDvMtpecn226TNwHByFokYwJmt/aQQNlO5CRw=="
+      },
+      "System.Text.Encodings.Web": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "o16m2YpDN/pjHsnxf9pTGwkpcuvjW8v1/wGUwJtM1c3QZUKm7ZEO/eYRJg7iIx6GxS2Zv9lAMHpiQwHDdgqauA==",
+        "dependencies": {
+          "System.Buffers": "4.6.1",
+          "System.Memory": "4.6.3",
+          "System.Runtime.CompilerServices.Unsafe": "6.1.2"
+        }
+      },
+      "System.Threading.Tasks.Extensions": {
+        "type": "Transitive",
+        "resolved": "4.6.3",
+        "contentHash": "7sCiwilJLYbTZELaKnc7RecBBXWXA+xMLQWZKWawBxYjp6DBlSE3v9/UcvKBvr1vv2tTOhipiogM8rRmxlhrVA=="
+      },
       "finalfactory.rendezvous.contracts": {
-        "type": "Project"
+        "type": "Project",
+        "dependencies": {
+          "System.Text.Json": "[10.0.10, )"
+        }
+      },
+      "System.Text.Json": {
+        "type": "CentralTransitive",
+        "requested": "[10.0.10, )",
+        "resolved": "10.0.10",
+        "contentHash": "bmsO6UdYtBdtn32zYXfsh7KlyTIzV/3V9hdT9RIb4pXKgYOsNxXR+VbWigNwBtNFVGYGm6Hwmqw5a+/IWFd36Q==",
+        "dependencies": {
+          "Microsoft.Bcl.AsyncInterfaces": "10.0.10",
+          "System.Buffers": "4.6.1",
+          "System.IO.Pipelines": "10.0.10",
+          "System.Memory": "4.6.3",
+          "System.Runtime.CompilerServices.Unsafe": "6.1.2",
+          "System.Text.Encodings.Web": "10.0.10",
+          "System.Threading.Tasks.Extensions": "4.6.3"
+        }
       }
     }
   }

src/FinalFactory.Rendezvous.Contracts/ContractEnums.cs

@@ -0,0 +1,75 @@
+namespace FinalFactory.Rendezvous.Contracts;
+
+public enum RendezvousErrorCode
+{
+    None = 0,
+    InvalidRequest = 1,
+    UnsupportedContractVersion = 2,
+    IncompatibleProtocol = 3,
+    AuthenticationRequired = 4,
+    Forbidden = 5,
+    NotFound = 6,
+    Conflict = 7,
+    RateLimited = 8,
+    StaleHost = 9,
+    Expired = 10,
+    ReplayRejected = 11,
+    CapacityExceeded = 12,
+    ServiceUnavailable = 13,
+    InternalError = 14,
+}
+
+public enum ListingVisibility
+{
+    Public = 1,
+    Unlisted = 2,
+}
+
+public enum PublisherTrustMode
+{
+    ManagedDedicated = 1,
+    PlayerGrant = 2,
+    AnonymousUnlisted = 3,
+}
+
+public enum AddressFamilyKind
+{
+    Ipv4 = 4,
+    Ipv6 = 6,
+}
+
+public enum ConnectionOutcomeKind
+{
+    Connected = 1,
+    Cancelled = 2,
+    TimedOut = 3,
+    IncompatibleProtocol = 4,
+    StaleHost = 5,
+    ServiceRejected = 6,
+    HostRejected = 7,
+    TransportFailed = 8,
+    FallbackOffered = 9,
+}
+
+public enum UdpPresenceMessageType : byte
+{
+    HostPresence = 1,
+    ClientPresence = 2,
+}
+
+public enum UdpDecodeError
+{
+    None = 0,
+    DatagramTooLarge = 1,
+    Truncated = 2,
+    InvalidMagic = 3,
+    UnsupportedVersion = 4,
+    UnknownMessageType = 5,
+    InvalidFlags = 6,
+    InvalidHandle = 7,
+    InvalidAddressFamily = 8,
+    InvalidAddress = 9,
+    InvalidPort = 10,
+    InvalidCapability = 11,
+    TrailingData = 12,
+}

src/FinalFactory.Rendezvous.Contracts/ContractLimits.cs

@@ -0,0 +1,30 @@
+namespace FinalFactory.Rendezvous.Contracts;
+
+public static class ContractLimits
+{
+    public const int ContractVersion = 1;
+    public const int HttpRequestMaxBytes = 16 * 1024;
+    public const int BrowserResponseMaxBytes = 256 * 1024;
+    public const int UdpDatagramMaxBytes = 1_200;
+    public const int MetadataMaxBytes = 4 * 1024;
+    public const int MetadataMaxKeys = 32;
+    public const int MetadataKeyMaxBytes = 64;
+    public const int MetadataValueMaxBytes = 256;
+    public const int BrowserPageMaxItems = 100;
+    public const int GameIdMaxCharacters = 64;
+    public const int EnvironmentIdMaxCharacters = 32;
+    public const int RegionIdMaxCharacters = 32;
+    public const int DisplayNameMaxBytes = 128;
+    public const int BuildVersionMaxBytes = 64;
+    public const int IdempotencyKeyMaxCharacters = 64;
+    public const int CursorMaxCharacters = 512;
+    public const int DiagnosticCodeMaxCharacters = 64;
+    public const int ErrorMessageMaxBytes = 256;
+    public const int OpaqueHttpCredentialMaxCharacters = 1_024;
+    public const int UdpCapabilityMaxCharacters = 192;
+    public const int ConnectionTicketMaxCharacters = 192;
+    public const int DerivedCredentialCharacters = 43;
+    public const int NatPunchRequestTokenCharacters = 192;
+    public const int LiteNetLibNatTokenMaxCharacters = 256;
+    public const int SessionCapacityMaxPlayers = 10_000;
+}

src/FinalFactory.Rendezvous.Contracts/ContractModels.cs

@@ -0,0 +1,47 @@
+using System.Text.Json.Serialization;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+public sealed class SessionCapacity
+{
+    [JsonRequired]
+    public int CurrentPlayers { get; set; }
+
+    [JsonRequired]
+    public int MaximumPlayers { get; set; }
+}
+
+public sealed class NetworkEndpoint
+{
+    [JsonRequired]
+    public AddressFamilyKind AddressFamily { get; set; }
+
+    [JsonRequired]
+    public string Address { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public int Port { get; set; }
+}
+
+public sealed class ApiError
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public RendezvousErrorCode Code { get; set; }
+
+    [JsonRequired]
+    public string Message { get; set; } = string.Empty;
+    public string? CorrelationId { get; set; }
+    public int? RetryAfterSeconds { get; set; }
+}
+
+public sealed class HealthResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public string Status { get; set; } = string.Empty;
+}

src/FinalFactory.Rendezvous.Contracts/ContractValidation.cs

@@ -0,0 +1,136 @@
+using System.Net;
+using System.Net.Sockets;
+using System.Text;
+using System.Text.Json;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+public static class ContractValidation
+{
+    private const string CapabilityAlphabet =
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+    public static RendezvousErrorCode ValidateContractVersion(int contractVersion) =>
+        contractVersion == ContractLimits.ContractVersion
+            ? RendezvousErrorCode.None
+            : RendezvousErrorCode.UnsupportedContractVersion;
+
+    public static bool AreProtocolsCompatible(uint requested, uint offered) => requested == offered;
+
+    public static bool IsHttpRequestSizeValid(int byteCount) =>
+        byteCount is >= 0 and <= ContractLimits.HttpRequestMaxBytes;
+
+    public static bool IsBrowserResponseSizeValid(int byteCount) =>
+        byteCount is >= 0 and <= ContractLimits.BrowserResponseMaxBytes;
+
+    public static bool IsUtf8LengthWithin(string? value, int maximumBytes)
+    {
+        if (maximumBytes < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(maximumBytes));
+        }
+
+        return value is not null && Encoding.UTF8.GetByteCount(value) <= maximumBytes;
+    }
+
+    public static bool IsPageSizeValid(int pageSize) =>
+        pageSize is >= 1 and <= ContractLimits.BrowserPageMaxItems;
+
+    public static bool IsIdempotencyKeyValid(string? value) =>
+        IsVisibleAsciiWithin(value, ContractLimits.IdempotencyKeyMaxCharacters);
+
+    public static bool IsCursorValid(string? value) =>
+        value is null || IsVisibleAsciiWithin(value, ContractLimits.CursorMaxCharacters);
+
+    public static bool IsDiagnosticCodeValid(string? value) =>
+        value is null || IsVisibleAsciiWithin(value, ContractLimits.DiagnosticCodeMaxCharacters);
+
+    public static bool IsBuildVersionValid(string? value) =>
+        !string.IsNullOrWhiteSpace(value)
+        && IsUtf8LengthWithin(value, ContractLimits.BuildVersionMaxBytes);
+
+    public static bool IsDisplayNameValid(string? value) =>
+        !string.IsNullOrWhiteSpace(value)
+        && IsUtf8LengthWithin(value, ContractLimits.DisplayNameMaxBytes);
+
+    public static bool IsOpaqueHttpCredentialValid(string? value) =>
+        value is not null
+        && value.Length is > 0 and <= ContractLimits.OpaqueHttpCredentialMaxCharacters;
+
+    public static bool IsCapacityValid(SessionCapacity? capacity) =>
+        capacity is not null
+        && capacity.MaximumPlayers is >= 1 and <= ContractLimits.SessionCapacityMaxPlayers
+        && capacity.CurrentPlayers >= 0
+        && capacity.CurrentPlayers <= capacity.MaximumPlayers;
+
+    public static bool IsCapabilityValid(string? capability) =>
+        IsBase64UrlValueValid(capability, ContractLimits.UdpCapabilityMaxCharacters);
+
+    public static bool IsConnectionTicketValid(string? ticket) =>
+        IsBase64UrlValueValid(ticket, ContractLimits.ConnectionTicketMaxCharacters);
+
+    public static bool IsNetworkEndpointValid(NetworkEndpoint? endpoint)
+    {
+        if (endpoint is null
+            || endpoint.Port is < 1 or > ushort.MaxValue
+            || !IPAddress.TryParse(endpoint.Address, out IPAddress? address))
+        {
+            return false;
+        }
+
+        return endpoint.AddressFamily switch
+        {
+            AddressFamilyKind.Ipv4 => address.AddressFamily == AddressFamily.InterNetwork,
+            AddressFamilyKind.Ipv6 => address.AddressFamily == AddressFamily.InterNetworkV6,
+            _ => false,
+        };
+    }
+
+    public static bool IsMetadataValid(IReadOnlyDictionary<string, string>? metadata)
+    {
+        if (metadata is null || metadata.Count > ContractLimits.MetadataMaxKeys)
+        {
+            return false;
+        }
+
+        foreach (KeyValuePair<string, string> item in metadata)
+        {
+            if (string.IsNullOrWhiteSpace(item.Key)
+                || !IsUtf8LengthWithin(item.Key, ContractLimits.MetadataKeyMaxBytes)
+                || !IsUtf8LengthWithin(item.Value, ContractLimits.MetadataValueMaxBytes))
+            {
+                return false;
+            }
+        }
+
+        byte[] encoded = JsonSerializer.SerializeToUtf8Bytes(metadata, ContractJson.Options);
+        return encoded.Length <= ContractLimits.MetadataMaxBytes;
+    }
+
+    internal static bool IsSlug(string? value, int maximumCharacters)
+    {
+        if (string.IsNullOrEmpty(value)
+            || value.Length > maximumCharacters
+            || value[0] is < 'a' or > 'z')
+        {
+            return false;
+        }
+
+        return value.All(static character =>
+            character is >= 'a' and <= 'z'
+            or >= '0' and <= '9'
+            or '-');
+    }
+
+    private static bool IsBase64UrlValueValid(string? value, int maximumCharacters) =>
+        value is not null
+        && value.Length is > 0
+        && value.Length <= maximumCharacters
+        && value.All(static character => CapabilityAlphabet.Contains(character));
+
+    private static bool IsVisibleAsciiWithin(string? value, int maximumCharacters) =>
+        value is not null
+        && value.Length is > 0
+        && value.Length <= maximumCharacters
+        && value.All(static character => character is >= '!' and <= '~');
+}

src/FinalFactory.Rendezvous.Contracts/FinalFactory.Rendezvous.Contracts.csproj

@@ -7,4 +7,7 @@
     <PackageId>FinalFactory.Rendezvous.Contracts</PackageId>
     <Description>Versioned transport-neutral contracts for Final Factory Rendezvous.</Description>
   </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="System.Text.Json" />
+  </ItemGroup>
 </Project>

src/FinalFactory.Rendezvous.Contracts/Http/JoinContracts.cs

@@ -0,0 +1,101 @@
+using System.Text.Json.Serialization;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+public sealed class CreateJoinAttemptRequest
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public string IdempotencyKey { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public GameId GameId { get; set; }
+
+    [JsonRequired]
+    public EnvironmentId EnvironmentId { get; set; }
+
+    [JsonRequired]
+    public SessionListingId ListingId { get; set; }
+
+    [JsonRequired]
+    public uint ProtocolVersion { get; set; }
+}
+
+public sealed class CreateJoinAttemptResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public JoinAttemptId AttemptId { get; set; }
+
+    [JsonRequired]
+    public MediationHandle MediationHandle { get; set; }
+
+    [JsonRequired]
+    public string ClientPunchCapability { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string ConnectionTicketDigest { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public DateTimeOffset ExpiresAt { get; set; }
+    public NetworkEndpoint? DedicatedFallback { get; set; }
+}
+
+public sealed class HostJoinAttempt
+{
+    [JsonRequired]
+    public JoinAttemptId AttemptId { get; set; }
+
+    [JsonRequired]
+    public MediationHandle MediationHandle { get; set; }
+
+    [JsonRequired]
+    public string HostPunchCapability { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string ConnectionTicketDigest { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public bool IsCancelled { get; set; }
+
+    [JsonRequired]
+    public DateTimeOffset ExpiresAt { get; set; }
+}
+
+public sealed class BrowseHostJoinAttemptsResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public List<HostJoinAttempt> Items { get; set; } = [];
+
+    public string? NextCursor { get; set; }
+}
+
+public sealed class ReportConnectionOutcomeRequest
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public ConnectionOutcomeKind Outcome { get; set; }
+
+    [JsonRequired]
+    public int ElapsedMilliseconds { get; set; }
+
+    public string? DiagnosticCode { get; set; }
+}
+
+public sealed class ReportConnectionOutcomeResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public bool Accepted { get; set; }
+}

src/FinalFactory.Rendezvous.Contracts/Http/SessionContracts.cs

@@ -0,0 +1,200 @@
+using System.Text.Json.Serialization;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+public sealed class SessionListing
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public SessionListingId ListingId { get; set; }
+
+    [JsonRequired]
+    public GameId GameId { get; set; }
+
+    [JsonRequired]
+    public EnvironmentId EnvironmentId { get; set; }
+
+    [JsonRequired]
+    public RegionId RegionId { get; set; }
+
+    [JsonRequired]
+    public uint ProtocolVersion { get; set; }
+
+    [JsonRequired]
+    public string BuildVersion { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string DisplayName { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public ListingVisibility Visibility { get; set; }
+
+    [JsonRequired]
+    public PublisherTrustMode PublisherTrustMode { get; set; }
+
+    [JsonRequired]
+    public SessionCapacity Capacity { get; set; } = new();
+
+    [JsonRequired]
+    public Dictionary<string, string> Metadata { get; set; } = new(StringComparer.Ordinal);
+}
+
+public sealed class RegisterSessionRequest
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public string IdempotencyKey { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public GameId GameId { get; set; }
+
+    [JsonRequired]
+    public EnvironmentId EnvironmentId { get; set; }
+
+    [JsonRequired]
+    public RegionId RegionId { get; set; }
+
+    [JsonRequired]
+    public uint ProtocolVersion { get; set; }
+
+    [JsonRequired]
+    public string BuildVersion { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string DisplayName { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public ListingVisibility Visibility { get; set; }
+
+    [JsonRequired]
+    public SessionCapacity Capacity { get; set; } = new();
+
+    [JsonRequired]
+    public Dictionary<string, string> Metadata { get; set; } = new(StringComparer.Ordinal);
+}
+
+public sealed class RegisterSessionResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public SessionListingId ListingId { get; set; }
+
+    [JsonRequired]
+    public LeaseId LeaseId { get; set; }
+
+    [JsonRequired]
+    public string LeaseToken { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public MediationHandle HostPresenceHandle { get; set; }
+
+    [JsonRequired]
+    public string HostPresenceCapability { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public DateTimeOffset ExpiresAt { get; set; }
+
+    [JsonRequired]
+    public int LeaseRenewAfterSeconds { get; set; }
+
+    [JsonRequired]
+    public int HostPresenceRefreshAfterSeconds { get; set; }
+}
+
+public sealed class RenewLeaseRequest
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public string LeaseToken { get; set; } = string.Empty;
+}
+
+public sealed class RenewLeaseResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public DateTimeOffset ExpiresAt { get; set; }
+
+    [JsonRequired]
+    public int RenewAfterSeconds { get; set; }
+}
+
+public sealed class UpdateSessionRequest
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public string LeaseToken { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string BuildVersion { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string DisplayName { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public SessionCapacity Capacity { get; set; } = new();
+
+    [JsonRequired]
+    public Dictionary<string, string> Metadata { get; set; } = new(StringComparer.Ordinal);
+}
+
+public sealed class DeleteSessionRequest
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public string LeaseToken { get; set; } = string.Empty;
+}
+
+public sealed class BrowseSessionsRequest
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public GameId GameId { get; set; }
+
+    [JsonRequired]
+    public EnvironmentId EnvironmentId { get; set; }
+
+    [JsonRequired]
+    public uint ProtocolVersion { get; set; }
+    public RegionId? RegionId { get; set; }
+    public int PageSize { get; set; } = ContractLimits.BrowserPageMaxItems;
+
+    public bool ExcludeFull { get; set; }
+
+    public string? Cursor { get; set; }
+}
+
+public sealed class BrowseSessionsResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public List<SessionListing> Items { get; set; } = [];
+
+    public string? NextCursor { get; set; }
+}
+
+public sealed class GetSessionResponse
+{
+    [JsonRequired]
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+
+    [JsonRequired]
+    public SessionListing Session { get; set; } = new();
+}

src/FinalFactory.Rendezvous.Contracts/Identifiers/OpaqueIdentifiers.cs

@@ -0,0 +1,112 @@
+using System.Text.Json.Serialization;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+[JsonConverter(typeof(SessionListingIdJsonConverter))]
+public readonly struct SessionListingId : IEquatable<SessionListingId>
+{
+    public SessionListingId(Guid value) => Value = GuidIdentifier.RequireNonEmpty(value, nameof(value));
+    public Guid Value { get; }
+    public static bool TryParse(string? value, out SessionListingId id) =>
+        GuidIdentifier.TryParse(value, static guid => new SessionListingId(guid), out id);
+    public bool Equals(SessionListingId other) => Value.Equals(other.Value);
+    public override bool Equals(object? obj) => obj is SessionListingId other && Equals(other);
+    public override int GetHashCode() => Value.GetHashCode();
+    public override string ToString() => Value.ToString("D");
+    public static bool operator ==(SessionListingId left, SessionListingId right) => left.Equals(right);
+    public static bool operator !=(SessionListingId left, SessionListingId right) => !left.Equals(right);
+}
+
+[JsonConverter(typeof(LeaseIdJsonConverter))]
+public readonly struct LeaseId : IEquatable<LeaseId>
+{
+    public LeaseId(Guid value) => Value = GuidIdentifier.RequireNonEmpty(value, nameof(value));
+    public Guid Value { get; }
+    public static bool TryParse(string? value, out LeaseId id) =>
+        GuidIdentifier.TryParse(value, static guid => new LeaseId(guid), out id);
+    public bool Equals(LeaseId other) => Value.Equals(other.Value);
+    public override bool Equals(object? obj) => obj is LeaseId other && Equals(other);
+    public override int GetHashCode() => Value.GetHashCode();
+    public override string ToString() => Value.ToString("D");
+    public static bool operator ==(LeaseId left, LeaseId right) => left.Equals(right);
+    public static bool operator !=(LeaseId left, LeaseId right) => !left.Equals(right);
+}
+
+[JsonConverter(typeof(JoinAttemptIdJsonConverter))]
+public readonly struct JoinAttemptId : IEquatable<JoinAttemptId>
+{
+    public JoinAttemptId(Guid value) => Value = GuidIdentifier.RequireNonEmpty(value, nameof(value));
+    public Guid Value { get; }
+    public static bool TryParse(string? value, out JoinAttemptId id) =>
+        GuidIdentifier.TryParse(value, static guid => new JoinAttemptId(guid), out id);
+    public bool Equals(JoinAttemptId other) => Value.Equals(other.Value);
+    public override bool Equals(object? obj) => obj is JoinAttemptId other && Equals(other);
+    public override int GetHashCode() => Value.GetHashCode();
+    public override string ToString() => Value.ToString("D");
+    public static bool operator ==(JoinAttemptId left, JoinAttemptId right) => left.Equals(right);
+    public static bool operator !=(JoinAttemptId left, JoinAttemptId right) => !left.Equals(right);
+}
+
+[JsonConverter(typeof(MediationHandleJsonConverter))]
+public readonly struct MediationHandle : IEquatable<MediationHandle>
+{
+    public MediationHandle(Guid value) => Value = GuidIdentifier.RequireNonEmpty(value, nameof(value));
+    public Guid Value { get; }
+    public static bool TryParse(string? value, out MediationHandle id) =>
+        GuidIdentifier.TryParse(value, static guid => new MediationHandle(guid), out id);
+    public bool Equals(MediationHandle other) => Value.Equals(other.Value);
+    public override bool Equals(object? obj) => obj is MediationHandle other && Equals(other);
+    public override int GetHashCode() => Value.GetHashCode();
+    public override string ToString() => Value.ToString("D");
+    public static bool operator ==(MediationHandle left, MediationHandle right) => left.Equals(right);
+    public static bool operator !=(MediationHandle left, MediationHandle right) => !left.Equals(right);
+}
+
+internal static class GuidIdentifier
+{
+    public static Guid RequireNonEmpty(Guid value, string parameterName) =>
+        value != Guid.Empty
+            ? value
+            : throw new ArgumentException("Opaque identifiers cannot be empty.", parameterName);
+
+    public static bool TryParse<TIdentifier>(
+        string? value,
+        Func<Guid, TIdentifier> factory,
+        out TIdentifier identifier)
+    {
+        if (Guid.TryParseExact(value, "D", out Guid guid) && guid != Guid.Empty)
+        {
+            identifier = factory(guid);
+            return true;
+        }
+
+        identifier = default!;
+        return false;
+    }
+}
+
+internal abstract class GuidIdentifierJsonConverter<TIdentifier> :
+    StringIdentifierJsonConverter<TIdentifier>
+{
+    protected sealed override string Format(TIdentifier value) => value?.ToString() ?? string.Empty;
+}
+
+internal sealed class SessionListingIdJsonConverter : GuidIdentifierJsonConverter<SessionListingId>
+{
+    protected override SessionListingId Parse(string value) => new(Guid.ParseExact(value, "D"));
+}
+
+internal sealed class LeaseIdJsonConverter : GuidIdentifierJsonConverter<LeaseId>
+{
+    protected override LeaseId Parse(string value) => new(Guid.ParseExact(value, "D"));
+}
+
+internal sealed class JoinAttemptIdJsonConverter : GuidIdentifierJsonConverter<JoinAttemptId>
+{
+    protected override JoinAttemptId Parse(string value) => new(Guid.ParseExact(value, "D"));
+}
+
+internal sealed class MediationHandleJsonConverter : GuidIdentifierJsonConverter<MediationHandle>
+{
+    protected override MediationHandle Parse(string value) => new(Guid.ParseExact(value, "D"));
+}

src/FinalFactory.Rendezvous.Contracts/Identifiers/ScopeIdentifiers.cs

@@ -0,0 +1,126 @@
+using System.Text.Json.Serialization;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+[JsonConverter(typeof(GameIdJsonConverter))]
+public readonly struct GameId : IEquatable<GameId>
+{
+    public GameId(string value)
+    {
+        if (!ContractValidation.IsSlug(value, ContractLimits.GameIdMaxCharacters))
+        {
+            throw new ArgumentException("Game IDs must be lowercase URL-safe slugs.", nameof(value));
+        }
+
+        Value = value;
+    }
+
+    public string Value { get; }
+
+    public static bool TryParse(string? value, out GameId gameId)
+    {
+        if (ContractValidation.IsSlug(value, ContractLimits.GameIdMaxCharacters))
+        {
+            gameId = new GameId(value!);
+            return true;
+        }
+
+        gameId = default;
+        return false;
+    }
+
+    public bool Equals(GameId other) => string.Equals(Value, other.Value, StringComparison.Ordinal);
+    public override bool Equals(object? obj) => obj is GameId other && Equals(other);
+    public override int GetHashCode() => StringComparer.Ordinal.GetHashCode(Value ?? string.Empty);
+    public override string ToString() => Value ?? string.Empty;
+    public static bool operator ==(GameId left, GameId right) => left.Equals(right);
+    public static bool operator !=(GameId left, GameId right) => !left.Equals(right);
+}
+
+[JsonConverter(typeof(EnvironmentIdJsonConverter))]
+public readonly struct EnvironmentId : IEquatable<EnvironmentId>
+{
+    public EnvironmentId(string value)
+    {
+        if (!ContractValidation.IsSlug(value, ContractLimits.EnvironmentIdMaxCharacters))
+        {
+            throw new ArgumentException("Environment IDs must be lowercase URL-safe slugs.", nameof(value));
+        }
+
+        Value = value;
+    }
+
+    public string Value { get; }
+
+    public static bool TryParse(string? value, out EnvironmentId environmentId)
+    {
+        if (ContractValidation.IsSlug(value, ContractLimits.EnvironmentIdMaxCharacters))
+        {
+            environmentId = new EnvironmentId(value!);
+            return true;
+        }
+
+        environmentId = default;
+        return false;
+    }
+
+    public bool Equals(EnvironmentId other) => string.Equals(Value, other.Value, StringComparison.Ordinal);
+    public override bool Equals(object? obj) => obj is EnvironmentId other && Equals(other);
+    public override int GetHashCode() => StringComparer.Ordinal.GetHashCode(Value ?? string.Empty);
+    public override string ToString() => Value ?? string.Empty;
+    public static bool operator ==(EnvironmentId left, EnvironmentId right) => left.Equals(right);
+    public static bool operator !=(EnvironmentId left, EnvironmentId right) => !left.Equals(right);
+}
+
+[JsonConverter(typeof(RegionIdJsonConverter))]
+public readonly struct RegionId : IEquatable<RegionId>
+{
+    public RegionId(string value)
+    {
+        if (!ContractValidation.IsSlug(value, ContractLimits.RegionIdMaxCharacters))
+        {
+            throw new ArgumentException("Region IDs must be lowercase URL-safe slugs.", nameof(value));
+        }
+
+        Value = value;
+    }
+
+    public string Value { get; }
+
+    public static bool TryParse(string? value, out RegionId regionId)
+    {
+        if (ContractValidation.IsSlug(value, ContractLimits.RegionIdMaxCharacters))
+        {
+            regionId = new RegionId(value!);
+            return true;
+        }
+
+        regionId = default;
+        return false;
+    }
+
+    public bool Equals(RegionId other) => string.Equals(Value, other.Value, StringComparison.Ordinal);
+    public override bool Equals(object? obj) => obj is RegionId other && Equals(other);
+    public override int GetHashCode() => StringComparer.Ordinal.GetHashCode(Value ?? string.Empty);
+    public override string ToString() => Value ?? string.Empty;
+    public static bool operator ==(RegionId left, RegionId right) => left.Equals(right);
+    public static bool operator !=(RegionId left, RegionId right) => !left.Equals(right);
+}
+
+internal sealed class GameIdJsonConverter : StringIdentifierJsonConverter<GameId>
+{
+    protected override GameId Parse(string value) => new(value);
+    protected override string Format(GameId value) => value.Value;
+}
+
+internal sealed class EnvironmentIdJsonConverter : StringIdentifierJsonConverter<EnvironmentId>
+{
+    protected override EnvironmentId Parse(string value) => new(value);
+    protected override string Format(EnvironmentId value) => value.Value;
+}
+
+internal sealed class RegionIdJsonConverter : StringIdentifierJsonConverter<RegionId>
+{
+    protected override RegionId Parse(string value) => new(value);
+    protected override string Format(RegionId value) => value.Value;
+}

src/FinalFactory.Rendezvous.Contracts/Identifiers/StringIdentifierJsonConverter.cs

@@ -0,0 +1,37 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+internal abstract class StringIdentifierJsonConverter<TIdentifier> : JsonConverter<TIdentifier>
+{
+    public sealed override TIdentifier Read(
+        ref Utf8JsonReader reader,
+        Type typeToConvert,
+        JsonSerializerOptions options)
+    {
+        if (reader.TokenType != JsonTokenType.String)
+        {
+            throw new JsonException($"{typeof(TIdentifier).Name} must be a JSON string.");
+        }
+
+        string value = reader.GetString() ?? string.Empty;
+
+        try
+        {
+            return Parse(value);
+        }
+        catch (Exception exception) when (exception is ArgumentException or FormatException)
+        {
+            throw new JsonException($"Invalid {typeof(TIdentifier).Name}.", exception);
+        }
+    }
+
+    public sealed override void Write(
+        Utf8JsonWriter writer,
+        TIdentifier value,
+        JsonSerializerOptions options) => writer.WriteStringValue(Format(value));
+
+    protected abstract TIdentifier Parse(string value);
+    protected abstract string Format(TIdentifier value);
+}

src/FinalFactory.Rendezvous.Contracts/Serialization/ContractJson.cs

@@ -0,0 +1,49 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+public static class ContractJson
+{
+    private static readonly JsonSerializerOptions SharedOptions = CreateReadOnlyOptions();
+
+    public static JsonSerializerOptions Options => SharedOptions;
+
+    public static JsonSerializerOptions CreateOptions()
+    {
+        JsonSerializerOptions options = new(JsonSerializerDefaults.Web);
+        Configure(options);
+        return options;
+    }
+
+    public static void Configure(JsonSerializerOptions options)
+    {
+        if (options is null)
+        {
+            throw new ArgumentNullException(nameof(options));
+        }
+
+        options.AllowTrailingCommas = false;
+        options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
+        options.MaxDepth = 8;
+        options.NumberHandling = JsonNumberHandling.Strict;
+        options.PropertyNameCaseInsensitive = false;
+        options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
+        options.ReadCommentHandling = JsonCommentHandling.Disallow;
+        options.UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip;
+        options.WriteIndented = false;
+
+        if (!options.Converters.OfType<JsonStringEnumConverter>().Any())
+        {
+            options.Converters.Add(
+                new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, allowIntegerValues: false));
+        }
+    }
+
+    private static JsonSerializerOptions CreateReadOnlyOptions()
+    {
+        JsonSerializerOptions options = CreateOptions();
+        options.MakeReadOnly(populateMissingResolver: true);
+        return options;
+    }
+}

src/FinalFactory.Rendezvous.Contracts/Udp/NatIntroductionTokenCodec.cs

@@ -0,0 +1,149 @@
+using System.Security.Cryptography;
+using System.Text;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+public sealed class NatIntroductionToken
+{
+    public JoinAttemptId AttemptId { get; set; }
+    public string ConnectionTicket { get; set; } = string.Empty;
+
+    public override string ToString() =>
+        $"[NatIntroductionToken {AttemptId}; ticket redacted]";
+}
+
+public static class NatIntroductionTokenCodec
+{
+    public const int EncodedLength = ContractLimits.DerivedCredentialCharacters;
+
+    private const int DecodedLength = 32;
+    private const int AttemptIdLength = 16;
+    private const int AuthenticatorLength = DecodedLength - AttemptIdLength;
+
+    public static string Encode(JoinAttemptId attemptId, string derivedAuthenticator)
+    {
+        if (attemptId.Value == Guid.Empty
+            || !ContractValidation.IsConnectionTicketValid(derivedAuthenticator)
+            || !TryDecodeBase64Url(derivedAuthenticator, out byte[]? authenticator)
+            || authenticator.Length != DecodedLength)
+        {
+            throw new ArgumentException("The NAT introduction token fields are invalid.");
+        }
+
+        byte[] payload = new byte[DecodedLength];
+        try
+        {
+            if (!attemptId.Value.TryWriteBytes(payload.AsSpan(0, AttemptIdLength)))
+            {
+                throw new InvalidOperationException("The join attempt identifier could not be encoded.");
+            }
+
+            authenticator.AsSpan(0, AuthenticatorLength).CopyTo(payload.AsSpan(AttemptIdLength));
+            return EncodeBase64Url(payload);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(authenticator);
+            CryptographicOperations.ZeroMemory(payload);
+        }
+    }
+
+    public static bool TryDecode(string? encoded, out NatIntroductionToken? token)
+    {
+        token = null;
+        if (!ContractValidation.IsConnectionTicketValid(encoded)
+            || !TryDecodeBase64Url(encoded!, out byte[]? payload)
+            || payload.Length != DecodedLength)
+        {
+            return false;
+        }
+
+        try
+        {
+            Guid attemptId = new(payload.AsSpan(0, AttemptIdLength));
+            if (attemptId == Guid.Empty)
+            {
+                return false;
+            }
+
+            token = new NatIntroductionToken
+            {
+                AttemptId = new JoinAttemptId(attemptId),
+                ConnectionTicket = encoded!,
+            };
+            return true;
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(payload);
+        }
+    }
+
+    public static string ComputeDigest(string connectionTicket)
+    {
+        if (!ContractValidation.IsConnectionTicketValid(connectionTicket))
+        {
+            throw new ArgumentException("The connection ticket is invalid.", nameof(connectionTicket));
+        }
+
+        byte[] encoded = Encoding.ASCII.GetBytes(connectionTicket);
+        byte[] digest;
+        using (SHA256 sha256 = SHA256.Create())
+        {
+            digest = sha256.ComputeHash(encoded);
+        }
+        CryptographicOperations.ZeroMemory(encoded);
+        try
+        {
+            return EncodeBase64Url(digest);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(digest);
+        }
+    }
+
+    public static bool MatchesDigest(string? connectionTicket, string? expectedDigest)
+    {
+        if (!ContractValidation.IsConnectionTicketValid(connectionTicket)
+            || !ContractValidation.IsConnectionTicketValid(expectedDigest))
+        {
+            return false;
+        }
+
+        byte[] actual = Encoding.ASCII.GetBytes(ComputeDigest(connectionTicket!));
+        byte[] expected = Encoding.ASCII.GetBytes(expectedDigest!);
+        try
+        {
+            return CryptographicOperations.FixedTimeEquals(actual, expected);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(actual);
+            CryptographicOperations.ZeroMemory(expected);
+        }
+    }
+
+    private static bool TryDecodeBase64Url(string? encoded, out byte[] bytes)
+    {
+        bytes = [];
+        if (encoded is null || encoded.Length != EncodedLength)
+        {
+            return false;
+        }
+
+        try
+        {
+            bytes = Convert.FromBase64String(
+                encoded.Replace('-', '+').Replace('_', '/') + "=");
+            return true;
+        }
+        catch (FormatException)
+        {
+            return false;
+        }
+    }
+
+    private static string EncodeBase64Url(byte[] value) =>
+        Convert.ToBase64String(value).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+}

src/FinalFactory.Rendezvous.Contracts/Udp/NatPunchRequestTokenCodec.cs

@@ -0,0 +1,131 @@
+namespace FinalFactory.Rendezvous.Contracts;
+
+public enum NatPunchPeerRole
+{
+    HostPresence = 1,
+    Host = 2,
+    Client = 3,
+}
+
+public sealed class NatPunchRequestToken
+{
+    public NatPunchPeerRole Role { get; set; }
+    public MediationHandle MediationHandle { get; set; }
+    public string Capability { get; set; } = string.Empty;
+
+    public override string ToString() => "[NatPunchRequestToken: capability redacted]";
+}
+
+public static class NatPunchRequestTokenCodec
+{
+    public const int EncodedLength = ContractLimits.NatPunchRequestTokenCharacters;
+
+    private const string VersionPrefix = "rv1:";
+    private const int HandleLength = 32;
+    private const int CapabilityLength = ContractLimits.DerivedCredentialCharacters;
+    private const char Separator = ':';
+    private const char Padding = '.';
+
+    public static string Encode(
+        NatPunchPeerRole role,
+        MediationHandle mediationHandle,
+        string capability)
+    {
+        if (!TryGetRoleCode(role, out char roleCode)
+            || mediationHandle.Value == Guid.Empty
+            || capability is null
+            || capability.Length != CapabilityLength
+            || !ContractValidation.IsCapabilityValid(capability))
+        {
+            throw new ArgumentException("The NAT punch request token fields are invalid.");
+        }
+
+        string payload = string.Concat(
+            VersionPrefix,
+            roleCode,
+            Separator,
+            mediationHandle.Value.ToString("N"),
+            Separator,
+            capability);
+        return payload.PadRight(EncodedLength, Padding);
+    }
+
+    public static bool TryDecode(string? encoded, out NatPunchRequestToken? token)
+    {
+        token = null;
+        if (encoded is null
+            || encoded.Length != EncodedLength
+            || !encoded.StartsWith(VersionPrefix, StringComparison.Ordinal)
+            || !TryParseRole(encoded[VersionPrefix.Length], out NatPunchPeerRole role))
+        {
+            return false;
+        }
+
+        int roleSeparator = VersionPrefix.Length + 1;
+        int handleOffset = roleSeparator + 1;
+        int capabilitySeparator = handleOffset + HandleLength;
+        int capabilityOffset = capabilitySeparator + 1;
+        int paddingOffset = capabilityOffset + CapabilityLength;
+        string handleText = encoded.Substring(handleOffset, HandleLength);
+        if (encoded[roleSeparator] != Separator
+            || encoded[capabilitySeparator] != Separator
+            || !Guid.TryParseExact(handleText, "N", out Guid handle)
+            || handle == Guid.Empty
+            || !string.Equals(handleText, handle.ToString("N"), StringComparison.Ordinal)
+            || !ContainsOnlyPadding(encoded, paddingOffset))
+        {
+            return false;
+        }
+
+        string capability = encoded.Substring(capabilityOffset, CapabilityLength);
+        if (!ContractValidation.IsCapabilityValid(capability))
+        {
+            return false;
+        }
+
+        token = new NatPunchRequestToken
+        {
+            Role = role,
+            MediationHandle = new MediationHandle(handle),
+            Capability = capability,
+        };
+        return true;
+    }
+
+    private static bool TryGetRoleCode(NatPunchPeerRole role, out char code)
+    {
+        code = role switch
+        {
+            NatPunchPeerRole.HostPresence => 'p',
+            NatPunchPeerRole.Host => 'h',
+            NatPunchPeerRole.Client => 'c',
+            _ => default,
+        };
+        return code != default;
+    }
+
+    private static bool TryParseRole(char code, out NatPunchPeerRole role)
+    {
+        role = code switch
+        {
+            'p' => NatPunchPeerRole.HostPresence,
+            'h' => NatPunchPeerRole.Host,
+            'c' => NatPunchPeerRole.Client,
+            _ => default,
+        };
+        return role != default;
+    }
+
+    private static bool ContainsOnlyPadding(string value, int offset)
+    {
+        for (int index = offset; index < value.Length; index++)
+        {
+            if (value[index] != Padding)
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

src/FinalFactory.Rendezvous.Contracts/Udp/PresenceDatagram.cs

@@ -0,0 +1,12 @@
+namespace FinalFactory.Rendezvous.Contracts;
+
+public sealed class PresenceDatagram
+{
+    public int ContractVersion { get; set; } = ContractLimits.ContractVersion;
+    public UdpPresenceMessageType MessageType { get; set; }
+    public MediationHandle MediationHandle { get; set; }
+    public AddressFamilyKind AddressFamily { get; set; }
+    public string LocalAddress { get; set; } = string.Empty;
+    public int LocalPort { get; set; }
+    public string Capability { get; set; } = string.Empty;
+}

src/FinalFactory.Rendezvous.Contracts/Udp/RendezvousUdpCodec.cs

@@ -0,0 +1,281 @@
+using System.Net;
+using System.Net.Sockets;
+using System.Text;
+
+namespace FinalFactory.Rendezvous.Contracts;
+
+public static class RendezvousUdpCodec
+{
+    public const byte MagicFirst = 0x52;
+    public const byte MagicSecond = 0x56;
+    public const byte FlagsNone = 0;
+
+    private const int FixedPrefixLength = 23;
+    private const int FixedSuffixLength = 3;
+
+    public static byte[] Encode(PresenceDatagram datagram)
+    {
+        if (datagram is null)
+        {
+            throw new ArgumentNullException(nameof(datagram));
+        }
+
+        if (ContractValidation.ValidateContractVersion(datagram.ContractVersion)
+            != RendezvousErrorCode.None)
+        {
+            throw new ArgumentException("The UDP contract version is unsupported.", nameof(datagram));
+        }
+
+        if (datagram.MessageType is not UdpPresenceMessageType.HostPresence
+            and not UdpPresenceMessageType.ClientPresence)
+        {
+            throw new ArgumentException("The UDP presence message type is unknown.", nameof(datagram));
+        }
+
+        if (datagram.MediationHandle.Value == Guid.Empty)
+        {
+            throw new ArgumentException("The mediation handle cannot be empty.", nameof(datagram));
+        }
+
+        if (!TryGetAddressBytes(datagram.LocalAddress, datagram.AddressFamily, out byte[] addressBytes))
+        {
+            throw new ArgumentException("The local address does not match its address family.", nameof(datagram));
+        }
+
+        if (datagram.LocalPort is < 1 or > ushort.MaxValue)
+        {
+            throw new ArgumentOutOfRangeException(nameof(datagram), "The local port must be between 1 and 65535.");
+        }
+
+        if (!ContractValidation.IsCapabilityValid(datagram.Capability))
+        {
+            throw new ArgumentException("The UDP capability is invalid.", nameof(datagram));
+        }
+
+        byte[] capabilityBytes = Encoding.ASCII.GetBytes(datagram.Capability);
+        int encodedLength = FixedPrefixLength + addressBytes.Length + FixedSuffixLength
+            + capabilityBytes.Length;
+        if (encodedLength > ContractLimits.UdpDatagramMaxBytes)
+        {
+            throw new ArgumentException("The encoded UDP datagram exceeds its size limit.", nameof(datagram));
+        }
+
+        byte[] encoded = new byte[encodedLength];
+        int offset = 0;
+        encoded[offset++] = MagicFirst;
+        encoded[offset++] = MagicSecond;
+        encoded[offset++] = checked((byte)datagram.ContractVersion);
+        encoded[offset++] = (byte)datagram.MessageType;
+        encoded[offset++] = FlagsNone;
+        WriteGuid(datagram.MediationHandle.Value, encoded, offset);
+        offset += 16;
+        encoded[offset++] = (byte)datagram.AddressFamily;
+        encoded[offset++] = checked((byte)addressBytes.Length);
+        addressBytes.CopyTo(encoded, offset);
+        offset += addressBytes.Length;
+        encoded[offset++] = checked((byte)(datagram.LocalPort >> 8));
+        encoded[offset++] = checked((byte)(datagram.LocalPort & 0xff));
+        encoded[offset++] = checked((byte)capabilityBytes.Length);
+        capabilityBytes.CopyTo(encoded, offset);
+        return encoded;
+    }
+
+    public static bool TryDecode(
+        ReadOnlySpan<byte> encoded,
+        out PresenceDatagram? datagram,
+        out UdpDecodeError error)
+    {
+        datagram = null;
+        error = UdpDecodeError.None;
+
+        if (encoded.Length > ContractLimits.UdpDatagramMaxBytes)
+        {
+            error = UdpDecodeError.DatagramTooLarge;
+            return false;
+        }
+
+        if (encoded.Length < FixedPrefixLength)
+        {
+            error = UdpDecodeError.Truncated;
+            return false;
+        }
+
+        int offset = 0;
+        if (encoded[offset++] != MagicFirst || encoded[offset++] != MagicSecond)
+        {
+            error = UdpDecodeError.InvalidMagic;
+            return false;
+        }
+
+        int version = encoded[offset++];
+        if (ContractValidation.ValidateContractVersion(version) != RendezvousErrorCode.None)
+        {
+            error = UdpDecodeError.UnsupportedVersion;
+            return false;
+        }
+
+        UdpPresenceMessageType messageType = (UdpPresenceMessageType)encoded[offset++];
+        if (messageType is not UdpPresenceMessageType.HostPresence
+            and not UdpPresenceMessageType.ClientPresence)
+        {
+            error = UdpDecodeError.UnknownMessageType;
+            return false;
+        }
+
+        if (encoded[offset++] != FlagsNone)
+        {
+            error = UdpDecodeError.InvalidFlags;
+            return false;
+        }
+
+        if (!TryReadGuid(encoded.Slice(offset, 16), out Guid handle)
+            || handle == Guid.Empty)
+        {
+            error = UdpDecodeError.InvalidHandle;
+            return false;
+        }
+
+        offset += 16;
+        AddressFamilyKind addressFamily = (AddressFamilyKind)encoded[offset++];
+        int expectedAddressLength = addressFamily switch
+        {
+            AddressFamilyKind.Ipv4 => 4,
+            AddressFamilyKind.Ipv6 => 16,
+            _ => 0,
+        };
+        if (expectedAddressLength == 0)
+        {
+            error = UdpDecodeError.InvalidAddressFamily;
+            return false;
+        }
+
+        int addressLength = encoded[offset++];
+        if (addressLength != expectedAddressLength)
+        {
+            error = UdpDecodeError.InvalidAddress;
+            return false;
+        }
+
+        if (encoded.Length < offset + addressLength + FixedSuffixLength)
+        {
+            error = UdpDecodeError.Truncated;
+            return false;
+        }
+
+        string address;
+        try
+        {
+            address = new IPAddress(encoded.Slice(offset, addressLength).ToArray()).ToString();
+        }
+        catch (ArgumentException)
+        {
+            error = UdpDecodeError.InvalidAddress;
+            return false;
+        }
+
+        offset += addressLength;
+        int port = (encoded[offset++] << 8) | encoded[offset++];
+        if (port == 0)
+        {
+            error = UdpDecodeError.InvalidPort;
+            return false;
+        }
+
+        int capabilityLength = encoded[offset++];
+        if (capabilityLength == 0 || capabilityLength > ContractLimits.UdpCapabilityMaxCharacters)
+        {
+            error = UdpDecodeError.InvalidCapability;
+            return false;
+        }
+
+        if (encoded.Length < offset + capabilityLength)
+        {
+            error = UdpDecodeError.Truncated;
+            return false;
+        }
+
+        if (encoded.Length > offset + capabilityLength)
+        {
+            error = UdpDecodeError.TrailingData;
+            return false;
+        }
+
+        string capability = Encoding.ASCII.GetString(encoded.Slice(offset, capabilityLength).ToArray());
+        if (!ContractValidation.IsCapabilityValid(capability))
+        {
+            error = UdpDecodeError.InvalidCapability;
+            return false;
+        }
+
+        datagram = new PresenceDatagram
+        {
+            ContractVersion = version,
+            MessageType = messageType,
+            MediationHandle = new MediationHandle(handle),
+            AddressFamily = addressFamily,
+            LocalAddress = address,
+            LocalPort = port,
+            Capability = capability,
+        };
+        return true;
+    }
+
+    private static bool TryGetAddressBytes(
+        string value,
+        AddressFamilyKind addressFamily,
+        out byte[] addressBytes)
+    {
+        addressBytes = [];
+        if (!IPAddress.TryParse(value, out IPAddress? address))
+        {
+            return false;
+        }
+
+        bool familyMatches = addressFamily switch
+        {
+            AddressFamilyKind.Ipv4 => address.AddressFamily == AddressFamily.InterNetwork,
+            AddressFamilyKind.Ipv6 => address.AddressFamily == AddressFamily.InterNetworkV6,
+            _ => false,
+        };
+        if (!familyMatches)
+        {
+            return false;
+        }
+
+        addressBytes = address.GetAddressBytes();
+        return true;
+    }
+
+    private static void WriteGuid(Guid value, byte[] destination, int offset)
+    {
+        string hexadecimal = value.ToString("N");
+        for (int index = 0; index < 16; index++)
+        {
+            int high = ParseHexadecimal(hexadecimal[index * 2]);
+            int low = ParseHexadecimal(hexadecimal[(index * 2) + 1]);
+            destination[offset + index] = checked((byte)((high << 4) | low));
+        }
+    }
+
+    private static bool TryReadGuid(ReadOnlySpan<byte> encoded, out Guid value)
+    {
+        char[] hexadecimal = new char[32];
+        for (int index = 0; index < encoded.Length; index++)
+        {
+            hexadecimal[index * 2] = FormatHexadecimal(encoded[index] >> 4);
+            hexadecimal[(index * 2) + 1] = FormatHexadecimal(encoded[index] & 0x0f);
+        }
+
+        return Guid.TryParseExact(new string(hexadecimal), "N", out value);
+    }
+
+    private static int ParseHexadecimal(char value) => value switch
+    {
+        >= '0' and <= '9' => value - '0',
+        >= 'a' and <= 'f' => value - 'a' + 10,
+        _ => throw new FormatException("A GUID contained a non-hexadecimal character."),
+    };
+
+    private static char FormatHexadecimal(int value) =>
+        (char)(value < 10 ? '0' + value : 'a' + value - 10);
+}

src/FinalFactory.Rendezvous.Contracts/packages.lock.json

@@ -1,6 +1,67 @@
 {
   "version": 2,
   "dependencies": {
-    ".NETStandard,Version=v2.1": {}
+    ".NETStandard,Version=v2.1": {
+      "System.Text.Json": {
+        "type": "Direct",
+        "requested": "[10.0.10, )",
+        "resolved": "10.0.10",
+        "contentHash": "bmsO6UdYtBdtn32zYXfsh7KlyTIzV/3V9hdT9RIb4pXKgYOsNxXR+VbWigNwBtNFVGYGm6Hwmqw5a+/IWFd36Q==",
+        "dependencies": {
+          "Microsoft.Bcl.AsyncInterfaces": "10.0.10",
+          "System.Buffers": "4.6.1",
+          "System.IO.Pipelines": "10.0.10",
+          "System.Memory": "4.6.3",
+          "System.Runtime.CompilerServices.Unsafe": "6.1.2",
+          "System.Text.Encodings.Web": "10.0.10",
+          "System.Threading.Tasks.Extensions": "4.6.3"
+        }
+      },
+      "Microsoft.Bcl.AsyncInterfaces": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "TFI6OKYE1XZz4SGuTSH70c6SBdPpFktXsoa1gCxTr3mKrhmXirnvaS0tKz+J3ZWICEAmMpEGn59nO4ICtUpQXA=="
+      },
+      "System.Buffers": {
+        "type": "Transitive",
+        "resolved": "4.6.1",
+        "contentHash": "N8GXpmiLMtljq7gwvyS+1QvKT/W2J8sNAvx+HVg4NGmsG/H+2k/y9QI23auLJRterrzCiDH+IWAw4V/GPwsMlw=="
+      },
+      "System.IO.Pipelines": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "7WX0W96y3dpQdYG4sEGdh38g3/0lOD4/dKbn2rRVOVzKhzoZUn2gKNIKaFeKWs8RCbpFfmmEWsRhSy95hMpvqA==",
+        "dependencies": {
+          "System.Buffers": "4.6.1",
+          "System.Memory": "4.6.3",
+          "System.Threading.Tasks.Extensions": "4.6.3"
+        }
+      },
+      "System.Memory": {
+        "type": "Transitive",
+        "resolved": "4.6.3",
+        "contentHash": "qdcDOgnFZY40+Q9876JUHnlHu7bosOHX8XISRoH94fwk6hgaeQGSgfZd8srWRZNt5bV9ZW2TljcegDNxsf+96A=="
+      },
+      "System.Runtime.CompilerServices.Unsafe": {
+        "type": "Transitive",
+        "resolved": "6.1.2",
+        "contentHash": "2hBr6zdbIBTDE3EhK7NSVNdX58uTK6iHW/P/Axmm9sl1xoGSLqDvMtpecn226TNwHByFokYwJmt/aQQNlO5CRw=="
+      },
+      "System.Text.Encodings.Web": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "o16m2YpDN/pjHsnxf9pTGwkpcuvjW8v1/wGUwJtM1c3QZUKm7ZEO/eYRJg7iIx6GxS2Zv9lAMHpiQwHDdgqauA==",
+        "dependencies": {
+          "System.Buffers": "4.6.1",
+          "System.Memory": "4.6.3",
+          "System.Runtime.CompilerServices.Unsafe": "6.1.2"
+        }
+      },
+      "System.Threading.Tasks.Extensions": {
+        "type": "Transitive",
+        "resolved": "4.6.3",
+        "contentHash": "7sCiwilJLYbTZELaKnc7RecBBXWXA+xMLQWZKWawBxYjp6DBlSE3v9/UcvKBvr1vv2tTOhipiogM8rRmxlhrVA=="
+      }
+    }
   }
 }

src/FinalFactory.Rendezvous.Server/Browser/EphemeralCursorProtector.cs

@@ -0,0 +1,103 @@
+using System.Security.Cryptography;
+using System.Text;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Browser;
+
+internal sealed class EphemeralCursorProtector : IDisposable
+{
+    private readonly byte[] _key = RandomNumberGenerator.GetBytes(32);
+    private bool _disposed;
+
+    public string Protect(string prefix, ReadOnlySpan<byte> payload)
+    {
+        ObjectDisposedException.ThrowIf(_disposed, this);
+        string content = $"{prefix}.{EncodeBytes(payload)}";
+        byte[] signature = HMACSHA256.HashData(_key, Encoding.ASCII.GetBytes(content));
+        try
+        {
+            string cursor = $"{content}.{EncodeBytes(signature)}";
+            return ContractValidation.IsCursorValid(cursor)
+                ? cursor
+                : throw new InvalidOperationException("The protected cursor exceeds its contract limit.");
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(signature);
+        }
+    }
+
+    public bool TryUnprotect(string prefix, string? cursor, out byte[] payload)
+    {
+        payload = [];
+        if (_disposed || !ContractValidation.IsCursorValid(cursor))
+        {
+            return false;
+        }
+
+        string[] segments = cursor!.Split('.');
+        if (segments.Length != 3 || !string.Equals(segments[0], prefix, StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        byte[] expected = HMACSHA256.HashData(
+            _key,
+            Encoding.ASCII.GetBytes($"{segments[0]}.{segments[1]}"));
+        if (!TryDecodeBytes(segments[2], out byte[] supplied))
+        {
+            CryptographicOperations.ZeroMemory(expected);
+            return false;
+        }
+
+        bool validSignature = supplied.Length == expected.Length
+            && CryptographicOperations.FixedTimeEquals(supplied, expected);
+        CryptographicOperations.ZeroMemory(supplied);
+        CryptographicOperations.ZeroMemory(expected);
+        return validSignature && TryDecodeBytes(segments[1], out payload);
+    }
+
+    public void Dispose()
+    {
+        if (!_disposed)
+        {
+            _disposed = true;
+            CryptographicOperations.ZeroMemory(_key);
+        }
+    }
+
+    public override string ToString() => "[EphemeralCursorProtector: key redacted]";
+
+    private static string EncodeBytes(ReadOnlySpan<byte> bytes) => Convert
+        .ToBase64String(bytes)
+        .TrimEnd('=')
+        .Replace('+', '-')
+        .Replace('/', '_');
+
+    private static bool TryDecodeBytes(string value, out byte[] bytes)
+    {
+        bytes = [];
+        if (string.IsNullOrEmpty(value)
+            || value.Any(static character =>
+                character is not (>= 'A' and <= 'Z')
+                and not (>= 'a' and <= 'z')
+                and not (>= '0' and <= '9')
+                and not '-'
+                and not '_'))
+        {
+            return false;
+        }
+
+        string padded = value.Replace('-', '+').Replace('_', '/');
+        padded += (padded.Length % 4) switch { 0 => "", 2 => "==", 3 => "=", _ => "!" };
+        try
+        {
+            bytes = Convert.FromBase64String(padded);
+            return true;
+        }
+        catch (FormatException)
+        {
+            return false;
+        }
+    }
+}

src/FinalFactory.Rendezvous.Server/Browser/SessionBrowserCursorCodec.cs

@@ -0,0 +1,115 @@
+using System.Security.Cryptography;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.State;
+
+namespace FinalFactory.Rendezvous.Server.Browser;
+
+internal sealed class SessionBrowserCursorCodec : IDisposable
+{
+    private const string Prefix = "rvc1";
+    private readonly EphemeralCursorProtector _protector = new();
+
+    public string Encode(VisibleListingQuery query, SessionListingId after, DateTimeOffset now)
+    {
+        BrowserCursorPayload payload = new()
+        {
+            GameId = query.Scope.GameId.Value,
+            EnvironmentId = query.Scope.EnvironmentId.Value,
+            ProtocolVersion = query.ProtocolVersion,
+            RegionId = query.RegionId?.Value,
+            ExcludeFull = query.ExcludeFull,
+            AfterListingId = after.ToString(),
+            ExpiresAtUnixSeconds = now.AddMinutes(5).ToUnixTimeSeconds(),
+        };
+        byte[] encoded = JsonSerializer.SerializeToUtf8Bytes(payload, ContractJson.Options);
+        try
+        {
+            return _protector.Protect(Prefix, encoded);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(encoded);
+        }
+    }
+
+    public bool TryDecode(
+        string? cursor,
+        TenantScope scope,
+        uint protocolVersion,
+        RegionId? regionId,
+        bool excludeFull,
+        DateTimeOffset now,
+        out SessionListingId? after)
+    {
+        after = null;
+        if (cursor is null)
+        {
+            return true;
+        }
+
+        if (!_protector.TryUnprotect(Prefix, cursor, out byte[] encodedPayload))
+        {
+            return false;
+        }
+
+        BrowserCursorPayload? payload;
+        try
+        {
+            payload = JsonSerializer.Deserialize<BrowserCursorPayload>(
+                encodedPayload,
+                ContractJson.Options);
+        }
+        catch (JsonException)
+        {
+            payload = null;
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(encodedPayload);
+        }
+
+        if (payload is null
+            || payload.ExpiresAtUnixSeconds <= now.ToUnixTimeSeconds()
+            || !string.Equals(payload.GameId, scope.GameId.Value, StringComparison.Ordinal)
+            || !string.Equals(payload.EnvironmentId, scope.EnvironmentId.Value, StringComparison.Ordinal)
+            || payload.ProtocolVersion != protocolVersion
+            || !string.Equals(payload.RegionId, regionId?.Value, StringComparison.Ordinal)
+            || payload.ExcludeFull != excludeFull
+            || !SessionListingId.TryParse(payload.AfterListingId, out SessionListingId listingId))
+        {
+            return false;
+        }
+
+        after = listingId;
+        return true;
+    }
+
+    public void Dispose() => _protector.Dispose();
+
+    public override string ToString() => "[SessionBrowserCursorCodec: key and cursors redacted]";
+}
+
+internal sealed class BrowserCursorPayload
+{
+    [JsonRequired]
+    public string GameId { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string EnvironmentId { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public uint ProtocolVersion { get; set; }
+
+    public string? RegionId { get; set; }
+
+    [JsonRequired]
+    public bool ExcludeFull { get; set; }
+
+    [JsonRequired]
+    public string AfterListingId { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public long ExpiresAtUnixSeconds { get; set; }
+}

src/FinalFactory.Rendezvous.Server/Browser/SessionBrowserService.cs

@@ -0,0 +1,157 @@
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.State;
+
+namespace FinalFactory.Rendezvous.Server.Browser;
+
+internal sealed record BrowserServiceResult<T>(RendezvousErrorCode Error, T? Value = default)
+{
+    public bool Succeeded => Error == RendezvousErrorCode.None;
+}
+
+internal sealed class SessionBrowserService(
+    IEphemeralRendezvousStore store,
+    SessionBrowserCursorCodec cursors,
+    IWallClock clock)
+{
+    public BrowserServiceResult<BrowseSessionsResponse> Browse(
+        BrowseSessionsRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        RendezvousErrorCode validation = Validate(request);
+        if (validation != RendezvousErrorCode.None)
+        {
+            return new(validation);
+        }
+
+        TenantScope scope = new(request.GameId, request.EnvironmentId);
+        if (!cursors.TryDecode(
+                request.Cursor,
+                scope,
+                request.ProtocolVersion,
+                request.RegionId,
+                request.ExcludeFull,
+                clock.UtcNow,
+                out SessionListingId? after))
+        {
+            return new(RendezvousErrorCode.InvalidRequest);
+        }
+
+        VisibleListingQuery query = new(
+            scope,
+            request.ProtocolVersion,
+            request.RegionId,
+            request.PageSize + 1,
+            after,
+            request.ExcludeFull);
+        StoreResult<IReadOnlyList<StoredListing>> found = store.BrowseVisibleListings(
+            query,
+            cancellationToken);
+        if (!found.Succeeded || found.Value is null)
+        {
+            return new(found.Code == StoreResultCode.ServiceUnavailable
+                ? RendezvousErrorCode.ServiceUnavailable
+                : RendezvousErrorCode.InternalError);
+        }
+
+        List<SessionListing> items = found.Value
+            .Take(request.PageSize)
+            .Select(ToContract)
+            .ToList();
+        bool hasMore = found.Value.Count > request.PageSize;
+        while (items.Count > 0)
+        {
+            string? nextCursor = hasMore
+                ? cursors.Encode(query, items[^1].ListingId, clock.UtcNow)
+                : null;
+            BrowseSessionsResponse response = new() { Items = items, NextCursor = nextCursor };
+            if (JsonSerializer.SerializeToUtf8Bytes(response, ContractJson.Options).Length
+                <= ContractLimits.BrowserResponseMaxBytes)
+            {
+                return new(RendezvousErrorCode.None, response);
+            }
+
+            items.RemoveAt(items.Count - 1);
+            hasMore = true;
+        }
+
+        return new(RendezvousErrorCode.None, new BrowseSessionsResponse());
+    }
+
+    public BrowserServiceResult<GetSessionResponse> Get(
+        SessionListingId listingId,
+        GameId gameId,
+        EnvironmentId environmentId,
+        uint protocolVersion,
+        CancellationToken cancellationToken = default)
+    {
+        if (listingId.Value == Guid.Empty
+            || string.IsNullOrEmpty(gameId.Value)
+            || string.IsNullOrEmpty(environmentId.Value)
+            || protocolVersion == 0)
+        {
+            return new(RendezvousErrorCode.InvalidRequest);
+        }
+
+        StoreResult<StoredListing> found = store.GetListing(listingId, true, cancellationToken);
+        if (!found.Succeeded || found.Value is null)
+        {
+            return new(found.Code == StoreResultCode.ServiceUnavailable
+                ? RendezvousErrorCode.ServiceUnavailable
+                : RendezvousErrorCode.NotFound);
+        }
+
+        StoredListing listing = found.Value;
+        if (listing.Definition.Scope != new TenantScope(gameId, environmentId)
+            || listing.Definition.ProtocolVersion != protocolVersion)
+        {
+            return new(RendezvousErrorCode.NotFound);
+        }
+
+        return new(RendezvousErrorCode.None, new GetSessionResponse
+        {
+            Session = ToContract(listing),
+        });
+    }
+
+    private static RendezvousErrorCode Validate(BrowseSessionsRequest request)
+    {
+        RendezvousErrorCode version = ContractValidation.ValidateContractVersion(request.ContractVersion);
+        if (version != RendezvousErrorCode.None)
+        {
+            return version;
+        }
+
+        return string.IsNullOrEmpty(request.GameId.Value)
+            || string.IsNullOrEmpty(request.EnvironmentId.Value)
+            || request.ProtocolVersion == 0
+            || (request.RegionId.HasValue && string.IsNullOrEmpty(request.RegionId.Value.Value))
+            || !ContractValidation.IsPageSizeValid(request.PageSize)
+            || !ContractValidation.IsCursorValid(request.Cursor)
+            ? RendezvousErrorCode.InvalidRequest
+            : RendezvousErrorCode.None;
+    }
+
+    private static SessionListing ToContract(StoredListing stored) => new()
+    {
+        ListingId = stored.Definition.ListingId,
+        GameId = stored.Definition.Scope.GameId,
+        EnvironmentId = stored.Definition.Scope.EnvironmentId,
+        RegionId = stored.Definition.RegionId,
+        ProtocolVersion = stored.Definition.ProtocolVersion,
+        BuildVersion = stored.Definition.BuildVersion,
+        DisplayName = stored.Definition.DisplayName,
+        Visibility = stored.Definition.Visibility,
+        PublisherTrustMode = stored.Definition.TrustMode,
+        Capacity = new()
+        {
+            CurrentPlayers = stored.Definition.CurrentPlayers,
+            MaximumPlayers = stored.Definition.MaximumPlayers,
+        },
+        Metadata = stored.Definition.Metadata.ToDictionary(
+            static item => item.Key,
+            static item => item.Value,
+            StringComparer.Ordinal),
+    };
+}

src/FinalFactory.Rendezvous.Server/FinalFactory.Rendezvous.Server.csproj

@@ -4,9 +4,14 @@
     <AssemblyName>FinalFactory.Rendezvous.Server</AssemblyName>
     <RootNamespace>FinalFactory.Rendezvous.Server</RootNamespace>
     <IsPackable>false</IsPackable>
+    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
+    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)/../../docs/api</OpenApiDocumentsDirectory>
+    <OpenApiGenerateDocumentsOptions>--document-name v1 --file-name rendezvous-v1 --openapi-version OpenApi3_1</OpenApiGenerateDocumentsOptions>
   </PropertyGroup>
   <ItemGroup>
     <ProjectReference Include="../FinalFactory.Rendezvous.Contracts/FinalFactory.Rendezvous.Contracts.csproj" />
     <PackageReference Include="LiteNetLib" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
+    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" PrivateAssets="all" />
   </ItemGroup>
 </Project>

src/FinalFactory.Rendezvous.Server/Http/ContractEndpoints.cs

@@ -0,0 +1,415 @@
+using System.Net;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Browser;
+using FinalFactory.Rendezvous.Server.JoinAttempts;
+using FinalFactory.Rendezvous.Server.Provisioning;
+using FinalFactory.Rendezvous.Server.Sessions;
+using FinalFactory.Rendezvous.Server.State;
+using Microsoft.AspNetCore.Mvc;
+
+namespace FinalFactory.Rendezvous.Server.Http;
+
+internal static class ContractEndpoints
+{
+    private const int NotImplementedStatus = StatusCodes.Status501NotImplemented;
+
+    public static IEndpointRouteBuilder MapRendezvousContractEndpoints(
+        this IEndpointRouteBuilder endpoints)
+    {
+        RouteGroupBuilder sessions = endpoints.MapGroup("/v1/sessions").WithTags("Sessions");
+        sessions.MapPost("/", RegisterSession)
+            .Accepts<RegisterSessionRequest>("application/json")
+            .Produces<RegisterSessionResponse>(StatusCodes.Status201Created)
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status401Unauthorized)
+            .Produces<ApiError>(StatusCodes.Status403Forbidden)
+            .Produces<ApiError>(StatusCodes.Status409Conflict)
+            .Produces<ApiError>(StatusCodes.Status410Gone)
+            .Produces<ApiError>(StatusCodes.Status429TooManyRequests)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("RegisterSession");
+        sessions.MapPost("/{listingId}/renew", RenewLease)
+            .Accepts<RenewLeaseRequest>("application/json")
+            .Produces<RenewLeaseResponse>()
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status401Unauthorized)
+            .Produces<ApiError>(StatusCodes.Status403Forbidden)
+            .Produces<ApiError>(StatusCodes.Status404NotFound)
+            .Produces<ApiError>(StatusCodes.Status409Conflict)
+            .Produces<ApiError>(StatusCodes.Status410Gone)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("RenewSessionLease");
+        sessions.MapPut("/{listingId}", UpdateSession)
+            .Accepts<UpdateSessionRequest>("application/json")
+            .Produces(StatusCodes.Status204NoContent)
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status401Unauthorized)
+            .Produces<ApiError>(StatusCodes.Status403Forbidden)
+            .Produces<ApiError>(StatusCodes.Status404NotFound)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("UpdateSession");
+        sessions.MapDelete("/{listingId}", DeleteSession)
+            .Accepts<DeleteSessionRequest>("application/json")
+            .Produces(StatusCodes.Status204NoContent)
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status401Unauthorized)
+            .Produces<ApiError>(StatusCodes.Status403Forbidden)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("DeleteSession");
+        sessions.MapGet("/", BrowseSessions)
+            .Produces<BrowseSessionsResponse>()
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("BrowseSessions");
+        sessions.MapGet("/{listingId}", GetSession)
+            .Produces<GetSessionResponse>()
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status404NotFound)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("GetSession");
+        sessions.MapGet("/{listingId}/join-attempts", BrowseHostJoinAttempts)
+            .Produces<BrowseHostJoinAttemptsResponse>()
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status404NotFound)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("BrowseHostJoinAttempts");
+
+        RouteGroupBuilder attempts = endpoints
+            .MapGroup("/v1/join-attempts")
+            .WithTags("Join attempts");
+        attempts.MapPost("/", CreateJoinAttempt)
+            .Accepts<CreateJoinAttemptRequest>("application/json")
+            .Produces<CreateJoinAttemptResponse>(StatusCodes.Status201Created)
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status404NotFound)
+            .Produces<ApiError>(StatusCodes.Status409Conflict)
+            .Produces<ApiError>(StatusCodes.Status429TooManyRequests)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("CreateJoinAttempt");
+        attempts.MapDelete("/{attemptId}", CancelJoinAttempt)
+            .Produces(StatusCodes.Status204NoContent)
+            .Produces<ApiError>(StatusCodes.Status400BadRequest)
+            .Produces<ApiError>(StatusCodes.Status404NotFound)
+            .Produces<ApiError>(StatusCodes.Status503ServiceUnavailable)
+            .WithName("CancelJoinAttempt");
+        attempts.MapPost("/{attemptId}/outcome", ReportConnectionOutcome)
+            .Accepts<ReportConnectionOutcomeRequest>("application/json")
+            .Produces<ReportConnectionOutcomeResponse>()
+            .Produces<ApiError>(StatusCodes.Status501NotImplemented)
+            .WithName("ReportConnectionOutcome");
+
+        return endpoints;
+    }
+
+    private static IResult RegisterSession(
+        [FromBody] RegisterSessionRequest request,
+        [FromHeader(Name = "Authorization")] string? authorizationHeader,
+        [FromServices] PrincipalCredentialService credentials,
+        [FromServices] SessionLeaseService sessions,
+        [FromServices] IWallClock clock,
+        HttpContext httpContext,
+        CancellationToken cancellationToken)
+    {
+        if (!TryAuthenticatePublisher(
+                authorizationHeader,
+                credentials,
+                clock,
+                out AuthenticatedPrincipal? principal))
+        {
+            return AuthenticationRequired(httpContext);
+        }
+
+        SessionServiceResult<RegisterSessionResponse> result = sessions.Register(
+            principal!,
+            request,
+            cancellationToken);
+        return result.Succeeded && result.Value is not null
+            ? Results.Created($"/v1/sessions/{result.Value.ListingId}", result.Value)
+            : Error(result.Error);
+    }
+
+    private static IResult RenewLease(
+        SessionListingId listingId,
+        [FromBody] RenewLeaseRequest request,
+        [FromHeader(Name = "Authorization")] string? authorizationHeader,
+        [FromServices] PrincipalCredentialService credentials,
+        [FromServices] SessionLeaseService sessions,
+        [FromServices] IWallClock clock,
+        HttpContext httpContext,
+        CancellationToken cancellationToken)
+    {
+        if (!TryAuthenticatePublisher(
+                authorizationHeader,
+                credentials,
+                clock,
+                out AuthenticatedPrincipal? principal))
+        {
+            return AuthenticationRequired(httpContext);
+        }
+
+        SessionServiceResult<RenewLeaseResponse> result = sessions.Renew(
+            principal!,
+            listingId,
+            request,
+            cancellationToken);
+        return result.Succeeded && result.Value is not null
+            ? Results.Ok(result.Value)
+            : Error(result.Error);
+    }
+
+    private static IResult UpdateSession(
+        SessionListingId listingId,
+        [FromBody] UpdateSessionRequest request,
+        [FromHeader(Name = "Authorization")] string? authorizationHeader,
+        [FromServices] PrincipalCredentialService credentials,
+        [FromServices] SessionLeaseService sessions,
+        [FromServices] IWallClock clock,
+        HttpContext httpContext,
+        CancellationToken cancellationToken)
+    {
+        if (!TryAuthenticatePublisher(
+                authorizationHeader,
+                credentials,
+                clock,
+                out AuthenticatedPrincipal? principal))
+        {
+            return AuthenticationRequired(httpContext);
+        }
+
+        SessionServiceResult<bool> result = sessions.Update(
+            principal!,
+            listingId,
+            request,
+            cancellationToken);
+        return result.Succeeded ? Results.NoContent() : Error(result.Error);
+    }
+
+    private static IResult DeleteSession(
+        SessionListingId listingId,
+        [FromBody] DeleteSessionRequest request,
+        [FromHeader(Name = "Authorization")] string? authorizationHeader,
+        [FromServices] PrincipalCredentialService credentials,
+        [FromServices] SessionLeaseService sessions,
+        [FromServices] IWallClock clock,
+        HttpContext httpContext,
+        CancellationToken cancellationToken)
+    {
+        if (!TryAuthenticatePublisher(
+                authorizationHeader,
+                credentials,
+                clock,
+                out AuthenticatedPrincipal? principal))
+        {
+            return AuthenticationRequired(httpContext);
+        }
+
+        SessionServiceResult<bool> result = sessions.Delete(
+            principal!,
+            listingId,
+            request,
+            cancellationToken);
+        return result.Succeeded ? Results.NoContent() : Error(result.Error);
+    }
+
+    private static IResult BrowseSessions(
+        [FromQuery] int contractVersion,
+        [FromQuery] string gameId,
+        [FromQuery] string environmentId,
+        [FromQuery] uint protocolVersion,
+        [FromQuery] string? regionId,
+        [FromQuery] int? pageSize,
+        [FromQuery] bool? excludeFull,
+        [FromQuery] string? cursor,
+        [FromServices] SessionBrowserService browser,
+        CancellationToken cancellationToken)
+    {
+        if (!GameId.TryParse(gameId, out GameId parsedGameId)
+            || !EnvironmentId.TryParse(environmentId, out EnvironmentId parsedEnvironmentId)
+            || (regionId is not null && !RegionId.TryParse(regionId, out _)))
+        {
+            return Error(RendezvousErrorCode.InvalidRequest);
+        }
+
+        BrowserServiceResult<BrowseSessionsResponse> result = browser.Browse(new()
+        {
+            ContractVersion = contractVersion,
+            GameId = parsedGameId,
+            EnvironmentId = parsedEnvironmentId,
+            ProtocolVersion = protocolVersion,
+            RegionId = regionId is null ? null : new RegionId(regionId),
+            PageSize = pageSize ?? ContractLimits.BrowserPageMaxItems,
+            ExcludeFull = excludeFull ?? false,
+            Cursor = cursor,
+        }, cancellationToken);
+        return result.Succeeded && result.Value is not null
+            ? Results.Ok(result.Value)
+            : Error(result.Error);
+    }
+
+    private static IResult GetSession(
+        SessionListingId listingId,
+        [FromQuery] int contractVersion,
+        [FromQuery] string gameId,
+        [FromQuery] string environmentId,
+        [FromQuery] uint protocolVersion,
+        [FromServices] SessionBrowserService browser,
+        CancellationToken cancellationToken)
+    {
+        if (ContractValidation.ValidateContractVersion(contractVersion) != RendezvousErrorCode.None)
+        {
+            return Error(RendezvousErrorCode.UnsupportedContractVersion);
+        }
+
+        if (!GameId.TryParse(gameId, out GameId parsedGameId)
+            || !EnvironmentId.TryParse(environmentId, out EnvironmentId parsedEnvironmentId))
+        {
+            return Error(RendezvousErrorCode.InvalidRequest);
+        }
+
+        BrowserServiceResult<GetSessionResponse> result = browser.Get(
+            listingId,
+            parsedGameId,
+            parsedEnvironmentId,
+            protocolVersion,
+            cancellationToken);
+        return result.Succeeded && result.Value is not null
+            ? Results.Ok(result.Value)
+            : Error(result.Error);
+    }
+
+    private static IResult BrowseHostJoinAttempts(
+        SessionListingId listingId,
+        [FromQuery] int contractVersion,
+        [FromHeader(Name = "X-Rendezvous-Lease-Token")] string leaseToken,
+        [FromQuery] int? pageSize,
+        [FromQuery] string? cursor,
+        [FromServices] JoinAttemptService attempts,
+        CancellationToken cancellationToken)
+    {
+        JoinAttemptServiceResult<BrowseHostJoinAttemptsResponse> result = attempts.BrowseForHost(
+            listingId,
+            contractVersion,
+            leaseToken,
+            pageSize ?? ContractLimits.BrowserPageMaxItems,
+            cursor,
+            cancellationToken);
+        return result.Succeeded && result.Value is not null
+            ? Results.Ok(result.Value)
+            : Error(result.Error);
+    }
+
+    private static IResult CreateJoinAttempt(
+        [FromBody] CreateJoinAttemptRequest request,
+        [FromServices] JoinAttemptService attempts,
+        HttpContext httpContext,
+        CancellationToken cancellationToken)
+    {
+        if (httpContext.Connection.RemoteIpAddress is not IPAddress remoteAddress)
+        {
+            return Error(RendezvousErrorCode.InvalidRequest);
+        }
+
+        string clientSubject = attempts.CreateAnonymousClientSubject(remoteAddress);
+        JoinAttemptServiceResult<CreateJoinAttemptResponse> result = attempts.Create(
+            clientSubject,
+            request,
+            cancellationToken);
+        return result.Succeeded && result.Value is not null
+            ? Results.Created($"/v1/join-attempts/{result.Value.AttemptId}", result.Value)
+            : Error(result.Error);
+    }
+
+    private static IResult CancelJoinAttempt(
+        JoinAttemptId attemptId,
+        [FromHeader(Name = "X-Rendezvous-Client-Punch-Capability")] string clientPunchCapability,
+        [FromServices] JoinAttemptService attempts,
+        CancellationToken cancellationToken)
+    {
+        JoinAttemptServiceResult<bool> result = attempts.Cancel(
+            attemptId,
+            clientPunchCapability,
+            cancellationToken);
+        return result.Succeeded ? Results.NoContent() : Error(result.Error);
+    }
+
+    private static IResult ReportConnectionOutcome(
+        JoinAttemptId attemptId,
+        [FromBody] ReportConnectionOutcomeRequest request) => NotImplemented();
+
+    private static IResult NotImplemented() => Results.Json(
+        new ApiError
+        {
+            Code = RendezvousErrorCode.ServiceUnavailable,
+            Message = "The v1 contract is reserved; implementation is tracked by subsequent issues.",
+        },
+        ContractJson.Options,
+        statusCode: NotImplementedStatus);
+
+    private static bool TryAuthenticatePublisher(
+        string? authorizationHeader,
+        PrincipalCredentialService credentials,
+        IWallClock clock,
+        out AuthenticatedPrincipal? principal)
+    {
+        principal = null;
+        const string bearerPrefix = "Bearer ";
+        if (authorizationHeader is null
+            || !authorizationHeader.StartsWith(bearerPrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        string token = authorizationHeader[bearerPrefix.Length..];
+        CredentialValidationResult validation = credentials.Validate(token, clock.UtcNow);
+        if (!validation.IsValid || validation.Principal is not IPublisherPrincipal)
+        {
+            return false;
+        }
+
+        principal = validation.Principal;
+        return true;
+    }
+
+    private static IResult Error(RendezvousErrorCode code) => Results.Json(
+        new ApiError
+        {
+            Code = code,
+            Message = ErrorMessage(code),
+        },
+        ContractJson.Options,
+        statusCode: ErrorStatus(code));
+
+    private static IResult AuthenticationRequired(HttpContext context)
+    {
+        context.Response.Headers.WWWAuthenticate = "Bearer";
+        return Error(RendezvousErrorCode.AuthenticationRequired);
+    }
+
+    private static int ErrorStatus(RendezvousErrorCode code) => code switch
+    {
+        RendezvousErrorCode.AuthenticationRequired => StatusCodes.Status401Unauthorized,
+        RendezvousErrorCode.Forbidden => StatusCodes.Status403Forbidden,
+        RendezvousErrorCode.NotFound or RendezvousErrorCode.StaleHost => StatusCodes.Status404NotFound,
+        RendezvousErrorCode.Conflict or RendezvousErrorCode.ReplayRejected => StatusCodes.Status409Conflict,
+        RendezvousErrorCode.Expired => StatusCodes.Status410Gone,
+        RendezvousErrorCode.RateLimited or RendezvousErrorCode.CapacityExceeded =>
+            StatusCodes.Status429TooManyRequests,
+        RendezvousErrorCode.ServiceUnavailable => StatusCodes.Status503ServiceUnavailable,
+        RendezvousErrorCode.InternalError => StatusCodes.Status500InternalServerError,
+        _ => StatusCodes.Status400BadRequest,
+    };
+
+    private static string ErrorMessage(RendezvousErrorCode code) => code switch
+    {
+        RendezvousErrorCode.AuthenticationRequired => "A valid publisher bearer credential is required.",
+        RendezvousErrorCode.Forbidden => "The publisher is not authorized for this operation.",
+        RendezvousErrorCode.NotFound => "The session was not found or is not owned by this publisher.",
+        RendezvousErrorCode.Conflict => "The session changed concurrently; retry with current state.",
+        RendezvousErrorCode.Expired => "The session lease has expired.",
+        RendezvousErrorCode.IncompatibleProtocol => "The gameplay protocol is not enabled for this game.",
+        RendezvousErrorCode.CapacityExceeded => "The configured session capacity is currently exhausted.",
+        RendezvousErrorCode.ServiceUnavailable => "Session state is temporarily unavailable.",
+        RendezvousErrorCode.UnsupportedContractVersion => "The requested contract version is not supported.",
+        _ => "The session request is invalid.",
+    };
+}

src/FinalFactory.Rendezvous.Server/Http/RendezvousExceptionHandler.cs

@@ -0,0 +1,37 @@
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+using Microsoft.AspNetCore.Diagnostics;
+
+namespace FinalFactory.Rendezvous.Server.Http;
+
+internal sealed class RendezvousExceptionHandler : IExceptionHandler
+{
+    public async ValueTask<bool> TryHandleAsync(
+        HttpContext httpContext,
+        Exception exception,
+        CancellationToken cancellationToken)
+    {
+        if (httpContext.Response.HasStarted)
+        {
+            return false;
+        }
+
+        bool invalidRequest = exception is BadHttpRequestException or JsonException;
+        httpContext.Response.StatusCode = invalidRequest
+            ? StatusCodes.Status400BadRequest
+            : StatusCodes.Status500InternalServerError;
+        await httpContext.Response.WriteAsJsonAsync(
+            new ApiError
+            {
+                Code = invalidRequest
+                    ? RendezvousErrorCode.InvalidRequest
+                    : RendezvousErrorCode.InternalError,
+                Message = invalidRequest
+                    ? "The request body, route, or query value is invalid."
+                    : "The service could not complete the request.",
+            },
+            ContractJson.Options,
+            cancellationToken).ConfigureAwait(false);
+        return true;
+    }
+}

src/FinalFactory.Rendezvous.Server/JoinAttempts/JoinAttemptCursorCodec.cs

@@ -0,0 +1,96 @@
+using System.Security.Cryptography;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Browser;
+
+namespace FinalFactory.Rendezvous.Server.JoinAttempts;
+
+internal sealed class JoinAttemptCursorCodec : IDisposable
+{
+    private const string Prefix = "rvj1";
+    private readonly EphemeralCursorProtector _protector = new();
+
+    public string Encode(
+        SessionListingId listingId,
+        JoinAttemptId after,
+        DateTimeOffset now)
+    {
+        JoinAttemptCursorPayload payload = new()
+        {
+            ListingId = listingId.ToString(),
+            AfterAttemptId = after.ToString(),
+            ExpiresAtUnixSeconds = now.AddMinutes(5).ToUnixTimeSeconds(),
+        };
+        byte[] encoded = JsonSerializer.SerializeToUtf8Bytes(payload, ContractJson.Options);
+        try
+        {
+            return _protector.Protect(Prefix, encoded);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(encoded);
+        }
+    }
+
+    public bool TryDecode(
+        string? cursor,
+        SessionListingId listingId,
+        DateTimeOffset now,
+        out JoinAttemptId? after)
+    {
+        after = null;
+        if (cursor is null)
+        {
+            return true;
+        }
+
+        if (!_protector.TryUnprotect(Prefix, cursor, out byte[] encodedPayload))
+        {
+            return false;
+        }
+
+        JoinAttemptCursorPayload? payload;
+        try
+        {
+            payload = JsonSerializer.Deserialize<JoinAttemptCursorPayload>(
+                encodedPayload,
+                ContractJson.Options);
+        }
+        catch (JsonException)
+        {
+            payload = null;
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(encodedPayload);
+        }
+
+        if (payload is null
+            || payload.ExpiresAtUnixSeconds <= now.ToUnixTimeSeconds()
+            || !string.Equals(payload.ListingId, listingId.ToString(), StringComparison.Ordinal)
+            || !JoinAttemptId.TryParse(payload.AfterAttemptId, out JoinAttemptId attemptId))
+        {
+            return false;
+        }
+
+        after = attemptId;
+        return true;
+    }
+
+    public void Dispose() => _protector.Dispose();
+
+    public override string ToString() => "[JoinAttemptCursorCodec: key and cursors redacted]";
+}
+
+internal sealed class JoinAttemptCursorPayload
+{
+    [JsonRequired]
+    public string ListingId { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string AfterAttemptId { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public long ExpiresAtUnixSeconds { get; set; }
+}

src/FinalFactory.Rendezvous.Server/JoinAttempts/JoinAttemptService.cs

@@ -0,0 +1,342 @@
+using System.Net;
+using System.Security.Cryptography;
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Provisioning;
+using FinalFactory.Rendezvous.Server.Sessions;
+using FinalFactory.Rendezvous.Server.State;
+
+namespace FinalFactory.Rendezvous.Server.JoinAttempts;
+
+internal sealed record JoinAttemptServiceResult<T>(RendezvousErrorCode Error, T? Value = default)
+{
+    public bool Succeeded => Error == RendezvousErrorCode.None;
+}
+
+internal sealed record ConnectionTicketGrant(string Ticket, DateTimeOffset ExpiresAt)
+{
+    public override string ToString() => "[ConnectionTicketGrant: ticket redacted]";
+}
+
+internal sealed class JoinAttemptService(
+    GamePolicyRegistry policies,
+    IEphemeralRendezvousStore store,
+    ISessionCapabilityService capabilities,
+    JoinAttemptCursorCodec cursors,
+    IWallClock clock)
+{
+    public string CreateAnonymousClientSubject(IPAddress remoteAddress)
+    {
+        ArgumentNullException.ThrowIfNull(remoteAddress);
+        IPAddress normalized = remoteAddress.IsIPv4MappedToIPv6
+            ? remoteAddress.MapToIPv4()
+            : remoteAddress;
+        return capabilities.DeriveOpaqueIdentifier("join-http-client", normalized.ToString());
+    }
+
+    public JoinAttemptServiceResult<CreateJoinAttemptResponse> Create(
+        string clientSubject,
+        CreateJoinAttemptRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        if (string.IsNullOrWhiteSpace(clientSubject))
+        {
+            throw new ArgumentException("A bounded client subject is required.", nameof(clientSubject));
+        }
+
+        RendezvousErrorCode validation = ValidateCreate(request);
+        if (validation != RendezvousErrorCode.None)
+        {
+            return new(validation);
+        }
+
+        if (!policies.TryGet(request.GameId, request.EnvironmentId, out GamePolicy? policy)
+            || policy is null)
+        {
+            return new(RendezvousErrorCode.NotFound);
+        }
+
+        if (!policy.AllowsProtocol(request.ProtocolVersion))
+        {
+            return new(RendezvousErrorCode.IncompatibleProtocol);
+        }
+
+        string requestFingerprint = ComputeRequestFingerprint(request);
+        string derivationSalt = capabilities.CreateDerivationSalt();
+        string hostCapability = Derive("join-host-punch", clientSubject, request, requestFingerprint, derivationSalt);
+        string clientCapability = Derive("join-client-punch", clientSubject, request, requestFingerprint, derivationSalt);
+        JoinAttemptId attemptId = new(capabilities.DeriveGuid(
+            "join-attempt-id",
+            clientSubject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt));
+        string connectionTicket = NatIntroductionTokenCodec.Encode(
+            attemptId,
+            Derive("connection-ticket", clientSubject, request, requestFingerprint, derivationSalt));
+        if (!CredentialLengthsAreValid(hostCapability, clientCapability, connectionTicket)
+            || !capabilities.TryFingerprint(hostCapability, out SecretFingerprint hostFingerprint)
+            || !capabilities.TryFingerprint(clientCapability, out SecretFingerprint clientFingerprint)
+            || !capabilities.TryFingerprint(connectionTicket, out SecretFingerprint ticketFingerprint))
+        {
+            throw new InvalidOperationException("Derived join credentials violated their contract invariants.");
+        }
+
+        MediationHandle mediationHandle = new(capabilities.DeriveGuid(
+            "join-mediation-handle",
+            clientSubject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt));
+        StoreResult<StoredJoinAttempt> created = store.CreateJoinAttempt(new()
+        {
+            IdempotencyOwner = clientSubject,
+            IdempotencyKey = request.IdempotencyKey,
+            RequestFingerprint = requestFingerprint,
+            ClientSubject = clientSubject,
+            AttemptId = attemptId,
+            MediationHandle = mediationHandle,
+            Scope = new(request.GameId, request.EnvironmentId),
+            ListingId = request.ListingId,
+            ProtocolVersion = request.ProtocolVersion,
+            HostCapabilityFingerprint = hostFingerprint,
+            ClientCapabilityFingerprint = clientFingerprint,
+            ConnectionTicketFingerprint = ticketFingerprint,
+            CapabilityDerivationSalt = derivationSalt,
+            ScopeAttemptLimit = policy.MaxActiveJoinAttempts,
+        }, cancellationToken);
+        if (!created.Succeeded || created.Value is null)
+        {
+            return new(created.Code.ToContractError());
+        }
+
+        StoredJoinAttempt persisted = created.Value;
+        clientCapability = Derive(
+            "join-client-punch",
+            persisted.ClientSubject,
+            persisted.IdempotencyKey,
+            persisted.RequestFingerprint,
+            persisted.CapabilityDerivationSalt);
+        if (!capabilities.TryFingerprint(clientCapability, out SecretFingerprint persistedFingerprint)
+            || persistedFingerprint != persisted.ClientCapabilityFingerprint)
+        {
+            throw new InvalidOperationException("Stored join state could not reproduce its client capability.");
+        }
+        return new(RendezvousErrorCode.None, new CreateJoinAttemptResponse
+        {
+            AttemptId = persisted.AttemptId,
+            MediationHandle = persisted.MediationHandle,
+            ClientPunchCapability = clientCapability,
+            ConnectionTicketDigest = NatIntroductionTokenCodec.ComputeDigest(
+                CreateConnectionTicket(persisted)),
+            ExpiresAt = persisted.ExpiresAt,
+        });
+    }
+
+    public JoinAttemptServiceResult<BrowseHostJoinAttemptsResponse> BrowseForHost(
+        SessionListingId listingId,
+        int contractVersion,
+        string? leaseToken,
+        int pageSize,
+        string? cursor,
+        CancellationToken cancellationToken = default)
+    {
+        RendezvousErrorCode version = ContractValidation.ValidateContractVersion(contractVersion);
+        if (version != RendezvousErrorCode.None)
+        {
+            return new(version);
+        }
+
+        if (!ContractValidation.IsOpaqueHttpCredentialValid(leaseToken)
+            || !ContractValidation.IsPageSizeValid(pageSize)
+            || !ContractValidation.IsCursorValid(cursor)
+            || !capabilities.TryFingerprint(leaseToken, out SecretFingerprint leaseFingerprint))
+        {
+            return new(RendezvousErrorCode.InvalidRequest);
+        }
+
+        if (!cursors.TryDecode(cursor, listingId, clock.UtcNow, out JoinAttemptId? after))
+        {
+            return new(RendezvousErrorCode.InvalidRequest);
+        }
+
+        StoreResult<IReadOnlyList<StoredJoinAttempt>> found = store.BrowseHostJoinAttempts(new(
+            listingId,
+            leaseFingerprint,
+            pageSize + 1,
+            after), cancellationToken);
+        if (!found.Succeeded || found.Value is null)
+        {
+            return new(found.Code.ToContractError());
+        }
+
+        bool hasMore = found.Value.Count > pageSize;
+        StoredJoinAttempt[] page = found.Value.Take(pageSize).ToArray();
+        BrowseHostJoinAttemptsResponse response = new()
+        {
+            Items = page.Select(CreateHostAttempt).ToList(),
+            NextCursor = hasMore && page.Length > 0
+                ? cursors.Encode(listingId, page[^1].AttemptId, clock.UtcNow)
+                : null,
+        };
+        int encodedBytes = JsonSerializer.SerializeToUtf8Bytes(response, ContractJson.Options).Length;
+        return ContractValidation.IsBrowserResponseSizeValid(encodedBytes)
+            ? new(RendezvousErrorCode.None, response)
+            : new(RendezvousErrorCode.CapacityExceeded);
+    }
+
+    public JoinAttemptServiceResult<bool> Cancel(
+        JoinAttemptId attemptId,
+        string? clientPunchCapability,
+        CancellationToken cancellationToken = default)
+    {
+        if (!ContractValidation.IsCapabilityValid(clientPunchCapability)
+            || !capabilities.TryFingerprint(clientPunchCapability, out SecretFingerprint fingerprint))
+        {
+            return new(RendezvousErrorCode.InvalidRequest);
+        }
+
+        StoreResult<bool> cancelled = store.CancelJoinAttempt(new(attemptId, fingerprint), cancellationToken);
+        return cancelled.Succeeded
+            ? new(RendezvousErrorCode.None, true)
+            : new(cancelled.Code.ToContractError());
+    }
+
+    public JoinAttemptServiceResult<ConnectionTicketGrant> IssueConnectionTicket(
+        StoredJoinAttempt attempt)
+    {
+        ArgumentNullException.ThrowIfNull(attempt);
+        if (!attempt.IntroductionConsumed || attempt.IsCancelled)
+        {
+            return new(RendezvousErrorCode.Conflict);
+        }
+
+        if (attempt.ConnectionTicketExpiresAt <= clock.UtcNow)
+        {
+            return new(RendezvousErrorCode.Expired);
+        }
+
+        string ticket = CreateConnectionTicket(attempt);
+        if (!ContractValidation.IsConnectionTicketValid(ticket)
+            || !capabilities.TryFingerprint(ticket, out SecretFingerprint fingerprint)
+            || fingerprint != attempt.ConnectionTicketFingerprint)
+        {
+            throw new InvalidOperationException("Stored join state could not reproduce its connection ticket.");
+        }
+
+        return new(RendezvousErrorCode.None, new(ticket, attempt.ConnectionTicketExpiresAt));
+    }
+
+    private HostJoinAttempt CreateHostAttempt(StoredJoinAttempt attempt)
+    {
+        string capability = Derive(
+            "join-host-punch",
+            attempt.ClientSubject,
+            attempt.IdempotencyKey,
+            attempt.RequestFingerprint,
+            attempt.CapabilityDerivationSalt);
+        if (!ContractValidation.IsCapabilityValid(capability)
+            || !capabilities.TryFingerprint(capability, out SecretFingerprint fingerprint)
+            || fingerprint != attempt.HostCapabilityFingerprint)
+        {
+            throw new InvalidOperationException("Stored join state could not reproduce its host capability.");
+        }
+
+        return new()
+        {
+            AttemptId = attempt.AttemptId,
+            MediationHandle = attempt.MediationHandle,
+            HostPunchCapability = capability,
+            ConnectionTicketDigest = NatIntroductionTokenCodec.ComputeDigest(
+                CreateConnectionTicket(attempt)),
+            IsCancelled = attempt.IsCancelled,
+            ExpiresAt = attempt.ExpiresAt,
+        };
+    }
+
+    private string CreateConnectionTicket(StoredJoinAttempt attempt) =>
+        NatIntroductionTokenCodec.Encode(
+            attempt.AttemptId,
+            Derive(
+                "connection-ticket",
+                attempt.ClientSubject,
+                attempt.IdempotencyKey,
+                attempt.RequestFingerprint,
+                attempt.CapabilityDerivationSalt));
+
+    private static RendezvousErrorCode ValidateCreate(CreateJoinAttemptRequest request)
+    {
+        RendezvousErrorCode version = ContractValidation.ValidateContractVersion(request.ContractVersion);
+        if (version != RendezvousErrorCode.None)
+        {
+            return version;
+        }
+
+        return !ContractValidation.IsIdempotencyKeyValid(request.IdempotencyKey)
+            || string.IsNullOrEmpty(request.GameId.Value)
+            || string.IsNullOrEmpty(request.EnvironmentId.Value)
+            || request.ListingId.Value == Guid.Empty
+            || request.ProtocolVersion == 0
+            ? RendezvousErrorCode.InvalidRequest
+            : RendezvousErrorCode.None;
+    }
+
+    private static string ComputeRequestFingerprint(CreateJoinAttemptRequest request)
+    {
+        byte[] encoded = JsonSerializer.SerializeToUtf8Bytes(request, ContractJson.Options);
+        byte[] digest = SHA256.HashData(encoded);
+        CryptographicOperations.ZeroMemory(encoded);
+        try
+        {
+            return Encode(digest);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(digest);
+        }
+    }
+
+    private string Derive(
+        string purpose,
+        string clientSubject,
+        CreateJoinAttemptRequest request,
+        string requestFingerprint,
+        string derivationSalt) => Derive(
+            purpose,
+            clientSubject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt);
+
+    private string Derive(
+        string purpose,
+        string clientSubject,
+        string idempotencyKey,
+        string requestFingerprint,
+        string derivationSalt) => capabilities.DeriveCapability(
+            purpose,
+            clientSubject,
+            idempotencyKey,
+            requestFingerprint,
+            derivationSalt);
+
+    private static bool CredentialLengthsAreValid(
+        string hostCapability,
+        string clientCapability,
+        string ticket) =>
+        ContractValidation.IsCapabilityValid(hostCapability)
+        && ContractValidation.IsCapabilityValid(clientCapability)
+        && ContractValidation.IsConnectionTicketValid(ticket)
+        && hostCapability.Length == ContractLimits.DerivedCredentialCharacters
+        && clientCapability.Length == ContractLimits.DerivedCredentialCharacters
+        && ticket.Length == ContractLimits.DerivedCredentialCharacters
+        && hostCapability.Length <= ContractLimits.LiteNetLibNatTokenMaxCharacters
+        && clientCapability.Length <= ContractLimits.LiteNetLibNatTokenMaxCharacters;
+
+    private static string Encode(ReadOnlySpan<byte> bytes) => Convert
+        .ToBase64String(bytes)
+        .TrimEnd('=')
+        .Replace('+', '-')
+        .Replace('/', '_');
+}

src/FinalFactory.Rendezvous.Server/Program.cs

@@ -1,27 +1,183 @@
 using System.Net;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Browser;
+using FinalFactory.Rendezvous.Server.Http;
+using FinalFactory.Rendezvous.Server.JoinAttempts;
+using FinalFactory.Rendezvous.Server.Provisioning;
+using FinalFactory.Rendezvous.Server.Sessions;
+using FinalFactory.Rendezvous.Server.State;
 using FinalFactory.Rendezvous.Server.Transport;
+using Microsoft.OpenApi;
 
 WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+bool isOpenApiGeneration = string.Equals(
+    System.Reflection.Assembly.GetEntryAssembly()?.GetName().Name,
+    "GetDocument.Insider",
+    StringComparison.Ordinal);
+
+builder.Services.AddOpenApi("v1", static options =>
+{
+    options.AddSchemaTransformer(static (schema, context, cancellationToken) =>
+    {
+        Type type = context.JsonTypeInfo.Type;
+        if (type == typeof(GameId)
+            || type == typeof(EnvironmentId)
+            || type == typeof(RegionId))
+        {
+            schema.Type = JsonSchemaType.String;
+        }
+        else if (type == typeof(SessionListingId)
+                 || type == typeof(LeaseId)
+                 || type == typeof(JoinAttemptId)
+                 || type == typeof(MediationHandle))
+        {
+            schema.Type = JsonSchemaType.String;
+            schema.Format = "uuid";
+        }
+
+        return Task.CompletedTask;
+    });
+    options.AddDocumentTransformer(static (document, context, cancellationToken) =>
+    {
+        const string schemeName = "PublisherBearer";
+        document.Components ??= new OpenApiComponents();
+        document.Components.SecuritySchemes ??=
+            new Dictionary<string, IOpenApiSecurityScheme>(StringComparer.Ordinal);
+        document.Components.SecuritySchemes[schemeName] = new OpenApiSecurityScheme
+        {
+            Type = SecuritySchemeType.Http,
+            Scheme = "bearer",
+            BearerFormat = "rv1 publisher credential",
+            Description = "Tenant-scoped publisher credential issued during game provisioning.",
+        };
+
+        HashSet<string> securedOperations = new(StringComparer.Ordinal)
+        {
+            "RegisterSession",
+            "RenewSessionLease",
+            "UpdateSession",
+            "DeleteSession",
+        };
+        OpenApiSecuritySchemeReference reference = new(schemeName, document, null);
+        foreach (OpenApiPathItem path in document.Paths.Values)
+        {
+            if (path.Operations is null)
+            {
+                continue;
+            }
+
+            foreach (OpenApiOperation operation in path.Operations.Values.Where(
+                         operation => securedOperations.Contains(operation.OperationId ?? string.Empty)))
+            {
+                operation.Security ??= [];
+                operation.Security.Add(new OpenApiSecurityRequirement
+                {
+                    [reference] = [],
+                });
+            }
+        }
+
+        return Task.CompletedTask;
+    });
+});
+builder.Services.ConfigureHttpJsonOptions(static options =>
+    ContractJson.Configure(options.SerializerOptions));
+builder.Services.Configure<RouteHandlerOptions>(static options =>
+    options.ThrowOnBadRequest = true);
+builder.Services.AddProblemDetails();
+builder.Services.AddExceptionHandler<RendezvousExceptionHandler>();
+
+SystemRendezvousClock rendezvousClock = new();
+EphemeralStoreOptions stateOptions = new();
+InMemoryEphemeralRendezvousStore stateStore = new(
+    stateOptions,
+    rendezvousClock,
+    rendezvousClock);
+builder.Services.AddSingleton<IEphemeralRendezvousStore>(stateStore);
+builder.Services.AddSingleton<IWallClock>(rendezvousClock);
+
+if (isOpenApiGeneration)
+{
+    builder.Services.AddSingleton(new ProvisioningReadiness(false));
+}
+else
+{
+    ProvisioningOptions provisioningOptions = builder.Configuration
+        .GetSection(ProvisioningOptions.SectionName)
+        .Get<ProvisioningOptions>() ?? new ProvisioningOptions();
+    ISecretProvider secretProvider = builder.Environment.IsDevelopment()
+        ? new EphemeralDevelopmentSecretProvider()
+        : new EnvironmentSecretProvider();
+    ProvisioningRuntime provisioning = ProvisioningRuntime.Create(
+        provisioningOptions,
+        secretProvider,
+        DateTimeOffset.UtcNow);
+    builder.Services.AddSingleton(provisioning);
+    builder.Services.AddSingleton(provisioning.Policies);
+    builder.Services.AddSingleton(provisioning.Credentials);
+    builder.Services.AddSingleton(provisioning.PublisherAuthorization);
+    EphemeralCapabilityIssuer sessionCapabilities = new();
+    builder.Services.AddSingleton(sessionCapabilities);
+    builder.Services.AddSingleton<ISessionCapabilityService>(sessionCapabilities);
+    builder.Services.AddSingleton(SessionLeaseTiming.From(stateOptions));
+    builder.Services.AddSingleton<SessionLeaseService>();
+    builder.Services.AddSingleton<SessionBrowserCursorCodec>();
+    builder.Services.AddSingleton<SessionBrowserService>();
+    builder.Services.AddSingleton<JoinAttemptCursorCodec>();
+    builder.Services.AddSingleton<JoinAttemptService>();
+    builder.Services.AddSingleton(new ProvisioningReadiness(true));
+}
 
 builder.Services
     .AddOptions<UdpMediatorOptions>()
     .BindConfiguration(UdpMediatorOptions.SectionName)
     .ValidateDataAnnotations()
     .Validate(
-        options => IPAddress.TryParse(options.ListenAddress, out _),
-        $"{UdpMediatorOptions.SectionName}:ListenAddress must be an IP address.")
+        options => IPAddress.TryParse(options.ListenAddress, out IPAddress? address)
+                   && address.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork,
+        $"{UdpMediatorOptions.SectionName}:ListenAddress must be an IPv4 address.")
+    .Validate(
+        options => string.IsNullOrWhiteSpace(options.Ipv6ListenAddress)
+                   || (IPAddress.TryParse(options.Ipv6ListenAddress, out IPAddress? address)
+                       && address.AddressFamily == System.Net.Sockets.AddressFamily.InterNetworkV6),
+        $"{UdpMediatorOptions.SectionName}:Ipv6ListenAddress must be an IPv6 address when configured.")
     .ValidateOnStart();
 builder.Services.AddSingleton<UdpMediatorService>();
-builder.Services.AddHostedService(static services => services.GetRequiredService<UdpMediatorService>());
+if (!isOpenApiGeneration)
+{
+    builder.Services.AddSingleton<NatMediationProcessor>();
+    builder.Services.AddHostedService(static services =>
+        services.GetRequiredService<UdpMediatorService>());
+}
 
 WebApplication app = builder.Build();
+app.Lifetime.ApplicationStopping.Register(() => stateStore.BeginDrain());
 
-app.MapGet("/health/live", static () => Results.Ok(new { status = "live" }));
+app.UseExceptionHandler();
+app.MapOpenApi();
+app.MapRendezvousContractEndpoints();
+app.MapGet(
+        "/health/live",
+        static () => Results.Ok(new HealthResponse { Status = "live" }))
+    .Produces<HealthResponse>()
+    .WithName("GetLiveness")
+    .WithTags("Health");
 app.MapGet(
     "/health/ready",
-    static (UdpMediatorService mediator) => mediator.LocalEndpoint is null
+    static (
+        UdpMediatorService mediator,
+        ProvisioningReadiness provisioning,
+        IEphemeralRendezvousStore state) =>
+        mediator.LocalEndpoint is null
+        || !provisioning.IsReady
+        || !state.IsAvailable
+        || state.IsDraining
         ? Results.StatusCode(StatusCodes.Status503ServiceUnavailable)
-        : Results.Ok(new { status = "ready" }));
+        : Results.Ok(new HealthResponse { Status = "ready" }))
+    .Produces<HealthResponse>()
+    .Produces(StatusCodes.Status503ServiceUnavailable)
+    .WithName("GetReadiness")
+    .WithTags("Health");
 
 await app.RunAsync();
 

src/FinalFactory.Rendezvous.Server/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("FinalFactory.Rendezvous.Tests")]

src/FinalFactory.Rendezvous.Server/Properties/launchSettings.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "development": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "http://127.0.0.1:5096",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

src/FinalFactory.Rendezvous.Server/Provisioning/GamePolicy.cs

@@ -0,0 +1,80 @@
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal sealed class GamePolicy
+{
+    private readonly HashSet<uint> _protocolVersions;
+    private readonly HashSet<RegionId> _regions;
+    private readonly HashSet<ListingVisibility> _visibilityModes;
+    private readonly HashSet<PublisherTrustMode> _publisherTrustModes;
+    private readonly Dictionary<string, int> _metadataValueMaxBytes;
+    private readonly HashSet<string> _requiredMetadataKeys;
+
+    public GamePolicy(GamePolicyOptions options)
+    {
+        GameId = new GameId(options.GameId);
+        EnvironmentId = new EnvironmentId(options.EnvironmentId);
+        Enabled = options.Enabled;
+        _protocolVersions = new HashSet<uint>(options.ProtocolVersions);
+        _regions = options.Regions.Select(static region => new RegionId(region)).ToHashSet();
+        _visibilityModes = new HashSet<ListingVisibility>(options.VisibilityModes);
+        _publisherTrustModes = new HashSet<PublisherTrustMode>(options.PublisherTrustModes);
+        _metadataValueMaxBytes = new Dictionary<string, int>(
+            options.MetadataValueMaxBytes,
+            StringComparer.Ordinal);
+        _requiredMetadataKeys = new HashSet<string>(
+            options.RequiredMetadataKeys,
+            StringComparer.Ordinal);
+        MetadataMaxBytes = options.MetadataMaxBytes;
+        MetadataMaxKeys = options.MetadataMaxKeys;
+        MaxListingsPerPrincipal = options.MaxListingsPerPrincipal;
+        MaxAnonymousListingsPerAddress = options.MaxAnonymousListingsPerAddress;
+        MaxActiveJoinAttempts = options.MaxActiveJoinAttempts;
+        FallbackPolicy = options.FallbackPolicy;
+    }
+
+    public GameId GameId { get; }
+    public EnvironmentId EnvironmentId { get; }
+    public bool Enabled { get; }
+    public int MetadataMaxBytes { get; }
+    public int MetadataMaxKeys { get; }
+    public int MaxListingsPerPrincipal { get; }
+    public int MaxAnonymousListingsPerAddress { get; }
+    public int MaxActiveJoinAttempts { get; }
+    public FallbackPolicyMode FallbackPolicy { get; }
+
+    public bool AllowsProtocol(uint protocolVersion) =>
+        _protocolVersions.Contains(protocolVersion);
+
+    public bool AllowsRegion(RegionId regionId) => _regions.Contains(regionId);
+
+    public bool AllowsVisibility(ListingVisibility visibility) =>
+        _visibilityModes.Contains(visibility);
+
+    public bool AllowsPublisherTrust(PublisherTrustMode trustMode) =>
+        _publisherTrustModes.Contains(trustMode);
+
+    public bool AllowsMetadata(IReadOnlyDictionary<string, string>? metadata)
+    {
+        if (!ContractValidation.IsMetadataValid(metadata)
+            || metadata!.Count > MetadataMaxKeys
+            || !_requiredMetadataKeys.IsSubsetOf(metadata.Keys))
+        {
+            return false;
+        }
+
+        foreach (KeyValuePair<string, string> item in metadata)
+        {
+            if (!_metadataValueMaxBytes.TryGetValue(item.Key, out int maximumBytes)
+                || !ContractValidation.IsUtf8LengthWithin(item.Value, maximumBytes))
+            {
+                return false;
+            }
+        }
+
+        return JsonSerializer.SerializeToUtf8Bytes(metadata, ContractJson.Options).Length
+            <= MetadataMaxBytes;
+    }
+}

src/FinalFactory.Rendezvous.Server/Provisioning/GamePolicyRegistry.cs

@@ -0,0 +1,118 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal sealed class GamePolicyRegistry
+{
+    private readonly Dictionary<(GameId Game, EnvironmentId Environment), GamePolicy> _policies;
+
+    private GamePolicyRegistry(
+        Dictionary<(GameId Game, EnvironmentId Environment), GamePolicy> policies) =>
+        _policies = policies;
+
+    public bool HasEnabledPolicies => _policies.Values.Any(static policy => policy.Enabled);
+    public IEnumerable<GamePolicy> EnabledPolicies =>
+        _policies.Values.Where(static policy => policy.Enabled);
+
+    public static GamePolicyRegistry Create(IEnumerable<GamePolicyOptions> options)
+    {
+        GamePolicyOptions[] configuredPolicies = options.ToArray();
+        if (configuredPolicies.Length > ProvisioningLimits.MaxGamePolicies)
+        {
+            throw new ProvisioningConfigurationException(
+                $"At most {ProvisioningLimits.MaxGamePolicies} game policies may be configured.");
+        }
+
+        Dictionary<(GameId Game, EnvironmentId Environment), GamePolicy> policies = [];
+        foreach (GamePolicyOptions policyOptions in configuredPolicies)
+        {
+            Validate(policyOptions);
+            GamePolicy policy = new(policyOptions);
+            if (!policies.TryAdd((policy.GameId, policy.EnvironmentId), policy))
+            {
+                throw new ProvisioningConfigurationException(
+                    $"Duplicate game/environment policy: {policy.GameId}/{policy.EnvironmentId}.");
+            }
+        }
+
+        return new GamePolicyRegistry(policies);
+    }
+
+    public bool TryGet(
+        GameId gameId,
+        EnvironmentId environmentId,
+        out GamePolicy? policy)
+    {
+        if (_policies.TryGetValue((gameId, environmentId), out GamePolicy? candidate)
+            && candidate.Enabled)
+        {
+            policy = candidate;
+            return true;
+        }
+
+        policy = null;
+        return false;
+    }
+
+    private static void Validate(GamePolicyOptions options)
+    {
+        if (!GameId.TryParse(options.GameId, out _)
+            || !EnvironmentId.TryParse(options.EnvironmentId, out _))
+        {
+            throw new ProvisioningConfigurationException(
+                "Game policies require valid game and environment IDs.");
+        }
+
+        if (options.ProtocolVersions.Count is 0 or > ProvisioningLimits.MaxProtocolVersionsPerPolicy
+            || options.ProtocolVersions.Contains(0)
+            || options.ProtocolVersions.Count != options.ProtocolVersions.Distinct().Count())
+        {
+            throw new ProvisioningConfigurationException(
+                $"Policy {options.GameId}/{options.EnvironmentId} requires unique non-zero protocol versions.");
+        }
+
+        if (options.Regions.Count is 0 or > ProvisioningLimits.MaxRegionsPerPolicy
+            || options.Regions.Any(static region => !RegionId.TryParse(region, out _))
+            || options.Regions.Count != options.Regions.Distinct(StringComparer.Ordinal).Count())
+        {
+            throw new ProvisioningConfigurationException(
+                $"Policy {options.GameId}/{options.EnvironmentId} requires unique valid regions.");
+        }
+
+        if (options.VisibilityModes.Count == 0
+            || options.VisibilityModes.Any(static mode => !Enum.IsDefined(mode))
+            || options.VisibilityModes.Count != options.VisibilityModes.Distinct().Count()
+            || options.PublisherTrustModes.Count == 0
+            || options.PublisherTrustModes.Any(static mode => !Enum.IsDefined(mode))
+            || options.PublisherTrustModes.Count != options.PublisherTrustModes.Distinct().Count())
+        {
+            throw new ProvisioningConfigurationException(
+                $"Policy {options.GameId}/{options.EnvironmentId} requires valid visibility and trust modes.");
+        }
+
+        if (options.MetadataMaxBytes is < 2 or > ContractLimits.MetadataMaxBytes
+            || options.MetadataMaxKeys is < 0 or > ContractLimits.MetadataMaxKeys
+            || options.MetadataValueMaxBytes.Count > options.MetadataMaxKeys
+            || options.MetadataValueMaxBytes.Any(static item =>
+                string.IsNullOrWhiteSpace(item.Key)
+                || !ContractValidation.IsUtf8LengthWithin(item.Key, ContractLimits.MetadataKeyMaxBytes)
+                || item.Value is < 0 or > ContractLimits.MetadataValueMaxBytes)
+            || options.RequiredMetadataKeys.Any(key =>
+                !options.MetadataValueMaxBytes.ContainsKey(key)))
+        {
+            throw new ProvisioningConfigurationException(
+                $"Policy {options.GameId}/{options.EnvironmentId} has an invalid metadata schema.");
+        }
+
+        if (options.MaxListingsPerPrincipal is < 1 or > ProvisioningLimits.MaxListingsPerPrincipal
+            || options.MaxAnonymousListingsPerAddress < 0
+            || options.MaxAnonymousListingsPerAddress > options.MaxListingsPerPrincipal
+            || options.MaxActiveJoinAttempts is < 1
+                or > ProvisioningLimits.MaxActiveJoinAttemptsPerPolicy
+            || !Enum.IsDefined(options.FallbackPolicy))
+        {
+            throw new ProvisioningConfigurationException(
+                $"Policy {options.GameId}/{options.EnvironmentId} has invalid quotas or fallback policy.");
+        }
+    }
+}

src/FinalFactory.Rendezvous.Server/Provisioning/PrincipalCredentialService.cs

@@ -0,0 +1,458 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal sealed class PrincipalCredentialService
+{
+    private const string TokenPrefix = "rv1";
+    private readonly string _issuer;
+    private readonly string _audience;
+    private readonly TimeSpan _clockSkew;
+    private readonly SigningKeyRing _keyRing;
+
+    public PrincipalCredentialService(
+        string issuer,
+        string audience,
+        TimeSpan clockSkew,
+        SigningKeyRing keyRing)
+    {
+        if (!IsSafeAuthority(issuer) || !IsSafeAuthority(audience))
+        {
+            throw new ProvisioningConfigurationException(
+                "Credential issuer and audience are required.");
+        }
+
+        if (clockSkew < TimeSpan.Zero || clockSkew > TimeSpan.FromSeconds(30))
+        {
+            throw new ProvisioningConfigurationException(
+                "Credential clock skew must be between zero and 30 seconds.");
+        }
+
+        _issuer = issuer;
+        _audience = audience;
+        _clockSkew = clockSkew;
+        _keyRing = keyRing;
+    }
+
+    public string Issue(AuthenticatedPrincipal principal, DateTimeOffset now)
+    {
+        if (!IsSafeSubject(principal.Subject))
+        {
+            throw new ArgumentException(
+                "Principal subjects must be 1–128 visible ASCII characters.",
+                nameof(principal));
+        }
+
+        if (principal.ExpiresAt <= now)
+        {
+            throw new ArgumentException("Cannot issue an already-expired principal.", nameof(principal));
+        }
+
+        CredentialPayload payload = CreatePayload(principal, now);
+        if (CreatePrincipal(payload, principal.ExpiresAt) is null)
+        {
+            throw new ArgumentException(
+                "The principal contains an invalid kind or scope.",
+                nameof(principal));
+        }
+
+        if (!_keyRing.TryGetSigningKey(
+                now,
+                payload.Kind,
+                payload.GameId,
+                payload.EnvironmentId,
+                out SigningKey? signingKey)
+            || signingKey is null)
+        {
+            throw new InvalidOperationException("No active signing key is available.");
+        }
+
+        if (principal.ExpiresAt > signingKey.VerifyUntil)
+        {
+            throw new InvalidOperationException(
+                "The active key verification window is shorter than the credential lifetime.");
+        }
+
+        string encodedPayload = Base64Url.Encode(
+            JsonSerializer.SerializeToUtf8Bytes(payload, ContractJson.Options));
+        string signedContent = $"{TokenPrefix}.{signingKey.KeyId}.{encodedPayload}";
+        string signature = Base64Url.Encode(signingKey.Sign(signedContent));
+        string token = $"{signedContent}.{signature}";
+        if (!ContractValidation.IsOpaqueHttpCredentialValid(token))
+        {
+            throw new InvalidOperationException("The signed credential exceeds the v1 size limit.");
+        }
+
+        return token;
+    }
+
+    public CredentialValidationResult Validate(string? token, DateTimeOffset now)
+    {
+        if (!ContractValidation.IsOpaqueHttpCredentialValid(token))
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.Malformed);
+        }
+
+        string[] segments = token!.Split('.');
+        if (segments.Length != 4
+            || !string.Equals(segments[0], TokenPrefix, StringComparison.Ordinal)
+            || segments[1].Length == 0)
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.Malformed);
+        }
+
+        VerificationKeyLookup lookup = _keyRing.FindVerificationKey(
+            segments[1],
+            now,
+            out SigningKey? signingKey);
+        if (lookup != VerificationKeyLookup.Available || signingKey is null)
+        {
+            return CredentialValidationResult.Invalid(lookup switch
+            {
+                VerificationKeyLookup.Revoked => CredentialValidationError.KeyRevoked,
+                VerificationKeyLookup.NotYetValid => CredentialValidationError.KeyNotYetValid,
+                VerificationKeyLookup.Retired => CredentialValidationError.KeyRetired,
+                _ => CredentialValidationError.UnknownKey,
+            });
+        }
+
+        if (!Base64Url.TryDecode(segments[3], out byte[]? suppliedSignature))
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.SignatureInvalid);
+        }
+
+        string signedContent = $"{segments[0]}.{segments[1]}.{segments[2]}";
+        byte[] expectedSignature = signingKey.Sign(signedContent);
+        bool signatureMatches = suppliedSignature.Length == expectedSignature.Length
+            && CryptographicOperations.FixedTimeEquals(suppliedSignature, expectedSignature);
+        CryptographicOperations.ZeroMemory(suppliedSignature);
+        CryptographicOperations.ZeroMemory(expectedSignature);
+        if (!signatureMatches)
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.SignatureInvalid);
+        }
+
+        if (!Base64Url.TryDecode(segments[2], out byte[]? encodedPayload))
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.Malformed);
+        }
+
+        CredentialPayload? payload;
+        try
+        {
+            payload = JsonSerializer.Deserialize<CredentialPayload>(
+                encodedPayload,
+                ContractJson.Options);
+        }
+        catch (JsonException)
+        {
+            payload = null;
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(encodedPayload);
+        }
+
+        if (payload is null || payload.Version != ContractLimits.ContractVersion)
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.PayloadInvalid);
+        }
+
+        if (!string.Equals(payload.Issuer, _issuer, StringComparison.Ordinal))
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.IssuerMismatch);
+        }
+
+        if (!string.Equals(payload.Audience, _audience, StringComparison.Ordinal))
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.AudienceMismatch);
+        }
+
+        if (!signingKey.Authorizes(payload.Kind, payload.GameId, payload.EnvironmentId))
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.KeyScopeMismatch);
+        }
+
+        DateTimeOffset issuedAt;
+        DateTimeOffset notBefore;
+        DateTimeOffset expiresAt;
+        try
+        {
+            issuedAt = DateTimeOffset.FromUnixTimeSeconds(payload.IssuedAtUnixSeconds);
+            notBefore = DateTimeOffset.FromUnixTimeSeconds(payload.NotBeforeUnixSeconds);
+            expiresAt = DateTimeOffset.FromUnixTimeSeconds(payload.ExpiresAtUnixSeconds);
+        }
+        catch (ArgumentOutOfRangeException)
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.PayloadInvalid);
+        }
+
+        if (issuedAt > now + _clockSkew || notBefore > now + _clockSkew)
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.NotYetValid);
+        }
+
+        if (expiresAt <= now - _clockSkew || expiresAt <= notBefore)
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.Expired);
+        }
+
+        if (issuedAt > notBefore
+            || issuedAt < signingKey.NotBefore - _clockSkew
+            || expiresAt > signingKey.VerifyUntil)
+        {
+            return CredentialValidationResult.Invalid(CredentialValidationError.PayloadInvalid);
+        }
+
+        AuthenticatedPrincipal? principal = CreatePrincipal(payload, expiresAt);
+        return principal is null
+            ? CredentialValidationResult.Invalid(CredentialValidationError.ScopeInvalid)
+            : CredentialValidationResult.Valid(principal);
+    }
+
+    public override string ToString() => "[PrincipalCredentialService: key material and credentials redacted]";
+
+    private CredentialPayload CreatePayload(AuthenticatedPrincipal principal, DateTimeOffset now)
+    {
+        CredentialPayload payload = new()
+        {
+            Version = ContractLimits.ContractVersion,
+            Issuer = _issuer,
+            Audience = _audience,
+            Subject = principal.Subject,
+            IssuedAtUnixSeconds = now.ToUnixTimeSeconds(),
+            NotBeforeUnixSeconds = now.ToUnixTimeSeconds(),
+            ExpiresAtUnixSeconds = principal.ExpiresAt.ToUnixTimeSeconds(),
+            Nonce = Guid.NewGuid().ToString("N"),
+        };
+
+        switch (principal)
+        {
+            case DedicatedPublisherPrincipal publisher:
+                SetPublisherPayload(payload, publisher, PrincipalCredentialKind.DedicatedPublisher);
+                break;
+            case PlayerHostGrantPrincipal publisher:
+                SetPublisherPayload(payload, publisher, PrincipalCredentialKind.PlayerHostGrant);
+                break;
+            case OperatorPrincipal operatorPrincipal:
+                payload.Kind = PrincipalCredentialKind.Operator;
+                payload.Permissions = operatorPrincipal.Permissions.Order().ToList();
+                break;
+            default:
+                throw new ArgumentException(
+                    "Anonymous principals cannot receive reusable signed credentials.",
+                    nameof(principal));
+        }
+
+        return payload;
+    }
+
+    private static void SetPublisherPayload(
+        CredentialPayload payload,
+        IPublisherPrincipal publisher,
+        PrincipalCredentialKind kind)
+    {
+        payload.Kind = kind;
+        payload.GameId = publisher.GameId.ToString();
+        payload.EnvironmentId = publisher.EnvironmentId.ToString();
+        payload.Regions = publisher.AllowedRegions
+            .Select(static region => region.ToString())
+            .Order(StringComparer.Ordinal)
+            .ToList();
+    }
+
+    private static AuthenticatedPrincipal? CreatePrincipal(
+        CredentialPayload payload,
+        DateTimeOffset expiresAt)
+    {
+        if (!IsSafeSubject(payload.Subject)
+            || !Guid.TryParseExact(payload.Nonce, "N", out Guid nonce)
+            || nonce == Guid.Empty)
+        {
+            return null;
+        }
+
+        if (payload.Kind == PrincipalCredentialKind.Operator)
+        {
+            if (payload.GameId is not null
+                || payload.EnvironmentId is not null
+                || payload.Regions.Count != 0
+                || payload.Permissions.Count == 0
+                || payload.Permissions.Any(static permission => !Enum.IsDefined(permission))
+                || payload.Permissions.Count != payload.Permissions.Distinct().Count())
+            {
+                return null;
+            }
+
+            return new OperatorPrincipal(
+                payload.Subject,
+                expiresAt,
+                new HashSet<OperatorPermission>(payload.Permissions));
+        }
+
+        if (!GameId.TryParse(payload.GameId, out GameId gameId)
+            || !EnvironmentId.TryParse(payload.EnvironmentId, out EnvironmentId environmentId)
+            || payload.Regions.Count == 0
+            || payload.Regions.Any(static region => !RegionId.TryParse(region, out _))
+            || payload.Regions.Count != payload.Regions.Distinct(StringComparer.Ordinal).Count()
+            || payload.Permissions.Count != 0)
+        {
+            return null;
+        }
+
+        HashSet<RegionId> regions = payload.Regions.Select(static region => new RegionId(region)).ToHashSet();
+        return payload.Kind switch
+        {
+            PrincipalCredentialKind.DedicatedPublisher => new DedicatedPublisherPrincipal(
+                payload.Subject,
+                expiresAt,
+                gameId,
+                environmentId,
+                regions),
+            PrincipalCredentialKind.PlayerHostGrant => new PlayerHostGrantPrincipal(
+                payload.Subject,
+                expiresAt,
+                gameId,
+                environmentId,
+                regions),
+            _ => null,
+        };
+    }
+
+    private static bool IsSafeSubject(string? value) =>
+        value is not null
+        && value.Length is > 0 and <= 128
+        && value.All(static character => character is >= '!' and <= '~');
+
+    private static bool IsSafeAuthority(string? value) =>
+        value is not null
+        && value.Length is > 0 and <= 128
+        && value.All(static character => character is >= '!' and <= '~');
+}
+
+internal sealed class CredentialPayload
+{
+    [JsonRequired]
+    public int Version { get; set; }
+
+    [JsonRequired]
+    public string Issuer { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string Audience { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public string Subject { get; set; } = string.Empty;
+
+    [JsonRequired]
+    public PrincipalCredentialKind Kind { get; set; }
+
+    public string? GameId { get; set; }
+    public string? EnvironmentId { get; set; }
+    public List<string> Regions { get; set; } = [];
+    public List<OperatorPermission> Permissions { get; set; } = [];
+
+    [JsonRequired]
+    public long IssuedAtUnixSeconds { get; set; }
+
+    [JsonRequired]
+    public long NotBeforeUnixSeconds { get; set; }
+
+    [JsonRequired]
+    public long ExpiresAtUnixSeconds { get; set; }
+
+    [JsonRequired]
+    public string Nonce { get; set; } = string.Empty;
+}
+
+internal readonly record struct CredentialValidationResult(
+    bool IsValid,
+    CredentialValidationError Error,
+    AuthenticatedPrincipal? Principal)
+{
+    public static CredentialValidationResult Valid(AuthenticatedPrincipal principal) =>
+        new(true, CredentialValidationError.None, principal);
+
+    public static CredentialValidationResult Invalid(CredentialValidationError error) =>
+        new(false, error, null);
+
+    public override string ToString() => $"[CredentialValidation: {Error}, credential redacted]";
+}
+
+internal enum CredentialValidationError
+{
+    None = 0,
+    Malformed = 1,
+    UnknownKey = 2,
+    KeyRevoked = 3,
+    KeyNotYetValid = 4,
+    KeyRetired = 5,
+    SignatureInvalid = 6,
+    PayloadInvalid = 7,
+    IssuerMismatch = 8,
+    AudienceMismatch = 9,
+    KeyScopeMismatch = 10,
+    NotYetValid = 11,
+    Expired = 12,
+    ScopeInvalid = 13,
+}
+
+internal static class Base64Url
+{
+    public static string Encode(ReadOnlySpan<byte> bytes) => Convert
+        .ToBase64String(bytes)
+        .TrimEnd('=')
+        .Replace('+', '-')
+        .Replace('/', '_');
+
+    public static bool TryDecode(string value, out byte[] bytes)
+    {
+        bytes = [];
+        if (string.IsNullOrEmpty(value)
+            || value.Any(static character =>
+                character is not (>= 'A' and <= 'Z')
+                and not (>= 'a' and <= 'z')
+                and not (>= '0' and <= '9')
+                and not '-'
+                and not '_'))
+        {
+            return false;
+        }
+
+        string padded = value.Replace('-', '+').Replace('_', '/');
+        int remainder = padded.Length % 4;
+        if (remainder == 1)
+        {
+            return false;
+        }
+
+        padded += remainder switch
+        {
+            0 => string.Empty,
+            2 => "==",
+            3 => "=",
+            _ => string.Empty,
+        };
+
+        try
+        {
+            bytes = Convert.FromBase64String(padded);
+            if (string.Equals(Encode(bytes), value, StringComparison.Ordinal))
+            {
+                return true;
+            }
+
+            CryptographicOperations.ZeroMemory(bytes);
+            bytes = [];
+            return false;
+        }
+        catch (FormatException)
+        {
+            return false;
+        }
+    }
+}

src/FinalFactory.Rendezvous.Server/Provisioning/Principals.cs

@@ -0,0 +1,107 @@
+using System.Collections.Frozen;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal abstract record AuthenticatedPrincipal(
+    string Subject,
+    DateTimeOffset ExpiresAt);
+
+internal interface IPublisherPrincipal
+{
+    string Subject { get; }
+    DateTimeOffset ExpiresAt { get; }
+    GameId GameId { get; }
+    EnvironmentId EnvironmentId { get; }
+    PublisherTrustMode TrustMode { get; }
+    IReadOnlySet<RegionId> AllowedRegions { get; }
+}
+
+internal sealed record DedicatedPublisherPrincipal : AuthenticatedPrincipal, IPublisherPrincipal
+{
+    public DedicatedPublisherPrincipal(
+        string subject,
+        DateTimeOffset expiresAt,
+        GameId gameId,
+        EnvironmentId environmentId,
+        IEnumerable<RegionId> allowedRegions)
+        : base(subject, expiresAt)
+    {
+        GameId = gameId;
+        EnvironmentId = environmentId;
+        AllowedRegions = allowedRegions.ToFrozenSet();
+    }
+
+    public GameId GameId { get; }
+    public EnvironmentId EnvironmentId { get; }
+    public IReadOnlySet<RegionId> AllowedRegions { get; }
+    public PublisherTrustMode TrustMode => PublisherTrustMode.ManagedDedicated;
+}
+
+internal sealed record PlayerHostGrantPrincipal : AuthenticatedPrincipal, IPublisherPrincipal
+{
+    public PlayerHostGrantPrincipal(
+        string subject,
+        DateTimeOffset expiresAt,
+        GameId gameId,
+        EnvironmentId environmentId,
+        IEnumerable<RegionId> allowedRegions)
+        : base(subject, expiresAt)
+    {
+        GameId = gameId;
+        EnvironmentId = environmentId;
+        AllowedRegions = allowedRegions.ToFrozenSet();
+    }
+
+    public GameId GameId { get; }
+    public EnvironmentId EnvironmentId { get; }
+    public IReadOnlySet<RegionId> AllowedRegions { get; }
+    public PublisherTrustMode TrustMode => PublisherTrustMode.PlayerGrant;
+}
+
+internal sealed record AnonymousUnlistedPrincipal : AuthenticatedPrincipal, IPublisherPrincipal
+{
+    public AnonymousUnlistedPrincipal(
+        string subject,
+        DateTimeOffset expiresAt,
+        GameId gameId,
+        EnvironmentId environmentId,
+        IEnumerable<RegionId> allowedRegions)
+        : base(subject, expiresAt)
+    {
+        GameId = gameId;
+        EnvironmentId = environmentId;
+        AllowedRegions = allowedRegions.ToFrozenSet();
+    }
+
+    public GameId GameId { get; }
+    public EnvironmentId EnvironmentId { get; }
+    public IReadOnlySet<RegionId> AllowedRegions { get; }
+    public PublisherTrustMode TrustMode => PublisherTrustMode.AnonymousUnlisted;
+}
+
+internal sealed record OperatorPrincipal : AuthenticatedPrincipal
+{
+    public OperatorPrincipal(
+        string subject,
+        DateTimeOffset expiresAt,
+        IEnumerable<OperatorPermission> permissions)
+        : base(subject, expiresAt) => Permissions = permissions.ToFrozenSet();
+
+    public IReadOnlySet<OperatorPermission> Permissions { get; }
+}
+
+internal enum OperatorPermission
+{
+    ReadPolicy = 1,
+    ManagePolicy = 2,
+    RevokePublisher = 3,
+    RotateKeys = 4,
+}
+
+internal enum PrincipalCredentialKind
+{
+    DedicatedPublisher = 1,
+    PlayerHostGrant = 2,
+    Operator = 3,
+}

src/FinalFactory.Rendezvous.Server/Provisioning/ProvisioningOptions.cs

@@ -0,0 +1,71 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal sealed class ProvisioningOptions
+{
+    public const string SectionName = "Rendezvous:Provisioning";
+
+    public string Issuer { get; set; } = string.Empty;
+    public string Audience { get; set; } = string.Empty;
+    public int ClockSkewSeconds { get; set; } = 30;
+    public List<SigningKeyOptions> SigningKeys { get; set; } = [];
+    public List<GamePolicyOptions> Games { get; set; } = [];
+}
+
+internal sealed class SigningKeyOptions
+{
+    public string KeyId { get; set; } = string.Empty;
+    public string SecretReference { get; set; } = string.Empty;
+    public List<PrincipalCredentialKind> CredentialKinds { get; set; } = [];
+    public string? GameId { get; set; }
+    public string? EnvironmentId { get; set; }
+    public DateTimeOffset NotBefore { get; set; }
+    public DateTimeOffset SignUntil { get; set; }
+    public DateTimeOffset VerifyUntil { get; set; }
+    public bool Revoked { get; set; }
+}
+
+internal sealed class GamePolicyOptions
+{
+    public string GameId { get; set; } = string.Empty;
+    public string EnvironmentId { get; set; } = string.Empty;
+    public bool Enabled { get; set; } = true;
+    public List<uint> ProtocolVersions { get; set; } = [];
+    public List<string> Regions { get; set; } = [];
+    public List<ListingVisibility> VisibilityModes { get; set; } = [];
+    public List<PublisherTrustMode> PublisherTrustModes { get; set; } = [];
+    public Dictionary<string, int> MetadataValueMaxBytes { get; set; } =
+        new(StringComparer.Ordinal);
+    public List<string> RequiredMetadataKeys { get; set; } = [];
+    public int MetadataMaxBytes { get; set; } = ContractLimits.MetadataMaxBytes;
+    public int MetadataMaxKeys { get; set; } = ContractLimits.MetadataMaxKeys;
+    public int MaxListingsPerPrincipal { get; set; } = 100;
+    public int MaxAnonymousListingsPerAddress { get; set; } = 2;
+    public int MaxActiveJoinAttempts { get; set; } = 1_000;
+    public FallbackPolicyMode FallbackPolicy { get; set; }
+}
+
+internal enum FallbackPolicyMode
+{
+    Disabled = 0,
+    DedicatedEndpointAllowed = 1,
+}
+
+internal static class ProvisioningLimits
+{
+    public const int MaxGamePolicies = 1_024;
+    public const int MaxSigningKeys = 128;
+    public const int MaxProtocolVersionsPerPolicy = 64;
+    public const int MaxRegionsPerPolicy = 32;
+    public const int MaxListingsPerPrincipal = 25_000;
+    public const int MaxActiveJoinAttemptsPerPolicy = 10_000;
+}
+
+internal sealed class ProvisioningConfigurationException : Exception
+{
+    public ProvisioningConfigurationException(string message)
+        : base(message)
+    {
+    }
+}

src/FinalFactory.Rendezvous.Server/Provisioning/ProvisioningRuntime.cs

@@ -0,0 +1,120 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal sealed class ProvisioningRuntime : IDisposable
+{
+    private readonly IDisposable? _secretProviderLifetime;
+
+    private ProvisioningRuntime(
+        GamePolicyRegistry policies,
+        SigningKeyRing signingKeys,
+        PrincipalCredentialService credentials,
+        PublisherAuthorizationService publisherAuthorization,
+        IDisposable? secretProviderLifetime)
+    {
+        Policies = policies;
+        SigningKeys = signingKeys;
+        Credentials = credentials;
+        PublisherAuthorization = publisherAuthorization;
+        _secretProviderLifetime = secretProviderLifetime;
+    }
+
+    public GamePolicyRegistry Policies { get; }
+    public SigningKeyRing SigningKeys { get; }
+    public PrincipalCredentialService Credentials { get; }
+    public PublisherAuthorizationService PublisherAuthorization { get; }
+
+    public static ProvisioningRuntime Create(
+        ProvisioningOptions options,
+        ISecretProvider secretProvider,
+        DateTimeOffset now)
+    {
+        try
+        {
+            SigningKeyRing signingKeys = SigningKeyRing.Create(options.SigningKeys, secretProvider);
+            try
+            {
+                if (!signingKeys.HasKeys
+                    || !signingKeys.HasActiveSigningKey(now))
+                {
+                    throw new ProvisioningConfigurationException(
+                        "At least one active signing key with available production key material is required.");
+                }
+
+                GamePolicyRegistry policies = GamePolicyRegistry.Create(options.Games);
+                if (!policies.HasEnabledPolicies)
+                {
+                    throw new ProvisioningConfigurationException(
+                        "At least one enabled game/environment policy is required.");
+                }
+
+                foreach (GamePolicy policy in policies.EnabledPolicies)
+                {
+                    RequirePublisherKey(
+                        signingKeys,
+                        policy,
+                        PublisherTrustMode.ManagedDedicated,
+                        PrincipalCredentialKind.DedicatedPublisher,
+                        now);
+                    RequirePublisherKey(
+                        signingKeys,
+                        policy,
+                        PublisherTrustMode.PlayerGrant,
+                        PrincipalCredentialKind.PlayerHostGrant,
+                        now);
+                }
+
+                PrincipalCredentialService credentials = new(
+                    options.Issuer,
+                    options.Audience,
+                    TimeSpan.FromSeconds(options.ClockSkewSeconds),
+                    signingKeys);
+                PublisherAuthorizationService authorization = new(policies);
+                return new ProvisioningRuntime(
+                    policies,
+                    signingKeys,
+                    credentials,
+                    authorization,
+                    secretProvider as IDisposable);
+            }
+            catch
+            {
+                signingKeys.Dispose();
+                throw;
+            }
+        }
+        catch
+        {
+            (secretProvider as IDisposable)?.Dispose();
+            throw;
+        }
+    }
+
+    public void Dispose()
+    {
+        SigningKeys.Dispose();
+        _secretProviderLifetime?.Dispose();
+    }
+
+    private static void RequirePublisherKey(
+        SigningKeyRing signingKeys,
+        GamePolicy policy,
+        PublisherTrustMode trustMode,
+        PrincipalCredentialKind credentialKind,
+        DateTimeOffset now)
+    {
+        if (policy.AllowsPublisherTrust(trustMode)
+            && !signingKeys.HasActiveSigningKey(
+                now,
+                credentialKind,
+                policy.GameId.ToString(),
+                policy.EnvironmentId.ToString()))
+        {
+            throw new ProvisioningConfigurationException(
+                $"Policy {policy.GameId}/{policy.EnvironmentId} has no active {credentialKind} key.");
+        }
+    }
+}
+
+internal sealed record ProvisioningReadiness(bool IsReady);

src/FinalFactory.Rendezvous.Server/Provisioning/PublisherAuthorizationService.cs

@@ -0,0 +1,119 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal sealed class PublisherAuthorizationService(GamePolicyRegistry policies)
+{
+    public PublisherAuthorizationResult Authorize(
+        AuthenticatedPrincipal principal,
+        GameId requestedGameId,
+        EnvironmentId requestedEnvironmentId,
+        RegionId requestedRegionId,
+        uint requestedProtocolVersion,
+        ListingVisibility requestedVisibility,
+        IReadOnlyDictionary<string, string> requestedMetadata,
+        DateTimeOffset now)
+    {
+        if (principal.ExpiresAt <= now)
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.PrincipalExpired);
+        }
+
+        if (principal is not IPublisherPrincipal publisher)
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.NotPublisher);
+        }
+
+        if (publisher.GameId != requestedGameId
+            || publisher.EnvironmentId != requestedEnvironmentId)
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.ScopeMismatch);
+        }
+
+        if (!policies.TryGet(publisher.GameId, publisher.EnvironmentId, out GamePolicy? policy)
+            || policy is null)
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.PolicyNotFound);
+        }
+
+        if (!policy.AllowsPublisherTrust(publisher.TrustMode))
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.TrustModeNotAllowed);
+        }
+
+        if (!publisher.AllowedRegions.Contains(requestedRegionId)
+            || !policy.AllowsRegion(requestedRegionId))
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.RegionNotAllowed);
+        }
+
+        if (!policy.AllowsProtocol(requestedProtocolVersion))
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.ProtocolNotAllowed);
+        }
+
+        if (publisher.TrustMode == PublisherTrustMode.AnonymousUnlisted
+            && requestedVisibility != ListingVisibility.Unlisted)
+        {
+            return PublisherAuthorizationResult.Denied(
+                PublisherAuthorizationError.AnonymousMustBeUnlisted);
+        }
+
+        if (!policy.AllowsVisibility(requestedVisibility))
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.VisibilityNotAllowed);
+        }
+
+        if (!policy.AllowsMetadata(requestedMetadata))
+        {
+            return PublisherAuthorizationResult.Denied(PublisherAuthorizationError.MetadataNotAllowed);
+        }
+
+        return PublisherAuthorizationResult.Allowed(new AuthorizedPublisherContext(
+            publisher.Subject,
+            publisher.GameId,
+            publisher.EnvironmentId,
+            requestedRegionId,
+            requestedProtocolVersion,
+            requestedVisibility,
+            publisher.TrustMode,
+            policy));
+    }
+}
+
+internal sealed record AuthorizedPublisherContext(
+    string Subject,
+    GameId GameId,
+    EnvironmentId EnvironmentId,
+    RegionId RegionId,
+    uint ProtocolVersion,
+    ListingVisibility Visibility,
+    PublisherTrustMode TrustMode,
+    GamePolicy Policy);
+
+internal readonly record struct PublisherAuthorizationResult(
+    bool IsAllowed,
+    PublisherAuthorizationError Error,
+    AuthorizedPublisherContext? Context)
+{
+    public static PublisherAuthorizationResult Allowed(AuthorizedPublisherContext context) =>
+        new(true, PublisherAuthorizationError.None, context);
+
+    public static PublisherAuthorizationResult Denied(PublisherAuthorizationError error) =>
+        new(false, error, null);
+}
+
+internal enum PublisherAuthorizationError
+{
+    None = 0,
+    NotPublisher = 1,
+    ScopeMismatch = 2,
+    PolicyNotFound = 3,
+    TrustModeNotAllowed = 4,
+    RegionNotAllowed = 5,
+    ProtocolNotAllowed = 6,
+    AnonymousMustBeUnlisted = 7,
+    VisibilityNotAllowed = 8,
+    MetadataNotAllowed = 9,
+    PrincipalExpired = 10,
+}

src/FinalFactory.Rendezvous.Server/Provisioning/SecretProviders.cs

@@ -0,0 +1,144 @@
+using System.Security.Cryptography;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal interface ISecretProvider
+{
+    bool TryGetSecret(string reference, out SecretMaterial? secret);
+}
+
+internal sealed class SecretMaterial : IDisposable
+{
+    private byte[]? _bytes;
+
+    public SecretMaterial(ReadOnlySpan<byte> bytes)
+    {
+        if (bytes.Length == 0)
+        {
+            throw new ArgumentException("Secret material cannot be empty.", nameof(bytes));
+        }
+
+        _bytes = bytes.ToArray();
+    }
+
+    public int Length => _bytes?.Length ?? 0;
+
+    public byte[] CopyBytes() => _bytes?.ToArray()
+        ?? throw new ObjectDisposedException(nameof(SecretMaterial));
+
+    public void Dispose()
+    {
+        if (_bytes is not null)
+        {
+            CryptographicOperations.ZeroMemory(_bytes);
+            _bytes = null;
+        }
+    }
+
+    public override string ToString() => "[REDACTED SECRET]";
+}
+
+internal sealed class EnvironmentSecretProvider : ISecretProvider
+{
+    private const string Prefix = "env:";
+
+    public bool TryGetSecret(string reference, out SecretMaterial? secret)
+    {
+        secret = null;
+        if (!reference.StartsWith(Prefix, StringComparison.Ordinal)
+            || reference.Length == Prefix.Length)
+        {
+            return false;
+        }
+
+        string? encoded = Environment.GetEnvironmentVariable(reference[Prefix.Length..]);
+        if (string.IsNullOrEmpty(encoded))
+        {
+            return false;
+        }
+
+        try
+        {
+            byte[] bytes = Convert.FromBase64String(encoded);
+            secret = new SecretMaterial(bytes);
+            CryptographicOperations.ZeroMemory(bytes);
+            return true;
+        }
+        catch (FormatException)
+        {
+            return false;
+        }
+    }
+}
+
+internal sealed class EphemeralDevelopmentSecretProvider : ISecretProvider, IDisposable
+{
+    private const string Prefix = "development:ephemeral/";
+    private readonly Dictionary<string, byte[]> _secrets = new(StringComparer.Ordinal);
+
+    public bool TryGetSecret(string reference, out SecretMaterial? secret)
+    {
+        secret = null;
+        if (!reference.StartsWith(Prefix, StringComparison.Ordinal)
+            || reference.Length == Prefix.Length)
+        {
+            return false;
+        }
+
+        if (!_secrets.TryGetValue(reference, out byte[]? bytes))
+        {
+            bytes = RandomNumberGenerator.GetBytes(32);
+            _secrets.Add(reference, bytes);
+        }
+
+        secret = new SecretMaterial(bytes);
+        return true;
+    }
+
+    public void Dispose()
+    {
+        foreach (byte[] bytes in _secrets.Values)
+        {
+            CryptographicOperations.ZeroMemory(bytes);
+        }
+
+        _secrets.Clear();
+    }
+
+    public override string ToString() => "[EphemeralDevelopmentSecretProvider]";
+}
+
+internal sealed class DictionarySecretProvider : ISecretProvider, IDisposable
+{
+    private readonly Dictionary<string, byte[]> _secrets;
+
+    public DictionarySecretProvider(IReadOnlyDictionary<string, byte[]> secrets) =>
+        _secrets = secrets.ToDictionary(
+            static item => item.Key,
+            static item => item.Value.ToArray(),
+            StringComparer.Ordinal);
+
+    public bool TryGetSecret(string reference, out SecretMaterial? secret)
+    {
+        if (_secrets.TryGetValue(reference, out byte[]? bytes))
+        {
+            secret = new SecretMaterial(bytes);
+            return true;
+        }
+
+        secret = null;
+        return false;
+    }
+
+    public void Dispose()
+    {
+        foreach (byte[] bytes in _secrets.Values)
+        {
+            CryptographicOperations.ZeroMemory(bytes);
+        }
+
+        _secrets.Clear();
+    }
+
+    public override string ToString() => "[DictionarySecretProvider: REDACTED]";
+}

src/FinalFactory.Rendezvous.Server/Provisioning/SigningKeyRing.cs

@@ -0,0 +1,275 @@
+using System.Collections.Concurrent;
+using System.Collections.Frozen;
+using System.Security.Cryptography;
+using System.Text;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Provisioning;
+
+internal sealed class SigningKeyRing : IDisposable
+{
+    private readonly Dictionary<string, SigningKey> _keys;
+    private readonly ConcurrentDictionary<string, byte> _runtimeRevocations =
+        new(StringComparer.Ordinal);
+
+    private SigningKeyRing(Dictionary<string, SigningKey> keys) => _keys = keys;
+
+    public bool HasKeys => _keys.Count > 0;
+
+    public static SigningKeyRing Create(
+        IEnumerable<SigningKeyOptions> options,
+        ISecretProvider secretProvider)
+    {
+        SigningKeyOptions[] configuredKeys = options.ToArray();
+        if (configuredKeys.Length > ProvisioningLimits.MaxSigningKeys)
+        {
+            throw new ProvisioningConfigurationException(
+                $"At most {ProvisioningLimits.MaxSigningKeys} signing keys may be configured.");
+        }
+
+        Dictionary<string, SigningKey> keys = new(StringComparer.Ordinal);
+        try
+        {
+            foreach (SigningKeyOptions keyOptions in configuredKeys)
+            {
+                Validate(keyOptions);
+                if (keys.ContainsKey(keyOptions.KeyId))
+                {
+                    throw new ProvisioningConfigurationException(
+                        $"Duplicate signing key ID '{keyOptions.KeyId}'.");
+                }
+
+                if (keyOptions.Revoked)
+                {
+                    keys.Add(keyOptions.KeyId, new SigningKey(keyOptions, null));
+                    continue;
+                }
+
+                if (!secretProvider.TryGetSecret(
+                        keyOptions.SecretReference,
+                        out SecretMaterial? material)
+                    || material is null)
+                {
+                    throw new ProvisioningConfigurationException(
+                        $"Signing key '{keyOptions.KeyId}' has no available key material.");
+                }
+
+                using (material)
+                {
+                    if (material.Length < 32)
+                    {
+                        throw new ProvisioningConfigurationException(
+                            $"Signing key '{keyOptions.KeyId}' must contain at least 32 bytes.");
+                    }
+
+                    keys.Add(keyOptions.KeyId, new SigningKey(keyOptions, material.CopyBytes()));
+                }
+            }
+
+            return new SigningKeyRing(keys);
+        }
+        catch
+        {
+            foreach (SigningKey key in keys.Values)
+            {
+                key.Dispose();
+            }
+
+            throw;
+        }
+    }
+
+    public bool HasActiveSigningKey(DateTimeOffset now) => _keys.Values.Any(key =>
+        !IsRevoked(key)
+        && key.NotBefore <= now
+        && now < key.SignUntil);
+
+    public bool HasActiveSigningKey(
+        DateTimeOffset now,
+        PrincipalCredentialKind kind,
+        string? gameId,
+        string? environmentId) => _keys.Values.Any(key =>
+            !IsRevoked(key)
+            && key.NotBefore <= now
+            && now < key.SignUntil
+            && key.Authorizes(kind, gameId, environmentId));
+
+    public bool TryGetSigningKey(
+        DateTimeOffset now,
+        PrincipalCredentialKind kind,
+        string? gameId,
+        string? environmentId,
+        out SigningKey? signingKey)
+    {
+        signingKey = _keys.Values
+            .Where(key => !IsRevoked(key)
+                && key.NotBefore <= now
+                && now < key.SignUntil
+                && key.Authorizes(kind, gameId, environmentId))
+            .OrderByDescending(static key => key.NotBefore)
+            .ThenByDescending(static key => key.KeyId, StringComparer.Ordinal)
+            .FirstOrDefault();
+        return signingKey is not null;
+    }
+
+    public VerificationKeyLookup FindVerificationKey(
+        string keyId,
+        DateTimeOffset now,
+        out SigningKey? signingKey)
+    {
+        signingKey = null;
+        if (!_keys.TryGetValue(keyId, out SigningKey? candidate))
+        {
+            return VerificationKeyLookup.Unknown;
+        }
+
+        if (IsRevoked(candidate))
+        {
+            return VerificationKeyLookup.Revoked;
+        }
+
+        if (now < candidate.NotBefore)
+        {
+            return VerificationKeyLookup.NotYetValid;
+        }
+
+        if (now >= candidate.VerifyUntil)
+        {
+            return VerificationKeyLookup.Retired;
+        }
+
+        signingKey = candidate;
+        return VerificationKeyLookup.Available;
+    }
+
+    public bool Revoke(string keyId) =>
+        _keys.ContainsKey(keyId) && _runtimeRevocations.TryAdd(keyId, 0);
+
+    public void Dispose()
+    {
+        foreach (SigningKey key in _keys.Values)
+        {
+            key.Dispose();
+        }
+
+        _keys.Clear();
+        _runtimeRevocations.Clear();
+    }
+
+    public override string ToString() => $"[SigningKeyRing: {_keys.Count} keys, material redacted]";
+
+    private bool IsRevoked(SigningKey key) =>
+        key.ConfiguredRevoked || _runtimeRevocations.ContainsKey(key.KeyId);
+
+    private static void Validate(SigningKeyOptions options)
+    {
+        if (string.IsNullOrEmpty(options.KeyId)
+            || options.KeyId.Length > 64
+            || options.KeyId.Any(static character =>
+                character is not (>= 'A' and <= 'Z')
+                and not (>= 'a' and <= 'z')
+                and not (>= '0' and <= '9')
+                and not '-'
+                and not '_'))
+        {
+            throw new ProvisioningConfigurationException(
+                "Signing key IDs must be 1–64 base64url characters.");
+        }
+
+        if (string.IsNullOrWhiteSpace(options.SecretReference)
+            || options.NotBefore >= options.SignUntil
+            || options.SignUntil > options.VerifyUntil)
+        {
+            throw new ProvisioningConfigurationException(
+                $"Signing key '{options.KeyId}' has an invalid secret reference or lifetime.");
+        }
+
+        if (options.CredentialKinds.Count == 0
+            || options.CredentialKinds.Any(static kind => !Enum.IsDefined(kind))
+            || options.CredentialKinds.Count != options.CredentialKinds.Distinct().Count())
+        {
+            throw new ProvisioningConfigurationException(
+                $"Signing key '{options.KeyId}' requires unique valid credential kinds.");
+        }
+
+        bool operatorKey = options.CredentialKinds.Contains(PrincipalCredentialKind.Operator);
+        bool hasPublisherKind = options.CredentialKinds.Any(static kind =>
+            kind is PrincipalCredentialKind.DedicatedPublisher
+                or PrincipalCredentialKind.PlayerHostGrant);
+        if (operatorKey
+            ? options.CredentialKinds.Count != 1
+                || options.GameId is not null
+                || options.EnvironmentId is not null
+            : !hasPublisherKind
+                || !GameId.TryParse(options.GameId, out _)
+                || !EnvironmentId.TryParse(options.EnvironmentId, out _))
+        {
+            throw new ProvisioningConfigurationException(
+                $"Signing key '{options.KeyId}' must be operator-only or bound to one game/environment.");
+        }
+    }
+}
+
+internal sealed class SigningKey : IDisposable
+{
+    private byte[]? _material;
+
+    public SigningKey(SigningKeyOptions options, byte[]? material)
+    {
+        KeyId = options.KeyId;
+        NotBefore = options.NotBefore;
+        SignUntil = options.SignUntil;
+        VerifyUntil = options.VerifyUntil;
+        ConfiguredRevoked = options.Revoked;
+        CredentialKinds = options.CredentialKinds.ToFrozenSet();
+        GameId = options.GameId;
+        EnvironmentId = options.EnvironmentId;
+        _material = material;
+    }
+
+    public string KeyId { get; }
+    public DateTimeOffset NotBefore { get; }
+    public DateTimeOffset SignUntil { get; }
+    public DateTimeOffset VerifyUntil { get; }
+    public bool ConfiguredRevoked { get; }
+    public IReadOnlySet<PrincipalCredentialKind> CredentialKinds { get; }
+    public string? GameId { get; }
+    public string? EnvironmentId { get; }
+
+    public bool Authorizes(
+        PrincipalCredentialKind kind,
+        string? gameId,
+        string? environmentId) =>
+        CredentialKinds.Contains(kind)
+        && (kind == PrincipalCredentialKind.Operator
+            ? gameId is null && environmentId is null
+            : string.Equals(GameId, gameId, StringComparison.Ordinal)
+                && string.Equals(EnvironmentId, environmentId, StringComparison.Ordinal));
+
+    public byte[] Sign(string input)
+    {
+        ObjectDisposedException.ThrowIf(_material is null, this);
+
+        return HMACSHA256.HashData(_material, Encoding.ASCII.GetBytes(input));
+    }
+
+    public void Dispose()
+    {
+        if (_material is not null)
+        {
+            CryptographicOperations.ZeroMemory(_material);
+            _material = null;
+        }
+    }
+
+    public override string ToString() => $"[SigningKey {KeyId}: material redacted]";
+}
+
+internal enum VerificationKeyLookup
+{
+    Available = 0,
+    Unknown = 1,
+    Revoked = 2,
+    NotYetValid = 3,
+    Retired = 4,
+}

src/FinalFactory.Rendezvous.Server/Sessions/EphemeralCapabilityIssuer.cs

@@ -0,0 +1,172 @@
+using System.Buffers.Binary;
+using System.Security.Cryptography;
+using System.Text;
+using FinalFactory.Rendezvous.Server.State;
+
+namespace FinalFactory.Rendezvous.Server.Sessions;
+
+internal interface ISessionCapabilityService
+{
+    string CreateDerivationSalt();
+    string DeriveCapability(
+        string purpose,
+        string ownerSubject,
+        string idempotencyKey,
+        string requestFingerprint,
+        string derivationSalt);
+    Guid DeriveGuid(
+        string purpose,
+        string ownerSubject,
+        string idempotencyKey,
+        string requestFingerprint,
+        string derivationSalt);
+    string DeriveOpaqueIdentifier(string purpose, string value);
+    bool TryFingerprint(string? capability, out SecretFingerprint fingerprint);
+}
+
+internal sealed class EphemeralCapabilityIssuer : ISessionCapabilityService, IDisposable
+{
+    private readonly byte[] _key = RandomNumberGenerator.GetBytes(32);
+    private bool _disposed;
+
+    public string CreateDerivationSalt()
+    {
+        ObjectDisposedException.ThrowIf(_disposed, this);
+        byte[] salt = RandomNumberGenerator.GetBytes(32);
+        try
+        {
+            return Encode(salt);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(salt);
+        }
+    }
+
+    public string DeriveCapability(
+        string purpose,
+        string ownerSubject,
+        string idempotencyKey,
+        string requestFingerprint,
+        string derivationSalt)
+    {
+        byte[] digest = Derive(
+            purpose,
+            ownerSubject,
+            idempotencyKey,
+            requestFingerprint,
+            derivationSalt);
+        try
+        {
+            return Encode(digest);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(digest);
+        }
+    }
+
+    public Guid DeriveGuid(
+        string purpose,
+        string ownerSubject,
+        string idempotencyKey,
+        string requestFingerprint,
+        string derivationSalt)
+    {
+        byte[] digest = Derive(
+            purpose,
+            ownerSubject,
+            idempotencyKey,
+            requestFingerprint,
+            derivationSalt);
+        try
+        {
+            Span<byte> guidBytes = digest.AsSpan(0, 16);
+            guidBytes[7] = (byte)((guidBytes[7] & 0x0f) | 0x80);
+            guidBytes[8] = (byte)((guidBytes[8] & 0x3f) | 0x80);
+            return new Guid(guidBytes);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(digest);
+        }
+    }
+
+    public string DeriveOpaqueIdentifier(string purpose, string value)
+    {
+        byte[] digest = Derive(purpose, value);
+        try
+        {
+            return Encode(digest);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(digest);
+        }
+    }
+
+    public bool TryFingerprint(string? capability, out SecretFingerprint fingerprint)
+    {
+        fingerprint = default;
+        if (_disposed
+            || capability is null
+            || capability.Length != 43
+            || capability.Any(static character =>
+                character is not (>= 'A' and <= 'Z')
+                and not (>= 'a' and <= 'z')
+                and not (>= '0' and <= '9')
+                and not '-'
+                and not '_'))
+        {
+            return false;
+        }
+
+        byte[] digest = Derive("fingerprint", capability);
+        try
+        {
+            fingerprint = new SecretFingerprint(Encode(digest));
+            return true;
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(digest);
+        }
+    }
+
+    public void Dispose()
+    {
+        if (_disposed)
+        {
+            return;
+        }
+
+        _disposed = true;
+        CryptographicOperations.ZeroMemory(_key);
+    }
+
+    public override string ToString() => "[EphemeralCapabilityIssuer: key and capabilities redacted]";
+
+    private byte[] Derive(params string[] segments)
+    {
+        ObjectDisposedException.ThrowIf(_disposed, this);
+        using IncrementalHash hmac = IncrementalHash.CreateHMAC(HashAlgorithmName.SHA256, _key);
+        Span<byte> length = stackalloc byte[sizeof(int)];
+        foreach (string segment in segments)
+        {
+            ArgumentException.ThrowIfNullOrEmpty(segment);
+            byte[] encoded = Encoding.UTF8.GetBytes(segment);
+            BinaryPrimitives.WriteInt32BigEndian(length, encoded.Length);
+            hmac.AppendData(length);
+            hmac.AppendData(encoded);
+            CryptographicOperations.ZeroMemory(encoded);
+        }
+
+        return hmac.GetHashAndReset();
+    }
+
+    private static string Encode(ReadOnlySpan<byte> bytes) => Convert
+        .ToBase64String(bytes)
+        .TrimEnd('=')
+        .Replace('+', '-')
+        .Replace('/', '_');
+}

src/FinalFactory.Rendezvous.Server/Sessions/SessionLeaseService.cs

@@ -0,0 +1,440 @@
+using System.Security.Cryptography;
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Provisioning;
+using FinalFactory.Rendezvous.Server.State;
+
+namespace FinalFactory.Rendezvous.Server.Sessions;
+
+internal sealed record SessionLeaseTiming(
+    int LeaseRenewAfterSeconds,
+    int HostPresenceRefreshAfterSeconds)
+{
+    public static SessionLeaseTiming From(EphemeralStoreOptions options) => new(
+        Math.Max(1, (int)(options.LeaseLifetime.TotalSeconds / 2)),
+        Math.Max(1, (int)(options.PresenceLifetime.TotalSeconds / 2)));
+}
+
+internal sealed record SessionServiceResult<T>(RendezvousErrorCode Error, T? Value = default)
+{
+    public bool Succeeded => Error == RendezvousErrorCode.None;
+}
+
+internal sealed class SessionLeaseService(
+    PublisherAuthorizationService authorization,
+    IEphemeralRendezvousStore store,
+    ISessionCapabilityService capabilities,
+    SessionLeaseTiming timing,
+    IWallClock clock)
+{
+    public SessionServiceResult<RegisterSessionResponse> Register(
+        AuthenticatedPrincipal principal,
+        RegisterSessionRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(principal);
+        ArgumentNullException.ThrowIfNull(request);
+        RendezvousErrorCode validation = ValidateRegistration(request);
+        if (validation != RendezvousErrorCode.None)
+        {
+            return new(validation);
+        }
+
+        PublisherAuthorizationResult authorized = authorization.Authorize(
+            principal,
+            request.GameId,
+            request.EnvironmentId,
+            request.RegionId,
+            request.ProtocolVersion,
+            request.Visibility,
+            request.Metadata,
+            clock.UtcNow);
+        if (!authorized.IsAllowed || authorized.Context is null)
+        {
+            return new(MapAuthorization(authorized.Error));
+        }
+
+        AuthorizedPublisherContext context = authorized.Context;
+        string requestFingerprint = ComputeRegistrationFingerprint(request);
+        string derivationSalt = capabilities.CreateDerivationSalt();
+        string leaseToken = capabilities.DeriveCapability(
+            "lease-token",
+            context.Subject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt);
+        string presenceCapability = capabilities.DeriveCapability(
+            "host-presence",
+            context.Subject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt);
+        if (!capabilities.TryFingerprint(leaseToken, out SecretFingerprint leaseFingerprint)
+            || !capabilities.TryFingerprint(presenceCapability, out SecretFingerprint presenceFingerprint))
+        {
+            throw new InvalidOperationException("Derived session capabilities could not be fingerprinted.");
+        }
+
+        SessionListingId listingId = new(capabilities.DeriveGuid(
+            "listing-id",
+            context.Subject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt));
+        LeaseId leaseId = new(capabilities.DeriveGuid(
+            "lease-id",
+            context.Subject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt));
+        MediationHandle presenceHandle = new(capabilities.DeriveGuid(
+            "presence-handle",
+            context.Subject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            derivationSalt));
+        int ownerLimit = context.TrustMode == PublisherTrustMode.AnonymousUnlisted
+            ? context.Policy.MaxAnonymousListingsPerAddress
+            : context.Policy.MaxListingsPerPrincipal;
+        if (ownerLimit <= 0)
+        {
+            return new(RendezvousErrorCode.CapacityExceeded);
+        }
+
+        StoreResult<StoredListing> created = store.CreateListing(new(
+            request.IdempotencyKey,
+            requestFingerprint,
+            new ListingDefinition
+            {
+                ListingId = listingId,
+                LeaseId = leaseId,
+                Scope = new(context.GameId, context.EnvironmentId),
+                OwnerSubject = context.Subject,
+                RegionId = context.RegionId,
+                ProtocolVersion = context.ProtocolVersion,
+                BuildVersion = request.BuildVersion,
+                DisplayName = request.DisplayName,
+                Visibility = context.Visibility,
+                TrustMode = context.TrustMode,
+                CurrentPlayers = request.Capacity.CurrentPlayers,
+                MaximumPlayers = request.Capacity.MaximumPlayers,
+                Metadata = request.Metadata,
+                LeaseFingerprint = leaseFingerprint,
+                HostPresenceHandle = presenceHandle,
+                HostPresenceFingerprint = presenceFingerprint,
+                CapabilityDerivationSalt = derivationSalt,
+            },
+            ownerLimit), cancellationToken);
+        if (!created.Succeeded || created.Value is null)
+        {
+            return new(created.Code.ToContractError());
+        }
+
+        ListingDefinition persisted = created.Value.Definition;
+        leaseToken = capabilities.DeriveCapability(
+            "lease-token",
+            context.Subject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            persisted.CapabilityDerivationSalt);
+        presenceCapability = capabilities.DeriveCapability(
+            "host-presence",
+            context.Subject,
+            request.IdempotencyKey,
+            requestFingerprint,
+            persisted.CapabilityDerivationSalt);
+
+        return new(RendezvousErrorCode.None, new RegisterSessionResponse
+        {
+            ListingId = persisted.ListingId,
+            LeaseId = persisted.LeaseId,
+            LeaseToken = leaseToken,
+            HostPresenceHandle = persisted.HostPresenceHandle,
+            HostPresenceCapability = presenceCapability,
+            ExpiresAt = created.Value.LeaseExpiresAt,
+            LeaseRenewAfterSeconds = timing.LeaseRenewAfterSeconds,
+            HostPresenceRefreshAfterSeconds = timing.HostPresenceRefreshAfterSeconds,
+        });
+    }
+
+    public SessionServiceResult<RenewLeaseResponse> Renew(
+        AuthenticatedPrincipal principal,
+        SessionListingId listingId,
+        RenewLeaseRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(principal);
+        ArgumentNullException.ThrowIfNull(request);
+        RendezvousErrorCode validation = ValidateLeaseRequest(request.ContractVersion, request.LeaseToken);
+        if (validation != RendezvousErrorCode.None)
+        {
+            return new(validation);
+        }
+
+        RendezvousErrorCode lookup = GetAuthorizedListing(
+            principal,
+            listingId,
+            request.LeaseToken,
+            cancellationToken,
+            out StoredListing? listing);
+        if (lookup != RendezvousErrorCode.None)
+        {
+            return new(lookup);
+        }
+
+        StoredListing ownedListing = listing!;
+        PublisherAuthorizationResult authorized = AuthorizeExisting(
+            principal,
+            ownedListing,
+            ownedListing.Definition.Metadata);
+        if (!authorized.IsAllowed)
+        {
+            return new(MapAuthorization(authorized.Error));
+        }
+
+        capabilities.TryFingerprint(request.LeaseToken, out SecretFingerprint fingerprint);
+        StoreResult<StoredListing> renewed = store.RenewLease(new(
+            listingId,
+            ownedListing.Definition.LeaseId,
+            fingerprint,
+            ownedListing.Definition.OwnerSubject,
+            ownedListing.Version), cancellationToken);
+        return renewed.Succeeded && renewed.Value is not null
+            ? new(RendezvousErrorCode.None, new RenewLeaseResponse
+            {
+                ExpiresAt = renewed.Value.LeaseExpiresAt,
+                RenewAfterSeconds = timing.LeaseRenewAfterSeconds,
+            })
+            : new(renewed.Code.ToContractError());
+    }
+
+    public SessionServiceResult<bool> Update(
+        AuthenticatedPrincipal principal,
+        SessionListingId listingId,
+        UpdateSessionRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(principal);
+        ArgumentNullException.ThrowIfNull(request);
+        RendezvousErrorCode validation = ValidateUpdate(request);
+        if (validation != RendezvousErrorCode.None)
+        {
+            return new(validation);
+        }
+
+        RendezvousErrorCode lookup = GetAuthorizedListing(
+            principal,
+            listingId,
+            request.LeaseToken,
+            cancellationToken,
+            out StoredListing? listing);
+        if (lookup != RendezvousErrorCode.None)
+        {
+            return new(lookup);
+        }
+
+        StoredListing ownedListing = listing!;
+        PublisherAuthorizationResult authorized = AuthorizeExisting(principal, ownedListing, request.Metadata);
+        if (!authorized.IsAllowed)
+        {
+            return new(MapAuthorization(authorized.Error));
+        }
+
+        capabilities.TryFingerprint(request.LeaseToken, out SecretFingerprint fingerprint);
+        StoreResult<StoredListing> updated = store.UpdateListing(new(
+            listingId,
+            ownedListing.Definition.LeaseId,
+            fingerprint,
+            ownedListing.Definition.OwnerSubject,
+            request.BuildVersion,
+            request.DisplayName,
+            request.Capacity.CurrentPlayers,
+            request.Capacity.MaximumPlayers,
+            request.Metadata), cancellationToken);
+        return updated.Succeeded
+            ? new(RendezvousErrorCode.None, true)
+            : new(updated.Code.ToContractError());
+    }
+
+    public SessionServiceResult<bool> Delete(
+        AuthenticatedPrincipal principal,
+        SessionListingId listingId,
+        DeleteSessionRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(principal);
+        ArgumentNullException.ThrowIfNull(request);
+        RendezvousErrorCode validation = ValidateLeaseRequest(request.ContractVersion, request.LeaseToken);
+        if (validation != RendezvousErrorCode.None)
+        {
+            return new(validation);
+        }
+
+        if (principal is not IPublisherPrincipal publisher
+            || !capabilities.TryFingerprint(request.LeaseToken, out SecretFingerprint fingerprint))
+        {
+            return new(RendezvousErrorCode.Forbidden);
+        }
+
+        StoreResult<StoredListing> found = store.GetListing(listingId, false, cancellationToken);
+        if (!found.Succeeded || found.Value is null)
+        {
+            return found.Code == StoreResultCode.ServiceUnavailable
+                ? new(RendezvousErrorCode.ServiceUnavailable)
+                : new(RendezvousErrorCode.None, true);
+        }
+
+        StoreResult<bool> deleted = store.DeleteListing(new(
+            listingId,
+            found.Value.Definition.LeaseId,
+            fingerprint,
+            publisher.Subject), cancellationToken);
+        return deleted.Succeeded || deleted.Code == StoreResultCode.NotFound
+            ? new(RendezvousErrorCode.None, true)
+            : new(deleted.Code.ToContractError());
+    }
+
+    private RendezvousErrorCode GetAuthorizedListing(
+        AuthenticatedPrincipal principal,
+        SessionListingId listingId,
+        string leaseToken,
+        CancellationToken cancellationToken,
+        out StoredListing? listing)
+    {
+        listing = null;
+        if (principal is not IPublisherPrincipal publisher)
+        {
+            return RendezvousErrorCode.Forbidden;
+        }
+
+        if (!capabilities.TryFingerprint(leaseToken, out SecretFingerprint fingerprint))
+        {
+            return RendezvousErrorCode.NotFound;
+        }
+
+        StoreResult<StoredListing> found = store.GetListing(listingId, false, cancellationToken);
+        if (!found.Succeeded || found.Value is null)
+        {
+            return found.Code.ToContractError();
+        }
+
+        if (!string.Equals(found.Value.Definition.OwnerSubject, publisher.Subject, StringComparison.Ordinal)
+            || found.Value.Definition.LeaseFingerprint != fingerprint)
+        {
+            return RendezvousErrorCode.NotFound;
+        }
+
+        listing = found.Value;
+        return RendezvousErrorCode.None;
+    }
+
+    private PublisherAuthorizationResult AuthorizeExisting(
+        AuthenticatedPrincipal principal,
+        StoredListing listing,
+        IReadOnlyDictionary<string, string> metadata) => authorization.Authorize(
+            principal,
+            listing.Definition.Scope.GameId,
+            listing.Definition.Scope.EnvironmentId,
+            listing.Definition.RegionId,
+            listing.Definition.ProtocolVersion,
+            listing.Definition.Visibility,
+            metadata,
+            clock.UtcNow);
+
+    private static RendezvousErrorCode ValidateRegistration(RegisterSessionRequest request)
+    {
+        RendezvousErrorCode version = ContractValidation.ValidateContractVersion(request.ContractVersion);
+        if (version != RendezvousErrorCode.None)
+        {
+            return version;
+        }
+
+        return !ContractValidation.IsIdempotencyKeyValid(request.IdempotencyKey)
+            || string.IsNullOrEmpty(request.GameId.Value)
+            || string.IsNullOrEmpty(request.EnvironmentId.Value)
+            || string.IsNullOrEmpty(request.RegionId.Value)
+            || request.ProtocolVersion == 0
+            || !ContractValidation.IsBuildVersionValid(request.BuildVersion)
+            || !ContractValidation.IsDisplayNameValid(request.DisplayName)
+            || !Enum.IsDefined(request.Visibility)
+            || !ContractValidation.IsCapacityValid(request.Capacity)
+            || !ContractValidation.IsMetadataValid(request.Metadata)
+            ? RendezvousErrorCode.InvalidRequest
+            : RendezvousErrorCode.None;
+    }
+
+    private static RendezvousErrorCode ValidateUpdate(UpdateSessionRequest request)
+    {
+        RendezvousErrorCode lease = ValidateLeaseRequest(request.ContractVersion, request.LeaseToken);
+        if (lease != RendezvousErrorCode.None)
+        {
+            return lease;
+        }
+
+        return !ContractValidation.IsBuildVersionValid(request.BuildVersion)
+            || !ContractValidation.IsDisplayNameValid(request.DisplayName)
+            || !ContractValidation.IsCapacityValid(request.Capacity)
+            || !ContractValidation.IsMetadataValid(request.Metadata)
+            ? RendezvousErrorCode.InvalidRequest
+            : RendezvousErrorCode.None;
+    }
+
+    private static RendezvousErrorCode ValidateLeaseRequest(int contractVersion, string leaseToken)
+    {
+        RendezvousErrorCode version = ContractValidation.ValidateContractVersion(contractVersion);
+        if (version != RendezvousErrorCode.None)
+        {
+            return version;
+        }
+
+        return ContractValidation.IsOpaqueHttpCredentialValid(leaseToken)
+            ? RendezvousErrorCode.None
+            : RendezvousErrorCode.InvalidRequest;
+    }
+
+    private static RendezvousErrorCode MapAuthorization(PublisherAuthorizationError error) => error switch
+    {
+        PublisherAuthorizationError.PrincipalExpired => RendezvousErrorCode.AuthenticationRequired,
+        PublisherAuthorizationError.ProtocolNotAllowed => RendezvousErrorCode.IncompatibleProtocol,
+        PublisherAuthorizationError.RegionNotAllowed
+            or PublisherAuthorizationError.VisibilityNotAllowed
+            or PublisherAuthorizationError.AnonymousMustBeUnlisted
+            or PublisherAuthorizationError.MetadataNotAllowed => RendezvousErrorCode.InvalidRequest,
+        _ => RendezvousErrorCode.Forbidden,
+    };
+
+    private static string ComputeRegistrationFingerprint(RegisterSessionRequest request)
+    {
+        RegisterSessionRequest canonical = new()
+        {
+            ContractVersion = request.ContractVersion,
+            IdempotencyKey = request.IdempotencyKey,
+            GameId = request.GameId,
+            EnvironmentId = request.EnvironmentId,
+            RegionId = request.RegionId,
+            ProtocolVersion = request.ProtocolVersion,
+            BuildVersion = request.BuildVersion,
+            DisplayName = request.DisplayName,
+            Visibility = request.Visibility,
+            Capacity = new SessionCapacity
+            {
+                CurrentPlayers = request.Capacity.CurrentPlayers,
+                MaximumPlayers = request.Capacity.MaximumPlayers,
+            },
+            Metadata = request.Metadata
+                .OrderBy(static item => item.Key, StringComparer.Ordinal)
+                .ToDictionary(static item => item.Key, static item => item.Value, StringComparer.Ordinal),
+        };
+        byte[] encoded = JsonSerializer.SerializeToUtf8Bytes(canonical, ContractJson.Options);
+        byte[] digest = SHA256.HashData(encoded);
+        CryptographicOperations.ZeroMemory(encoded);
+        try
+        {
+            return Convert.ToBase64String(digest).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(digest);
+        }
+    }
+}

src/FinalFactory.Rendezvous.Server/State/EphemeralStateContracts.cs

@@ -0,0 +1,369 @@
+using System.Collections.Frozen;
+using System.Diagnostics;
+using System.Net;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.State;
+
+internal interface IWallClock
+{
+    DateTimeOffset UtcNow { get; }
+}
+
+internal interface IMonotonicClock
+{
+    TimeSpan Elapsed { get; }
+}
+
+internal sealed class SystemRendezvousClock : IWallClock, IMonotonicClock
+{
+    private readonly long _origin = Stopwatch.GetTimestamp();
+
+    public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
+
+    public TimeSpan Elapsed => Stopwatch.GetElapsedTime(_origin);
+}
+
+internal sealed record EphemeralStoreOptions
+{
+    public int MaxListings { get; init; } = 25_000;
+    public int MaxPresenceBindings { get; init; } = 25_000;
+    public int MaxJoinAttempts { get; init; } = 10_000;
+    public int MaxReplayEntries { get; init; } = 30_000;
+    public int MaxRevocations { get; init; } = 10_000;
+    public int MaxIdempotencyEntries { get; init; } = 35_000;
+    public TimeSpan LeaseLifetime { get; init; } = TimeSpan.FromSeconds(60);
+    public TimeSpan PresenceLifetime { get; init; } = TimeSpan.FromSeconds(20);
+    public TimeSpan JoinAttemptLifetime { get; init; } = TimeSpan.FromSeconds(30);
+    public TimeSpan ConnectionTicketLifetime { get; init; } = TimeSpan.FromSeconds(20);
+    public TimeSpan ReplayLifetime { get; init; } = TimeSpan.FromSeconds(30);
+    public TimeSpan IdempotencyLifetime { get; init; } = TimeSpan.FromMinutes(2);
+    public TimeSpan GracefulDrainLifetime { get; init; } = TimeSpan.FromSeconds(30);
+
+    public void Validate()
+    {
+        RequirePositive(MaxListings, nameof(MaxListings));
+        RequirePositive(MaxPresenceBindings, nameof(MaxPresenceBindings));
+        RequirePositive(MaxJoinAttempts, nameof(MaxJoinAttempts));
+        RequirePositive(MaxReplayEntries, nameof(MaxReplayEntries));
+        RequirePositive(MaxRevocations, nameof(MaxRevocations));
+        RequirePositive(MaxIdempotencyEntries, nameof(MaxIdempotencyEntries));
+        RequireDuration(LeaseLifetime, TimeSpan.FromSeconds(60), nameof(LeaseLifetime));
+        RequireDuration(PresenceLifetime, TimeSpan.FromSeconds(20), nameof(PresenceLifetime));
+        RequireDuration(JoinAttemptLifetime, TimeSpan.FromSeconds(30), nameof(JoinAttemptLifetime));
+        RequireDuration(ConnectionTicketLifetime, TimeSpan.FromSeconds(20), nameof(ConnectionTicketLifetime));
+        RequireDuration(ReplayLifetime, TimeSpan.FromSeconds(30), nameof(ReplayLifetime));
+        RequireDuration(IdempotencyLifetime, TimeSpan.FromMinutes(10), nameof(IdempotencyLifetime));
+        RequireDuration(GracefulDrainLifetime, TimeSpan.FromSeconds(30), nameof(GracefulDrainLifetime));
+        if (ConnectionTicketLifetime > JoinAttemptLifetime)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(ConnectionTicketLifetime),
+                "Connection tickets cannot outlive their join attempt.");
+        }
+
+        if (IdempotencyLifetime < LeaseLifetime || IdempotencyLifetime < JoinAttemptLifetime)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(IdempotencyLifetime),
+                "Idempotency retention must cover every idempotent resource lifetime.");
+        }
+    }
+
+    private static void RequirePositive(int value, string name)
+    {
+        if (value <= 0)
+        {
+            throw new ArgumentOutOfRangeException(name, "Store capacity must be positive.");
+        }
+    }
+
+    private static void RequireDuration(TimeSpan value, TimeSpan maximum, string name)
+    {
+        if (value <= TimeSpan.Zero || value > maximum)
+        {
+            throw new ArgumentOutOfRangeException(name, $"Duration must be positive and no greater than {maximum}.");
+        }
+    }
+}
+
+internal readonly record struct TenantScope(GameId GameId, EnvironmentId EnvironmentId);
+
+internal readonly struct SecretFingerprint : IEquatable<SecretFingerprint>
+{
+    private readonly string? _value;
+
+    public SecretFingerprint(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value) || value.Length > 128)
+        {
+            throw new ArgumentException("Secret fingerprints must contain 1-128 characters.", nameof(value));
+        }
+
+        _value = value;
+    }
+
+    public bool IsValid => !string.IsNullOrWhiteSpace(_value) && _value.Length <= 128;
+    public bool Equals(SecretFingerprint other)
+    {
+        ReadOnlySpan<char> left = _value.AsSpan();
+        ReadOnlySpan<char> right = other._value.AsSpan();
+        if (left.Length != right.Length)
+        {
+            return false;
+        }
+
+        int difference = 0;
+        for (int index = 0; index < left.Length; index++)
+        {
+            difference |= left[index] ^ right[index];
+        }
+
+        return difference == 0;
+    }
+
+    public override bool Equals(object? obj) => obj is SecretFingerprint other && Equals(other);
+    public override int GetHashCode() => StringComparer.Ordinal.GetHashCode(_value ?? string.Empty);
+    public override string ToString() => "[REDACTED]";
+    public static bool operator ==(SecretFingerprint left, SecretFingerprint right) => left.Equals(right);
+    public static bool operator !=(SecretFingerprint left, SecretFingerprint right) => !left.Equals(right);
+}
+
+internal readonly record struct ObservedEndpoint
+{
+    public ObservedEndpoint(AddressFamilyKind addressFamily, string address, int port)
+    {
+        if (!IPAddress.TryParse(address, out IPAddress? parsed)
+            || (addressFamily == AddressFamilyKind.Ipv4 && parsed.AddressFamily != System.Net.Sockets.AddressFamily.InterNetwork)
+            || (addressFamily == AddressFamilyKind.Ipv6 && parsed.AddressFamily != System.Net.Sockets.AddressFamily.InterNetworkV6))
+        {
+            throw new ArgumentException("The address must match the declared address family.", nameof(address));
+        }
+
+        if (port is < 1 or > 65_535)
+        {
+            throw new ArgumentOutOfRangeException(nameof(port));
+        }
+
+        AddressFamily = addressFamily;
+        Address = parsed.ToString();
+        Port = port;
+    }
+
+    public AddressFamilyKind AddressFamily { get; }
+    public string Address { get; }
+    public int Port { get; }
+    public bool IsValid => !string.IsNullOrEmpty(Address)
+        && Port is >= 1 and <= 65_535
+        && AddressFamily is AddressFamilyKind.Ipv4 or AddressFamilyKind.Ipv6;
+}
+
+internal sealed record ListingDefinition
+{
+    public required SessionListingId ListingId { get; init; }
+    public required LeaseId LeaseId { get; init; }
+    public required TenantScope Scope { get; init; }
+    public required string OwnerSubject { get; init; }
+    public required RegionId RegionId { get; init; }
+    public required uint ProtocolVersion { get; init; }
+    public required string BuildVersion { get; init; }
+    public required string DisplayName { get; init; }
+    public required ListingVisibility Visibility { get; init; }
+    public required PublisherTrustMode TrustMode { get; init; }
+    public required int CurrentPlayers { get; init; }
+    public required int MaximumPlayers { get; init; }
+    public required IReadOnlyDictionary<string, string> Metadata { get; init; }
+    public required SecretFingerprint LeaseFingerprint { get; init; }
+    public required MediationHandle HostPresenceHandle { get; init; }
+    public required SecretFingerprint HostPresenceFingerprint { get; init; }
+    public required string CapabilityDerivationSalt { get; init; }
+}
+
+internal sealed record StoredListing
+{
+    public required ListingDefinition Definition { get; init; }
+    public required DateTimeOffset LeaseExpiresAt { get; init; }
+    public required long Version { get; init; }
+    public required bool HasFreshPresence { get; init; }
+
+    public static ListingDefinition Freeze(ListingDefinition source) => source with
+    {
+        Metadata = source.Metadata.ToFrozenDictionary(StringComparer.Ordinal),
+    };
+}
+
+internal sealed record CreateListingCommand(
+    string IdempotencyKey,
+    string RequestFingerprint,
+    ListingDefinition Listing,
+    int OwnerListingLimit = int.MaxValue);
+
+internal sealed record RenewLeaseCommand(
+    SessionListingId ListingId,
+    LeaseId LeaseId,
+    SecretFingerprint LeaseFingerprint,
+    string OwnerSubject,
+    long ExpectedVersion);
+
+internal sealed record UpdateListingCommand(
+    SessionListingId ListingId,
+    LeaseId LeaseId,
+    SecretFingerprint LeaseFingerprint,
+    string OwnerSubject,
+    string BuildVersion,
+    string DisplayName,
+    int CurrentPlayers,
+    int MaximumPlayers,
+    IReadOnlyDictionary<string, string> Metadata);
+
+internal sealed record DeleteListingCommand(
+    SessionListingId ListingId,
+    LeaseId LeaseId,
+    SecretFingerprint LeaseFingerprint,
+    string OwnerSubject);
+
+internal sealed record BindHostPresenceCommand(
+    MediationHandle Handle,
+    SecretFingerprint CapabilityFingerprint,
+    ObservedEndpoint PublicEndpoint,
+    ObservedEndpoint? LocalEndpoint);
+
+internal sealed record VisibleListingQuery(
+    TenantScope Scope,
+    uint ProtocolVersion,
+    RegionId? RegionId,
+    int MaximumResults = ContractLimits.BrowserPageMaxItems,
+    SessionListingId? AfterListingId = null,
+    bool ExcludeFull = false);
+
+internal enum AttemptPeerRole
+{
+    Host = 1,
+    Client = 2,
+}
+
+internal sealed record CreateJoinAttemptCommand
+{
+    public required string IdempotencyOwner { get; init; }
+    public required string IdempotencyKey { get; init; }
+    public required string RequestFingerprint { get; init; }
+    public required string ClientSubject { get; init; }
+    public required JoinAttemptId AttemptId { get; init; }
+    public required MediationHandle MediationHandle { get; init; }
+    public required TenantScope Scope { get; init; }
+    public required SessionListingId ListingId { get; init; }
+    public required uint ProtocolVersion { get; init; }
+    public required SecretFingerprint HostCapabilityFingerprint { get; init; }
+    public required SecretFingerprint ClientCapabilityFingerprint { get; init; }
+    public required SecretFingerprint ConnectionTicketFingerprint { get; init; }
+    public required string CapabilityDerivationSalt { get; init; }
+    public int ScopeAttemptLimit { get; init; } = int.MaxValue;
+
+    public override string ToString() => "[CreateJoinAttemptCommand: credentials redacted]";
+}
+
+internal sealed record AttemptEndpointBinding(
+    ObservedEndpoint PublicEndpoint,
+    ObservedEndpoint? LocalEndpoint);
+
+internal sealed record StoredJoinAttempt
+{
+    public required JoinAttemptId AttemptId { get; init; }
+    public required MediationHandle MediationHandle { get; init; }
+    public required TenantScope Scope { get; init; }
+    public required SessionListingId ListingId { get; init; }
+    public required string ClientSubject { get; init; }
+    public required uint ProtocolVersion { get; init; }
+    public required string IdempotencyKey { get; init; }
+    public required string RequestFingerprint { get; init; }
+    public required string CapabilityDerivationSalt { get; init; }
+    public required SecretFingerprint HostCapabilityFingerprint { get; init; }
+    public required SecretFingerprint ClientCapabilityFingerprint { get; init; }
+    public required SecretFingerprint ConnectionTicketFingerprint { get; init; }
+    public required DateTimeOffset ExpiresAt { get; init; }
+    public required DateTimeOffset ConnectionTicketExpiresAt { get; init; }
+    public AttemptEndpointBinding? HostEndpoint { get; init; }
+    public AttemptEndpointBinding? ClientEndpoint { get; init; }
+    public required bool IntroductionConsumed { get; init; }
+    public required bool ConnectionTicketConsumed { get; init; }
+    public required bool IsCancelled { get; init; }
+
+    public override string ToString() => $"[StoredJoinAttempt {AttemptId}; credentials redacted]";
+}
+
+internal sealed record HostJoinAttemptQuery(
+    SessionListingId ListingId,
+    SecretFingerprint LeaseFingerprint,
+    int MaximumResults,
+    JoinAttemptId? AfterAttemptId = null);
+
+internal sealed record BindAttemptEndpointCommand(
+    MediationHandle Handle,
+    AttemptPeerRole Role,
+    SecretFingerprint CapabilityFingerprint,
+    ObservedEndpoint PublicEndpoint,
+    ObservedEndpoint? LocalEndpoint);
+
+internal sealed record IntroductionEndpoints(
+    StoredJoinAttempt Attempt,
+    AttemptEndpointBinding Host,
+    AttemptEndpointBinding Client)
+{
+    public JoinAttemptId AttemptId => Attempt.AttemptId;
+}
+
+internal sealed record CancelJoinAttemptCommand(
+    JoinAttemptId AttemptId,
+    SecretFingerprint ClientCapabilityFingerprint);
+
+internal sealed record ConsumeConnectionTicketCommand(
+    JoinAttemptId AttemptId,
+    SecretFingerprint ConnectionTicketFingerprint);
+
+internal sealed record ReplayConsumption(
+    string Namespace,
+    string Key,
+    TimeSpan? Lifetime = null);
+
+internal enum StoreResultCode
+{
+    Success = 0,
+    NotFound = 1,
+    Expired = 2,
+    Revoked = 3,
+    Conflict = 4,
+    CapacityExceeded = 5,
+    Draining = 6,
+    ReplayRejected = 7,
+    ServiceUnavailable = 8,
+}
+
+internal sealed record StoreResult<T>(StoreResultCode Code, T? Value = default, bool IsIdempotentReplay = false)
+{
+    public bool Succeeded => Code == StoreResultCode.Success;
+}
+
+internal interface IEphemeralRendezvousStore
+{
+    Guid InstanceId { get; }
+    bool IsAvailable { get; }
+    bool IsDraining { get; }
+
+    StoreResult<StoredListing> CreateListing(CreateListingCommand command, CancellationToken cancellationToken = default);
+    StoreResult<StoredListing> RenewLease(RenewLeaseCommand command, CancellationToken cancellationToken = default);
+    StoreResult<StoredListing> UpdateListing(UpdateListingCommand command, CancellationToken cancellationToken = default);
+    StoreResult<bool> DeleteListing(DeleteListingCommand command, CancellationToken cancellationToken = default);
+    StoreResult<StoredListing> GetListing(SessionListingId listingId, bool requireFreshPresence, CancellationToken cancellationToken = default);
+    StoreResult<IReadOnlyList<StoredListing>> BrowseVisibleListings(VisibleListingQuery query, CancellationToken cancellationToken = default);
+    StoreResult<StoredListing> BindHostPresence(BindHostPresenceCommand command, CancellationToken cancellationToken = default);
+    StoreResult<StoredJoinAttempt> CreateJoinAttempt(CreateJoinAttemptCommand command, CancellationToken cancellationToken = default);
+    StoreResult<IReadOnlyList<StoredJoinAttempt>> BrowseHostJoinAttempts(HostJoinAttemptQuery query, CancellationToken cancellationToken = default);
+    StoreResult<bool> CancelJoinAttempt(CancelJoinAttemptCommand command, CancellationToken cancellationToken = default);
+    StoreResult<StoredJoinAttempt> BindAttemptEndpoint(BindAttemptEndpointCommand command, CancellationToken cancellationToken = default);
+    StoreResult<IntroductionEndpoints> ConsumeIntroduction(MediationHandle handle, CancellationToken cancellationToken = default);
+    StoreResult<bool> ConsumeConnectionTicket(ConsumeConnectionTicketCommand command, CancellationToken cancellationToken = default);
+    StoreResult<bool> ConsumeReplay(ReplayConsumption consumption, CancellationToken cancellationToken = default);
+    StoreResult<bool> RevokeListing(SessionListingId listingId, CancellationToken cancellationToken = default);
+    StoreResult<int> RevokePrincipal(string subject, TimeSpan lifetime, CancellationToken cancellationToken = default);
+    void BeginDrain(CancellationToken cancellationToken = default);
+}

src/FinalFactory.Rendezvous.Server/State/StoreResultMapping.cs

@@ -0,0 +1,20 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.State;
+
+internal static class StoreResultMapping
+{
+    public static RendezvousErrorCode ToContractError(this StoreResultCode code) => code switch
+    {
+        StoreResultCode.Success => RendezvousErrorCode.None,
+        StoreResultCode.NotFound => RendezvousErrorCode.NotFound,
+        StoreResultCode.Expired => RendezvousErrorCode.Expired,
+        StoreResultCode.Revoked => RendezvousErrorCode.Forbidden,
+        StoreResultCode.Conflict => RendezvousErrorCode.Conflict,
+        StoreResultCode.CapacityExceeded => RendezvousErrorCode.CapacityExceeded,
+        StoreResultCode.ReplayRejected => RendezvousErrorCode.ReplayRejected,
+        StoreResultCode.Draining or StoreResultCode.ServiceUnavailable =>
+            RendezvousErrorCode.ServiceUnavailable,
+        _ => RendezvousErrorCode.InternalError,
+    };
+}

src/FinalFactory.Rendezvous.Server/Transport/LiteNetNatRequestCodec.cs

@@ -0,0 +1,73 @@
+using System.Buffers.Binary;
+using System.Net;
+using System.Text;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Server.Transport;
+
+internal static class LiteNetNatRequestCodec
+{
+    private const byte NatMessageProperty = 17;
+    private const int TypeIdentifierLength = 8;
+    private const int TokenLengthPrefix = NatPunchRequestTokenCodec.EncodedLength + 1;
+    // LiteNetLib 2.1.4's private NatIntroduceRequest type ID. The native socket
+    // integration test deliberately fails if a package upgrade changes this wire value.
+    private static ReadOnlySpan<byte> RequestTypeIdentifier =>
+        [0x88, 0xbe, 0x10, 0x26, 0xbf, 0xb1, 0x66, 0x9c];
+
+    public static bool TryDecode(
+        ReadOnlySpan<byte> datagram,
+        out IPEndPoint? claimedLocalEndpoint,
+        out string? token)
+    {
+        claimedLocalEndpoint = null;
+        token = null;
+        if (datagram.Length < 1 + TypeIdentifierLength + 1 + 4 + 2 + 2
+            + NatPunchRequestTokenCodec.EncodedLength
+            || datagram[0] != NatMessageProperty
+            || !datagram.Slice(1, TypeIdentifierLength).SequenceEqual(RequestTypeIdentifier))
+        {
+            return false;
+        }
+
+        int offset = 1 + TypeIdentifierLength;
+        int addressLength = datagram[offset++] switch
+        {
+            0 => 4,
+            1 => 16,
+            _ => 0,
+        };
+        int expectedLength = offset + addressLength + 2 + 2
+            + NatPunchRequestTokenCodec.EncodedLength;
+        if (addressLength == 0 || datagram.Length != expectedLength)
+        {
+            return false;
+        }
+
+        IPAddress localAddress = new(datagram.Slice(offset, addressLength));
+        offset += addressLength;
+        int localPort = BinaryPrimitives.ReadUInt16LittleEndian(datagram.Slice(offset, 2));
+        offset += 2;
+        int encodedTokenLength = BinaryPrimitives.ReadUInt16LittleEndian(datagram.Slice(offset, 2));
+        offset += 2;
+        if (localPort == 0 || encodedTokenLength != TokenLengthPrefix)
+        {
+            return false;
+        }
+
+        ReadOnlySpan<byte> tokenBytes = datagram.Slice(
+            offset,
+            NatPunchRequestTokenCodec.EncodedLength);
+        for (int index = 0; index < tokenBytes.Length; index++)
+        {
+            if (tokenBytes[index] > 0x7f)
+            {
+                return false;
+            }
+        }
+
+        claimedLocalEndpoint = new(localAddress, localPort);
+        token = Encoding.ASCII.GetString(tokenBytes);
+        return true;
+    }
+}

src/FinalFactory.Rendezvous.Server/Transport/NatMediationProcessor.cs

@@ -0,0 +1,328 @@
+using System.Net;
+using System.Net.Sockets;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.JoinAttempts;
+using FinalFactory.Rendezvous.Server.Sessions;
+using FinalFactory.Rendezvous.Server.State;
+
+namespace FinalFactory.Rendezvous.Server.Transport;
+
+internal interface INatIntroductionSink
+{
+    void Introduce(NatIntroductionPlan plan);
+}
+
+internal sealed record NatIntroductionPlan(
+    IPEndPoint HostLocal,
+    IPEndPoint HostPublic,
+    IPEndPoint ClientLocal,
+    IPEndPoint ClientPublic,
+    string IntroductionToken)
+{
+    public override string ToString() => "[NatIntroductionPlan: endpoints and ticket redacted]";
+}
+
+internal enum NatMediationResult
+{
+    Dropped = 0,
+    HostPresenceAccepted = 1,
+    HostPresenceRejected = 2,
+    WaitingForPeer = 3,
+    Introduced = 4,
+    Duplicate = 5,
+    Rejected = 6,
+}
+
+internal sealed class NatMediationProcessor(
+    IEphemeralRendezvousStore store,
+    ISessionCapabilityService capabilities,
+    JoinAttemptService joinAttempts)
+{
+    public NatMediationResult ProcessDatagram(
+        ReadOnlySpan<byte> encoded,
+        IPEndPoint observedPublicEndpoint,
+        INatIntroductionSink introductionSink,
+        CancellationToken cancellationToken = default)
+    {
+        if (!RendezvousUdpCodec.TryDecode(encoded, out PresenceDatagram? datagram, out _)
+            || datagram is null
+            || datagram.Capability.Length != ContractLimits.DerivedCredentialCharacters
+            || !IPAddress.TryParse(datagram.LocalAddress, out IPAddress? localAddress))
+        {
+            return NatMediationResult.Dropped;
+        }
+
+        IPEndPoint claimedLocalEndpoint = new(localAddress, datagram.LocalPort);
+        NatPunchPeerRole role = datagram.MessageType == UdpPresenceMessageType.ClientPresence
+            ? NatPunchPeerRole.Client
+            : NatPunchPeerRole.HostPresence;
+        bool observedIpv6 = observedPublicEndpoint.AddressFamily == AddressFamily.InterNetworkV6
+            && !observedPublicEndpoint.Address.IsIPv4MappedToIPv6;
+        if (role == NatPunchPeerRole.Client && observedIpv6)
+        {
+            return NatMediationResult.Dropped;
+        }
+
+        NatMediationResult result = ProcessRequest(
+            claimedLocalEndpoint,
+            observedPublicEndpoint,
+            NatPunchRequestTokenCodec.Encode(role, datagram.MediationHandle, datagram.Capability),
+            introductionSink,
+            cancellationToken);
+        if (role != NatPunchPeerRole.HostPresence
+            || result != NatMediationResult.HostPresenceRejected
+            || observedIpv6)
+        {
+            return result;
+        }
+
+        return ProcessRequest(
+            claimedLocalEndpoint,
+            observedPublicEndpoint,
+            NatPunchRequestTokenCodec.Encode(
+                NatPunchPeerRole.Host,
+                datagram.MediationHandle,
+                datagram.Capability),
+            introductionSink,
+            cancellationToken);
+    }
+
+    public NatMediationResult ProcessRequest(
+        IPEndPoint claimedLocalEndpoint,
+        IPEndPoint observedPublicEndpoint,
+        string token,
+        INatIntroductionSink introductionSink,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(claimedLocalEndpoint);
+        ArgumentNullException.ThrowIfNull(observedPublicEndpoint);
+        ArgumentNullException.ThrowIfNull(introductionSink);
+
+        if (!NatPunchRequestTokenCodec.TryDecode(token, out NatPunchRequestToken? request)
+            || request is null
+            || !TryCreateObservedEndpoint(observedPublicEndpoint, out ObservedEndpoint publicEndpoint)
+            || !capabilities.TryFingerprint(request.Capability, out SecretFingerprint fingerprint))
+        {
+            return NatMediationResult.Dropped;
+        }
+
+        ObservedEndpoint? localEndpoint = TryCreatePrivateCandidate(
+            claimedLocalEndpoint,
+            publicEndpoint.AddressFamily,
+            out ObservedEndpoint candidate)
+            ? candidate
+            : null;
+
+        if (request.Role == NatPunchPeerRole.HostPresence)
+        {
+            StoreResult<StoredListing> presence = store.BindHostPresence(new(
+                request.MediationHandle,
+                fingerprint,
+                publicEndpoint,
+                localEndpoint), cancellationToken);
+            return presence.Succeeded
+                ? NatMediationResult.HostPresenceAccepted
+                : NatMediationResult.HostPresenceRejected;
+        }
+
+        AttemptPeerRole role = request.Role switch
+        {
+            NatPunchPeerRole.Host => AttemptPeerRole.Host,
+            NatPunchPeerRole.Client => AttemptPeerRole.Client,
+            _ => default,
+        };
+        if (role == default)
+        {
+            return NatMediationResult.Dropped;
+        }
+
+        StoreResult<StoredJoinAttempt> bound = store.BindAttemptEndpoint(new(
+            request.MediationHandle,
+            role,
+            fingerprint,
+            publicEndpoint,
+            localEndpoint), cancellationToken);
+        if (!bound.Succeeded || bound.Value is null)
+        {
+            return bound.Code == StoreResultCode.ReplayRejected
+                ? NatMediationResult.Rejected
+                : NatMediationResult.Dropped;
+        }
+
+        StoredJoinAttempt attempt = bound.Value;
+        if (attempt.IntroductionConsumed)
+        {
+            return NatMediationResult.Duplicate;
+        }
+
+        if (attempt.HostEndpoint is null || attempt.ClientEndpoint is null)
+        {
+            return NatMediationResult.WaitingForPeer;
+        }
+
+        if (attempt.HostEndpoint.PublicEndpoint.AddressFamily
+            != attempt.ClientEndpoint.PublicEndpoint.AddressFamily)
+        {
+            return NatMediationResult.Rejected;
+        }
+
+        StoreResult<IntroductionEndpoints> consumed = store.ConsumeIntroduction(
+            request.MediationHandle,
+            cancellationToken);
+        if (!consumed.Succeeded || consumed.Value is null)
+        {
+            return consumed.Code == StoreResultCode.ReplayRejected
+                ? NatMediationResult.Duplicate
+                : NatMediationResult.Rejected;
+        }
+
+        JoinAttemptServiceResult<ConnectionTicketGrant> ticket = joinAttempts.IssueConnectionTicket(
+            consumed.Value.Attempt);
+        if (!ticket.Succeeded || ticket.Value is null)
+        {
+            return NatMediationResult.Rejected;
+        }
+
+        try
+        {
+            introductionSink.Introduce(CreatePlan(consumed.Value, ticket.Value));
+            return NatMediationResult.Introduced;
+        }
+        catch (Exception exception) when (exception is SocketException
+                                          or InvalidOperationException
+                                          or ArgumentException)
+        {
+            return NatMediationResult.Rejected;
+        }
+    }
+
+    private static NatIntroductionPlan CreatePlan(
+        IntroductionEndpoints endpoints,
+        ConnectionTicketGrant ticket)
+    {
+        IPEndPoint hostPublic = ToIpEndpoint(endpoints.Host.PublicEndpoint);
+        IPEndPoint clientPublic = ToIpEndpoint(endpoints.Client.PublicEndpoint);
+        bool sameNat = hostPublic.Address.Equals(clientPublic.Address);
+        IPEndPoint hostLocal = sameNat && endpoints.Host.LocalEndpoint is { } hostCandidate
+            ? ToIpEndpoint(hostCandidate)
+            : hostPublic;
+        IPEndPoint clientLocal = sameNat && endpoints.Client.LocalEndpoint is { } clientCandidate
+            ? ToIpEndpoint(clientCandidate)
+            : clientPublic;
+        return new(
+            hostLocal,
+            hostPublic,
+            clientLocal,
+            clientPublic,
+            ticket.Ticket);
+    }
+
+    private static bool TryCreateObservedEndpoint(
+        IPEndPoint source,
+        out ObservedEndpoint endpoint)
+    {
+        endpoint = default;
+        if (source.Port is < 1 or > 65_535)
+        {
+            return false;
+        }
+
+        IPAddress address = source.Address.IsIPv4MappedToIPv6
+            ? source.Address.MapToIPv4()
+            : source.Address;
+        if (address.Equals(IPAddress.Any)
+            || address.Equals(IPAddress.IPv6Any)
+            || address.IsIPv6Multicast
+            || IsIpv4MulticastOrBroadcast(address)
+            || (address.AddressFamily == AddressFamily.InterNetworkV6
+                && !IsGlobalIpv6(address)))
+        {
+            return false;
+        }
+
+        AddressFamilyKind family = address.AddressFamily switch
+        {
+            AddressFamily.InterNetwork => AddressFamilyKind.Ipv4,
+            AddressFamily.InterNetworkV6 => AddressFamilyKind.Ipv6,
+            _ => default,
+        };
+        if (family == default)
+        {
+            return false;
+        }
+
+        endpoint = new(family, address.ToString(), source.Port);
+        return true;
+    }
+
+    private static bool TryCreatePrivateCandidate(
+        IPEndPoint source,
+        AddressFamilyKind publicFamily,
+        out ObservedEndpoint endpoint)
+    {
+        endpoint = default;
+        if (source.Port is < 1 or > 65_535)
+        {
+            return false;
+        }
+
+        IPAddress address = source.Address.IsIPv4MappedToIPv6
+            ? source.Address.MapToIPv4()
+            : source.Address;
+        AddressFamilyKind family = address.AddressFamily switch
+        {
+            AddressFamily.InterNetwork => AddressFamilyKind.Ipv4,
+            AddressFamily.InterNetworkV6 => AddressFamilyKind.Ipv6,
+            _ => default,
+        };
+        if (family != publicFamily || !IsPrivateUnicast(address))
+        {
+            return false;
+        }
+
+        endpoint = new(family, address.ToString(), source.Port);
+        return true;
+    }
+
+    private static bool IsPrivateUnicast(IPAddress address)
+    {
+        byte[] bytes = address.GetAddressBytes();
+        return address.AddressFamily switch
+        {
+            AddressFamily.InterNetwork => bytes[0] == 10
+                || (bytes[0] == 172 && bytes[1] is >= 16 and <= 31)
+                || (bytes[0] == 192 && bytes[1] == 168),
+            AddressFamily.InterNetworkV6 => (bytes[0] & 0xfe) == 0xfc,
+            _ => false,
+        };
+    }
+
+    private static bool IsGlobalIpv6(IPAddress address) =>
+        !address.Equals(IPAddress.IPv6Loopback)
+        && !address.Equals(IPAddress.IPv6Any)
+        && !address.IsIPv6LinkLocal
+        && !address.IsIPv6Multicast
+        && !address.IsIPv6SiteLocal
+        && !IsPrivateUnicast(address)
+        && !IsDocumentationIpv6(address);
+
+    private static bool IsIpv4MulticastOrBroadcast(IPAddress address)
+    {
+        if (address.AddressFamily != AddressFamily.InterNetwork)
+        {
+            return false;
+        }
+
+        byte[] bytes = address.GetAddressBytes();
+        return bytes[0] >= 224 || bytes.All(static value => value == byte.MaxValue);
+    }
+
+    private static bool IsDocumentationIpv6(IPAddress address)
+    {
+        byte[] bytes = address.GetAddressBytes();
+        return bytes[0] == 0x20 && bytes[1] == 0x01 && bytes[2] == 0x0d && bytes[3] == 0xb8;
+    }
+
+    private static IPEndPoint ToIpEndpoint(ObservedEndpoint endpoint) =>
+        new(IPAddress.Parse(endpoint.Address), endpoint.Port);
+}

src/FinalFactory.Rendezvous.Server/Transport/UdpMediatorOptions.cs

@@ -18,9 +18,17 @@ public sealed class UdpMediatorOptions
     [Required]
     public string ListenAddress { get; set; } = "0.0.0.0";
 
+    public string? Ipv6ListenAddress { get; set; }
+
     /// <summary>
     /// Gets or sets the UDP port. Zero requests an ephemeral port for tests.
     /// </summary>
     [Range(0, 65_535)]
     public int Port { get; set; } = 9050;
+
+    [Range(1, 4_096)]
+    public int MaxDatagramsPerPoll { get; set; } = 256;
+
+    [Range(1, 100)]
+    public int PollIntervalMilliseconds { get; set; } = 2;
 }

src/FinalFactory.Rendezvous.Server/Transport/UdpMediatorService.cs

@@ -1,104 +1,138 @@
+using System.Diagnostics;
 using System.Net;
 using System.Net.Sockets;
+using FinalFactory.Rendezvous.Contracts;
+using LiteNetLib;
+using LiteNetLib.Layers;
 using Microsoft.Extensions.Options;
 
 namespace FinalFactory.Rendezvous.Server.Transport;
 
-/// <summary>
-/// Owns the cancellable UDP socket used by the future NAT mediator.
-/// </summary>
-public sealed partial class UdpMediatorService : BackgroundService
+internal sealed partial class UdpMediatorService : BackgroundService
 {
     private readonly ILogger<UdpMediatorService> _logger;
     private readonly UdpMediatorOptions _options;
-    private UdpClient? _udpClient;
+    private readonly NatMediationProcessor _processor;
+    private LiteNetManager? _manager;
+    private LiteNetIntroductionSink? _introductionSink;
 
-    /// <summary>
-    /// Initializes a new UDP mediator service.
-    /// </summary>
     public UdpMediatorService(
         IOptions<UdpMediatorOptions> options,
-        ILogger<UdpMediatorService> logger)
+        ILogger<UdpMediatorService> logger,
+        NatMediationProcessor processor)
     {
         _options = options.Value;
         _logger = logger;
+        _processor = processor;
     }
 
-    /// <summary>
-    /// Gets the bound endpoint after startup completes.
-    /// </summary>
     public IPEndPoint? LocalEndpoint { get; private set; }
+    public IPEndPoint? LocalIpv6Endpoint { get; private set; }
 
-    /// <inheritdoc />
     public override Task StartAsync(CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
-
-        if (_udpClient is not null)
+        if (_manager is not null)
         {
             throw new InvalidOperationException("The UDP mediator is already running.");
         }
 
         IPAddress listenAddress = IPAddress.Parse(_options.ListenAddress);
-        UdpClient udpClient = new(new IPEndPoint(listenAddress, _options.Port));
-        _udpClient = udpClient;
-        IPEndPoint localEndpoint =
-            (IPEndPoint?)udpClient.Client.LocalEndPoint
-            ?? throw new InvalidOperationException("The UDP socket did not expose its bound endpoint.");
-        LocalEndpoint = localEndpoint;
+        if (listenAddress.AddressFamily != AddressFamily.InterNetwork)
+        {
+            throw new InvalidOperationException("The required UDP listen address must be IPv4.");
+        }
 
-        LogMediatorListening(_logger, localEndpoint.Address, localEndpoint.Port);
+        IPAddress? ipv6ListenAddress = string.IsNullOrWhiteSpace(_options.Ipv6ListenAddress)
+            ? null
+            : IPAddress.Parse(_options.Ipv6ListenAddress);
+        if (ipv6ListenAddress is not null
+            && ipv6ListenAddress.AddressFamily != AddressFamily.InterNetworkV6)
+        {
+            throw new InvalidOperationException("The optional UDP IPv6 listen address must be IPv6.");
+        }
 
+        EventBasedLiteNetListener listener = new();
+        RendezvousPacketLayer packetLayer = new(_processor);
+        LiteNetManager manager = new(listener, packetLayer)
+        {
+            NatPunchEnabled = true,
+            IPv6Enabled = ipv6ListenAddress is not null,
+            UnsyncedEvents = true,
+            MaxPacketPerManualReceive = _options.MaxDatagramsPerPoll,
+        };
+        manager.NatPunchModule.UnsyncedEvents = true;
+        _introductionSink = new(manager.NatPunchModule);
+        packetLayer.Attach(_introductionSink);
+
+        if (!manager.StartInManualMode(
+                listenAddress,
+                ipv6ListenAddress ?? IPAddress.IPv6Any,
+                _options.Port))
+        {
+            _introductionSink = null;
+            manager.Stop();
+            throw new InvalidOperationException("The UDP mediator could not bind its LiteNetLib socket.");
+        }
+
+        _manager = manager;
+        LocalEndpoint = new(listenAddress, manager.LocalPort);
+        LocalIpv6Endpoint = ipv6ListenAddress is null
+            ? null
+            : new(ipv6ListenAddress, manager.LocalPort);
+        LogMediatorListening(_logger, listenAddress, manager.LocalPort);
         return base.StartAsync(cancellationToken);
     }
 
-    /// <inheritdoc />
     public override async Task StopAsync(CancellationToken cancellationToken)
     {
         await base.StopAsync(cancellationToken).ConfigureAwait(false);
-        _udpClient?.Dispose();
-        _udpClient = null;
-        LocalEndpoint = null;
+        StopManager();
         LogMediatorStopped(_logger);
     }
 
-    /// <inheritdoc />
     public override void Dispose()
     {
-        _udpClient?.Dispose();
-        _udpClient = null;
-        LocalEndpoint = null;
+        StopManager();
         base.Dispose();
     }
 
-    /// <inheritdoc />
     protected override async Task ExecuteAsync(CancellationToken stoppingToken)
     {
-        UdpClient udpClient = _udpClient
+        LiteNetManager manager = _manager
             ?? throw new InvalidOperationException("The UDP mediator socket was not initialized.");
-
+        long previous = Stopwatch.GetTimestamp();
         try
         {
             while (!stoppingToken.IsCancellationRequested)
             {
-                _ = await udpClient.ReceiveAsync(stoppingToken).ConfigureAwait(false);
-                // Bootstrap deliberately emits no UDP response. Protocol handling lands in #11.
+                manager.PollEvents();
+                manager.NatPunchModule.PollEvents();
+                long current = Stopwatch.GetTimestamp();
+                manager.ManualUpdate((float)Stopwatch.GetElapsedTime(previous, current).TotalMilliseconds);
+                previous = current;
+                await Task.Delay(_options.PollIntervalMilliseconds, stoppingToken).ConfigureAwait(false);
             }
         }
         catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
         {
-            // Expected during normal shutdown.
-        }
-        catch (ObjectDisposedException) when (stoppingToken.IsCancellationRequested)
-        {
-            // Disposing the socket is the fallback that releases a blocked receive.
         }
         finally
         {
             LocalEndpoint = null;
+            LocalIpv6Endpoint = null;
         }
     }
 
+    private void StopManager()
+    {
+        LiteNetManager? manager = Interlocked.Exchange(ref _manager, null);
+        _introductionSink = null;
+        LocalEndpoint = null;
+        LocalIpv6Endpoint = null;
+        manager?.Stop();
+    }
+
     [LoggerMessage(
         EventId = 1,
         Level = LogLevel.Information,
@@ -113,4 +147,62 @@ public sealed partial class UdpMediatorService : BackgroundService
         Level = LogLevel.Information,
         Message = "UDP mediator stopped")]
     private static partial void LogMediatorStopped(ILogger logger);
+
+    private sealed class LiteNetIntroductionSink(NatPunchModule module) : INatIntroductionSink
+    {
+        public void Introduce(NatIntroductionPlan plan) => module.NatIntroduce(
+            plan.HostLocal,
+            plan.HostPublic,
+            plan.ClientLocal,
+            plan.ClientPublic,
+            plan.IntroductionToken);
+    }
+
+    private sealed class RendezvousPacketLayer(NatMediationProcessor processor) : PacketLayerBase(0)
+    {
+        private INatIntroductionSink? _sink;
+
+        public void Attach(INatIntroductionSink sink) => _sink = sink;
+
+        public override void ProcessInboundPacket(
+            ref IPEndPoint endPoint,
+            ref byte[] data,
+            ref int length)
+        {
+            bool isFrozenEnvelope = length >= 2
+                && data[0] == RendezvousUdpCodec.MagicFirst
+                && data[1] == RendezvousUdpCodec.MagicSecond;
+            INatIntroductionSink? sink = _sink;
+            if (isFrozenEnvelope)
+            {
+                if (sink is not null)
+                {
+                    _ = processor.ProcessDatagram(data.AsSpan(0, length), endPoint, sink);
+                }
+            }
+            else if (sink is not null
+                     && LiteNetNatRequestCodec.TryDecode(
+                         data.AsSpan(0, length),
+                         out IPEndPoint? claimedLocalEndpoint,
+                         out string? token)
+                     && claimedLocalEndpoint is not null
+                     && token is not null)
+            {
+                _ = processor.ProcessRequest(claimedLocalEndpoint, endPoint, token, sink);
+            }
+
+            // Every inbound packet is consumed here. NatPunchModule is used only for outbound introductions.
+            Drop(ref length);
+        }
+
+        public override void ProcessOutBoundPacket(
+            ref IPEndPoint endPoint,
+            ref byte[] data,
+            ref int offset,
+            ref int length)
+        {
+        }
+
+        private static void Drop(ref int length) => length = 0;
+    }
 }

src/FinalFactory.Rendezvous.Server/appsettings.Development.json

@@ -0,0 +1,43 @@
+{
+  "Rendezvous": {
+    "Provisioning": {
+      "Issuer": "final-factory-rendezvous-development",
+      "Audience": "final-factory-rendezvous",
+      "ClockSkewSeconds": 30,
+      "SigningKeys": [
+        {
+          "KeyId": "development-ephemeral-1",
+          "SecretReference": "development:ephemeral/rendezvous-signing",
+          "CredentialKinds": ["DedicatedPublisher", "PlayerHostGrant"],
+          "GameId": "space-game",
+          "EnvironmentId": "development",
+          "NotBefore": "2025-01-01T00:00:00Z",
+          "SignUntil": "2035-01-01T00:00:00Z",
+          "VerifyUntil": "2035-01-02T00:00:00Z"
+        }
+      ],
+      "Games": [
+        {
+          "GameId": "space-game",
+          "EnvironmentId": "development",
+          "Enabled": true,
+          "ProtocolVersions": [1],
+          "Regions": ["local"],
+          "VisibilityModes": ["Public", "Unlisted"],
+          "PublisherTrustModes": ["ManagedDedicated", "PlayerGrant", "AnonymousUnlisted"],
+          "MetadataValueMaxBytes": {
+            "map": 64,
+            "mode": 32
+          },
+          "RequiredMetadataKeys": [],
+          "MetadataMaxBytes": 512,
+          "MetadataMaxKeys": 2,
+          "MaxListingsPerPrincipal": 10,
+          "MaxAnonymousListingsPerAddress": 1,
+          "MaxActiveJoinAttempts": 100,
+          "FallbackPolicy": "Disabled"
+        }
+      ]
+    }
+  }
+}

src/FinalFactory.Rendezvous.Server/appsettings.json

@@ -2,7 +2,9 @@
   "Rendezvous": {
     "Udp": {
       "ListenAddress": "0.0.0.0",
-      "Port": 9050
+      "Port": 9050,
+      "MaxDatagramsPerPoll": 256,
+      "PollIntervalMilliseconds": 2
     }
   },
   "Logging": {

src/FinalFactory.Rendezvous.Server/packages.lock.json

@@ -8,8 +8,29 @@
         "resolved": "2.1.4",
         "contentHash": "KWlxvMw3Urpqj9joD96LRiK+LC62pQNs/zkXRJc+rHnxgkGp+vV703xzDrxRmv+V1YhCFfIGzs5nrVWtREIlyA=="
       },
+      "Microsoft.AspNetCore.OpenApi": {
+        "type": "Direct",
+        "requested": "[10.0.9, )",
+        "resolved": "10.0.9",
+        "contentHash": "1ihb8FO9cGgEK1/m3CTtT/SfnynwmiZib0W2pcDVj3KSWk/Sca4VOXEtaptKQc582zpFrzTFiwkGRCglt6H+WQ==",
+        "dependencies": {
+          "Microsoft.OpenApi": "2.0.0"
+        }
+      },
+      "Microsoft.Extensions.ApiDescription.Server": {
+        "type": "Direct",
+        "requested": "[10.0.9, )",
+        "resolved": "10.0.9",
+        "contentHash": "n1m7EAbCbHMGiTy++F+mLSan4MrZe0t00XEpJrkai6BFpB6lwEcirflI9FiMm4G4u55h/2RnWToYBDwS+MnN6g=="
+      },
       "finalfactory.rendezvous.contracts": {
         "type": "Project"
+      },
+      "Microsoft.OpenApi": {
+        "type": "CentralTransitive",
+        "requested": "[2.7.5, )",
+        "resolved": "2.7.5",
+        "contentHash": "0FA67RSnRM4tcBKqiqVu/HPdZ9+QOKbmeRjxRUGTCjPU4C0bmUhd97Dso7Yild5P7nOV6GxJ2xrK0Kv/O9xp0w=="
       }
     }
   }

src/FinalFactory.Rendezvous.TestClient/packages.lock.json

@@ -8,6 +8,16 @@
         "resolved": "2.1.4",
         "contentHash": "KWlxvMw3Urpqj9joD96LRiK+LC62pQNs/zkXRJc+rHnxgkGp+vV703xzDrxRmv+V1YhCFfIGzs5nrVWtREIlyA=="
       },
+      "System.IO.Pipelines": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "7WX0W96y3dpQdYG4sEGdh38g3/0lOD4/dKbn2rRVOVzKhzoZUn2gKNIKaFeKWs8RCbpFfmmEWsRhSy95hMpvqA=="
+      },
+      "System.Text.Encodings.Web": {
+        "type": "Transitive",
+        "resolved": "10.0.10",
+        "contentHash": "o16m2YpDN/pjHsnxf9pTGwkpcuvjW8v1/wGUwJtM1c3QZUKm7ZEO/eYRJg7iIx6GxS2Zv9lAMHpiQwHDdgqauA=="
+      },
       "finalfactory.rendezvous.client": {
         "type": "Project",
         "dependencies": {
@@ -16,7 +26,20 @@
         }
       },
       "finalfactory.rendezvous.contracts": {
-        "type": "Project"
+        "type": "Project",
+        "dependencies": {
+          "System.Text.Json": "[10.0.10, )"
+        }
+      },
+      "System.Text.Json": {
+        "type": "CentralTransitive",
+        "requested": "[10.0.10, )",
+        "resolved": "10.0.10",
+        "contentHash": "bmsO6UdYtBdtn32zYXfsh7KlyTIzV/3V9hdT9RIb4pXKgYOsNxXR+VbWigNwBtNFVGYGm6Hwmqw5a+/IWFd36Q==",
+        "dependencies": {
+          "System.IO.Pipelines": "10.0.10",
+          "System.Text.Encodings.Web": "10.0.10"
+        }
       }
     }
   }

tests/FinalFactory.Rendezvous.Tests/Architecture/DependencyBoundaryTests.cs

@@ -39,7 +39,7 @@ public sealed class DependencyBoundaryTests
         AssertDeclaredDependencies(
             "src/FinalFactory.Rendezvous.Contracts/FinalFactory.Rendezvous.Contracts.csproj",
             [],
-            []);
+            ["System.Text.Json"]);
         AssertDeclaredDependencies(
             "src/FinalFactory.Rendezvous.Client/FinalFactory.Rendezvous.Client.csproj",
             ["FinalFactory.Rendezvous.Contracts"],
@@ -47,7 +47,11 @@ public sealed class DependencyBoundaryTests
         AssertDeclaredDependencies(
             "src/FinalFactory.Rendezvous.Server/FinalFactory.Rendezvous.Server.csproj",
             ["FinalFactory.Rendezvous.Contracts"],
-            ["LiteNetLib"]);
+            [
+                "LiteNetLib",
+                "Microsoft.AspNetCore.OpenApi",
+                "Microsoft.Extensions.ApiDescription.Server",
+            ]);
         AssertDeclaredDependencies(
             "src/FinalFactory.Rendezvous.TestClient/FinalFactory.Rendezvous.TestClient.csproj",
             ["FinalFactory.Rendezvous.Client", "FinalFactory.Rendezvous.Contracts"],

tests/FinalFactory.Rendezvous.Tests/Browser/SessionBrowserServiceTests.cs

@@ -0,0 +1,153 @@
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Browser;
+using FinalFactory.Rendezvous.Server.State;
+
+namespace FinalFactory.Rendezvous.Tests.Browser;
+
+public sealed class SessionBrowserServiceTests
+{
+    [Fact]
+    public void ListEnforcesTenantProtocolPresenceVisibilityAndAvailabilityFilters()
+    {
+        using SessionBrowserFixture fixture = new();
+        StoredListing eligible = fixture.Add();
+        fixture.Add(scope: new(new("other-game"), fixture.Scope.EnvironmentId));
+        fixture.Add(scope: new(fixture.Scope.GameId, new("other-env")));
+        fixture.Add(protocolVersion: 8);
+        fixture.Add(regionId: new("us-east"));
+        fixture.Add(visibility: ListingVisibility.Unlisted);
+        fixture.Add(fresh: false);
+        fixture.Add(currentPlayers: 8, maximumPlayers: 8);
+        BrowseSessionsRequest request = fixture.Request();
+        request.ExcludeFull = true;
+
+        BrowserServiceResult<BrowseSessionsResponse> result = fixture.Browser.Browse(request);
+
+        Assert.True(result.Succeeded);
+        Assert.Collection(result.Value!.Items, item => Assert.Equal(eligible.Definition.ListingId, item.ListingId));
+    }
+
+    [Fact]
+    public void UnguessableIdRetrievalAllowsFreshUnlistedOnlyWithinExactScope()
+    {
+        using SessionBrowserFixture fixture = new();
+        StoredListing unlisted = fixture.Add(visibility: ListingVisibility.Unlisted);
+
+        Assert.True(fixture.Browser.Get(
+            unlisted.Definition.ListingId,
+            fixture.Scope.GameId,
+            fixture.Scope.EnvironmentId,
+            7).Succeeded);
+        Assert.Equal(RendezvousErrorCode.NotFound, fixture.Browser.Get(
+            unlisted.Definition.ListingId,
+            new("other-game"),
+            fixture.Scope.EnvironmentId,
+            7).Error);
+        Assert.Equal(RendezvousErrorCode.NotFound, fixture.Browser.Get(
+            unlisted.Definition.ListingId,
+            fixture.Scope.GameId,
+            fixture.Scope.EnvironmentId,
+            8).Error);
+        fixture.Clock.Advance(TimeSpan.FromSeconds(20));
+        Assert.Equal(RendezvousErrorCode.NotFound, fixture.Browser.Get(
+            unlisted.Definition.ListingId,
+            fixture.Scope.GameId,
+            fixture.Scope.EnvironmentId,
+            7).Error);
+    }
+
+    [Fact]
+    public void KeysetCursorReturnsStableRecordsOnceAndRejectsTamperingOrRescoping()
+    {
+        using SessionBrowserFixture fixture = new();
+        for (int index = 0; index < 7; index++)
+        {
+            fixture.Add();
+        }
+
+        BrowseSessionsRequest request = fixture.Request(pageSize: 2);
+        List<SessionListingId> seen = [];
+        do
+        {
+            BrowseSessionsResponse page = fixture.Browser.Browse(request).Value!;
+            seen.AddRange(page.Items.Select(static item => item.ListingId));
+            request.Cursor = page.NextCursor;
+        }
+        while (request.Cursor is not null);
+
+        Assert.Equal(7, seen.Count);
+        Assert.Equal(7, seen.Distinct().Count());
+        Assert.Equal(seen.OrderBy(static id => id.Value), seen);
+
+        BrowseSessionsRequest tampered = fixture.Request(pageSize: 2);
+        tampered.Cursor = fixture.Browser.Browse(tampered).Value!.NextCursor + "A";
+        Assert.Equal(RendezvousErrorCode.InvalidRequest, fixture.Browser.Browse(tampered).Error);
+        BrowseSessionsRequest rescoped = fixture.Request(pageSize: 2);
+        rescoped.Cursor = fixture.Browser.Browse(fixture.Request(pageSize: 2)).Value!.NextCursor;
+        rescoped.ExcludeFull = true;
+        Assert.Equal(RendezvousErrorCode.InvalidRequest, fixture.Browser.Browse(rescoped).Error);
+
+        BrowseSessionsRequest expired = fixture.Request(pageSize: 2);
+        expired.Cursor = fixture.Browser.Browse(expired).Value!.NextCursor;
+        fixture.Clock.Advance(TimeSpan.FromMinutes(5));
+        Assert.Equal(RendezvousErrorCode.InvalidRequest, fixture.Browser.Browse(expired).Error);
+    }
+
+    [Fact]
+    public void ResponseByteBudgetTrimsLargePagesAndContinuesWithCursor()
+    {
+        using SessionBrowserFixture fixture = new();
+        Dictionary<string, string> metadata = Enumerable.Range(0, 14).ToDictionary(
+            static index => $"key-{index}",
+            static index => new string((char)('a' + index % 26), 256),
+            EqualityComparer<string>.Default);
+        for (int index = 0; index < 100; index++)
+        {
+            fixture.Add(metadata: metadata);
+        }
+
+        BrowseSessionsResponse response = fixture.Browser.Browse(fixture.Request()).Value!;
+        int encodedBytes = JsonSerializer.SerializeToUtf8Bytes(response, ContractJson.Options).Length;
+
+        Assert.InRange(encodedBytes, 1, ContractLimits.BrowserResponseMaxBytes);
+        Assert.NotEmpty(response.Items);
+        Assert.NotNull(response.NextCursor);
+        Assert.True(response.Items.Count < 100);
+    }
+
+    [Fact]
+    public void PresentationMetadataIsJsonEscapedAndResponseHasNoConnectionSecrets()
+    {
+        using SessionBrowserFixture fixture = new();
+        fixture.Add(metadata: new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            ["mode"] = "co-op",
+            ["map"] = "<script>alert(1)</script>",
+        });
+
+        BrowseSessionsResponse response = fixture.Browser.Browse(fixture.Request()).Value!;
+        string json = JsonSerializer.Serialize(response, ContractJson.Options);
+
+        Assert.DoesNotContain("<script>", json, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("endpoint", json, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("token", json, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("capability", json, StringComparison.OrdinalIgnoreCase);
+        Assert.Equal("<script>alert(1)</script>", Assert.Single(response.Items).Metadata["map"]);
+    }
+
+    [Fact]
+    public void RevokedListingDisappearsBeforeAnotherReadPathCanObserveIt()
+    {
+        using SessionBrowserFixture fixture = new();
+        StoredListing listing = fixture.Add();
+        fixture.Store.RevokeListing(listing.Definition.ListingId);
+
+        Assert.Empty(fixture.Browser.Browse(fixture.Request()).Value!.Items);
+        Assert.Equal(RendezvousErrorCode.NotFound, fixture.Browser.Get(
+            listing.Definition.ListingId,
+            fixture.Scope.GameId,
+            fixture.Scope.EnvironmentId,
+            7).Error);
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Browser/SessionBrowserTestData.cs

@@ -0,0 +1,71 @@
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Browser;
+using FinalFactory.Rendezvous.Server.State;
+using FinalFactory.Rendezvous.Tests.State;
+
+namespace FinalFactory.Rendezvous.Tests.Browser;
+
+internal sealed class SessionBrowserFixture : IDisposable
+{
+    private readonly EphemeralStateFixture _state = new();
+
+    public SessionBrowserFixture()
+    {
+        Cursors = new();
+        Browser = new(_state.Store, Cursors, _state.Clock);
+    }
+
+    public InMemoryEphemeralRendezvousStore Store => _state.Store;
+    public ManualRendezvousClock Clock => _state.Clock;
+    public SessionBrowserCursorCodec Cursors { get; }
+    public SessionBrowserService Browser { get; }
+    public TenantScope Scope => _state.Scope;
+
+    public StoredListing Add(
+        TenantScope? scope = null,
+        uint protocolVersion = 7,
+        RegionId? regionId = null,
+        ListingVisibility visibility = ListingVisibility.Public,
+        bool fresh = true,
+        int currentPlayers = 1,
+        int maximumPlayers = 8,
+        IReadOnlyDictionary<string, string>? metadata = null)
+    {
+        CreateListingCommand seed = _state.ListingCommand();
+        CreateListingCommand command = seed with
+        {
+            Listing = seed.Listing with
+            {
+                Scope = scope ?? Scope,
+                ProtocolVersion = protocolVersion,
+                RegionId = regionId ?? seed.Listing.RegionId,
+                Visibility = visibility,
+                CurrentPlayers = currentPlayers,
+                MaximumPlayers = maximumPlayers,
+                Metadata = metadata ?? seed.Listing.Metadata,
+            },
+        };
+        StoredListing listing = Store.CreateListing(command).Value!;
+        if (fresh)
+        {
+            listing = Store.BindHostPresence(new(
+                command.Listing.HostPresenceHandle,
+                command.Listing.HostPresenceFingerprint,
+                EphemeralStateFixture.PublicEndpoint(40_000),
+                null)).Value!;
+        }
+
+        return listing;
+    }
+
+    public BrowseSessionsRequest Request(int pageSize = 100) => new()
+    {
+        GameId = Scope.GameId,
+        EnvironmentId = Scope.EnvironmentId,
+        ProtocolVersion = 7,
+        RegionId = new("eu-central"),
+        PageSize = pageSize,
+    };
+
+    public void Dispose() => Cursors.Dispose();
+}

tests/FinalFactory.Rendezvous.Tests/Client/ConnectionTicketValidatorTests.cs

@@ -0,0 +1,102 @@
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Client;
+
+public sealed class ConnectionTicketValidatorTests
+{
+    private static readonly DateTimeOffset Now = new(2026, 7, 16, 12, 0, 0, TimeSpan.Zero);
+
+    [Fact]
+    public void AuthorizedTicketIsAcceptedExactlyOnce()
+    {
+        ManualConnectionTicketClock clock = new();
+        using ConnectionTicketValidator validator = new(1_024, clock);
+        JoinAttemptId attempt = NewAttempt();
+        string ticket = Ticket('A');
+        Assert.True(validator.TryAuthorize(attempt, ticket, Now.AddSeconds(20)));
+        Assert.True(validator.TryAuthorize(attempt, ticket, Now.AddSeconds(20)));
+
+        Assert.Equal(
+            ConnectionTicketConsumptionResult.Accepted,
+            validator.Consume(attempt, ticket));
+        Assert.Equal(
+            ConnectionTicketConsumptionResult.AlreadyConsumed,
+            validator.Consume(attempt, ticket));
+    }
+
+    [Fact]
+    public void AlteredCrossAttemptExpiredAndRevokedTicketsAreRejected()
+    {
+        ManualConnectionTicketClock clock = new();
+        using ConnectionTicketValidator validator = new(1_024, clock);
+        JoinAttemptId first = NewAttempt();
+        JoinAttemptId second = NewAttempt();
+        Assert.True(validator.TryAuthorize(first, Ticket('A'), Now.AddSeconds(20)));
+        Assert.True(validator.TryAuthorize(second, Ticket('B'), Now.AddSeconds(40)));
+
+        Assert.Equal(
+            ConnectionTicketConsumptionResult.Rejected,
+            validator.Consume(first, Ticket('B')));
+        clock.Advance(TimeSpan.FromSeconds(20));
+        Assert.Equal(
+            ConnectionTicketConsumptionResult.Expired,
+            validator.Consume(first, Ticket('A')));
+        Assert.True(validator.Revoke(second));
+        Assert.Equal(
+            ConnectionTicketConsumptionResult.Revoked,
+            validator.Consume(second, Ticket('B')));
+    }
+
+    [Fact]
+    public async Task ConcurrentConsumptionHasOneWinner()
+    {
+        ManualConnectionTicketClock clock = new();
+        using ConnectionTicketValidator validator = new(1_024, clock);
+        JoinAttemptId attempt = NewAttempt();
+        string ticket = Ticket('C');
+        Assert.True(validator.TryAuthorize(attempt, ticket, Now.AddSeconds(20)));
+        using ManualResetEventSlim start = new(false);
+        Task<ConnectionTicketConsumptionResult> left = Task.Run(() =>
+        {
+            start.Wait();
+            return validator.Consume(attempt, ticket);
+        });
+        Task<ConnectionTicketConsumptionResult> right = Task.Run(() =>
+        {
+            start.Wait();
+            return validator.Consume(attempt, ticket);
+        });
+
+        start.Set();
+        ConnectionTicketConsumptionResult[] results = await Task.WhenAll(left, right);
+
+        Assert.Single(results, static result => result == ConnectionTicketConsumptionResult.Accepted);
+        Assert.Single(results, static result => result == ConnectionTicketConsumptionResult.AlreadyConsumed);
+    }
+
+    [Fact]
+    public void ValidatorIsBoundedDisposableAndRedacted()
+    {
+        ManualConnectionTicketClock clock = new();
+        ConnectionTicketValidator validator = new(1, clock);
+        Assert.True(validator.TryAuthorize(NewAttempt(), Ticket('A'), Now.AddSeconds(20)));
+        Assert.False(validator.TryAuthorize(NewAttempt(), Ticket('B'), Now.AddSeconds(20)));
+        Assert.DoesNotContain(Ticket('A'), validator.ToString(), StringComparison.Ordinal);
+
+        validator.Dispose();
+
+        Assert.Throws<ObjectDisposedException>(() => validator.Revoke(NewAttempt()));
+        Assert.Throws<ObjectDisposedException>(() => validator.Consume(default, string.Empty));
+    }
+
+    private static JoinAttemptId NewAttempt() => new(Guid.NewGuid());
+    private static string Ticket(char value) => new(value, 43);
+
+    private sealed class ManualConnectionTicketClock : IConnectionTicketClock
+    {
+        public DateTimeOffset UtcNow { get; set; } = Now;
+
+        public void Advance(TimeSpan duration) => UtcNow += duration;
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousClientBehaviorTests.cs

@@ -0,0 +1,342 @@
+using System.Net;
+using System.Text;
+using System.Text.Json;
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Client;
+
+public sealed class RendezvousClientBehaviorTests
+{
+    [Fact]
+    public async Task RegistrationRetriesWithTheSameIdempotentPayloadAndDisposesResponses()
+    {
+        TrackingContent unavailable = JsonContent(new ApiError
+        {
+            Code = RendezvousErrorCode.ServiceUnavailable,
+            Message = "try later",
+            RetryAfterSeconds = 1,
+        });
+        TrackingContent created = JsonContent(CreateRegistrationResponse());
+        ScriptedHandler handler = new(
+            Response(HttpStatusCode.ServiceUnavailable, unavailable),
+            Response(HttpStatusCode.Created, created),
+            new HttpResponseMessage(HttpStatusCode.NoContent));
+        using HttpClient httpClient = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RegisterSessionRequest request = CreateRegistrationRequest("stable-idempotency-key");
+        RecordingDelay delay = new(() => request.DisplayName = "mutated during retry delay");
+        RendezvousPublisherClient publisher = new(
+            httpClient,
+            new RendezvousClientOptions { JitterRatio = 0 },
+            delay);
+
+        RendezvousClientResult<PublishedSession> result = await publisher.RegisterAsync(
+            request,
+            "publisher-credential");
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(2, handler.RequestBodies.Count);
+        Assert.Equal(handler.RequestBodies[0], handler.RequestBodies[1]);
+        Assert.Contains("stable-idempotency-key", handler.RequestBodies[0], StringComparison.Ordinal);
+        Assert.Equal(TimeSpan.FromSeconds(1), Assert.Single(delay.Delays));
+        Assert.True(unavailable.IsDisposed);
+        Assert.True(created.IsDisposed);
+
+        using HttpResponseMessage stillOwnedByCaller = await httpClient.GetAsync("health");
+        Assert.Equal(HttpStatusCode.NoContent, stillOwnedByCaller.StatusCode);
+    }
+
+    [Fact]
+    public async Task UpdateUsesTheLeaseWithoutMutatingTheCallersRequest()
+    {
+        ScriptedHandler handler = new(
+            Response(HttpStatusCode.Created, JsonContent(CreateRegistrationResponse())),
+            new HttpResponseMessage(HttpStatusCode.NoContent));
+        using HttpClient httpClient = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousPublisherClient publisher = new(httpClient);
+        PublishedSession session = AssertSuccess(await publisher.RegisterAsync(
+            CreateRegistrationRequest("update-idempotency-key"),
+            "publisher-credential"));
+        UpdateSessionRequest update = new()
+        {
+            LeaseToken = "caller-placeholder",
+            BuildVersion = "2.0.0",
+            DisplayName = "updated",
+            Capacity = new() { CurrentPlayers = 2, MaximumPlayers = 4 },
+            Metadata = new() { ["mode"] = "online-coop" },
+        };
+
+        RendezvousClientResult<bool> result = await publisher.UpdateAsync(
+            session,
+            update,
+            "publisher-credential");
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal("caller-placeholder", update.LeaseToken);
+        Assert.Contains("lease-token", handler.RequestBodies[1], StringComparison.Ordinal);
+        Assert.DoesNotContain("caller-placeholder", handler.RequestBodies[1], StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task GatewayFailureIsRetriedForSafeBrowserReads()
+    {
+        ScriptedHandler handler = new(
+            new HttpResponseMessage(HttpStatusCode.BadGateway),
+            Response(HttpStatusCode.OK, JsonContent(new BrowseSessionsResponse())));
+        using HttpClient httpClient = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RecordingDelay delay = new();
+        RendezvousSessionBrowserClient browser = new(
+            httpClient,
+            new RendezvousClientOptions { JitterRatio = 0 },
+            delay);
+
+        RendezvousClientResult<BrowseSessionsResponse> result = await browser.BrowseAsync(new()
+        {
+            GameId = new("space-game"),
+            EnvironmentId = new("production"),
+            ProtocolVersion = 7,
+        });
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.Equal(2, handler.RequestUris.Count);
+        Assert.Equal(TimeSpan.FromMilliseconds(200), Assert.Single(delay.Delays));
+    }
+
+    [Fact]
+    public void SuccessResultRequiresAValue()
+    {
+        Assert.Throws<ArgumentNullException>(() => RendezvousClientResult.Success<string>(null!));
+    }
+
+    [Fact]
+    public async Task BrowseAllFollowsCursorsWithoutMutatingTheCallersRequest()
+    {
+        ScriptedHandler handler = new(
+            Response(HttpStatusCode.OK, JsonContent(new BrowseSessionsResponse
+            {
+                Items = [CreateListing("00000000-0000-0000-0000-000000000001")],
+                NextCursor = "next page+token",
+            })),
+            Response(HttpStatusCode.OK, JsonContent(new BrowseSessionsResponse
+            {
+                Items = [CreateListing("00000000-0000-0000-0000-000000000002")],
+            })));
+        using HttpClient httpClient = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousSessionBrowserClient browser = new(httpClient);
+        BrowseSessionsRequest request = new()
+        {
+            GameId = new("space-game"),
+            EnvironmentId = new("production"),
+            ProtocolVersion = 7,
+            PageSize = 1,
+        };
+
+        RendezvousClientResult<IReadOnlyList<SessionListing>> result = await browser.BrowseAllAsync(request);
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(2, result.Value!.Count);
+        Assert.Null(request.Cursor);
+        Assert.DoesNotContain("cursor=", handler.RequestUris[0].Query, StringComparison.Ordinal);
+        Assert.Contains("cursor=next%20page%2Btoken", handler.RequestUris[1].Query, StringComparison.Ordinal);
+        Assert.Contains("gameId=space-game", handler.RequestUris[0].Query, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task LeaseMaintainerReportsLeaseLoss()
+    {
+        ScriptedHandler handler = new(
+            Response(HttpStatusCode.Created, JsonContent(CreateRegistrationResponse())),
+            Response(HttpStatusCode.Gone, JsonContent(new ApiError
+            {
+                Code = RendezvousErrorCode.Expired,
+                Message = "lease expired",
+            })));
+        using HttpClient httpClient = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RecordingDelay delay = new();
+        RendezvousPublisherClient publisher = new(httpClient, delay: delay);
+        PublishedSession session = AssertSuccess(await publisher.RegisterAsync(
+            CreateRegistrationRequest("lease-loss-key"),
+            "publisher-credential"));
+        await using SessionLeaseMaintainer maintainer = publisher.CreateLeaseMaintainer(
+            session,
+            "publisher-credential");
+        bool eventRaised = false;
+        maintainer.LeaseLost += (_, _) => eventRaised = true;
+
+        LeaseMaintenanceResult result = await maintainer.RunAsync();
+
+        Assert.Equal(LeaseMaintenanceStopReason.LeaseLost, result.Reason);
+        Assert.Equal(RendezvousErrorCode.Expired, result.Error);
+        Assert.True(eventRaised);
+        Assert.Equal(TimeSpan.FromSeconds(15), Assert.Single(delay.Delays));
+    }
+
+    [Fact]
+    public async Task DisposingLeaseMaintainerCancelsItsWaitAndDoesNotRenew()
+    {
+        ScriptedHandler handler = new(
+            Response(HttpStatusCode.Created, JsonContent(CreateRegistrationResponse())));
+        using HttpClient httpClient = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        BlockingDelay delay = new();
+        RendezvousPublisherClient publisher = new(httpClient, delay: delay);
+        PublishedSession session = AssertSuccess(await publisher.RegisterAsync(
+            CreateRegistrationRequest("dispose-key"),
+            "publisher-credential"));
+        SessionLeaseMaintainer maintainer = publisher.CreateLeaseMaintainer(
+            session,
+            "publisher-credential");
+        Task<LeaseMaintenanceResult> active = maintainer.RunAsync();
+        await delay.Started.Task.WaitAsync(TimeSpan.FromSeconds(2));
+
+        await maintainer.DisposeAsync();
+        LeaseMaintenanceResult result = await active;
+
+        Assert.Equal(LeaseMaintenanceStopReason.Disposed, result.Reason);
+        Assert.Single(handler.RequestUris);
+        await Assert.ThrowsAsync<ObjectDisposedException>(() => maintainer.RunAsync());
+    }
+
+    [Fact]
+    public async Task CallerCancellationStopsLeaseMaintenanceWithoutRenewing()
+    {
+        ScriptedHandler handler = new(
+            Response(HttpStatusCode.Created, JsonContent(CreateRegistrationResponse())));
+        using HttpClient httpClient = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        BlockingDelay delay = new();
+        RendezvousPublisherClient publisher = new(httpClient, delay: delay);
+        PublishedSession session = AssertSuccess(await publisher.RegisterAsync(
+            CreateRegistrationRequest("cancel-key"),
+            "publisher-credential"));
+        await using SessionLeaseMaintainer maintainer = publisher.CreateLeaseMaintainer(
+            session,
+            "publisher-credential");
+        using CancellationTokenSource cancellation = new();
+        Task<LeaseMaintenanceResult> active = maintainer.RunAsync(cancellation.Token);
+        await delay.Started.Task.WaitAsync(TimeSpan.FromSeconds(2));
+
+        await cancellation.CancelAsync();
+        LeaseMaintenanceResult result = await active;
+
+        Assert.Equal(LeaseMaintenanceStopReason.Cancelled, result.Reason);
+        Assert.Single(handler.RequestUris);
+    }
+
+    private static T AssertSuccess<T>(RendezvousClientResult<T> result)
+    {
+        Assert.True(result.IsSuccess, result.Message);
+        return Assert.IsType<T>(result.Value);
+    }
+
+    private static RegisterSessionRequest CreateRegistrationRequest(string idempotencyKey) => new()
+    {
+        IdempotencyKey = idempotencyKey,
+        GameId = new("space-game"),
+        EnvironmentId = new("production"),
+        RegionId = new("eu-central"),
+        ProtocolVersion = 7,
+        BuildVersion = "1.0.0",
+        DisplayName = "SDK host",
+        Visibility = ListingVisibility.Public,
+        Capacity = new() { CurrentPlayers = 1, MaximumPlayers = 4 },
+    };
+
+    private static RegisterSessionResponse CreateRegistrationResponse() => new()
+    {
+        ListingId = new(Guid.Parse("00000000-0000-0000-0000-000000000010")),
+        LeaseId = new(Guid.Parse("00000000-0000-0000-0000-000000000011")),
+        LeaseToken = "lease-token",
+        HostPresenceHandle = new(Guid.Parse("00000000-0000-0000-0000-000000000012")),
+        HostPresenceCapability = "presence-capability",
+        ExpiresAt = new DateTimeOffset(2030, 1, 1, 0, 0, 0, TimeSpan.Zero),
+        LeaseRenewAfterSeconds = 15,
+        HostPresenceRefreshAfterSeconds = 10,
+    };
+
+    private static SessionListing CreateListing(string id) => new()
+    {
+        ListingId = new(Guid.Parse(id)),
+        GameId = new("space-game"),
+        EnvironmentId = new("production"),
+        RegionId = new("eu-central"),
+        ProtocolVersion = 7,
+        BuildVersion = "1.0.0",
+        DisplayName = "host",
+        Visibility = ListingVisibility.Public,
+        PublisherTrustMode = PublisherTrustMode.ManagedDedicated,
+        Capacity = new() { CurrentPlayers = 1, MaximumPlayers = 4 },
+    };
+
+    private static TrackingContent JsonContent<T>(T value) => new(
+        JsonSerializer.SerializeToUtf8Bytes(value, ContractJson.Options));
+
+    private static HttpResponseMessage Response(HttpStatusCode status, HttpContent content) => new(status)
+    {
+        Content = content,
+    };
+
+    private sealed class ScriptedHandler(params HttpResponseMessage[] responses) : HttpMessageHandler
+    {
+        private readonly Queue<HttpResponseMessage> _responses = new(responses);
+
+        internal List<string> RequestBodies { get; } = [];
+        internal List<Uri> RequestUris { get; } = [];
+
+        protected override async Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            RequestUris.Add(request.RequestUri!);
+            RequestBodies.Add(request.Content is null
+                ? string.Empty
+                : await request.Content.ReadAsStringAsync(cancellationToken));
+            return _responses.Count > 0
+                ? _responses.Dequeue()
+                : throw new InvalidOperationException("No scripted response remains.");
+        }
+    }
+
+    private sealed class TrackingContent(byte[] bytes) : HttpContent
+    {
+        internal bool IsDisposed { get; private set; }
+
+        protected override Task SerializeToStreamAsync(Stream stream, TransportContext? context) =>
+            stream.WriteAsync(bytes).AsTask();
+
+        protected override bool TryComputeLength(out long length)
+        {
+            length = bytes.Length;
+            return true;
+        }
+
+        protected override void Dispose(bool disposing)
+        {
+            IsDisposed = true;
+            base.Dispose(disposing);
+        }
+    }
+
+    private sealed class RecordingDelay(Action? onDelay = null) : IRendezvousDelay
+    {
+        internal List<TimeSpan> Delays { get; } = [];
+
+        public Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            Delays.Add(delay);
+            onDelay?.Invoke();
+            return Task.CompletedTask;
+        }
+    }
+
+    private sealed class BlockingDelay : IRendezvousDelay
+    {
+        internal TaskCompletionSource Started { get; } = new(
+            TaskCreationOptions.RunContinuationsAsynchronously);
+
+        public Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken)
+        {
+            Started.TrySetResult();
+            return Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken);
+        }
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousClientIntegrationTests.cs

@@ -0,0 +1,195 @@
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Browser;
+using FinalFactory.Rendezvous.Server.Http;
+using FinalFactory.Rendezvous.Server.Provisioning;
+using FinalFactory.Rendezvous.Server.Sessions;
+using FinalFactory.Rendezvous.Server.State;
+using FinalFactory.Rendezvous.Tests.Provisioning;
+using FinalFactory.Rendezvous.Tests.State;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Hosting.Server;
+using Microsoft.AspNetCore.Hosting.Server.Features;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace FinalFactory.Rendezvous.Tests.Client;
+
+public sealed class RendezvousClientIntegrationTests
+{
+    [Fact]
+    public async Task PublisherAndBrowserClientsCompleteTheRealSessionLifecycleAndPaging()
+    {
+        await using ClientTestHost host = await ClientTestHost.StartAsync();
+        RendezvousPublisherClient publisher = new(host.HttpClient);
+        RendezvousSessionBrowserClient browser = new(host.HttpClient);
+        List<PublishedSession> sessions = [];
+
+        for (int index = 0; index < 3; index++)
+        {
+            RendezvousClientResult<PublishedSession> registered = await publisher.RegisterAsync(
+                CreateRegistration(index),
+                host.PublisherCredential);
+            PublishedSession session = AssertSuccess(registered);
+            sessions.Add(session);
+            Assert.True(host.Capabilities.TryFingerprint(
+                session.HostPresenceCapability,
+                out SecretFingerprint fingerprint));
+            StoreResult<StoredListing> bound = host.Store.BindHostPresence(new(
+                session.HostPresenceHandle,
+                fingerprint,
+                new(AddressFamilyKind.Ipv4, $"203.0.113.{80 + index}", 41_000 + index),
+                null));
+            Assert.Equal(StoreResultCode.Success, bound.Code);
+        }
+
+        PublishedSession first = sessions[0];
+        RendezvousClientResult<RenewLeaseResponse> renewed = await publisher.RenewAsync(
+            first,
+            host.PublisherCredential);
+        Assert.True(renewed.IsSuccess, renewed.Message);
+        Assert.Equal(renewed.Value!.ExpiresAt, first.ExpiresAt);
+
+        UpdateSessionRequest update = new()
+        {
+            BuildVersion = "2.0.0",
+            DisplayName = "SDK host updated",
+            Capacity = new() { CurrentPlayers = 2, MaximumPlayers = 8 },
+            Metadata = new() { ["mode"] = "online-coop" },
+        };
+        RendezvousClientResult<bool> updated = await publisher.UpdateAsync(
+            first,
+            update,
+            host.PublisherCredential);
+        Assert.True(updated.IsSuccess, updated.Message);
+
+        BrowseSessionsRequest browseRequest = new()
+        {
+            GameId = new("space-game"),
+            EnvironmentId = new("production"),
+            RegionId = new("eu-central"),
+            ProtocolVersion = 7,
+            PageSize = 1,
+            ExcludeFull = true,
+        };
+        IReadOnlyList<SessionListing> listings = AssertSuccess(
+            await browser.BrowseAllAsync(browseRequest));
+        Assert.Equal(3, listings.Count);
+        Assert.Equal("SDK host updated", listings.Single(item => item.ListingId == first.ListingId).DisplayName);
+
+        GetSessionResponse direct = AssertSuccess(await browser.GetAsync(
+            first.ListingId,
+            new("space-game"),
+            new("production"),
+            7));
+        Assert.Equal("2.0.0", direct.Session.BuildVersion);
+
+        foreach (PublishedSession session in sessions)
+        {
+            RendezvousClientResult<bool> deregistered = await publisher.DeregisterAsync(
+                session,
+                host.PublisherCredential);
+            Assert.True(deregistered.IsSuccess, deregistered.Message);
+            Assert.Equal(StoreResultCode.NotFound, host.Store.GetListing(session.ListingId, false).Code);
+        }
+    }
+
+    private static T AssertSuccess<T>(RendezvousClientResult<T> result)
+    {
+        Assert.True(result.IsSuccess, result.Message);
+        return Assert.IsAssignableFrom<T>(result.Value);
+    }
+
+    private static RegisterSessionRequest CreateRegistration(int index) => new()
+    {
+        IdempotencyKey = $"sdk-integration-{index}",
+        GameId = new("space-game"),
+        EnvironmentId = new("production"),
+        RegionId = new("eu-central"),
+        ProtocolVersion = 7,
+        BuildVersion = "1.0.0",
+        DisplayName = $"SDK host {index}",
+        Visibility = ListingVisibility.Public,
+        Capacity = new() { CurrentPlayers = 1, MaximumPlayers = 8 },
+        Metadata = new() { ["mode"] = "online-coop" },
+    };
+
+    private sealed class ClientTestHost : IAsyncDisposable
+    {
+        private readonly WebApplication _application;
+
+        private ClientTestHost(
+            WebApplication application,
+            HttpClient httpClient,
+            InMemoryEphemeralRendezvousStore store,
+            EphemeralCapabilityIssuer capabilities,
+            string publisherCredential)
+        {
+            _application = application;
+            HttpClient = httpClient;
+            Store = store;
+            Capabilities = capabilities;
+            PublisherCredential = publisherCredential;
+        }
+
+        internal HttpClient HttpClient { get; }
+        internal InMemoryEphemeralRendezvousStore Store { get; }
+        internal EphemeralCapabilityIssuer Capabilities { get; }
+        internal string PublisherCredential { get; }
+
+        internal static async Task<ClientTestHost> StartAsync()
+        {
+            ManualRendezvousClock clock = new(ProvisioningTestData.Now);
+            EphemeralStoreOptions stateOptions = new();
+            InMemoryEphemeralRendezvousStore store = new(stateOptions, clock, clock);
+            EphemeralCapabilityIssuer capabilities = new();
+            ProvisioningRuntime provisioning = ProvisioningRuntime.Create(
+                ProvisioningTestData.CreateOptions(),
+                ProvisioningTestData.CreateSecrets("secret-1"),
+                clock.UtcNow);
+            DedicatedPublisherPrincipal principal = ProvisioningTestData.CreateDedicatedPublisher();
+            string credential = provisioning.Credentials.Issue(principal, clock.UtcNow);
+
+            WebApplicationBuilder builder = WebApplication.CreateBuilder();
+            builder.WebHost.UseUrls("http://127.0.0.1:0");
+            builder.Services.ConfigureHttpJsonOptions(static options =>
+                ContractJson.Configure(options.SerializerOptions));
+            builder.Services.Configure<RouteHandlerOptions>(static options =>
+                options.ThrowOnBadRequest = true);
+            builder.Services.AddProblemDetails();
+            builder.Services.AddExceptionHandler<RendezvousExceptionHandler>();
+            builder.Services.AddSingleton(provisioning);
+            builder.Services.AddSingleton(provisioning.Credentials);
+            builder.Services.AddSingleton(provisioning.PublisherAuthorization);
+            builder.Services.AddSingleton<IEphemeralRendezvousStore>(store);
+            builder.Services.AddSingleton<IWallClock>(clock);
+            builder.Services.AddSingleton(capabilities);
+            builder.Services.AddSingleton<ISessionCapabilityService>(capabilities);
+            builder.Services.AddSingleton(SessionLeaseTiming.From(stateOptions));
+            builder.Services.AddSingleton<SessionLeaseService>();
+            builder.Services.AddSingleton<SessionBrowserCursorCodec>();
+            builder.Services.AddSingleton<SessionBrowserService>();
+
+            WebApplication app = builder.Build();
+            app.UseExceptionHandler();
+            app.MapRendezvousContractEndpoints();
+            await app.StartAsync();
+            IServer server = app.Services.GetRequiredService<IServer>();
+            string address = Assert.Single(server.Features.Get<IServerAddressesFeature>()!.Addresses);
+            return new(
+                app,
+                new HttpClient { BaseAddress = new Uri(address) },
+                store,
+                capabilities,
+                credential);
+        }
+
+        public async ValueTask DisposeAsync()
+        {
+            HttpClient.Dispose();
+            await _application.StopAsync();
+            await _application.DisposeAsync();
+        }
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousCoordinatorBehaviorTests.cs

@@ -0,0 +1,616 @@
+using System.Net;
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+using LiteNetLib;
+
+namespace FinalFactory.Rendezvous.Tests.Client;
+
+public sealed class RendezvousCoordinatorBehaviorTests
+{
+    [Fact]
+    public void NatIntroductionAloneDoesNotCompleteTheClientAttempt()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness harness = new(clock);
+        int completions = 0;
+        harness.Coordinator.Completed += (_, _) => completions++;
+
+        ((INatPunchListener)harness.PunchEvents).OnNatIntroductionSuccess(
+            new IPEndPoint(IPAddress.Loopback, 65_000),
+            NatAddressType.External,
+            harness.IntroductionToken);
+
+        Assert.Equal(RendezvousConnectionState.Connecting, harness.Coordinator.State);
+        Assert.False(harness.Coordinator.IsCompleted);
+        Assert.Equal(0, completions);
+    }
+
+    [Fact]
+    public void ClientRejectsASyntacticallyValidIntroductionWithTheWrongTicket()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness harness = new(clock);
+        string forged = NatIntroductionTokenCodec.Encode(
+            harness.AttemptId,
+            Credential('F'));
+
+        ((INatPunchListener)harness.PunchEvents).OnNatIntroductionSuccess(
+            new IPEndPoint(IPAddress.Loopback, 65_000),
+            NatAddressType.External,
+            forged);
+
+        Assert.Equal(RendezvousConnectionState.Punching, harness.Coordinator.State);
+        Assert.False(harness.Coordinator.IsCompleted);
+    }
+
+    [Fact]
+    public void CancellationCompletesExactlyOnceAndLateCallbacksCannotReopenTheAttempt()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness harness = new(clock);
+        List<RendezvousConnectionState> completions = [];
+        harness.Coordinator.Completed += (_, completion) => completions.Add(completion.State);
+
+        harness.Coordinator.Cancel();
+        harness.Coordinator.Poll();
+        ((INatPunchListener)harness.PunchEvents).OnNatIntroductionSuccess(
+            new IPEndPoint(IPAddress.Loopback, 65_000),
+            NatAddressType.External,
+            harness.IntroductionToken);
+        harness.Coordinator.Poll();
+
+        Assert.Equal(RendezvousConnectionState.Cancelled, harness.Coordinator.State);
+        Assert.Equal([RendezvousConnectionState.Cancelled], completions);
+    }
+
+    [Fact]
+    public void ExhaustedPunchBudgetTimesOutExactlyOnceUnderAFakeClock()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness harness = new(clock, new RendezvousCoordinatorOptions
+        {
+            MaximumPunchRequests = 1,
+            InitialPunchRetryDelay = TimeSpan.FromMilliseconds(10),
+            MaximumPunchRetryDelay = TimeSpan.FromMilliseconds(10),
+            JitterRatio = 0,
+        });
+        int completions = 0;
+        harness.Coordinator.Completed += (_, _) => completions++;
+
+        harness.Coordinator.Poll();
+        clock.Advance(TimeSpan.FromMilliseconds(10));
+        harness.Coordinator.Poll();
+        clock.Advance(TimeSpan.FromMinutes(1));
+        harness.Coordinator.Poll();
+
+        Assert.Equal(RendezvousConnectionState.TimedOut, harness.Coordinator.State);
+        Assert.Equal(1, completions);
+    }
+
+    [Fact]
+    public void ManagerShutdownAndDisposalEachReleaseTheirTerminalPathOnce()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness stopped = new(clock);
+        int stoppedCompletions = 0;
+        stopped.Coordinator.Completed += (_, _) => stoppedCompletions++;
+        stopped.Manager.Stop();
+
+        stopped.Coordinator.Poll();
+        stopped.Coordinator.Poll();
+
+        Assert.Equal(RendezvousConnectionState.ManagerStopped, stopped.Coordinator.State);
+        Assert.Equal(1, stoppedCompletions);
+
+        using ClientHarness disposed = new(clock);
+        int disposedCompletions = 0;
+        disposed.Coordinator.Completed += (_, _) => disposedCompletions++;
+        disposed.Coordinator.Dispose();
+        disposed.Coordinator.Dispose();
+        ((INatPunchListener)disposed.PunchEvents).OnNatIntroductionSuccess(
+            new IPEndPoint(IPAddress.Loopback, 65_000),
+            NatAddressType.External,
+            disposed.IntroductionToken);
+
+        Assert.Equal(RendezvousConnectionState.Disposed, disposed.Coordinator.State);
+        Assert.Equal(1, disposedCompletions);
+        Assert.Throws<ObjectDisposedException>(() => disposed.Coordinator.Poll());
+    }
+
+    [Fact]
+    public async Task DirectConnectionRejectionProducesOneTerminalTransition()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        using ClientHarness client = new(clock);
+        EventBasedNetListener rejectingEvents = new();
+        rejectingEvents.ConnectionRequestEvent += request => request.Reject();
+        NetManager rejectingHost = new(rejectingEvents);
+        try
+        {
+            Assert.True(rejectingHost.Start(0));
+            int completions = 0;
+            client.Coordinator.Completed += (_, _) => completions++;
+            ((INatPunchListener)client.PunchEvents).OnNatIntroductionSuccess(
+                new IPEndPoint(IPAddress.Loopback, rejectingHost.LocalPort),
+                NatAddressType.External,
+                client.IntroductionToken);
+
+            DateTime deadline = DateTime.UtcNow.AddSeconds(2);
+            while (!client.Coordinator.IsCompleted && DateTime.UtcNow < deadline)
+            {
+                rejectingHost.PollEvents();
+                client.Coordinator.Poll();
+                await Task.Delay(2);
+            }
+
+            Assert.Equal(RendezvousConnectionState.Rejected, client.Coordinator.State);
+            Assert.Equal(1, completions);
+            client.Coordinator.Poll();
+            Assert.Equal(1, completions);
+        }
+        finally
+        {
+            rejectingHost.Stop();
+        }
+    }
+
+    [Fact]
+    public void UnsynchronizedLiteNetCallbacksAreRejectedAtConstruction()
+    {
+        RendezvousNetListener networkEvents = new();
+        NetManager manager = networkEvents.CreateManager();
+        manager.UnsyncedEvents = true;
+        try
+        {
+            Assert.True(manager.Start(0));
+            Assert.Throws<InvalidOperationException>(() => new RendezvousClientCoordinator(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 9_050),
+                CreateAttempt(new DateTimeOffset(2030, 1, 1, 0, 0, 30, TimeSpan.Zero))));
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
+    [Fact]
+    public void CoordinatorRejectsAManagerCreatedByAnotherRoutingListener()
+    {
+        RendezvousNetListener managerEvents = new();
+        NetManager manager = managerEvents.CreateManager();
+        RendezvousNetListener mismatchedEvents = new();
+        try
+        {
+            Assert.True(manager.Start(0));
+
+            Assert.Throws<InvalidOperationException>(() => new RendezvousClientCoordinator(
+                manager,
+                mismatchedEvents,
+                new IPEndPoint(IPAddress.Loopback, 9_050),
+                CreateAttempt(new DateTimeOffset(2030, 1, 1, 0, 0, 30, TimeSpan.Zero))));
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
+    [Fact]
+    public async Task PublishedSessionTimingRemainsValidDuringConcurrentRenewalReads()
+    {
+        DateTimeOffset firstExpiry = new(2030, 1, 1, 0, 1, 0, TimeSpan.Zero);
+        DateTimeOffset secondExpiry = new(2030, 1, 1, 0, 2, 0, TimeSpan.Zero);
+        PublishedSession session = CreateSession(firstExpiry);
+
+        Task writer = Task.Run(() =>
+        {
+            for (int index = 0; index < 10_000; index++)
+            {
+                session.ExpiresAt = index % 2 == 0 ? firstExpiry : secondExpiry;
+                session.LeaseRenewAfterSeconds = index % 2 == 0 ? 10 : 20;
+            }
+        });
+        Task reader = Task.Run(() =>
+        {
+            for (int index = 0; index < 10_000; index++)
+            {
+                DateTimeOffset expiry = session.ExpiresAt;
+                int renewAfter = session.LeaseRenewAfterSeconds;
+                Assert.True(expiry == firstExpiry || expiry == secondExpiry);
+                Assert.True(renewAfter is 10 or 20 or 30);
+            }
+        });
+
+        await Task.WhenAll(writer, reader);
+    }
+
+    [Fact]
+    public async Task HostDoesNotMistakeAnIntroducedAttemptForCancellationWhenItLeavesPolling()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        RendezvousNetListener networkEvents = new();
+        EventBasedNatPunchListener punchEvents = networkEvents.PunchEvents;
+        NetManager manager = networkEvents.CreateManager();
+        JoinAttemptId attemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000111"));
+        HostJoinAttempt invitation = new()
+        {
+            AttemptId = attemptId,
+            MediationHandle = new(Guid.Parse("00000000-0000-0000-0000-000000000112")),
+            HostPunchCapability = Credential('H'),
+            ConnectionTicketDigest = NatIntroductionTokenCodec.ComputeDigest(
+                NatIntroductionTokenCodec.Encode(attemptId, Credential('T'))),
+            ExpiresAt = clock.UtcNow + TimeSpan.FromSeconds(30),
+        };
+        MutableJoinClient joins = new([invitation]);
+        using ConnectionTicketValidator tickets = new(16, clock);
+        try
+        {
+            Assert.True(manager.Start(0));
+            using RendezvousHostCoordinator host = new(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_002),
+                CreateSession(clock.UtcNow + TimeSpan.FromMinutes(1)),
+                joins,
+                new RendezvousCoordinatorOptions { JitterRatio = 0 },
+                clock,
+                tickets);
+            int completions = 0;
+            host.AttemptCompleted += (_, _) => completions++;
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+            Assert.Equal(1, host.PendingAttemptCount);
+
+            ((INatPunchListener)punchEvents).OnNatIntroductionSuccess(
+                new IPEndPoint(IPAddress.Loopback, 65_003),
+                NatAddressType.External,
+                NatIntroductionTokenCodec.Encode(attemptId, Credential('T')));
+            joins.Attempts = [];
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+
+            Assert.Equal(1, host.PendingAttemptCount);
+            Assert.Equal(0, completions);
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
+    [Fact]
+    public async Task HostCancellationSnapshotRevokesAnAuthorizedTicketAndCompletesOnce()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        RendezvousNetListener networkEvents = new();
+        EventBasedNatPunchListener punchEvents = networkEvents.PunchEvents;
+        NetManager manager = networkEvents.CreateManager();
+        JoinAttemptId attemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000131"));
+        string ticket = NatIntroductionTokenCodec.Encode(attemptId, Credential('T'));
+        HostJoinAttempt invitation = CreateHostAttempt(
+            attemptId,
+            new(Guid.Parse("00000000-0000-0000-0000-000000000132")),
+            ticket,
+            clock.UtcNow + TimeSpan.FromSeconds(30));
+        MutableJoinClient joins = new([invitation]);
+        using ConnectionTicketValidator tickets = new(16, clock);
+        try
+        {
+            Assert.True(manager.Start(0));
+            using RendezvousHostCoordinator host = new(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_002),
+                CreateSession(clock.UtcNow + TimeSpan.FromMinutes(1)),
+                joins,
+                new RendezvousCoordinatorOptions { JitterRatio = 0 },
+                clock,
+                tickets);
+            List<RendezvousConnectionState> completions = [];
+            host.AttemptCompleted += (_, completion) => completions.Add(completion.State);
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+            ((INatPunchListener)punchEvents).OnNatIntroductionSuccess(
+                new IPEndPoint(IPAddress.Loopback, 65_003),
+                NatAddressType.External,
+                ticket);
+
+            invitation.IsCancelled = true;
+            joins.Attempts = [invitation];
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+            host.Poll();
+
+            Assert.Equal(0, host.PendingAttemptCount);
+            Assert.Equal([RendezvousConnectionState.Cancelled], completions);
+            Assert.Equal(
+                ConnectionTicketConsumptionResult.Revoked,
+                tickets.Consume(attemptId, ticket));
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
+    [Fact]
+    public async Task HostAppliesOnlyTheLatestUnpolledSnapshot()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        RendezvousNetListener networkEvents = new();
+        NetManager manager = networkEvents.CreateManager();
+        JoinAttemptId attemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000141"));
+        HostJoinAttempt invitation = CreateHostAttempt(
+            attemptId,
+            new(Guid.Parse("00000000-0000-0000-0000-000000000142")),
+            NatIntroductionTokenCodec.Encode(attemptId, Credential('T')),
+            clock.UtcNow + TimeSpan.FromSeconds(30));
+        MutableJoinClient joins = new([invitation]);
+        try
+        {
+            Assert.True(manager.Start(0));
+            using RendezvousHostCoordinator host = new(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_002),
+                CreateSession(clock.UtcNow + TimeSpan.FromMinutes(1)),
+                joins,
+                new RendezvousCoordinatorOptions { JitterRatio = 0 },
+                clock,
+                null);
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            joins.Attempts = [];
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+
+            host.Poll();
+
+            Assert.Equal(0, host.PendingAttemptCount);
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
+    [Fact]
+    public async Task DisposingHostDuringRefreshDropsTheLateSnapshot()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        RendezvousNetListener networkEvents = new();
+        NetManager manager = networkEvents.CreateManager();
+        BlockingJoinClient joins = new();
+        try
+        {
+            Assert.True(manager.Start(0));
+            RendezvousHostCoordinator host = new(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_002),
+                CreateSession(clock.UtcNow + TimeSpan.FromMinutes(1)),
+                joins,
+                new RendezvousCoordinatorOptions { JitterRatio = 0 },
+                clock,
+                null);
+            Task<RendezvousClientResult<int>> refresh = host.RefreshJoinAttemptsAsync();
+            await joins.WaitUntilCalled;
+
+            host.Dispose();
+            joins.Complete([]);
+
+            await Assert.ThrowsAsync<ObjectDisposedException>(async () => await refresh);
+            Assert.Throws<ObjectDisposedException>(() => host.Poll());
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
+    [Fact]
+    public async Task HostBoundsAttemptExpiryChecksPerPoll()
+    {
+        ManualCoordinatorClock clock = new(new(2030, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        RendezvousNetListener networkEvents = new();
+        NetManager manager = networkEvents.CreateManager();
+        JoinAttemptId firstId = new(Guid.Parse("00000000-0000-0000-0000-000000000151"));
+        JoinAttemptId secondId = new(Guid.Parse("00000000-0000-0000-0000-000000000152"));
+        DateTimeOffset expiresAt = clock.UtcNow + TimeSpan.FromSeconds(1);
+        MutableJoinClient joins = new([
+            CreateHostAttempt(
+                firstId,
+                new(Guid.Parse("00000000-0000-0000-0000-000000000153")),
+                NatIntroductionTokenCodec.Encode(firstId, Credential('T')),
+                expiresAt),
+            CreateHostAttempt(
+                secondId,
+                new(Guid.Parse("00000000-0000-0000-0000-000000000154")),
+                NatIntroductionTokenCodec.Encode(secondId, Credential('U')),
+                expiresAt),
+        ]);
+        try
+        {
+            Assert.True(manager.Start(0));
+            using RendezvousHostCoordinator host = new(
+                manager,
+                networkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_002),
+                CreateSession(clock.UtcNow + TimeSpan.FromMinutes(1)),
+                joins,
+                new RendezvousCoordinatorOptions
+                {
+                    MaximumAttemptChecksPerPoll = 1,
+                    JitterRatio = 0,
+                },
+                clock,
+                null);
+            List<RendezvousConnectionState> completions = [];
+            host.AttemptCompleted += (_, completion) => completions.Add(completion.State);
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+            clock.Advance(TimeSpan.FromSeconds(2));
+
+            host.Poll();
+
+            Assert.Equal(1, host.PendingAttemptCount);
+            Assert.Equal([RendezvousConnectionState.TimedOut], completions);
+            host.Poll();
+            Assert.Equal(0, host.PendingAttemptCount);
+            Assert.Equal(
+                [RendezvousConnectionState.TimedOut, RendezvousConnectionState.TimedOut],
+                completions);
+        }
+        finally
+        {
+            manager.Stop();
+        }
+    }
+
+    private static CreateJoinAttemptResponse CreateAttempt(DateTimeOffset expiresAt) => new()
+    {
+        AttemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000101")),
+        MediationHandle = new(Guid.Parse("00000000-0000-0000-0000-000000000102")),
+        ClientPunchCapability = Credential('C'),
+        ConnectionTicketDigest = NatIntroductionTokenCodec.ComputeDigest(
+            NatIntroductionTokenCodec.Encode(
+                new JoinAttemptId(Guid.Parse("00000000-0000-0000-0000-000000000101")),
+                Credential('T'))),
+        ExpiresAt = expiresAt,
+    };
+
+    private static PublishedSession CreateSession(DateTimeOffset expiresAt) => new(new RegisterSessionResponse
+    {
+        ListingId = new(Guid.Parse("00000000-0000-0000-0000-000000000121")),
+        LeaseId = new(Guid.Parse("00000000-0000-0000-0000-000000000122")),
+        LeaseToken = "lease-token",
+        HostPresenceHandle = new(Guid.Parse("00000000-0000-0000-0000-000000000123")),
+        HostPresenceCapability = Credential('P'),
+        ExpiresAt = expiresAt,
+        LeaseRenewAfterSeconds = 30,
+        HostPresenceRefreshAfterSeconds = 10,
+    });
+
+    private static HostJoinAttempt CreateHostAttempt(
+        JoinAttemptId attemptId,
+        MediationHandle mediationHandle,
+        string connectionTicket,
+        DateTimeOffset expiresAt) => new()
+        {
+            AttemptId = attemptId,
+            MediationHandle = mediationHandle,
+            HostPunchCapability = Credential('H'),
+            ConnectionTicketDigest = NatIntroductionTokenCodec.ComputeDigest(connectionTicket),
+            ExpiresAt = expiresAt,
+        };
+
+    private static string Credential(char value) => new(value, ContractLimits.DerivedCredentialCharacters);
+
+    private sealed class ClientHarness : IDisposable
+    {
+        internal ClientHarness(
+            ManualCoordinatorClock clock,
+            RendezvousCoordinatorOptions? options = null)
+        {
+            NetworkEvents = new();
+            PunchEvents = NetworkEvents.PunchEvents;
+            Manager = NetworkEvents.CreateManager();
+            Assert.True(Manager.Start(0));
+            CreateJoinAttemptResponse attempt = CreateAttempt(clock.UtcNow + TimeSpan.FromSeconds(30));
+            AttemptId = attempt.AttemptId;
+            IntroductionToken = NatIntroductionTokenCodec.Encode(
+                attempt.AttemptId,
+                Credential('T'));
+            Coordinator = new(
+                Manager,
+                NetworkEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_001),
+                attempt,
+                options,
+                clock);
+        }
+
+        internal RendezvousNetListener NetworkEvents { get; }
+        internal EventBasedNatPunchListener PunchEvents { get; }
+        internal NetManager Manager { get; }
+        internal RendezvousClientCoordinator Coordinator { get; }
+        internal JoinAttemptId AttemptId { get; }
+        internal string IntroductionToken { get; }
+
+        public void Dispose()
+        {
+            Coordinator.Dispose();
+            Manager.Stop();
+        }
+    }
+
+    private sealed class MutableJoinClient(IReadOnlyList<HostJoinAttempt> attempts) : IRendezvousJoinClient
+    {
+        internal IReadOnlyList<HostJoinAttempt> Attempts { get; set; } = attempts;
+
+        public Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
+            CreateJoinAttemptRequest request,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<bool>> CancelAsync(
+            CreateJoinAttemptResponse attempt,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<BrowseHostJoinAttemptsResponse>> BrowseForHostAsync(
+            PublishedSession session,
+            int pageSize = ContractLimits.BrowserPageMaxItems,
+            string? cursor = null,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<IReadOnlyList<HostJoinAttempt>>> BrowseAllForHostAsync(
+            PublishedSession session,
+            int maximumPages = 100,
+            CancellationToken cancellationToken = default) => Task.FromResult(
+                RendezvousClientResult.Success(Attempts));
+    }
+
+    private sealed class BlockingJoinClient : IRendezvousJoinClient
+    {
+        private readonly TaskCompletionSource<bool> _called = new(
+            TaskCreationOptions.RunContinuationsAsynchronously);
+        private readonly TaskCompletionSource<IReadOnlyList<HostJoinAttempt>> _result = new(
+            TaskCreationOptions.RunContinuationsAsynchronously);
+
+        internal Task WaitUntilCalled => _called.Task;
+
+        internal void Complete(IReadOnlyList<HostJoinAttempt> attempts) =>
+            _result.SetResult(attempts);
+
+        public Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
+            CreateJoinAttemptRequest request,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<bool>> CancelAsync(
+            CreateJoinAttemptResponse attempt,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<BrowseHostJoinAttemptsResponse>> BrowseForHostAsync(
+            PublishedSession session,
+            int pageSize = ContractLimits.BrowserPageMaxItems,
+            string? cursor = null,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public async Task<RendezvousClientResult<IReadOnlyList<HostJoinAttempt>>> BrowseAllForHostAsync(
+            PublishedSession session,
+            int maximumPages = 100,
+            CancellationToken cancellationToken = default)
+        {
+            _called.SetResult(true);
+            return RendezvousClientResult.Success(await _result.Task.WaitAsync(cancellationToken));
+        }
+    }
+
+    private sealed class ManualCoordinatorClock(DateTimeOffset now) :
+        IRendezvousCoordinatorClock,
+        IConnectionTicketClock
+    {
+        public DateTimeOffset UtcNow { get; private set; } = now;
+
+        internal void Advance(TimeSpan amount) => UtcNow += amount;
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousCoordinatorIntegrationTests.cs

@@ -0,0 +1,272 @@
+using System.Net;
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.JoinAttempts;
+using FinalFactory.Rendezvous.Server.State;
+using FinalFactory.Rendezvous.Server.Transport;
+using FinalFactory.Rendezvous.Tests.JoinAttempts;
+using LiteNetLib;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+
+namespace FinalFactory.Rendezvous.Tests.Client;
+
+public sealed class RendezvousCoordinatorIntegrationTests
+{
+    [Fact]
+    public async Task CallerOwnedManagersCompleteAuthenticatedDirectConnectionAndRejectTicketReplay()
+    {
+        using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(8));
+        using JoinAttemptFixture fixture = new();
+        (RegisterSessionResponse registration, _) = fixture.CreateHost();
+        CreateJoinAttemptResponse created = fixture.Create(registration.ListingId, "sdk-direct-connect");
+        HostJoinAttempt hostAttempt = fixture.Service.BrowseForHost(
+            registration.ListingId,
+            ContractLimits.ContractVersion,
+            registration.LeaseToken,
+            ContractLimits.BrowserPageMaxItems,
+            null).Value!.Items.Single(item => item.AttemptId == created.AttemptId);
+        NatMediationProcessor processor = new(
+            fixture.Sessions.Store,
+            fixture.Sessions.Capabilities,
+            fixture.Service);
+        using UdpMediatorService mediatorService = new(
+            Options.Create(new UdpMediatorOptions
+            {
+                ListenAddress = IPAddress.Loopback.ToString(),
+                Port = 0,
+                PollIntervalMilliseconds = 1,
+            }),
+            NullLogger<UdpMediatorService>.Instance,
+            processor);
+        await mediatorService.StartAsync(timeout.Token);
+
+        RendezvousNetListener hostEvents = new();
+        RendezvousNetListener clientEvents = new();
+        bool gameplayConnectionRequestHandled = false;
+        hostEvents.GameplayEvents.ConnectionRequestEvent += _ =>
+            gameplayConnectionRequestHandled = true;
+        EventBasedNatPunchListener hostPunch = hostEvents.PunchEvents;
+        EventBasedNatPunchListener clientPunch = clientEvents.PunchEvents;
+        NetManager hostManager = hostEvents.CreateManager();
+        NetManager clientManager = clientEvents.CreateManager();
+        string? introductionToken = null;
+        string? hostIntroductionToken = null;
+        clientPunch.NatIntroductionSuccess += (_, _, token) => introductionToken = token;
+        hostPunch.NatIntroductionSuccess += (_, _, token) => hostIntroductionToken = token;
+
+        try
+        {
+            Assert.True(hostManager.Start(0));
+            Assert.True(clientManager.Start(0));
+            IPEndPoint mediator = Assert.IsType<IPEndPoint>(mediatorService.LocalEndpoint);
+            FakeJoinClient joinClient = new([hostAttempt]);
+            FixedCoordinatorClock clock = new(fixture.Sessions.Clock.UtcNow);
+            using ConnectionTicketValidator tickets = new(1_024, clock);
+            using RendezvousHostCoordinator host = new(
+                hostManager,
+                hostEvents,
+                mediator,
+                new PublishedSession(registration),
+                joinClient,
+                FastOptions(),
+                clock,
+                tickets);
+            using RendezvousClientCoordinator client = new(
+                clientManager,
+                clientEvents,
+                mediator,
+                created,
+                FastOptions(),
+                clock);
+            List<RendezvousHostAttemptCompletedEventArgs> hostCompletions = [];
+            List<RendezvousConnectionCompletedEventArgs> clientCompletions = [];
+            host.AttemptCompleted += (_, completion) => hostCompletions.Add(completion);
+            client.Completed += (_, completion) => clientCompletions.Add(completion);
+            Assert.True((await host.RefreshJoinAttemptsAsync(timeout.Token)).IsSuccess);
+
+            while ((!client.IsCompleted || hostCompletions.Count == 0)
+                   && !timeout.IsCancellationRequested)
+            {
+                host.Poll();
+                client.Poll();
+                await Task.Delay(2);
+            }
+
+            Assert.True(
+                client.State == RendezvousConnectionState.Connected,
+                $"Client ended in {client.State}; host pending={host.PendingAttemptCount}; "
+                + $"host completions={hostCompletions.Count}; introduction={introductionToken is not null}; "
+                + $"host introduction={hostIntroductionToken is not null}; "
+                + $"client digest={NatIntroductionTokenCodec.MatchesDigest(introductionToken, created.ConnectionTicketDigest)}; "
+                + $"host digest={NatIntroductionTokenCodec.MatchesDigest(hostIntroductionToken, hostAttempt.ConnectionTicketDigest)}.");
+            Assert.NotNull(client.ConnectedPeer);
+            Assert.Equal(
+                RendezvousConnectionState.Connected,
+                Assert.Single(clientCompletions).State);
+            RendezvousHostAttemptCompletedEventArgs hostCompletion = Assert.Single(hostCompletions);
+            Assert.Equal(created.AttemptId, hostCompletion.AttemptId);
+            Assert.Equal(RendezvousConnectionState.Connected, hostCompletion.State);
+            Assert.NotNull(hostCompletion.Peer);
+            Assert.False(gameplayConnectionRequestHandled);
+            Assert.True(NatIntroductionTokenCodec.TryDecode(
+                introductionToken,
+                out NatIntroductionToken? introduction));
+            Assert.NotNull(introduction);
+
+            EventBasedNetListener replayEvents = new();
+            bool replayConnected = false;
+            replayEvents.PeerConnectedEvent += _ => replayConnected = true;
+            NetManager replayManager = new(replayEvents);
+            try
+            {
+                Assert.True(replayManager.Start(0));
+                replayManager.Connect(
+                    new IPEndPoint(IPAddress.Loopback, hostManager.LocalPort),
+                    DirectConnectionRequestCodec.Encode(
+                        created.AttemptId,
+                        introduction.ConnectionTicket));
+                DateTime replayDeadline = DateTime.UtcNow.AddSeconds(1);
+                while (DateTime.UtcNow < replayDeadline && !replayConnected)
+                {
+                    host.Poll();
+                    replayManager.PollEvents();
+                    await Task.Delay(2, timeout.Token);
+                }
+
+                Assert.False(replayConnected);
+                Assert.False(gameplayConnectionRequestHandled);
+                Assert.Single(hostCompletions);
+            }
+            finally
+            {
+                replayManager.Stop();
+            }
+        }
+        finally
+        {
+            hostManager.Stop();
+            clientManager.Stop();
+            await mediatorService.StopAsync(CancellationToken.None);
+        }
+    }
+
+    [Fact]
+    public async Task HostDefersADirectRequestUntilTheMatchingNatIntroductionArrives()
+    {
+        using JoinAttemptFixture fixture = new();
+        (RegisterSessionResponse registration, _) = fixture.CreateHost();
+        CreateJoinAttemptResponse created = fixture.Create(registration.ListingId, "direct-before-nat");
+        HostJoinAttempt hostAttempt = fixture.Service.BrowseForHost(
+            registration.ListingId,
+            ContractLimits.ContractVersion,
+            registration.LeaseToken,
+            ContractLimits.BrowserPageMaxItems,
+            null).Value!.Items.Single(item => item.AttemptId == created.AttemptId);
+        IntroductionEndpoints introduction = fixture.Introduce(registration, created);
+        ConnectionTicketGrant grant = Assert.IsType<ConnectionTicketGrant>(
+            fixture.Service.IssueConnectionTicket(introduction.Attempt).Value);
+        RendezvousNetListener hostEvents = new();
+        EventBasedNatPunchListener hostPunch = hostEvents.PunchEvents;
+        EventBasedNetListener clientEvents = new();
+        bool clientConnected = false;
+        clientEvents.PeerConnectedEvent += _ => clientConnected = true;
+        NetManager hostManager = hostEvents.CreateManager();
+        NetManager clientManager = new(clientEvents);
+        try
+        {
+            Assert.True(hostManager.Start(0));
+            Assert.True(clientManager.Start(0));
+            FixedCoordinatorClock clock = new(fixture.Sessions.Clock.UtcNow);
+            FakeJoinClient joins = new([hostAttempt]);
+            using ConnectionTicketValidator tickets = new(16, clock);
+            using RendezvousHostCoordinator host = new(
+                hostManager,
+                hostEvents,
+                new IPEndPoint(IPAddress.Loopback, 65_000),
+                new PublishedSession(registration),
+                joins,
+                FastOptions(),
+                clock,
+                tickets);
+            List<RendezvousHostAttemptCompletedEventArgs> completions = [];
+            host.AttemptCompleted += (_, completion) => completions.Add(completion);
+            Assert.True((await host.RefreshJoinAttemptsAsync()).IsSuccess);
+            host.Poll();
+            bool observedDeferredRequest = false;
+            hostEvents.RendezvousConnectionRequest += _ =>
+            {
+                observedDeferredRequest = host.DeferredRequestCount == 1;
+                ((INatPunchListener)hostPunch).OnNatIntroductionSuccess(
+                    new IPEndPoint(IPAddress.Loopback, clientManager.LocalPort),
+                    NatAddressType.External,
+                    grant.Ticket);
+            };
+
+            clientManager.Connect(
+                new IPEndPoint(IPAddress.Loopback, hostManager.LocalPort),
+                DirectConnectionRequestCodec.Encode(created.AttemptId, grant.Ticket));
+            DateTime connectedDeadline = DateTime.UtcNow.AddSeconds(1);
+            while ((!clientConnected || completions.Count == 0)
+                   && DateTime.UtcNow < connectedDeadline)
+            {
+                host.Poll();
+                clientManager.PollEvents();
+                await Task.Delay(2);
+            }
+
+            Assert.True(
+                clientConnected,
+                $"Deferred observed={observedDeferredRequest}; deferred={host.DeferredRequestCount}; "
+                + $"pending={host.PendingAttemptCount}; completions={completions.Count}.");
+            Assert.True(observedDeferredRequest);
+            Assert.Equal(0, host.DeferredRequestCount);
+            Assert.Equal(
+                RendezvousConnectionState.Connected,
+                Assert.Single(completions).State);
+        }
+        finally
+        {
+            hostManager.Stop();
+            clientManager.Stop();
+        }
+    }
+
+    private static RendezvousCoordinatorOptions FastOptions() => new()
+    {
+        MaximumPunchRequests = 20,
+        InitialPunchRetryDelay = TimeSpan.FromMilliseconds(10),
+        MaximumPunchRetryDelay = TimeSpan.FromMilliseconds(100),
+        JitterRatio = 0,
+    };
+
+    private sealed class FakeJoinClient(IReadOnlyList<HostJoinAttempt> attempts) : IRendezvousJoinClient
+    {
+        public Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
+            CreateJoinAttemptRequest request,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<bool>> CancelAsync(
+            CreateJoinAttemptResponse attempt,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<BrowseHostJoinAttemptsResponse>> BrowseForHostAsync(
+            PublishedSession session,
+            int pageSize = ContractLimits.BrowserPageMaxItems,
+            string? cursor = null,
+            CancellationToken cancellationToken = default) => throw new NotSupportedException();
+
+        public Task<RendezvousClientResult<IReadOnlyList<HostJoinAttempt>>> BrowseAllForHostAsync(
+            PublishedSession session,
+            int maximumPages = 100,
+            CancellationToken cancellationToken = default) => Task.FromResult(
+                RendezvousClientResult.Success(attempts));
+    }
+
+    private sealed class FixedCoordinatorClock(DateTimeOffset now) :
+        IRendezvousCoordinatorClock,
+        IConnectionTicketClock
+    {
+        public DateTimeOffset UtcNow { get; } = now;
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Client/RendezvousJoinClientTests.cs

@@ -0,0 +1,154 @@
+using System.Net;
+using System.Text.Json;
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Client;
+
+public sealed class RendezvousJoinClientTests
+{
+    [Fact]
+    public async Task JoinIssuanceRetriesTheSameIdempotentPayloadAndCancellationUsesCapability()
+    {
+        CreateJoinAttemptResponse created = CreateAttempt();
+        RecordingHandler handler = new(
+            new HttpResponseMessage(HttpStatusCode.ServiceUnavailable),
+            JsonResponse(HttpStatusCode.Created, created),
+            new HttpResponseMessage(HttpStatusCode.NoContent));
+        using HttpClient http = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousJoinClient client = new(
+            http,
+            new RendezvousClientOptions { JitterRatio = 0 },
+            new ImmediateDelay());
+        CreateJoinAttemptRequest request = new()
+        {
+            IdempotencyKey = "stable-join-key",
+            GameId = new("space-game"),
+            EnvironmentId = new("production"),
+            ListingId = new(Guid.Parse("00000000-0000-0000-0000-000000000201")),
+            ProtocolVersion = 7,
+        };
+
+        RendezvousClientResult<CreateJoinAttemptResponse> result = await client.CreateAsync(request);
+        RendezvousClientResult<bool> cancelled = await client.CancelAsync(created);
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.True(cancelled.IsSuccess, cancelled.Message);
+        Assert.Equal(handler.Requests[0].Body, handler.Requests[1].Body);
+        Assert.Contains("stable-join-key", handler.Requests[0].Body, StringComparison.Ordinal);
+        RecordedRequest cancellation = handler.Requests[2];
+        Assert.Equal(HttpMethod.Delete, cancellation.Method);
+        Assert.Equal(
+            created.ClientPunchCapability,
+            cancellation.Headers["X-Rendezvous-Client-Punch-Capability"]);
+    }
+
+    [Fact]
+    public async Task HostInvitationPollingFollowsCursorsWithTheLeaseToken()
+    {
+        HostJoinAttempt first = CreateHostAttempt("00000000-0000-0000-0000-000000000211");
+        HostJoinAttempt second = CreateHostAttempt("00000000-0000-0000-0000-000000000212");
+        RecordingHandler handler = new(
+            JsonResponse(HttpStatusCode.OK, new BrowseHostJoinAttemptsResponse
+            {
+                Items = [first],
+                NextCursor = "next page+cursor",
+            }),
+            JsonResponse(HttpStatusCode.OK, new BrowseHostJoinAttemptsResponse
+            {
+                Items = [second],
+            }));
+        using HttpClient http = new(handler) { BaseAddress = new("http://rendezvous.test/") };
+        RendezvousJoinClient client = new(http);
+        PublishedSession session = new(new RegisterSessionResponse
+        {
+            ListingId = new(Guid.Parse("00000000-0000-0000-0000-000000000220")),
+            LeaseId = new(Guid.Parse("00000000-0000-0000-0000-000000000221")),
+            LeaseToken = "lease-secret",
+            HostPresenceHandle = new(Guid.Parse("00000000-0000-0000-0000-000000000222")),
+            HostPresenceCapability = Credential('P'),
+            ExpiresAt = new DateTimeOffset(2030, 1, 1, 0, 0, 0, TimeSpan.Zero),
+            LeaseRenewAfterSeconds = 15,
+            HostPresenceRefreshAfterSeconds = 10,
+        });
+
+        RendezvousClientResult<IReadOnlyList<HostJoinAttempt>> result =
+            await client.BrowseAllForHostAsync(session);
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.Equal([first.AttemptId, second.AttemptId], result.Value!.Select(item => item.AttemptId));
+        Assert.Equal(2, handler.Requests.Count);
+        Assert.All(handler.Requests, request =>
+            Assert.Equal("lease-secret", request.Headers["X-Rendezvous-Lease-Token"]));
+        Assert.Contains("cursor=next%20page%2Bcursor", handler.Requests[1].Uri.Query, StringComparison.Ordinal);
+    }
+
+    private static CreateJoinAttemptResponse CreateAttempt() => new()
+    {
+        AttemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000202")),
+        MediationHandle = new(Guid.Parse("00000000-0000-0000-0000-000000000203")),
+        ClientPunchCapability = Credential('C'),
+        ConnectionTicketDigest = NatIntroductionTokenCodec.ComputeDigest(
+            NatIntroductionTokenCodec.Encode(
+                new JoinAttemptId(Guid.Parse("00000000-0000-0000-0000-000000000202")),
+                Credential('T'))),
+        ExpiresAt = new DateTimeOffset(2030, 1, 1, 0, 0, 30, TimeSpan.Zero),
+    };
+
+    private static HostJoinAttempt CreateHostAttempt(string id) => new()
+    {
+        AttemptId = new(Guid.Parse(id)),
+        MediationHandle = new(Guid.NewGuid()),
+        HostPunchCapability = Credential('H'),
+        ConnectionTicketDigest = NatIntroductionTokenCodec.ComputeDigest(
+            NatIntroductionTokenCodec.Encode(new JoinAttemptId(Guid.Parse(id)), Credential('T'))),
+        ExpiresAt = new DateTimeOffset(2030, 1, 1, 0, 0, 30, TimeSpan.Zero),
+    };
+
+    private static string Credential(char value) => new(value, ContractLimits.DerivedCredentialCharacters);
+
+    private static HttpResponseMessage JsonResponse<T>(HttpStatusCode status, T value) => new(status)
+    {
+        Content = new ByteArrayContent(JsonSerializer.SerializeToUtf8Bytes(value, ContractJson.Options)),
+    };
+
+    private sealed class RecordingHandler(params HttpResponseMessage[] responses) : HttpMessageHandler
+    {
+        private readonly Queue<HttpResponseMessage> _responses = new(responses);
+
+        internal List<RecordedRequest> Requests { get; } = [];
+
+        protected override async Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            Dictionary<string, string> headers = request.Headers.ToDictionary(
+                static item => item.Key,
+                static item => string.Join(",", item.Value),
+                StringComparer.OrdinalIgnoreCase);
+            Requests.Add(new(
+                request.Method,
+                request.RequestUri!,
+                headers,
+                request.Content is null
+                    ? string.Empty
+                    : await request.Content.ReadAsStringAsync(cancellationToken)));
+            return _responses.Dequeue();
+        }
+    }
+
+    private sealed record RecordedRequest(
+        HttpMethod Method,
+        Uri Uri,
+        IReadOnlyDictionary<string, string> Headers,
+        string Body);
+
+    private sealed class ImmediateDelay : IRendezvousDelay
+    {
+        public Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            return Task.CompletedTask;
+        }
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/ContractLimitTests.cs

@@ -0,0 +1,149 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+public sealed class ContractLimitTests
+{
+    [Fact]
+    public void RequiredPlayerFacingTextRejectsEmptyOrWhitespaceValues()
+    {
+        Assert.False(ContractValidation.IsBuildVersionValid(string.Empty));
+        Assert.False(ContractValidation.IsBuildVersionValid("   "));
+        Assert.False(ContractValidation.IsDisplayNameValid(string.Empty));
+        Assert.False(ContractValidation.IsDisplayNameValid("   "));
+    }
+
+    [Fact]
+    public void ByteAndCollectionLimitsAcceptTheBoundaryOnly()
+    {
+        Assert.True(ContractValidation.IsHttpRequestSizeValid(ContractLimits.HttpRequestMaxBytes));
+        Assert.False(ContractValidation.IsHttpRequestSizeValid(ContractLimits.HttpRequestMaxBytes + 1));
+        Assert.True(ContractValidation.IsBrowserResponseSizeValid(ContractLimits.BrowserResponseMaxBytes));
+        Assert.False(ContractValidation.IsBrowserResponseSizeValid(ContractLimits.BrowserResponseMaxBytes + 1));
+        Assert.True(ContractValidation.IsPageSizeValid(ContractLimits.BrowserPageMaxItems));
+        Assert.False(ContractValidation.IsPageSizeValid(ContractLimits.BrowserPageMaxItems + 1));
+        Assert.False(ContractValidation.IsPageSizeValid(0));
+    }
+
+    [Fact]
+    public void Utf8LimitsCountBytesInsteadOfCharacters()
+    {
+        string atLimit = new('é', ContractLimits.DisplayNameMaxBytes / 2);
+        string overLimit = atLimit + "é";
+
+        Assert.True(ContractValidation.IsDisplayNameValid(atLimit));
+        Assert.False(ContractValidation.IsDisplayNameValid(overLimit));
+        Assert.True(ContractValidation.IsBuildVersionValid(
+            new string('a', ContractLimits.BuildVersionMaxBytes)));
+        Assert.False(ContractValidation.IsBuildVersionValid(
+            new string('a', ContractLimits.BuildVersionMaxBytes + 1)));
+    }
+
+    [Fact]
+    public void CapabilityLimitStaysBelowLiteNetLibTokenLimit()
+    {
+        Assert.True(ContractValidation.IsCapabilityValid(
+            new string('a', ContractLimits.UdpCapabilityMaxCharacters - 1)));
+        Assert.True(ContractValidation.IsCapabilityValid(
+            new string('a', ContractLimits.UdpCapabilityMaxCharacters)));
+        Assert.False(ContractValidation.IsCapabilityValid(
+            new string('a', ContractLimits.UdpCapabilityMaxCharacters + 1)));
+        Assert.False(ContractValidation.IsCapabilityValid("not+base64url"));
+        Assert.True(
+            ContractLimits.UdpCapabilityMaxCharacters
+            < ContractLimits.LiteNetLibNatTokenMaxCharacters);
+    }
+
+    [Fact]
+    public void CapacityAndMetadataLimitsAreBounded()
+    {
+        Assert.True(ContractValidation.IsCapacityValid(new SessionCapacity
+        {
+            CurrentPlayers = ContractLimits.SessionCapacityMaxPlayers,
+            MaximumPlayers = ContractLimits.SessionCapacityMaxPlayers,
+        }));
+        Assert.False(ContractValidation.IsCapacityValid(new SessionCapacity
+        {
+            CurrentPlayers = 0,
+            MaximumPlayers = ContractLimits.SessionCapacityMaxPlayers + 1,
+        }));
+
+        Dictionary<string, string> maximumKeys = Enumerable
+            .Range(0, ContractLimits.MetadataMaxKeys)
+            .ToDictionary(index => $"key-{index}", _ => "value", StringComparer.Ordinal);
+        Dictionary<string, string> tooManyKeys = new(maximumKeys, StringComparer.Ordinal)
+        {
+            ["overflow"] = "value",
+        };
+
+        Assert.True(ContractValidation.IsMetadataValid(maximumKeys));
+        Assert.False(ContractValidation.IsMetadataValid(tooManyKeys));
+        Assert.False(ContractValidation.IsMetadataValid(new Dictionary<string, string>
+        {
+            [new string('k', ContractLimits.MetadataKeyMaxBytes + 1)] = "value",
+        }));
+        Assert.False(ContractValidation.IsMetadataValid(new Dictionary<string, string>
+        {
+            ["key"] = new string('v', ContractLimits.MetadataValueMaxBytes + 1),
+        }));
+    }
+
+    [Fact]
+    public void MetadataDocumentLimitAcceptsExactlyFourKibibytes()
+    {
+        Dictionary<string, string> atLimit = Enumerable
+            .Range(0, ContractLimits.MetadataMaxKeys)
+            .ToDictionary(index => $"k{index:00}", _ => string.Empty, StringComparer.Ordinal);
+        for (int index = 0; index < 14; index++)
+        {
+            atLimit[$"k{index:00}"] = new string('v', ContractLimits.MetadataValueMaxBytes);
+        }
+
+        atLimit["k14"] = new string('v', 223);
+        Dictionary<string, string> overLimit = new(atLimit, StringComparer.Ordinal)
+        {
+            ["k14"] = new string('v', 224),
+        };
+
+        Assert.True(ContractValidation.IsMetadataValid(atLimit));
+        Assert.False(ContractValidation.IsMetadataValid(overLimit));
+    }
+
+    [Fact]
+    public void EndpointValidationIsAddressFamilyAware()
+    {
+        Assert.True(ContractValidation.IsNetworkEndpointValid(new NetworkEndpoint
+        {
+            AddressFamily = AddressFamilyKind.Ipv4,
+            Address = "192.0.2.10",
+            Port = 9050,
+        }));
+        Assert.True(ContractValidation.IsNetworkEndpointValid(new NetworkEndpoint
+        {
+            AddressFamily = AddressFamilyKind.Ipv6,
+            Address = "2001:db8::10",
+            Port = 9050,
+        }));
+        Assert.False(ContractValidation.IsNetworkEndpointValid(new NetworkEndpoint
+        {
+            AddressFamily = AddressFamilyKind.Ipv4,
+            Address = "2001:db8::10",
+            Port = 9050,
+        }));
+    }
+
+    [Fact]
+    public void ScopeAndOpaqueTextBoundariesAreEnforced()
+    {
+        Assert.True(GameId.TryParse(new string('a', ContractLimits.GameIdMaxCharacters), out _));
+        Assert.False(GameId.TryParse(
+            new string('a', ContractLimits.GameIdMaxCharacters + 1),
+            out _));
+        Assert.True(ContractValidation.IsIdempotencyKeyValid(
+            new string('i', ContractLimits.IdempotencyKeyMaxCharacters)));
+        Assert.False(ContractValidation.IsIdempotencyKeyValid(
+            new string('i', ContractLimits.IdempotencyKeyMaxCharacters + 1)));
+        Assert.True(ContractValidation.IsCursorValid(null));
+        Assert.False(ContractValidation.IsCursorValid("contains whitespace"));
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/ContractSerializationTests.cs

@@ -0,0 +1,105 @@
+using System.Text.Json;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+public sealed class ContractSerializationTests
+{
+    public static TheoryData<string, Type> GoldenJsonVectors => new()
+    {
+        { "register-session.json", typeof(RegisterSessionRequest) },
+        { "register-session-response.json", typeof(RegisterSessionResponse) },
+        { "browse-sessions.json", typeof(BrowseSessionsResponse) },
+        { "create-join-response.json", typeof(CreateJoinAttemptResponse) },
+        { "api-error.json", typeof(ApiError) },
+    };
+
+    [Theory]
+    [MemberData(nameof(GoldenJsonVectors))]
+    public void CanonicalJsonRoundtripsGoldenVectors(string fileName, Type contractType)
+    {
+        string expected = ContractTestFiles.Read(fileName);
+        object? value = JsonSerializer.Deserialize(expected, contractType, ContractJson.Options);
+
+        Assert.NotNull(value);
+        Assert.Equal(expected, JsonSerializer.Serialize(value, contractType, ContractJson.Options));
+    }
+
+    [Fact]
+    public void IdentifiersAreSerializedAsStrings()
+    {
+        SessionListingId id = new(new Guid("00112233-4455-6677-8899-aabbccddeeff"));
+
+        Assert.Equal(
+            "\"00112233-4455-6677-8899-aabbccddeeff\"",
+            JsonSerializer.Serialize(id, ContractJson.Options));
+        Assert.Equal(id, JsonSerializer.Deserialize<SessionListingId>(
+            "\"00112233-4455-6677-8899-aabbccddeeff\"",
+            ContractJson.Options));
+    }
+
+    [Fact]
+    public void UnknownObjectFieldsAreIgnoredForAdditiveV1Changes()
+    {
+        const string json = """
+            {"contractVersion":1,"idempotencyKey":"join-001","gameId":"space-game","environmentId":"production","listingId":"00112233-4455-6677-8899-aabbccddeeff","protocolVersion":7,"futureField":{"nested":true}}
+            """;
+
+        CreateJoinAttemptRequest? request = JsonSerializer.Deserialize<CreateJoinAttemptRequest>(
+            json,
+            ContractJson.Options);
+
+        Assert.NotNull(request);
+        Assert.Equal(new GameId("space-game"), request.GameId);
+        Assert.Equal(7u, request.ProtocolVersion);
+    }
+
+    [Fact]
+    public void MissingNormativeFieldsAreRejectedInsteadOfDefaulted()
+    {
+        const string missingVersion = """
+            {"idempotencyKey":"join-001","gameId":"space-game","environmentId":"production","listingId":"00112233-4455-6677-8899-aabbccddeeff","protocolVersion":7}
+            """;
+
+        Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<CreateJoinAttemptRequest>(
+            missingVersion,
+            ContractJson.Options));
+    }
+
+    [Fact]
+    public void UnknownEnumNamesAndNumericValuesAreRejected()
+    {
+        Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<ReportConnectionOutcomeRequest>(
+            "{\"contractVersion\":1,\"outcome\":\"futureOutcome\",\"elapsedMilliseconds\":1}",
+            ContractJson.Options));
+        Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<ReportConnectionOutcomeRequest>(
+            "{\"contractVersion\":1,\"outcome\":99,\"elapsedMilliseconds\":1}",
+            ContractJson.Options));
+    }
+
+    [Theory]
+    [InlineData(0)]
+    [InlineData(2)]
+    [InlineData(int.MaxValue)]
+    public void UnknownContractVersionsFailPredictably(int version)
+    {
+        Assert.Equal(
+            RendezvousErrorCode.UnsupportedContractVersion,
+            ContractValidation.ValidateContractVersion(version));
+    }
+
+    [Fact]
+    public void GameplayProtocolCompatibilityIsExactAndBuildIndependent()
+    {
+        Assert.True(ContractValidation.AreProtocolsCompatible(7, 7));
+        Assert.False(ContractValidation.AreProtocolsCompatible(7, 8));
+    }
+
+    [Fact]
+    public void SharedCanonicalOptionsCannotBeMutatedByConsumers()
+    {
+        Assert.True(ContractJson.Options.IsReadOnly);
+        Assert.Throws<InvalidOperationException>(() =>
+            ContractJson.Options.WriteIndented = true);
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/ContractTestFiles.cs

@@ -0,0 +1,30 @@
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+internal static class ContractTestFiles
+{
+    public static string Read(string fileName) => File
+        .ReadAllText(Path.Combine(Directory, fileName))
+        .TrimEnd('\r', '\n');
+
+    public static string Directory
+    {
+        get
+        {
+            DirectoryInfo? directory = new(AppContext.BaseDirectory);
+            while (directory is not null)
+            {
+                string solution = Path.Combine(directory.FullName, "Rendezvous.slnx");
+                if (File.Exists(solution))
+                {
+                    return Path.Combine(
+                        directory.FullName,
+                        "tests/FinalFactory.Rendezvous.Tests/TestData/Contracts/v1");
+                }
+
+                directory = directory.Parent;
+            }
+
+            throw new DirectoryNotFoundException("Could not locate contract test data.");
+        }
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/NatPunchRequestTokenCodecTests.cs

@@ -0,0 +1,61 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+public sealed class NatPunchRequestTokenCodecTests
+{
+    [Theory]
+    [InlineData(NatPunchPeerRole.HostPresence)]
+    [InlineData(NatPunchPeerRole.Host)]
+    [InlineData(NatPunchPeerRole.Client)]
+    public void FixedSizeTokensRoundTripBelowLiteNetLibLimit(NatPunchPeerRole role)
+    {
+        MediationHandle handle = new(Guid.NewGuid());
+        const string capability = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
+
+        string encoded = NatPunchRequestTokenCodec.Encode(role, handle, capability);
+
+        Assert.Equal(NatPunchRequestTokenCodec.EncodedLength, encoded.Length);
+        Assert.True(encoded.Length <= ContractLimits.LiteNetLibNatTokenMaxCharacters);
+        Assert.True(NatPunchRequestTokenCodec.TryDecode(encoded, out NatPunchRequestToken? decoded));
+        Assert.NotNull(decoded);
+        Assert.Equal(role, decoded.Role);
+        Assert.Equal(handle, decoded.MediationHandle);
+        Assert.Equal(capability, decoded.Capability);
+        Assert.DoesNotContain(capability, decoded.ToString(), StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void MalformedAndNonCanonicalTokensAreRejected()
+    {
+        string valid = NatPunchRequestTokenCodec.Encode(
+            NatPunchPeerRole.Client,
+            new MediationHandle(Guid.Parse("00112233-4455-6677-8899-aabbccddeeff")),
+            "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA");
+        string uppercaseHandle = valid[..6]
+            + valid.Substring(6, 32).ToUpperInvariant()
+            + valid[38..];
+
+        Assert.False(NatPunchRequestTokenCodec.TryDecode(null, out _));
+        Assert.False(NatPunchRequestTokenCodec.TryDecode(valid[..^1], out _));
+        Assert.False(NatPunchRequestTokenCodec.TryDecode("x" + valid[1..], out _));
+        Assert.False(NatPunchRequestTokenCodec.TryDecode(valid[..^1] + "x", out _));
+        Assert.False(NatPunchRequestTokenCodec.TryDecode(uppercaseHandle, out _));
+        Assert.Throws<ArgumentException>(() => NatPunchRequestTokenCodec.Encode(
+            (NatPunchPeerRole)99,
+            new MediationHandle(Guid.NewGuid()),
+            "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"));
+    }
+
+    [Fact]
+    public void FixedWireLengthHasADedicatedLiteNetSafeContractLimit()
+    {
+        Assert.Equal(192, ContractLimits.NatPunchRequestTokenCharacters);
+        Assert.Equal(
+            ContractLimits.NatPunchRequestTokenCharacters,
+            NatPunchRequestTokenCodec.EncodedLength);
+        Assert.True(
+            ContractLimits.NatPunchRequestTokenCharacters
+            <= ContractLimits.LiteNetLibNatTokenMaxCharacters);
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/OpenApiCompatibilityTests.cs

@@ -0,0 +1,108 @@
+using System.Text.Json;
+
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+public sealed class OpenApiCompatibilityTests
+{
+    private static readonly string[] ExpectedPaths =
+    [
+        "/health/live",
+        "/health/ready",
+        "/v1/join-attempts",
+        "/v1/join-attempts/{attemptId}",
+        "/v1/join-attempts/{attemptId}/outcome",
+        "/v1/sessions",
+        "/v1/sessions/{listingId}",
+        "/v1/sessions/{listingId}/join-attempts",
+        "/v1/sessions/{listingId}/renew",
+    ];
+
+    private static readonly string[] ExpectedListingProperties =
+    [
+        "buildVersion",
+        "capacity",
+        "contractVersion",
+        "displayName",
+        "environmentId",
+        "gameId",
+        "listingId",
+        "metadata",
+        "protocolVersion",
+        "publisherTrustMode",
+        "regionId",
+        "visibility",
+    ];
+
+    [Fact]
+    public void GeneratedOpenApiContainsTheFrozenV1Surface()
+    {
+        string path = Path.Combine(
+            ContractTestFiles.Directory,
+            "../../../../../docs/api/rendezvous-v1.json");
+        using JsonDocument document = JsonDocument.Parse(File.ReadAllText(Path.GetFullPath(path)));
+        JsonElement root = document.RootElement;
+
+        Assert.Equal("3.1.1", root.GetProperty("openapi").GetString());
+        string[] paths = root.GetProperty("paths")
+            .EnumerateObject()
+            .Select(static item => item.Name)
+            .Order(StringComparer.Ordinal)
+            .ToArray();
+        Assert.Equal(ExpectedPaths, paths);
+
+        JsonElement schemas = root.GetProperty("components").GetProperty("schemas");
+        Assert.Equal("string", schemas.GetProperty("GameId").GetProperty("type").GetString());
+        Assert.Equal("uuid", schemas.GetProperty("SessionListingId").GetProperty("format").GetString());
+
+        string[] listingProperties = schemas.GetProperty("SessionListing")
+            .GetProperty("properties")
+            .EnumerateObject()
+            .Select(static item => item.Name)
+            .Order(StringComparer.Ordinal)
+            .ToArray();
+        Assert.Equal(ExpectedListingProperties, listingProperties);
+        Assert.DoesNotContain(listingProperties, static property =>
+            property.Contains("token", StringComparison.OrdinalIgnoreCase)
+            || property.Contains("endpoint", StringComparison.OrdinalIgnoreCase)
+            || property.Contains("playerId", StringComparison.OrdinalIgnoreCase));
+
+        JsonElement publisherBearer = root.GetProperty("components")
+            .GetProperty("securitySchemes")
+            .GetProperty("PublisherBearer");
+        Assert.Equal("http", publisherBearer.GetProperty("type").GetString());
+        Assert.Equal("bearer", publisherBearer.GetProperty("scheme").GetString());
+        (string Path, string Method)[] publisherOperations =
+        [
+            ("/v1/sessions", "post"),
+            ("/v1/sessions/{listingId}", "put"),
+            ("/v1/sessions/{listingId}", "delete"),
+            ("/v1/sessions/{listingId}/renew", "post"),
+        ];
+        foreach ((string operationPath, string method) in publisherOperations)
+        {
+            JsonElement security = root.GetProperty("paths")
+                .GetProperty(operationPath)
+                .GetProperty(method)
+                .GetProperty("security");
+            Assert.True(security[0].TryGetProperty("PublisherBearer", out _));
+        }
+
+        JsonElement cancelParameters = root.GetProperty("paths")
+            .GetProperty("/v1/join-attempts/{attemptId}")
+            .GetProperty("delete")
+            .GetProperty("parameters");
+        JsonElement cancelCapability = Assert.Single(cancelParameters.EnumerateArray(), static parameter =>
+            parameter.GetProperty("in").GetString() == "header"
+            && parameter.GetProperty("name").GetString()
+                == "X-Rendezvous-Client-Punch-Capability");
+        Assert.True(cancelCapability.GetProperty("required").GetBoolean());
+        JsonElement hostPollParameters = root.GetProperty("paths")
+            .GetProperty("/v1/sessions/{listingId}/join-attempts")
+            .GetProperty("get")
+            .GetProperty("parameters");
+        JsonElement leaseToken = Assert.Single(hostPollParameters.EnumerateArray(), static parameter =>
+            parameter.GetProperty("in").GetString() == "header"
+            && parameter.GetProperty("name").GetString() == "X-Rendezvous-Lease-Token");
+        Assert.True(leaseToken.GetProperty("required").GetBoolean());
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/PublicApiCompatibilityTests.cs

@@ -0,0 +1,128 @@
+using System.Reflection;
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+public sealed class PublicApiCompatibilityTests
+{
+    [Fact]
+    public void ContractsPublicApiMatchesTheV1Snapshot()
+    {
+        string snapshot = CreateSnapshot(typeof(ContractLimits).Assembly);
+        string expected = ContractTestFiles.Read("contracts-public-api.txt");
+        if (expected == "SNAPSHOT_PENDING"
+            && Environment.GetEnvironmentVariable("RENDEZVOUS_UPDATE_CONTRACT_SNAPSHOT") == "1")
+        {
+            string snapshotPath = Path.Combine(
+                ContractTestFiles.Directory,
+                "contracts-public-api.txt");
+            File.WriteAllText(snapshotPath, snapshot + Environment.NewLine);
+            expected = snapshot;
+        }
+
+        Assert.Equal(expected, snapshot);
+    }
+
+    [Fact]
+    public void ClientPublicApiMatchesTheV1Snapshot()
+    {
+        string snapshot = CreateSnapshot(typeof(RendezvousPublisherClient).Assembly);
+        string expected = ContractTestFiles.Read("client-public-api.txt");
+        if (expected == "SNAPSHOT_PENDING"
+            && Environment.GetEnvironmentVariable("RENDEZVOUS_UPDATE_CONTRACT_SNAPSHOT") == "1")
+        {
+            string snapshotPath = Path.Combine(
+                ContractTestFiles.Directory,
+                "client-public-api.txt");
+            File.WriteAllText(snapshotPath, snapshot + Environment.NewLine);
+            expected = snapshot;
+        }
+
+        Assert.Equal(expected, snapshot);
+    }
+
+    private static string CreateSnapshot(Assembly assembly)
+    {
+        List<string> lines = [];
+        foreach (Type type in assembly.GetExportedTypes().OrderBy(static type => type.FullName, StringComparer.Ordinal))
+        {
+            lines.Add($"TYPE {FormatType(type)}");
+            if (type.IsEnum)
+            {
+                foreach (string name in Enum.GetNames(type))
+                {
+                    object value = Enum.Parse(type, name);
+                    lines.Add($"  ENUM {name}={Convert.ToInt64(value, System.Globalization.CultureInfo.InvariantCulture)}");
+                }
+
+                continue;
+            }
+
+            foreach (FieldInfo field in type.GetFields(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly)
+                         .OrderBy(static field => field.Name, StringComparer.Ordinal))
+            {
+                string value = field.IsLiteral
+                    ? Convert.ToString(field.GetRawConstantValue(), System.Globalization.CultureInfo.InvariantCulture) ?? "null"
+                    : "non-literal";
+                lines.Add($"  FIELD {FormatType(field.FieldType)} {field.Name}={value}");
+            }
+
+            foreach (ConstructorInfo constructor in type.GetConstructors(BindingFlags.Public | BindingFlags.Instance)
+                         .OrderBy(static constructor => FormatParameters(constructor.GetParameters()), StringComparer.Ordinal))
+            {
+                lines.Add($"  CTOR ({FormatParameters(constructor.GetParameters())})");
+            }
+
+            foreach (PropertyInfo property in type.GetProperties(BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly)
+                         .OrderBy(static property => property.Name, StringComparer.Ordinal))
+            {
+                string accessors = $"{(property.GetMethod?.IsPublic == true ? "get;" : string.Empty)}{(property.SetMethod?.IsPublic == true ? "set;" : string.Empty)}";
+                lines.Add($"  PROP {FormatType(property.PropertyType)} {property.Name} {{{accessors}}}");
+            }
+
+            foreach (EventInfo eventInfo in type.GetEvents(BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly)
+                         .OrderBy(static eventInfo => eventInfo.Name, StringComparer.Ordinal))
+            {
+                lines.Add($"  EVENT {FormatType(eventInfo.EventHandlerType!)} {eventInfo.Name}");
+            }
+
+            foreach (MethodInfo method in type.GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly)
+                         .Where(static method => !method.IsSpecialName || method.Name.StartsWith("op_", StringComparison.Ordinal))
+                         .OrderBy(static method => method.Name, StringComparer.Ordinal)
+                         .ThenBy(static method => FormatParameters(method.GetParameters()), StringComparer.Ordinal))
+            {
+                lines.Add($"  METHOD {FormatType(method.ReturnType)} {method.Name}({FormatParameters(method.GetParameters())})");
+            }
+        }
+
+        return string.Join('\n', lines);
+    }
+
+    private static string FormatParameters(ParameterInfo[] parameters) => string.Join(
+        ", ",
+        parameters.Select(static parameter =>
+            $"{FormatType(parameter.ParameterType)} {parameter.Name}"));
+
+    private static string FormatType(Type type)
+    {
+        if (type.IsByRef)
+        {
+            return $"{FormatType(type.GetElementType()!)}&";
+        }
+
+        if (type.IsArray)
+        {
+            return $"{FormatType(type.GetElementType()!)}[]";
+        }
+
+        if (type.IsGenericType)
+        {
+            string name = type.GetGenericTypeDefinition().FullName!;
+            name = name[..name.IndexOf('`')];
+            return $"{name}<{string.Join(",", type.GetGenericArguments().Select(FormatType))}>";
+        }
+
+        return type.FullName ?? type.Name;
+    }
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/TraversalTokenCodecTests.cs

@@ -0,0 +1,59 @@
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+public sealed class TraversalTokenCodecTests
+{
+    [Fact]
+    public void IntroductionTokenBindsAttemptAndRedactsTheFixedTicket()
+    {
+        JoinAttemptId attemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000301"));
+        string authenticator = Credential('T');
+
+        string encoded = NatIntroductionTokenCodec.Encode(attemptId, authenticator);
+
+        Assert.Equal(NatIntroductionTokenCodec.EncodedLength, encoded.Length);
+        Assert.True(encoded.Length <= ContractLimits.LiteNetLibNatTokenMaxCharacters);
+        Assert.True(NatIntroductionTokenCodec.TryDecode(encoded, out NatIntroductionToken? decoded));
+        Assert.NotNull(decoded);
+        Assert.Equal(attemptId, decoded.AttemptId);
+        Assert.Equal(encoded, decoded.ConnectionTicket);
+        Assert.DoesNotContain(encoded, decoded.ToString(), StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void IntroductionTokenRejectsNonCanonicalOrAlteredFields()
+    {
+        string valid = NatIntroductionTokenCodec.Encode(
+            new JoinAttemptId(Guid.Parse("abcdef00-0000-0000-0000-000000000302")),
+            Credential('T'));
+
+        Assert.False(NatIntroductionTokenCodec.TryDecode(null, out _));
+        Assert.False(NatIntroductionTokenCodec.TryDecode(valid[..^1], out _));
+        Assert.False(NatIntroductionTokenCodec.TryDecode(valid[..^1] + "!", out _));
+        Assert.False(NatIntroductionTokenCodec.TryDecode(new string('A', 43), out _));
+    }
+
+    [Fact]
+    public void DirectConnectionRequestRoundTripsFixedBoundedPayloadAndRedactsTicket()
+    {
+        JoinAttemptId attemptId = new(Guid.Parse("00000000-0000-0000-0000-000000000303"));
+        string ticket = Credential('D');
+
+        byte[] encoded = DirectConnectionRequestCodec.Encode(attemptId, ticket);
+
+        Assert.Equal(DirectConnectionRequestCodec.EncodedLength, encoded.Length);
+        Assert.True(DirectConnectionRequestCodec.TryDecode(encoded, out DirectConnectionRequest? decoded));
+        Assert.NotNull(decoded);
+        Assert.Equal(attemptId, decoded.AttemptId);
+        Assert.Equal(ticket, decoded.ConnectionTicket);
+        Assert.DoesNotContain(ticket, decoded.ToString(), StringComparison.Ordinal);
+
+        encoded[0] ^= 0xff;
+        Assert.False(DirectConnectionRequestCodec.TryDecode(encoded, out _));
+        Assert.False(DirectConnectionRequestCodec.TryDecode(encoded.AsSpan(1), out _));
+    }
+
+    private static string Credential(char value) => new(value, ContractLimits.DerivedCredentialCharacters);
+}

tests/FinalFactory.Rendezvous.Tests/Contracts/UdpCodecTests.cs

@@ -0,0 +1,101 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Tests.Contracts;
+
+public sealed class UdpCodecTests
+{
+    private static readonly Guid Handle = new("00112233-4455-6677-8899-aabbccddeeff");
+
+    [Fact]
+    public void HostPresenceMatchesTheV1GoldenVector()
+    {
+        byte[] encoded = RendezvousUdpCodec.Encode(CreateDatagram());
+
+        Assert.Equal(ContractTestFiles.Read("udp-host-ipv4.hex"), Convert.ToHexString(encoded).ToLowerInvariant());
+        Assert.True(RendezvousUdpCodec.TryDecode(encoded, out PresenceDatagram? decoded, out UdpDecodeError error));
+        Assert.Equal(UdpDecodeError.None, error);
+        Assert.NotNull(decoded);
+        Assert.Equal(Handle, decoded.MediationHandle.Value);
+        Assert.Equal("192.0.2.10", decoded.LocalAddress);
+        Assert.Equal(9050, decoded.LocalPort);
+        Assert.Equal("Abc_123-xYz", decoded.Capability);
+    }
+
+    [Fact]
+    public void Ipv6RoundtripsWithoutLosingItsAddressFamily()
+    {
+        PresenceDatagram original = CreateDatagram();
+        original.MessageType = UdpPresenceMessageType.ClientPresence;
+        original.AddressFamily = AddressFamilyKind.Ipv6;
+        original.LocalAddress = "2001:db8::10";
+
+        byte[] encoded = RendezvousUdpCodec.Encode(original);
+
+        Assert.True(RendezvousUdpCodec.TryDecode(encoded, out PresenceDatagram? decoded, out _));
+        Assert.NotNull(decoded);
+        Assert.Equal(AddressFamilyKind.Ipv6, decoded.AddressFamily);
+        Assert.Equal("2001:db8::10", decoded.LocalAddress);
+    }
+
+    [Fact]
+    public void EncoderRejectsAnAddressFamilyMismatch()
+    {
+        PresenceDatagram datagram = CreateDatagram();
+        datagram.AddressFamily = AddressFamilyKind.Ipv4;
+        datagram.LocalAddress = "2001:db8::10";
+
+        Assert.Throws<ArgumentException>(() => RendezvousUdpCodec.Encode(datagram));
+    }
+
+    [Theory]
+    [InlineData(2, 2, UdpDecodeError.UnsupportedVersion)]
+    [InlineData(3, 3, UdpDecodeError.UnknownMessageType)]
+    [InlineData(4, 1, UdpDecodeError.InvalidFlags)]
+    [InlineData(21, 5, UdpDecodeError.InvalidAddressFamily)]
+    public void DecoderReturnsStableErrorsForUnknownHeaderValues(
+        int offset,
+        byte replacement,
+        UdpDecodeError expected)
+    {
+        byte[] encoded = RendezvousUdpCodec.Encode(CreateDatagram());
+        encoded[offset] = replacement;
+
+        Assert.False(RendezvousUdpCodec.TryDecode(encoded, out _, out UdpDecodeError actual));
+        Assert.Equal(expected, actual);
+    }
+
+    [Fact]
+    public void DecoderRejectsTruncationTrailingDataAndOversizedPackets()
+    {
+        byte[] encoded = RendezvousUdpCodec.Encode(CreateDatagram());
+        byte[] trailing = [.. encoded, 0];
+        byte[] oversized = new byte[ContractLimits.UdpDatagramMaxBytes + 1];
+
+        Assert.False(RendezvousUdpCodec.TryDecode(encoded.AsSpan(0, encoded.Length - 1), out _, out UdpDecodeError truncated));
+        Assert.Equal(UdpDecodeError.Truncated, truncated);
+        Assert.False(RendezvousUdpCodec.TryDecode(trailing, out _, out UdpDecodeError trailingError));
+        Assert.Equal(UdpDecodeError.TrailingData, trailingError);
+        Assert.False(RendezvousUdpCodec.TryDecode(oversized, out _, out UdpDecodeError oversizedError));
+        Assert.Equal(UdpDecodeError.DatagramTooLarge, oversizedError);
+    }
+
+    [Fact]
+    public void DecoderRejectsNonBase64UrlCapabilities()
+    {
+        byte[] encoded = RendezvousUdpCodec.Encode(CreateDatagram());
+        encoded[^1] = (byte)'+';
+
+        Assert.False(RendezvousUdpCodec.TryDecode(encoded, out _, out UdpDecodeError error));
+        Assert.Equal(UdpDecodeError.InvalidCapability, error);
+    }
+
+    private static PresenceDatagram CreateDatagram() => new()
+    {
+        MessageType = UdpPresenceMessageType.HostPresence,
+        MediationHandle = new MediationHandle(Handle),
+        AddressFamily = AddressFamilyKind.Ipv4,
+        LocalAddress = "192.0.2.10",
+        LocalPort = 9050,
+        Capability = "Abc_123-xYz",
+    };
+}

tests/FinalFactory.Rendezvous.Tests/JoinAttempts/JoinAttemptHttpEndpointTests.cs

@@ -0,0 +1,206 @@
+using System.Net;
+using System.Net.Http.Json;
+using FinalFactory.Rendezvous.Client;
+using FinalFactory.Rendezvous.Contracts;
+using FinalFactory.Rendezvous.Server.Browser;
+using FinalFactory.Rendezvous.Server.Http;
+using FinalFactory.Rendezvous.Server.JoinAttempts;
+using FinalFactory.Rendezvous.Server.Provisioning;
+using FinalFactory.Rendezvous.Server.Sessions;
+using FinalFactory.Rendezvous.Server.State;
+using FinalFactory.Rendezvous.Tests.Provisioning;
+using FinalFactory.Rendezvous.Tests.State;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Hosting.Server;
+using Microsoft.AspNetCore.Hosting.Server.Features;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace FinalFactory.Rendezvous.Tests.JoinAttempts;
+
+public sealed class JoinAttemptHttpEndpointTests
+{
+    [Fact]
+    public async Task ClientCreatesHostPollsAndCapabilityCancelsAnAttemptOverHttp()
+    {
+        await using JoinHttpTestHost host = await JoinHttpTestHost.StartAsync();
+        RendezvousPublisherClient publisher = new(host.HttpClient);
+        PublishedSession session = AssertSuccess(await publisher.RegisterAsync(
+            CreateRegistration(),
+            host.PublisherCredential));
+        Assert.True(host.Capabilities.TryFingerprint(
+            session.HostPresenceCapability,
+            out SecretFingerprint presenceFingerprint));
+        Assert.True(host.Store.BindHostPresence(new(
+            session.HostPresenceHandle,
+            presenceFingerprint,
+            new(AddressFamilyKind.Ipv4, "203.0.113.80", 41_000),
+            null)).Succeeded);
+        CreateJoinAttemptRequest request = new()
+        {
+            IdempotencyKey = "http-join-1",
+            GameId = new("space-game"),
+            EnvironmentId = new("production"),
+            ListingId = session.ListingId,
+            ProtocolVersion = 7,
+        };
+
+        using HttpResponseMessage createdResponse = await host.HttpClient.PostAsJsonAsync(
+            "v1/join-attempts",
+            request,
+            ContractJson.Options);
+        Assert.Equal(HttpStatusCode.Created, createdResponse.StatusCode);
+        CreateJoinAttemptResponse created = Assert.IsType<CreateJoinAttemptResponse>(
+            await createdResponse.Content.ReadFromJsonAsync<CreateJoinAttemptResponse>(ContractJson.Options));
+
+        using HttpRequestMessage pollRequest = new(
+            HttpMethod.Get,
+            $"v1/sessions/{session.ListingId}/join-attempts?contractVersion=1&pageSize=10");
+        pollRequest.Headers.Add("X-Rendezvous-Lease-Token", session.LeaseToken);
+        using HttpResponseMessage pollResponse = await host.HttpClient.SendAsync(pollRequest);
+        Assert.Equal(HttpStatusCode.OK, pollResponse.StatusCode);
+        BrowseHostJoinAttemptsResponse polled = Assert.IsType<BrowseHostJoinAttemptsResponse>(
+            await pollResponse.Content.ReadFromJsonAsync<BrowseHostJoinAttemptsResponse>(ContractJson.Options));
+        HostJoinAttempt hostAttempt = Assert.Single(polled.Items);
+        Assert.Equal(created.AttemptId, hostAttempt.AttemptId);
+        Assert.NotEqual(created.ClientPunchCapability, hostAttempt.HostPunchCapability);
+
+        using HttpResponseMessage missingCapability = await host.HttpClient.DeleteAsync(
+            $"v1/join-attempts/{created.AttemptId}");
+        Assert.Equal(HttpStatusCode.BadRequest, missingCapability.StatusCode);
+        ApiError missingCapabilityError = Assert.IsType<ApiError>(
+            await missingCapability.Content.ReadFromJsonAsync<ApiError>(ContractJson.Options));
+        Assert.Equal(RendezvousErrorCode.InvalidRequest, missingCapabilityError.Code);
+
+        using HttpRequestMessage unauthorizedCancel = new(
+            HttpMethod.Delete,
+            $"v1/join-attempts/{created.AttemptId}");
+        unauthorizedCancel.Headers.Add(
+            "X-Rendezvous-Client-Punch-Capability",
+            "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA");
+        using HttpResponseMessage unauthorized = await host.HttpClient.SendAsync(unauthorizedCancel);
+        Assert.Equal(HttpStatusCode.NotFound, unauthorized.StatusCode);
+
+        using HttpRequestMessage cancelRequest = new(
+            HttpMethod.Delete,
+            $"v1/join-attempts/{created.AttemptId}");
+        cancelRequest.Headers.Add(
+            "X-Rendezvous-Client-Punch-Capability",
+            created.ClientPunchCapability);
+        using HttpResponseMessage cancelled = await host.HttpClient.SendAsync(cancelRequest);
+        Assert.Equal(HttpStatusCode.NoContent, cancelled.StatusCode);
+
+        using HttpRequestMessage cancelledPollRequest = new(
+            HttpMethod.Get,
+            $"v1/sessions/{session.ListingId}/join-attempts?contractVersion=1&pageSize=10");
+        cancelledPollRequest.Headers.Add("X-Rendezvous-Lease-Token", session.LeaseToken);
+        using HttpResponseMessage cancelledPollResponse = await host.HttpClient.SendAsync(cancelledPollRequest);
+        BrowseHostJoinAttemptsResponse cancelledPoll = Assert.IsType<BrowseHostJoinAttemptsResponse>(
+            await cancelledPollResponse.Content.ReadFromJsonAsync<BrowseHostJoinAttemptsResponse>(ContractJson.Options));
+        HostJoinAttempt cancelledAttempt = Assert.Single(cancelledPoll.Items);
+        Assert.Equal(created.AttemptId, cancelledAttempt.AttemptId);
+        Assert.True(cancelledAttempt.IsCancelled);
+    }
+
+    private static T AssertSuccess<T>(RendezvousClientResult<T> result)
+    {
+        Assert.True(result.IsSuccess, result.Message);
+        return Assert.IsAssignableFrom<T>(result.Value);
+    }
+
+    private static RegisterSessionRequest CreateRegistration() => new()
+    {
+        IdempotencyKey = "join-http-host",
+        GameId = new("space-game"),
+        EnvironmentId = new("production"),
+        RegionId = new("eu-central"),
+        ProtocolVersion = 7,
+        BuildVersion = "1.0.0",
+        DisplayName = "Join HTTP host",
+        Visibility = ListingVisibility.Public,
+        Capacity = new() { CurrentPlayers = 8, MaximumPlayers = 8 },
+        Metadata = new() { ["mode"] = "online-coop" },
+    };
+
+    private sealed class JoinHttpTestHost : IAsyncDisposable
+    {
+        private readonly WebApplication _application;
+
+        private JoinHttpTestHost(
+            WebApplication application,
+            HttpClient httpClient,
+            InMemoryEphemeralRendezvousStore store,
+            EphemeralCapabilityIssuer capabilities,
+            string publisherCredential)
+        {
+            _application = application;
+            HttpClient = httpClient;
+            Store = store;
+            Capabilities = capabilities;
+            PublisherCredential = publisherCredential;
+        }
+
+        internal HttpClient HttpClient { get; }
+        internal InMemoryEphemeralRendezvousStore Store { get; }
+        internal EphemeralCapabilityIssuer Capabilities { get; }
+        internal string PublisherCredential { get; }
+
+        internal static async Task<JoinHttpTestHost> StartAsync()
+        {
+            ManualRendezvousClock clock = new(ProvisioningTestData.Now);
+            EphemeralStoreOptions stateOptions = new();
+            InMemoryEphemeralRendezvousStore store = new(stateOptions, clock, clock);
+            EphemeralCapabilityIssuer capabilities = new();
+            ProvisioningRuntime provisioning = ProvisioningRuntime.Create(
+                ProvisioningTestData.CreateOptions(),
+                ProvisioningTestData.CreateSecrets("secret-1"),
+                clock.UtcNow);
+            DedicatedPublisherPrincipal principal = ProvisioningTestData.CreateDedicatedPublisher();
+            string credential = provisioning.Credentials.Issue(principal, clock.UtcNow);
+
+            WebApplicationBuilder builder = WebApplication.CreateBuilder();
+            builder.WebHost.UseUrls("http://127.0.0.1:0");
+            builder.Services.ConfigureHttpJsonOptions(static options =>
+                ContractJson.Configure(options.SerializerOptions));
+            builder.Services.Configure<RouteHandlerOptions>(static options =>
+                options.ThrowOnBadRequest = true);
+            builder.Services.AddProblemDetails();
+            builder.Services.AddExceptionHandler<RendezvousExceptionHandler>();
+            builder.Services.AddSingleton(provisioning);
+            builder.Services.AddSingleton(provisioning.Policies);
+            builder.Services.AddSingleton(provisioning.Credentials);
+            builder.Services.AddSingleton(provisioning.PublisherAuthorization);
+            builder.Services.AddSingleton<IEphemeralRendezvousStore>(store);
+            builder.Services.AddSingleton<IWallClock>(clock);
+            builder.Services.AddSingleton(capabilities);
+            builder.Services.AddSingleton<ISessionCapabilityService>(capabilities);
+            builder.Services.AddSingleton(SessionLeaseTiming.From(stateOptions));
+            builder.Services.AddSingleton<SessionLeaseService>();
+            builder.Services.AddSingleton<SessionBrowserCursorCodec>();
+            builder.Services.AddSingleton<SessionBrowserService>();
+            builder.Services.AddSingleton<JoinAttemptCursorCodec>();
+            builder.Services.AddSingleton<JoinAttemptService>();
+
+            WebApplication app = builder.Build();
+            app.UseExceptionHandler();
+            app.MapRendezvousContractEndpoints();
+            await app.StartAsync();
+            IServer server = app.Services.GetRequiredService<IServer>();
+            string address = Assert.Single(server.Features.Get<IServerAddressesFeature>()!.Addresses);
+            return new(
+                app,
+                new HttpClient { BaseAddress = new Uri(address) },
+                store,
+                capabilities,
+                credential);
+        }
+
+        public async ValueTask DisposeAsync()
+        {
+            HttpClient.Dispose();
+            await _application.StopAsync();
+            await _application.DisposeAsync();
+        }
+    }
+}