@mpgd/cli 0.57.0 → 0.58.0

package/templates/phaser-game/src/platform/guestIdentity.ts

@@ -0,0 +1,301 @@
+import {
+  createGuestServerSession,
+  createGuestSessionCoordinator,
+  createGuestSessionHttpBackend,
+  GuestSessionCoordinatorError,
+  type GuestServerSession,
+  type GuestSessionBackend,
+  type GuestSessionCoordinator,
+} from '@mpgd/game-services';
+import type { SecureCredentialStore } from '@mpgd/platform';
+
+import { setStarterCommerceServerPlayer } from './commerceAccountBinding';
+import { onStarterAccountDeleted } from './deleteAccount';
+
+/**
+ * How long one identity request may hold the boot: 5 seconds. Offline, the
+ * game starts after one timeout (three on the rare path that replaces an
+ * ended session) and runs without a server session. The limit stays on the
+ * coordinator's later requests too (refreshes in play), which are small.
+ */
+export const starterGuestIdentityTimeoutMs = 5_000;
+
+/** Where the installation id is kept, next to the refresh token in the device's secure store. */
+export const starterInstallationIdKey = 'mpgd.guest.installation';
+
+export type StarterGuestIdentity =
+  /** No `VITE_MPGD_IDENTITY_URL`: the game runs on the platform's local player and sells nothing on the stores. */
+  | { readonly status: 'not-configured' }
+  /** The target has no secure credential store (a browser build), so no refresh token can be kept. */
+  | { readonly status: 'unavailable' }
+  /**
+   * Signed in: `playerId` is the server player that purchases, rewards, and
+   * notifications use; pass `serverSession` to `setStarterServerSession`.
+   */
+  | {
+      readonly status: 'signed-in';
+      readonly playerId: string;
+      /** `guest` until a later account linking makes the session `authenticated`. */
+      readonly identityLevel: 'guest' | 'authenticated';
+      readonly coordinator: GuestSessionCoordinator;
+      readonly serverSession: GuestServerSession;
+    }
+  /** The identity service could not be reached or answered an error; the next launch tries again. */
+  | { readonly status: 'failed'; readonly code: string };
+
+/**
+ * Signs the player in to the guest identity service at `identityUrl`
+ * (`VITE_MPGD_IDENTITY_URL`, the reference Worker in the kit's
+ * `apps/game-identity-worker`): a server-issued guest on the first launch,
+ * the same guest restored from the device's Keychain or Keystore after that.
+ * On success it binds store purchases to the server player
+ * (`setStarterCommerceServerPlayer`) and returns the server session for
+ * `setStarterServerSession`, whose header the game-services client and the
+ * notifications runtime send (`main.ts` does both). Call it once, before the
+ * game services are created.
+ *
+ * A refresh token the service refused for good (revoked, replayed, or idle
+ * past the service's window) is logged out and a new guest is issued in its
+ * place: that session cannot come back, and without a linked account its
+ * player cannot either. Any other failure (offline, an outage) leaves the
+ * stored token alone for the next attempt (`createStarterGuestSignIn`
+ * retries), and until one succeeds purchases are refused with the reason
+ * (`ACCOUNT_BINDING_REQUIRED` on Google Play, a StoreKit error naming the
+ * missing session). One attempt: the game calls it through
+ * `createStarterGuestSignIn`.
+ */
+export async function startStarterGuestIdentity(input: {
+  readonly identityUrl: string | undefined;
+  readonly credentials: SecureCredentialStore | undefined;
+  readonly warn?: (message: string) => void;
+  /** Tests replace the HTTP backend; a game passes nothing. */
+  readonly backend?: GuestSessionBackend;
+  readonly createInstallationId?: () => string;
+}): Promise<StarterGuestIdentity> {
+  const warn = input.warn ?? ((message: string) => console.warn(message));
+  const identityUrl = input.identityUrl?.trim();
+  if (identityUrl === undefined || identityUrl === '') {
+    return { status: 'not-configured' };
+  }
+  const credentials = input.credentials;
+  if (credentials === undefined) {
+    warn(
+      '[identity] VITE_MPGD_IDENTITY_URL is set, but this target has no secure credential store; the game runs without a server session.',
+    );
+    return { status: 'unavailable' };
+  }
+  try {
+    const backend = input.backend
+      ?? createGuestSessionHttpBackend({ baseUrl: identityUrl, timeoutMs: starterGuestIdentityTimeoutMs });
+    const installationId = await loadInstallationId(credentials, input.createInstallationId);
+    const start = async () => {
+      const coordinator = createGuestSessionCoordinator({ backend, credentials, installationId });
+      return { coordinator, view: await coordinator.start() };
+    };
+    let started: Awaited<ReturnType<typeof start>>;
+    try {
+      started = await start();
+    } catch (error) {
+      if (!(error instanceof GuestSessionCoordinatorError) || error.code !== 'GUEST_SESSION_REJECTED') {
+        throw error;
+      }
+      warn(
+        '[identity] The stored guest session was ended by the identity service; starting a new guest.',
+      );
+      // Logout removes the dead token, so the next coordinator issues a new guest.
+      await createGuestSessionCoordinator({ backend, credentials, installationId }).logout();
+      started = await start();
+    }
+    const serverSession = createGuestServerSession(started.coordinator);
+    setStarterCommerceServerPlayer(() => serverSession.current()?.playerId);
+    // A deleted account: close the coordinator (and wait for a refresh in flight)
+    // before its credentials are removed, so a late refresh cannot save them again.
+    onStarterAccountDeleted(() => started.coordinator.logout(), { phase: 'session' });
+    return {
+      status: 'signed-in',
+      playerId: started.view.serverUserId,
+      identityLevel: started.view.identityLevel,
+      coordinator: started.coordinator,
+      serverSession,
+    };
+  } catch (error) {
+    const code = error instanceof GuestSessionCoordinatorError
+      ? error.code
+      : 'GUEST_IDENTITY_FAILED';
+    warn(
+      `[identity] Guest sign-in failed (${code}); purchases stay unavailable until a sign-in succeeds.`,
+    );
+    // Purchases bind to the server player or to nothing: never to the platform's local player.
+    setStarterCommerceServerPlayer(() => undefined);
+    return { status: 'failed', code };
+  }
+}
+
+/**
+ * The installation id the identity service issues guests for: random, made
+ * once, and kept in the secure store so a restored session keeps its
+ * installation. It is never authority, only the key of the service's
+ * per-installation limit and of the notification endpoints.
+ */
+async function loadInstallationId(
+  credentials: SecureCredentialStore,
+  create: (() => string) | undefined,
+): Promise<string> {
+  const stored = await credentials.load({ key: starterInstallationIdKey });
+  if (stored !== null && /^[A-Za-z0-9_-]{8,128}$/u.test(stored)) {
+    return stored;
+  }
+  // randomUUID needs a secure context; getRandomValues does not.
+  const installationId = create?.() ?? globalThis.crypto.randomUUID?.()
+    ?? [...globalThis.crypto.getRandomValues(new Uint8Array(16))]
+      .map((byte) => byte.toString(16).padStart(2, '0'))
+      .join('');
+  await credentials.save({ key: starterInstallationIdKey, value: installationId });
+  return installationId;
+}
+
+export type StarterSignedIn = Extract<StarterGuestIdentity, { readonly status: 'signed-in' }>;
+
+/** Waits between background sign-in retries after a failure: 5 s, 15 s, 1 min, then every 5 min. */
+export const starterGuestSignInRetryDelaysMs: readonly number[] = Object.freeze([
+  5_000, 15_000, 60_000, 300_000,
+]);
+
+/**
+ * The game's guest sign-in for the whole run: the first attempt at boot, and
+ * when that fails (offline, an outage), more attempts in the background
+ * (`starterGuestSignInRetryDelaysMs`, and at once when the browser reports
+ * `online`) until one succeeds. `ensure()` also tries at once, so a purchase
+ * or restore started after the network returned signs in first. Listeners
+ * hear the first success; the signed-in session never changes after that
+ * within the run.
+ */
+export interface StarterGuestSignIn {
+  /** False without `VITE_MPGD_IDENTITY_URL` or a secure credential store: nothing is ever tried. */
+  readonly configured: boolean;
+  current(): StarterSignedIn | undefined;
+  /** The session, signing in now when there is none (joins an attempt in flight). */
+  ensure(): Promise<StarterSignedIn | undefined>;
+  /** Called once, when the first sign-in succeeds (at once when it already has); returns the unsubscribe. */
+  onSignedIn(listener: (signedIn: StarterSignedIn) => void): () => void;
+  /** Stops the background retries. */
+  dispose(): void;
+}
+
+export function createStarterGuestSignIn(input: Parameters<typeof startStarterGuestIdentity>[0] & {
+  /** Tests inject the timer; the game passes nothing. */
+  readonly schedule?: (callback: () => void, delayMs: number) => () => void;
+  /** Subscribes to "the network is back"; defaults to the window `online` event. */
+  readonly onOnline?: (callback: () => void) => () => void;
+}): StarterGuestSignIn {
+  const identityUrl = input.identityUrl?.trim();
+  const configured = identityUrl !== undefined && identityUrl !== '' && input.credentials !== undefined;
+  const schedule = input.schedule ?? ((callback: () => void, delayMs: number) => {
+    const timer = setTimeout(callback, delayMs);
+    return () => clearTimeout(timer);
+  });
+  const listeners = new Set<(signedIn: StarterSignedIn) => void>();
+  let signedIn: StarterSignedIn | undefined;
+  let attempt: Promise<StarterSignedIn | undefined> | undefined;
+  /** Failed background attempts: on-demand ones (a purchase, a restore tap) do not lengthen the backoff. */
+  let backgroundFailures = 0;
+  let cancelRetry: (() => void) | undefined;
+  let disposed = false;
+  let stopOnline: (() => void) | undefined;
+
+  const scheduleRetry = () => {
+    if (disposed || signedIn !== undefined || cancelRetry !== undefined || !configured) {
+      return;
+    }
+    const delays = starterGuestSignInRetryDelaysMs;
+    const delay = delays[Math.min(backgroundFailures, delays.length - 1)] ?? 300_000;
+    cancelRetry = schedule(() => {
+      cancelRetry = undefined;
+      void attemptNow(true);
+    }, delay);
+  };
+
+  function ensure(): Promise<StarterSignedIn | undefined> {
+    return attemptNow(false);
+  }
+
+  function attemptNow(background: boolean): Promise<StarterSignedIn | undefined> {
+    if (signedIn !== undefined) {
+      return Promise.resolve(signedIn);
+    }
+    if (attempt !== undefined) {
+      return attempt;
+    }
+    if (!configured) {
+      // One attempt reports why (and warns, for a missing secure store); nothing to retry.
+      attempt = startStarterGuestIdentity(input).then(() => undefined);
+      return attempt;
+    }
+    cancelRetry?.();
+    cancelRetry = undefined;
+    attempt = startStarterGuestIdentity(input).then((result) => {
+      attempt = undefined;
+      if (result.status !== 'signed-in') {
+        if (background) {
+          backgroundFailures += 1;
+        }
+        scheduleRetry();
+        return undefined;
+      }
+      signedIn = result;
+      stopOnline?.();
+      for (const listener of [...listeners]) {
+        try {
+          listener(result);
+        } catch (error) {
+          console.error('[identity] a sign-in listener failed', error);
+        }
+      }
+      listeners.clear();
+      return result;
+    });
+    return attempt;
+  }
+
+  if (configured) {
+    const subscribeOnline = input.onOnline ?? ((callback: () => void) => {
+      if (typeof globalThis.addEventListener !== 'function') {
+        return () => undefined;
+      }
+      globalThis.addEventListener('online', callback);
+      return () => globalThis.removeEventListener('online', callback);
+    });
+    stopOnline = subscribeOnline(() => {
+      if (!disposed && signedIn === undefined) {
+        void ensure();
+      }
+    });
+  }
+
+  return {
+    configured,
+    current: () => signedIn,
+    ensure,
+    onSignedIn(listener) {
+      // Already signed in (a retry won the race with the caller): heard at once.
+      if (signedIn !== undefined) {
+        try {
+          listener(signedIn);
+        } catch (error) {
+          console.error('[identity] a sign-in listener failed', error);
+        }
+        return () => undefined;
+      }
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      disposed = true;
+      cancelRetry?.();
+      cancelRetry = undefined;
+      stopOnline?.();
+    },
+  };
+}

