# V2 Cross-Platform Identity Integration Guide

Phase 72.29.1.15 documents the V2 cross-platform identity surface. Use this
guide when wiring publisher identity, linked platform accounts,
cross-progression services, platform ownership checks, display names,
matchmaking, support tools, privacy requests, and FairPlay enforcement into a V2
game flow.

## Source Of Truth

- Contract:
  [CrossPlatformIdentityIntegrationGuide_V2_Contract.json](../../ue/Content/V2/Online/CrossPlatformIdentity/CrossPlatformIdentityIntegrationGuide_V2_Contract.json)
- Account binding guide:
  [oshun-identity-binding.md](../integration/oshun-identity-binding.md)
- Runtime source package: `@oshun/identity`
- Unreal runtime surface: `V2OnlineServices`
- Canonical identity service contract:
  [UnifiedPlayerIdentityService_V2_Contract.json](../../ue/Content/V2/Online/CrossPlatformIdentity/UnifiedPlayerIdentityService_V2_Contract.json)

`FV2UnifiedPlayerIdentityService` is the source of truth inside the V2 runtime.
It mirrors `@oshun/identity` records into `FV2UnifiedPlayerIdentityRecord`
values keyed by `InternalPlayerId`, `OshunAccountId`, and linked
`FV2PlatformAccountLink` rows. Gameplay code may consume the resolved ids, but
platform account lookup, account merge, privacy handling, and support actions
stay off rollback in the online services layer.

## Identity Surface Map

| Surface           | Runtime contract                                           | Primary API                                                           | Required evidence                                                   |
| ----------------- | ---------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Unified identity  | `UnifiedPlayerIdentityService_V2_Contract.json`            | `ResolveUnifiedPlayerIdentity`                                        | Internal player id, Oshun account id, linked account count          |
| Platform linking  | `PlatformAccountLinkingFlow_V2_Contract.json`              | `LinkPlatformAccountWithOAuthProof`                                   | PKCE, state nonce, provider signature, linked target account        |
| Account merge     | `CrossPlatformAccountMergeStrategy_V2_Contract.json`       | `MergeLinkedPlatformAccount`                                          | Explicit consent, merge audit id, conflict records                  |
| Account split     | `PlatformAccountUnlinking_V2_Contract.json`                | `UnlinkPlatformAccount`                                               | Removed account id, remaining account count, preserved progression  |
| Cross-progression | `CrossPlatformProgressionSync_V2_Contract.json`            | `SyncCrossPlatformProgression`                                        | Central revision id and per-platform cloud-save write plans         |
| Entitlements      | `PlatformSpecificEntitlementVerification_V2_Contract.json` | `VerifyPlatformSpecificEntitlements`                                  | Current-platform base-game and DLC ownership                        |
| Display name      | `CrossPlatformDisplayName_V2_Contract.json`                | `FV2CrossPlatformDisplayNameSystem`, `UpdateCrossPlatformDisplayName` | Publisher display name distinct from platform usernames             |
| Matchmaking       | `CrossPlatformMatchmaking_V2_Contract.json`                | `FindCrossPlatformMatch`                                              | Cross-platform candidate selection and opt-out filter evidence      |
| Ban sync          | `CrossPlatformBanSynchronization_V2_Contract.json`         | `SyncCrossPlatformBan`                                                | Source platform linkage and all-linked-platform FairPlay fanout     |
| Privacy           | `AccountDataPrivacyCompliance_V2_Contract.json`            | `ExportAccountData`, `DeleteAccountAcrossLinkedPlatforms`             | GDPR/CCPA export bundle and deletion propagation plans              |
| Admin tools       | `CrossPlatformIdentityAdminTools_V2_Contract.json`         | `BuildCrossPlatformIdentityAdminDashboard`                            | Linked-account table, merge/split/ban controls, support audit trail |

The social stack also consumes the unified identity surface:
`CrossPlatformFriendSystem_V2_Contract.json`,
`CrossPlatformPartyLobby_V2_Contract.json`, and
`CrossPlatformVoiceChat_V2_Contract.json` must resolve friends, party members,
and voice routes through `FV2UnifiedPlayerIdentityService` instead of native
platform account ids.

## Integration Sequence

1. Register `FV2UnifiedPlayerIdentityService` with every active
   `FV2UnifiedPlayerIdentityRecord` from `@oshun/identity`.
2. Resolve platform login with `BuildUnifiedPlayerIdentityResolutionRequest` and
   `ResolveUnifiedPlayerIdentity`.
3. Link additional platform accounts only through
   `FV2PlatformAccountLinkingFlow` and OAuth ownership proof.
4. Merge account state with `FV2CrossPlatformAccountMergeStrategy` after the
   link result is complete and explicit player consent is recorded.
5. Sync central progression through `FV2CrossPlatformProgressionSyncSystem`
   before platform cloud-save fanout.
6. Verify base game and DLC ownership for the current platform with
   `FV2PlatformSpecificEntitlementVerifier`.
7. Apply display-name, matchmaking, friend, party, and voice features from the
   resolved Oshun account rather than from the native platform account alone.
8. Route support, privacy, unlinking, and ban workflows through the identity
   service so every linked platform account is visible and auditable.

## Platform Account Lifecycle

Platform accounts are credentials attached to one Oshun account. The lifecycle
is intentionally narrow:

- Link: `FV2PlatformAccountLinkingRequest` requires an authenticated source
  account, a target platform account, PKCE, state nonce, token exchange,
  provider signature, `openid`, `platform.account`, and `ownership.verify`
  scopes.
