@mpgd/game-services 0.28.1 → 0.30.0

package/README.md

@@ -236,9 +236,11 @@ with native Node imports, without a bundler or TypeScript runtime loader.
 ## Guest session and account binding foundation
 
 `createGuestSessionCoordinator` from `@mpgd/game-services/guest-session`
-accepts a game-owned `GuestSessionBackend` and a dedicated
-`SecureCredentialStore`. The kit does **not** issue tokens or infer server
-authentication from `installationId` or a local `playerId`. The backend must
+accepts a `GuestSessionBackend` and a dedicated `SecureCredentialStore`.
+The client never issues tokens or infers server authentication from
+`installationId` or a local `playerId`; the reference guest identity Worker
+in the kit repository (`apps/game-identity-worker`) is one backend that does,
+over `createGuestSessionHttpBackend`. The backend must
 authenticate opaque refresh tokens, verify external account proofs, atomically
 deduplicate account binding by idempotency key, return `conflict` for an account
 owned by another server user, and revoke sessions durably. It must define
@@ -277,6 +279,19 @@ family (not a refresh), and `getHeaders()` refreshes an expired access token
 before answering, and one that expires within a minute in the background
 (once per token, at most every ten seconds).
 
+`createGuestSessionHttpBackend({ baseUrl })` is a `GuestSessionBackend` over
+the HTTP routes in `guestIdentityHttpRoutes`, which the reference identity
+Worker (`apps/game-identity-worker`) serves. It takes an `https:` base URL (or
+`http:` on a local development host), never follows a redirect, and times a
+request out after 15 seconds; a `200` that is not a JSON object is a failure,
+so a logout is never assumed revoked. A refresh token the service refuses for
+good on a refresh or a binding (revoked, replayed, expired, or unknown) throws
+`GuestSessionRejectedError`, which the coordinator reports as
+`GUEST_SESSION_REJECTED`; it then stops using that session (`current()` is
+`undefined` and later calls fail with `GUEST_SESSION_NOT_READY` without a
+request). Log out (it removes the dead token) and start a new coordinator for
+a new guest. Any other failure stays `GUEST_SESSION_BACKEND_FAILED`.
+
 Binding an external account never switches to a different server user on a
 client callback. It does not merge purchases, currency, or progress. Use the
 existing `progress-link` nonce/idempotency service separately for a

package/dist/account-deletion.d.ts

