ADR 0017. Operator Linking via Signed Assertion and PlayerPal Popup

Status

Accepted.

Supplies the link-flow mechanics left open under ADR 0009.

Context

The player must consent to PlayerPal on a PlayerPal-controlled surface. The operator must prove which local player is connecting without sending PII or putting secrets in query strings. After consent, the operator needs its alias (and requested provider aliases) without a per-launch PlayerPal call.

Decision

1. The operator (or provider) calls POST /v1/link-intents with a short-lived signed assertion in the POST body (lifetime about five minutes; replay protected jti/nonce; no email/name/phone claims).
2. PlayerPal returns a link_url containing only an opaque one-time code.
3. The player completes authentication and consent on a first-party PlayerPal page (popup or redirect). Results return to the embedder via origin-checked postMessage.
4. The operator exchanges a one-time result code (POST /v1/link-results/exchange) and receives pp_plr_opr_... plus requested pp_plr_prv_... values for integrations already authorized for that operator.

requested_provider_integrations does not grant scope. Partner assertion proves context; it is not a permanent player credential.

HTTP examples: spec §10 and §37.3-§37.5.

Consequences

• The earlier open question on "where the one-time link surface lives" is closed: PlayerPal-hosted ceremony, operator-triggered intent.
• Game launch does not call PlayerPal (ADR 0015).
• See docs/linking-and-bootstrap.md.