- Merge: `FV2CrossPlatformAccountMergeRequest` requires a completed linking
  result, explicit consent, merge audit id, and deterministic conflict records
  for progression, inventory, and achievements.
- Split: `FV2PlatformAccountUnlinkingRequest` removes exactly one linked
  account, rejects unlinked targets, and fails closed when the remaining account
  count would violate the cross-progression invariant.
- Reconcile: after merge or split, update `FV2CrossProgressionAccountSnapshot`
  and preserve shared profile id, wallet id, currency, unlocked content, and
  achievement state on the remaining linked accounts.

Do not create a second publisher account when a player links Steam, PSN, Xbox
Live, Epic Games, GOG, or Nintendo credentials. New platform credentials attach
to the existing `OshunAccountId` or fail closed for manual review.

## Cross-Progression And Entitlement Routing

`FV2CrossPlatformProgressionSyncSystem` writes one central save payload and then
queues per-platform cloud-save plans. The central save is authoritative for
profile, shared currency, unlocked content, and achievement state. Native cloud
saves are transport copies and must not become independent identity roots.

`FV2PlatformSpecificEntitlementVerifier` validates ownership on the current
linked platform before loading game or DLC content. Missing DLC receipts may
queue provider entitlement API work, but unlinked current-platform accounts fail
closed. The entitlement result should be attached to the same runtime snapshot
that records the resolved identity and progression sync.

## Social Matchmaking And Voice

Cross-platform social features use one publisher identity graph:

- `FV2CrossPlatformFriendSystem` de-duplicates native friends by internal player
  id while preserving native provider aliases and platform icons.
- `FV2CrossPlatformPartyLobbySystem` invites unified friends into one cloud
  lobby and carries accepted party members into matchmaking.
- `FV2CrossPlatformVoiceChatSystem` creates central voice routes for the party
  and disables platform-native voice fallback for cross-platform parties.
- `FV2CrossPlatformMatchmakingSystem` matches across platforms by default when
  mutual crossplay is enabled, and applies the optional platform filter only for
  opt-out players.

Native ids remain visible for platform UX and compliance, but matchmaking,
party, and central voice decisions operate on `OshunAccountId` and
`InternalPlayerId`.

## Safety Privacy And Support Operations

Identity operations that affect ownership, sanctions, or player data are
support-audited:

- `FV2CrossPlatformBanSynchronizationSystem` resolves the source platform
  account and fans one FairPlay target out to every linked platform account.
- `FV2AccountDataPrivacyComplianceSystem` exports the Oshun identity profile and
  every linked platform account for GDPR/CCPA requests, and propagates deletion
  plans to every linked platform account after explicit confirmation.
- `FV2CrossPlatformIdentityAdminToolset` builds the customer support dashboard
  with one linked-account row per platform account, merge controls, split
  controls, ban management, and support audit evidence.

The support dashboard is an operational surface. Keep it dense, table-first, and
utility-focused: no marketing hero, no campaign copy, and no hidden linked
account state.

## Runtime Snapshot Evidence

`UV2OnlineServicesSubsystem::CaptureRuntimeSnapshot` is the shared signoff
surface. A complete cross-platform identity test pass should capture:

- unified identity service validity, linked platform account count, internal
  player id, and Oshun account id;
- platform linking OAuth verification and linked target account;
- account merge completion, progression merge, inventory de-duplication,
  achievement merge, and conflict count;
- cross-progression central sync, all-platform accessibility, and platform plan
  count;
- entitlement current-platform linkage, base-game ownership, DLC ownership, and
  content-load allow state;
- display-name update, platform-username separation, social projection, and
  projection count;
- matchmaking cross-platform result and opt-out platform filter evidence;
- ban synchronization source linkage, all-platform fanout, FairPlay result, and
  synced ban count;
- privacy export or deletion request id, linked platform count, and deletion
  propagation plan count;
- identity admin dashboard build state, merge/split/ban visibility, linked row
  count, and target Oshun account id.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-oshun-identity-binding.py
python3 V2/ue/Tools/check-v2-unified-player-identity-service.py
python3 V2/ue/Tools/check-v2-platform-account-linking-flow.py
python3 V2/ue/Tools/check-v2-cross-platform-account-merge-strategy.py
python3 V2/ue/Tools/check-v2-cross-platform-progression-sync.py
python3 V2/ue/Tools/check-v2-platform-specific-entitlement-verification.py
python3 V2/ue/Tools/check-v2-cross-platform-ban-synchronization.py
python3 V2/ue/Tools/check-v2-platform-account-unlinking.py
python3 V2/ue/Tools/check-v2-cross-platform-display-name.py
python3 V2/ue/Tools/check-v2-cross-platform-matchmaking.py
python3 V2/ue/Tools/check-v2-account-data-privacy-compliance.py
python3 V2/ue/Tools/check-v2-cross-platform-identity-admin-tools.py
python3 V2/ue/Tools/check-v2-cross-platform-friend-system.py
python3 V2/ue/Tools/check-v2-cross-platform-party-lobby.py
python3 V2/ue/Tools/check-v2-cross-platform-voice-chat.py
python3 V2/ue/Tools/check-v2-online-services-module.py
python3 V2/ue/Tools/check-v2-cross-platform-identity-integration-guide.py
python3 -m json.tool V2/ue/Content/V2/Online/CrossPlatformIdentity/CrossPlatformIdentityIntegrationGuide_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```