@@ -0,0 +1,306 @@
+/**
+* Account deletion (Google Play "account deletion requirements", App Store
+* Review Guideline 5.1.1(v)): the server erases what game services keep for
+* a player, keeps only the purchase records the law requires (detached from
+* the player), and has the identity service end the player's sessions.
+*
+* Retention decision (see docs/GAME_SERVICES_BACKEND.md#account-deletion):
+* - Purchase ledger rows (`source: 'purchase'`), the revocations that reverse
+*   them and their notes are kept for five years, the period the Korean
+*   E-Commerce Act's enforcement decree (article 6(1)) sets for payment and
+*   supply records. They are rewritten so nothing links them to the player:
+*   a random ledger id and idempotency key, the player id replaced by
+*   `deleted:<deletionId>`, and a `playerId` payload key removed. What
+*   identifies the store transaction (store, product, platform transaction
+*   and order ids, the token digest, the store's own account binding) stays,
+*   so a dispute can be answered from the store receipt and the same store
+*   purchase can never be granted again.
+* - Everything else (rewarded-ad and admin grants, scores, verified
+*   leaderboard entries, notification endpoints, consent records, notices,
+*   reminders, sends and their history) is deleted.
+*/
+import { type GameServicesHeaderResolver } from './request-headers.js';
+import type { EntitlementLedgerPayload } from './types.js';
+/** The public route a signed-in player deletes their own account through. */
+export declare const accountDeletionEndpoint = "/game-services/account/delete";
+/**
+* The request header carrying the deletion confirmation: a short-lived,
+* single-use token the identity service issues to the holder of the
+* session's refresh token after the in-app second step. A bare access
+* token (15 minutes, sent with every request) is not enough to destroy the
+* account.
+*/
+export declare const accountDeletionConfirmationHeader = "x-mpgd-account-deletion-confirmation";
+/**
+* The longest confirmation the server accepts (characters); the identity
+* service issues shorter ones.
+*/
+export declare const accountDeletionConfirmationMaxLength = 4096;
+/**
+* The identity service's check of a deletion confirmation: bound to the
+* player, unexpired, and not used before; a confirmed token is consumed.
+*/
+export interface AccountDeletionConfirmationVerifier {
+  verifyAccountDeletionConfirmation(input: {
+    readonly playerId: string;
+    readonly confirmation: string;
+  }): Promise<{
+    readonly confirmed: boolean;
+  }>;
+}
+/** How long the detached purchase records are kept (Korean E-Commerce Act decree, art. 6(1)). */
+export declare const retainedPurchaseRecordYears = 5;
+/** The prefix of the player id that replaces a deleted player's on the records kept. */
+export declare const retainedPlayerIdPrefix = "deleted:";
+export interface PlayerDataErasureInput {
+  /** The player whose data is erased. */
+  readonly playerId: string;
+  /** Replaces the player id on the purchase records kept (`deleted:<deletionId>`). */
+  readonly retainedPlayerId: string;
+}
+export interface PlayerDataErasureResult {
+  /** Rows deleted. */
+  readonly deleted: number;
+  /** Purchase ledger rows kept, detached from the player. */
+  readonly retained: number;
+}
+/** One store's part of an account deletion; idempotent, so it can run twice. */
+export interface PlayerDataEraser {
+  erasePlayerData(input: PlayerDataErasureInput): Promise<PlayerDataErasureResult>;
+}
+/**
+* The identity service's part (implemented by the identity Worker): revoke
+* every session family of the player and delete the guest record, so no
+* session authenticates as the player again. Idempotent: an unknown player
+* succeeds. The game-services session bindings must stop accepting the
+* player's access tokens at once too (not when they expire): the erasure
+* runs right after, and only a request authenticated before the call can
+* still write. It should delete the record last (or atomically): a failure
+* after the sessions are revoked answers the player a retryable error, but
+* the retry can no longer authenticate.
+*/
+export interface AccountDeletionIdentity {
+  deletePlayer(input: {
+    readonly playerId: string;
+  }): Promise<unknown>;
+}
+/** The audit entry of one deletion; it carries no player id or other personal data. */
+export interface AccountDeletionAuditEntry {
+  readonly deletionId: string;
+  readonly requestedAt: string;
+  readonly completedAt: string;
+  /** `not-configured` only where no identity service exists (local development). */
+  readonly identity: 'deleted' | 'not-configured';
+  /**
+  * `false` when a store's erasure still failed after the
+  * identity was deleted: the erasure stays pending (with the player id)
+  * until `finishPendingAccountErasures` completes it and records a
+  * `complete: true` entry under the same `deletionId`.
+  */
+  readonly complete: boolean;
+  /** Rows this request deleted; a retry after a failure counts only its own. */
+  readonly deleted: number;
+  readonly retained: number;
+}
+export interface AccountDeletionReceipt {
+  readonly status: 'deleted';
+  readonly deletionId: string;
+  readonly completedAt: string;
+  /**
+  * Purchase ledger rows (grants, the revocations reversing them, and their
+  * notes) this request kept, detached from the player, for the retention
+  * period. A retry after a partial failure counts only what it kept itself.
+  */
+  readonly retainedPurchaseRecords: number;
+}
+export type AccountDeletionErrorCode = 
+/** No signed-in session, or a session that no longer authenticates. */
+'UNAUTHORIZED'
+/** The request named another player. */
+| 'PLAYER_ID_MISMATCH'
+/**
+* No deletion confirmation, or one the identity service refused (expired,
+* used, another player's). Get a new one and try again.
+*/
+| 'ACCOUNT_DELETION_CONFIRMATION_REQUIRED'
+/** This server has no authentication or identity service for deletion. */
+| 'ACCOUNT_DELETION_NOT_CONFIGURED'
+/**
+* The server failed before the identity was deleted (or answered 5xx, 408, 425, or 429);
+* every step is idempotent, so retrying is safe.
+*/
+| 'ACCOUNT_DELETION_FAILED'
+/** The server refused the request as malformed (another 4xx); retrying does not help. */
+| 'ACCOUNT_DELETION_REJECTED'
+/** The request did not reach the server or its answer was not read. */
+| 'ACCOUNT_DELETION_UNREACHABLE';
+export declare class AccountDeletionError extends Error {
+  readonly code: AccountDeletionErrorCode;
+  readonly retryable: boolean;
+  /**
+  * Whether the request may have reached the server. For
+  * `ACCOUNT_DELETION_UNREACHABLE` it was sent and its answer was lost or
+  * unreadable, so the deletion may have completed; for `UNAUTHORIZED` the
+  * server refused the session (`false`: no session on this device).
+  */
+  readonly requestSent: boolean;
+  constructor(code: AccountDeletionErrorCode, options?: {
+    readonly cause?: unknown;
+    readonly requestSent?: boolean;
+  });
+}
+export interface AccountDeletionService {
+  /**
+  * Records the erasure as pending, deletes the identity (no session
+  * authenticates as the player any more, so nothing new is written), marks
+  * the pending erasure `identity-deleted`, then erases every store. A
+  * failure before the identity is deleted rejects with a retryable
+  * `ACCOUNT_DELETION_FAILED` and has erased nothing, so a misconfigured
+  * identity service never leaves a live account stripped of its data. Once
+  * the identity is deleted the player cannot retry, so each store is tried
+  * three times with a short backoff; a store that still fails leaves the
+  * erasure pending for `finishPendingAccountErasures` (the Worker's cron)
+  * and is reported in the audit entry (`complete: false`), never to the
+  * player.
+  */
+  deletePlayerAccount(input: {
+    readonly playerId: string;
+  }): Promise<AccountDeletionReceipt>;
+}
+/**
+* An erasure kept across the identity deletion. It holds the player id, so
+* it lives only until the erasure completes.
+*/
+export interface PendingAccountErasure extends PlayerDataErasureInput {
+  readonly deletionId: string;
+  readonly recordedAt: string;
+  /**
+  * `erasing` until the identity service confirmed the deletion. The sweep
+  * erases only `identity-deleted` erasures: an `erasing` one belongs to a
+  * request that failed or died before that confirmation, whose player most
+  * likely still exists and retries, so the sweep discards it once it is
+  * older than `staleErasingPendingMs` instead of erasing a live player.
+  * Residual gap: an identity call that committed but whose answer was lost
+  * on all three attempts (or a process that died before the mark) leaves
+  * an `erasing` entry, and
+  * the player's data then stays under the deleted id. Closing it needs the
+  * identity service to answer whether a player exists, which the binding
+  * does not offer yet.
+  */
+  readonly phase: 'erasing' | 'identity-deleted';
+  /** Sweep attempts so far. */
+  readonly attempts: number;
+  /** When the sweep last tried it; the store lists least recently tried first. */
+  readonly attemptedAt?: string;
+}
+export interface PendingAccountErasureStore {
+  /** Inserts or replaces the erasure named by `deletionId`. */
+  put(erasure: PendingAccountErasure): Promise<void>;
+  clear(input: {
+    readonly deletionId: string;
+  }): Promise<void>;
+  /**
+  * At most `limit` erasures: `identity-deleted` ones first, then by least
+  * recently tried (`attemptedAt`, else `recordedAt`). With
+  * `identityDeletedBefore`, an `identity-deleted` erasure recorded after it
+  * is left out (it is not due for its final pass yet), so young entries
+  * never take the slots of due ones.
+  */
+  list(input: {
+    readonly limit: number;
+    readonly identityDeletedBefore?: string;
+  }): Promise<readonly PendingAccountErasure[]>;
+}
+/** An `erasing` erasure older than this (one hour) is discarded by the sweep. */
+export declare const staleErasingPendingMs: number;
+/**
+* The sweep erases an `identity-deleted` erasure once more, and only then
+* clears it, at its first run at least this long (15 minutes) after the
+* request: longer than any request that authenticated before the identity
+* was deleted can still run. Until then the pending entry (with the player
+* id) is kept, so a deployment must run the sweep (the Worker's cron).
+*/
+export declare const finalErasureDelayMs: number;
+export declare function createInMemoryPendingAccountErasureStore(): PendingAccountErasureStore;
+export declare function createAccountDeletionService(input: {
+  readonly erasers: readonly PlayerDataEraser[];
+  /**
+  * The identity service. `null` only for local development without one:
+  * the player's sessions then survive the deletion.
+  */
+  readonly identity: AccountDeletionIdentity | null;
+  /** Keeps an erasure across the identity deletion; see `finishPendingAccountErasures`. */
+  readonly pending: PendingAccountErasureStore;
+  /** Records the audit entry. A failure is logged and does not fail the deletion. */
+  readonly audit?: (entry: AccountDeletionAuditEntry) => Promise<void>;
+  readonly now?: () => string;
+  readonly createDeletionId?: () => string;
+  /** Waits between retry attempts; defaults to a timer. */
+  readonly sleep?: (ms: number) => Promise<void>;
+}): AccountDeletionService;
+export interface PendingAccountErasureSweep {
+  /** `identity-deleted` erasures that every store completed and that were cleared. */
+  readonly finished: number;
+  /** Erasures a store failed (kept for the next sweep), and stale entries that could not be discarded. */
+  readonly failed: number;
+  /** Stale `erasing` erasures discarded without erasing. */
+  readonly discarded: number;
+}
+/**
+* Finishes erasures a deletion left pending: an `identity-deleted` one is
+* erased again `finalErasureDelayMs` after the request (every deletion
+* gets this final pass, which removes what a request authenticated before
+* the identity was deleted wrote later) and cleared once every store
+* completed it, with an audit entry that marks the deletion complete; an
+* `erasing` one older than
+* `staleErasingPendingMs` is discarded without erasing. Run it from a
+* scheduled job. A failing erasure is tried again later, least recently
+* tried first, so one that keeps failing does not block the others.
+*/
+export declare function finishPendingAccountErasures(input: {
+  readonly erasers: readonly PlayerDataEraser[];
+  readonly pending: PendingAccountErasureStore;
+  readonly audit?: (entry: AccountDeletionAuditEntry) => Promise<void>;
+  readonly now?: () => string;
+  readonly limit?: number;
+}): Promise<PendingAccountErasureSweep>;
+/** The player id stored on a deleted player's kept purchase records. */
+export declare function isRetainedPlayerId(playerId: string): boolean;
+/** Refuses an erasure input whose ids could re-erase another deletion's kept records. */
+export declare function assertPlayerDataErasureInput(input: PlayerDataErasureInput): PlayerDataErasureInput;
+/** A fresh id for a kept ledger row; it carries nothing of the player's ids. */
+export declare function createRetainedLedgerEntryId(): string;
+/** The kept row's payload: the store transaction stays, the player id goes. */
+export declare function detachRetainedLedgerPayload(payload: EntitlementLedgerPayload): EntitlementLedgerPayload;
+export interface AccountDeletionFetchResponse {
+  readonly status: number;
+  text(): Promise<string>;
+}
+export type AccountDeletionFetch = (url: string, init: {
+  readonly method: 'POST';
+  readonly headers: Record<string, string>;
+  readonly body: string;
+  readonly signal?: AbortSignal;
+}) => Promise<AccountDeletionFetchResponse>;
+/** How long `deleteAccount()` waits for the session and the server by default. */
+export declare const defaultAccountDeletionTimeoutMs = 30000;
+export interface AccountDeletionClient {
+  /**
+  * Deletes the signed-in player's account on the server. Resolves with the
+  * receipt; rejects with an `AccountDeletionError`. After an
+  * `ACCOUNT_DELETION_UNREACHABLE` failure the deletion may have completed:
+  * a retry that answers `UNAUTHORIZED` means the session no longer exists.
+  */
+  deleteAccount(input?: {
+    /** The identity service's deletion confirmation (`accountDeletionConfirmationHeader`). */
+    readonly confirmation?: string;
+  }): Promise<AccountDeletionReceipt>;
+}
+export declare function createAccountDeletionClient(input: {
+  readonly baseUrl: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly getHeaders?: GameServicesHeaderResolver;
+  readonly fetch?: AccountDeletionFetch;
+  /** Deadline for resolving the session headers and the server's answer; 30 s by default. */
+  readonly timeoutMs?: number;
+}): AccountDeletionClient;