Rendezvous/docs/architecture/0002-publisher-trust-and-connection-policy.md

ADR 0002: publisher trust, discovery, compatibility, and fallback

• Status: Accepted
• Date: 2026-07-16
• Tracking: #2

Context

Dedicated servers can protect provisioned credentials. Public game binaries cannot. Discovery also needs rules that prevent accidental cross-game joins and make the meaning of a successful authorization precise.

Decision

Publisher trust modes

Each GameId and EnvironmentId is provisioned policy, never caller-created free text. V1 supports two visibly distinct publisher modes:

1. Managed dedicated host. A provisioned workload principal authenticates with a rotatable credential held outside the game binary. It is scoped to allowed games, environments, regions, and listing limits. Public or unlisted discovery may be enabled by policy.
2. Player-hosted session. A short-lived publisher grant is minted by a game-owned backend and is scoped to one game, environment, host, and expiry. Rendezvous does not interpret it as player identity. If a game has no grant issuer, it may opt into anonymous unlisted hosting with strict address and concurrency limits; anonymous sessions can be joined only through an opaque share code and never appear in public browsing.

A reusable credential embedded in a downloadable client is not authentication and is rejected as a provisioning design. Responses and metrics expose the publisher trust mode so operators and games can apply different policy without claiming anonymous hosts are authenticated identities.

Discovery and metadata

• Public listings can appear only in tenant-scoped compatible browsing.
• Unlisted listings never appear in browse results and require a random, unguessable share code. Unlisted does not mean private; join authorization and host admission still apply.
• Browser responses contain display data only. They exclude raw endpoints, internal IDs, lease credentials, punch capabilities, and connection tickets.
• Metadata is treated as hostile data. It is schema/budget validated, stored and returned as data, and never rendered as markup by the SDK or TestClient.

Compatibility and address families

• NetworkProtocolVersion must match exactly in v1. BuildVersion is bounded display/diagnostic text and never overrides protocol compatibility.
• GameId and EnvironmentId must match exactly. Region is a browse filter and preference, not a compatibility escape hatch.
• IPv4 direct connection and NAT punching are required for v1.
• Contracts carry an address-family discriminator. IPv6 direct connections may use observed global IPv6 endpoints when both peers support them, but IPv6 NAT traversal is not a v1 release requirement.
• Public candidates are derived only from the authenticated UDP packet's source. For same-LAN attempts, that packet may additionally claim at most one private unicast candidate per supported address family. A local claim is scoped to the capability and is introduced only to the opposite role in the same authorized attempt after both roles contribute. Loopback, link-local, multicast, unspecified, documentation, and otherwise invalid destinations are rejected. The SDK bounds probes per introduced candidate and lets callers disable local candidates. HTTP-supplied endpoint claims are never introduced.

Authorization and fallback

Join authorization means only that Rendezvous permits a scoped connection attempt. It does not reserve a game slot and does not authenticate a player to the game. The host validates and consumes the connection ticket, then applies its own capacity, ban, identity, and gameplay rules.

The SDK returns a typed outcome including success, cancellation, timeout, incompatibility, stale host, service rejection, host rejection, and transport failure. A game may provision an optional dedicated fallback endpoint. The SDK reports it but never connects without an explicit caller decision.

Gameplay relay is not part of v1. It remains a separate future service whose need is evaluated from privacy-safe measured direct-connection failures.

Consequences

• A player-hosted game needs a game-owned grant issuer for public discovery.
• Anonymous player hosting is useful for direct invitations but makes no user identity claim and receives the strictest quotas.
• Games remain responsible for presenting unsafe user-authored text safely.
• The exact-match v1 rule favors predictable interoperation over flexible version ranges; a later compatibility scheme must be versioned explicitly.