package/templates/phaser-game/src/platform/restorePurchases.ts

@@ -0,0 +1,205 @@
+import type { RecoverableMonetizationClient } from '@mpgd/game-services';
+import type { Locale } from '@mpgd/i18n';
+import type { PlatformGateway } from '@mpgd/platform';
+
+import { t } from '../i18n/messages';
+import { resolveStarterCommercePlayerId } from './commerceAccountBinding';
+
+/**
+ * Stores whose purchases are bound to the player (StoreKit
+ * `appAccountToken`, Google Play `obfuscatedAccountId`): restoring needs the
+ * server session's player (`guestIdentity.ts`), or an authenticated,
+ * non-local platform session, so the backend can match the purchases.
+ */
+const accountBoundStores: ReadonlySet<string> = new Set(['app-store', 'google-play']);
+
+/** Reconciler states of a purchase the backend ledger has granted. */
+const settledStates: ReadonlySet<string> = new Set(['granted', 'finishing', 'finished']);
+
+type RestoreRecovery = Pick<RecoverableMonetizationClient, 'restorePurchases' | 'commerceReconciler'>;
+
+export type StarterRestoreOutcome =
+  /**
+   * `granted`: purchases the backend ledger granted in this pass (0 when
+   * nothing new). `restoredHere`: how many of them the backend granted this
+   * player from a purchase another guest of the same store account made or
+   * holds (a reinstall, a new device, a second device); absent when none.
+   */
+  | { readonly outcome: 'restored'; readonly granted: number; readonly restoredHere?: number }
+  /**
+   * Some purchases are still unconfirmed; `granted` were confirmed in this
+   * pass. `atHolderLimit`: how many of the unconfirmed ones are already held
+   * by the most devices the backend allows (`PURCHASE_HOLDER_LIMIT_REACHED`).
+   */
+  | {
+      readonly outcome: 'incomplete';
+      readonly granted: number;
+      readonly restoredHere?: number;
+      readonly atHolderLimit?: number;
+    }
+  /** No server session can bind the purchases (no identity service configured). */
+  | { readonly outcome: 'needs-session' }
+  /** The guest sign-in failed again (offline, an outage); the control is a retry. */
+  | { readonly outcome: 'needs-connection' }
+  | { readonly outcome: 'failed' }
+  | { readonly outcome: 'unavailable' };
+
+export interface StarterRestorePurchases {
+  /** Whether the game should show a Restore Purchases control on this target. */
+  readonly available: boolean;
+  /**
+   * Asks the store to resynchronize (StoreKit `AppStore.sync()`; Google Play
+   * re-reads owned items) and runs the reconciler, which verifies every
+   * purchase through the backend ledger before anything is granted. A second
+   * tap while one runs joins it.
+   */
+  restore(): Promise<StarterRestoreOutcome>;
+}
+
+/**
+ * Restore Purchases for the starter's store or settings UI. App Review
+ * expects a restore control in an app that sells non-consumables (the
+ * catalog's `REMOVE_ADS`); the grant itself still comes only from the
+ * backend ledger through `monetizationRecovery.restorePurchases()`.
+ */
+export function createStarterRestorePurchases(input: {
+  readonly gateway: Pick<PlatformGateway, 'commerce' | 'identity'>;
+  /**
+   * The recovery client, or a getter for it: a run whose guest sign-in
+   * failed at boot has none until a later sign-in (`ensureSession`).
+   */
+  readonly monetizationRecovery?:
+    | RestoreRecovery
+    | (() => RestoreRecovery | undefined);
+  /**
+   * Signs in now if the run is not signed in yet (the session-gated game
+   * services' `ensureSession`); a restore then tries once more before
+   * answering `needs-connection`, which the control shows as a retry.
+   */
+  readonly ensureSession?: () => Promise<boolean>;
+}): StarterRestorePurchases {
+  const commerce = input.gateway.commerce;
+  const source = input.monetizationRecovery;
+  const recoveryNow = (): RestoreRecovery | undefined =>
+    typeof source === 'function' ? source() : source;
+  // Shown while the run can still sign in, so the player has a retry, never a dead control.
+  const available = commerce !== undefined && (recoveryNow() !== undefined || input.ensureSession !== undefined);
+  let running: Promise<StarterRestoreOutcome> | undefined;
+  const run = async (): Promise<StarterRestoreOutcome> => {
+    if (commerce === undefined) {
+      return { outcome: 'unavailable' };
+    }
+    if (input.ensureSession !== undefined && !(await input.ensureSession())) {
+      return { outcome: 'needs-connection' };
+    }
+    const recovery = recoveryNow();
+    if (recovery === undefined) {
+      // Signed in (or nothing to sign in), and still no recovery client: nothing a retry would change.
+      return { outcome: 'unavailable' };
+    }
+    if (accountBoundStores.has(commerce.store)
+      && await resolveStarterCommercePlayerId(input.gateway) === undefined) {
+      return { outcome: 'needs-session' };
+    }
+    // The reconciler reports store failures as events, not rejections. A
+    // failed resync (`restore`) is only this restore's; a failed read of the
+    // store's purchases (`available`, the whole restore on stores without a
+    // resync such as Google Play) may also come from a concurrent startup or
+    // resume pass, so it makes the result unconfirmed rather than failed.
+    let resyncFailed = false;
+    let readFailed = false;
+    // A purchase found, verified and finished within this pass is no longer
+    // recoverable afterwards, so the summaries miss it; its transitions do not.
+    const settledKeys = new Set<string>();
+    // Purchases the backend granted from another guest of this device's
+    // store account (a reinstall, a new device): "restored to this device".
+    const restoredKeys = new Set<string>();
+    // Purchases already held by the most devices the backend allows.
+    const limitKeys = new Set<string>();
+    const unsubscribe = recovery.commerceReconciler?.subscribe((event) => {
+      if (event.type === 'verify-result') {
+        if (event.response.verified && event.response.restoredAcrossPlayers === true) {
+          restoredKeys.add(event.record.idempotencyKey);
+        } else if (!event.response.verified
+          && event.response.reason === 'PURCHASE_HOLDER_LIMIT_REACHED') {
+          limitKeys.add(event.record.idempotencyKey);
+        }
+      } else if (event.type === 'transition' && settledStates.has(event.record.state)) {
+        settledKeys.add(event.record.idempotencyKey);
+      } else if (event.type === 'failure' && event.stage === 'restore') {
+        resyncFailed = true;
+      } else if (event.type === 'failure' && event.stage === 'available') {
+        readFailed = true;
+      }
+    });
+    try {
+      const summaries = (await recovery.restorePurchases())
+        .filter((summary) => summary.kind !== 'rewarded-ad');
+      if (resyncFailed) {
+        return { outcome: 'failed' };
+      }
+      for (const summary of summaries) {
+        if (summary.status === 'granted') {
+          settledKeys.add(summary.idempotencyKey);
+        }
+      }
+      const granted = settledKeys.size;
+      const restoredHere = [...restoredKeys].filter((key) => settledKeys.has(key)).length;
+      const restoredCount = restoredHere === 0 ? {} : { restoredHere };
+      const atHolderLimit = [...limitKeys].filter((key) => !settledKeys.has(key)).length;
+      // A purchase the backend has not settled yet (verify unreachable, still
+      // pending at the store, waiting on an operator, at the holder limit) is
+      // reported as such, never as "nothing to restore".
+      if (atHolderLimit > 0 || readFailed || summaries.some((summary) => summary.status === 'pending'
+        || summary.status === 'action-required' || summary.status === 'failed')) {
+        return {
+          outcome: 'incomplete',
+          granted,
+          ...restoredCount,
+          ...(atHolderLimit === 0 ? {} : { atHolderLimit }),
+        };
+      }
+      return { outcome: 'restored', granted, ...restoredCount };
+    } catch (error) {
+      console.error('[restore-purchases]', error);
+      return { outcome: 'failed' };
+    } finally {
+      unsubscribe?.();
+    }
+  };
+  return {
+    available,
+    restore() {
+      running ??= run().finally(() => {
+        running = undefined;
+      });
+      return running;
+    },
+  };
+}
+
+/** The player-facing line for a restore outcome, shared by the Phaser lobby and the lite button. */
+export function restoreOutcomeText(locale: Locale, result: StarterRestoreOutcome): string {
+  switch (result.outcome) {
+    case 'restored':
+      if (result.granted === 0) {
+        return t(locale, 'restoreNothing');
+      }
+      return (result.restoredHere ?? 0) > 0
+        ? t(locale, 'restoreToDevice', { count: result.granted })
+        : t(locale, 'restoreDone', { count: result.granted });
+    case 'incomplete':
+      if ((result.atHolderLimit ?? 0) > 0) {
+        return t(locale, 'restoreHolderLimit');
+      }
+      return result.granted === 0
+        ? t(locale, 'restoreIncomplete')
+        : t(locale, 'restorePartial', { count: result.granted });
+    case 'needs-session':
+      return t(locale, 'restoreNeedsSession');
+    case 'needs-connection':
+      return t(locale, 'restoreNeedsConnection');
+    default:
+      return t(locale, 'restoreFailed');
+  }
+}

package/templates/phaser-game/src/platform/serverSession.ts

@@ -45,6 +45,14 @@ export interface StarterServerSession {
   ): () => void;
   /** The current session's request headers, such as `{ authorization: 'Bearer …' }`. */
   readonly getHeaders: GameServicesHeaderResolver;
+  /**
+   * An account deletion confirmation from the identity service, which the
+   * game-services deletion route requires besides the access token
+   * (`createGuestServerSession` answers the coordinator's). Optional: a
+   * session without it (a development session) sends none, which only a
+   * development server accepts.
+   */
+  requestAccountDeletionConfirmation?(): Promise<string>;
 }
 
 /** The game's session, or the development one (see `developmentServerSession.ts`). */