@mpgd/game-services 0.27.1 → 0.28.0

package/README.md

@@ -259,6 +259,24 @@ normalized to token-free coordinator codes, not forwarded with raw messages.
 `getHeaders()` can be passed as the Game Services runtime's
 `getHeaders` resolver. The public session view omits both bearer tokens.
 
+Each view also carries `sessionFamilyId`, the stable session-family id: one
+value for the session's whole life, whatever its `sessionId` does on refresh.
+A backend should send it (`sessionFamilyId` in its session answers, the same
+id its identity service answers to the notifications Worker). A backend that
+omits it gets a derived id that changes only where the backend's family might
+have: at a new guest, at a bound account whose `sessionId` changed, and at a
+restore whose saved family (`<credentialKey>.family` in the same secure
+storage, written before the token and removed at logout) cannot be read. Such
+a backend must give a binding that starts a new family a new `sessionId`.
+`current()` reads the active view and `onSession(listener)` hears each new one.
+`createGuestServerSession(coordinator)` reads the coordinator as the
+server-backed session the notifications client and the starter's
+`setStarterServerSession` take: `current()` answers the server user as
+`playerId` and the family id as `sessionId`, `onAuthenticated` hears a new
+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).
+
 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/development-session.d.ts

@@ -0,0 +1,64 @@
+/**
+* Local development notification sessions: an unauthenticated stand-in for
+* the game's identity service, so a developer can try the notifications
+* routes of a local game-services Worker before writing one.
+*
+* The Worker accepts `Authorization: Bearer mpgd-dev.<playerId>.<sessionId>.<installationId>`
+* only with `MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS = "true"`,
+* without a `GAME_SERVICES_NOTIFICATIONS_AUTH` binding, never with the D1
+* store, and only on a request to a local host (loopback, `*.localhost`, or
+* the Android emulator's `10.0.2.2`). Anyone can write such a header, so it is no authentication:
+* never use it outside local development.
+*/
+/** The scheme and prefix of a development session's `Authorization` header. */
+export declare const developmentNotificationSessionPrefix = "Bearer mpgd-dev.";
+/** The ids a development session token names. */
+export interface DevelopmentNotificationSession {
+  readonly playerId: string;
+  readonly sessionId: string;
+  readonly installationId: string;
+}
+/** Whether `value` can be one id of a development session. */
+export declare function isDevelopmentNotificationSessionId(value: unknown): value is string;
+/**
+* The `Authorization` header value for a development session. Throws when
+* an id is not 1 to 64 letters, digits, `_`, or `-`.
+*/
+export declare function formatDevelopmentNotificationSessionAuthorization(session: DevelopmentNotificationSession): string;
+/**
+* The session a development `Authorization` header names, or `undefined`
+* for any other value: exactly `Bearer mpgd-dev.` and three ids separated
+* by `.`, each 1 to 64 letters, digits, `_`, or `-`. It has no `expiresAt`.
+*/
+export declare function parseDevelopmentNotificationSessionAuthorization(authorization: unknown): DevelopmentNotificationSession | undefined;
+/** A development session as the game-services clients read a server-backed session. */
+export interface DevelopmentServerSession {
+  /** The development session; it is signed in from creation and never changes. */
+  current(): {
+    readonly playerId: string;
+    readonly sessionId: string;
+  };
+  /** Never calls `listener`: the session is current from creation. Returns the unsubscribe. */
+  onAuthenticated(listener: (session: {
+    readonly playerId: string;
+    readonly sessionId: string;
+  }) => void): () => void;
+  /** `{ authorization: 'Bearer mpgd-dev.…' }`. */
+  getHeaders(): Readonly<Record<'authorization', string>>;
+}
+/**
+* A server-backed session for local development against a Worker that has
+* `MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS = "true"`. `mode`
+* must be the build's real mode (`import.meta.env.MODE`): `production`
+* throws, so a production build cannot create one. A build in another mode
+* named like production (`prod`, `release`) is not refused here; gate the
+* call on `import.meta.env.DEV` as the starter does. `sessionId` defaults to
+* `dev-<installationId>` (its first 64 characters). Ids are 1 to 64
+* letters, digits, `_`, or `-`.
+*/
+export declare function createDevelopmentServerSession(input: {
+  readonly mode: string;
+  readonly playerId: string;
+  readonly installationId: string;
+  readonly sessionId?: string;
+}): DevelopmentServerSession;

package/dist/development-session.js

@@ -0,0 +1,79 @@
+import { resolveGameServicesAuthorityMode } from './runtime.js';
+/**
+ * Local development notification sessions: an unauthenticated stand-in for
+ * the game's identity service, so a developer can try the notifications
+ * routes of a local game-services Worker before writing one.
+ *
+ * The Worker accepts `Authorization: Bearer mpgd-dev.<playerId>.<sessionId>.<installationId>`
+ * only with `MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS = "true"`,
+ * without a `GAME_SERVICES_NOTIFICATIONS_AUTH` binding, never with the D1
+ * store, and only on a request to a local host (loopback, `*.localhost`, or
+ * the Android emulator's `10.0.2.2`). Anyone can write such a header, so it is no authentication:
+ * never use it outside local development.
+ */
+/** The scheme and prefix of a development session's `Authorization` header. */
+export const developmentNotificationSessionPrefix = 'Bearer mpgd-dev.';
+/** Each id: 1 to 64 letters, digits, `_`, or `-` (so `.` can separate them). */
+const idPattern = /^[A-Za-z0-9_-]{1,64}$/u;
+/** Whether `value` can be one id of a development session. */
+export function isDevelopmentNotificationSessionId(value) {
+    return typeof value === 'string' && idPattern.test(value);
+}
+/**
+ * The `Authorization` header value for a development session. Throws when
+ * an id is not 1 to 64 letters, digits, `_`, or `-`.
+ */
+export function formatDevelopmentNotificationSessionAuthorization(session) {
+    const { playerId, sessionId, installationId } = session;
+    if (!isDevelopmentNotificationSessionId(playerId)
+        || !isDevelopmentNotificationSessionId(sessionId)
+        || !isDevelopmentNotificationSessionId(installationId)) {
+        throw new Error('A development notification session needs a playerId, sessionId, and installationId '
+            + 'of 1 to 64 letters, digits, _ or -.');
+    }
+    return `${developmentNotificationSessionPrefix}${playerId}.${sessionId}.${installationId}`;
+}
+/**
+ * The session a development `Authorization` header names, or `undefined`
+ * for any other value: exactly `Bearer mpgd-dev.` and three ids separated
+ * by `.`, each 1 to 64 letters, digits, `_`, or `-`. It has no `expiresAt`.
+ */
+export function parseDevelopmentNotificationSessionAuthorization(authorization) {
+    if (typeof authorization !== 'string' || !authorization.startsWith(developmentNotificationSessionPrefix)) {
+        return undefined;
+    }
+    const parts = authorization.slice(developmentNotificationSessionPrefix.length).split('.');
+    if (parts.length !== 3 || !parts.every(isDevelopmentNotificationSessionId)) {
+        return undefined;
+    }
+    const [playerId, sessionId, installationId] = parts;
+    return { playerId, sessionId, installationId };
+}
+/**
+ * A server-backed session for local development against a Worker that has
+ * `MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS = "true"`. `mode`
+ * must be the build's real mode (`import.meta.env.MODE`): `production`
+ * throws, so a production build cannot create one. A build in another mode
+ * named like production (`prod`, `release`) is not refused here; gate the
+ * call on `import.meta.env.DEV` as the starter does. `sessionId` defaults to
+ * `dev-<installationId>` (its first 64 characters). Ids are 1 to 64
+ * letters, digits, `_`, or `-`.
+ */
+export function createDevelopmentServerSession(input) {
+    if (resolveGameServicesAuthorityMode(input.mode) === 'production') {
+        throw new Error('Development notification sessions are refused in a production build.');
+    }
+    const session = {
+        playerId: input.playerId,
+        // Cut to the id limit, so a 61- to 64-character installation id still has a default.
+        sessionId: input.sessionId ?? `dev-${input.installationId}`.slice(0, 64),
+        installationId: input.installationId,
+    };
+    const authorization = formatDevelopmentNotificationSessionAuthorization(session);
+    const current = Object.freeze({ playerId: session.playerId, sessionId: session.sessionId });
+    return {
+        current: () => current,
+        onAuthenticated: () => () => undefined,
+        getHeaders: () => ({ authorization }),
+    };
+}

package/dist/guest-session.d.ts

@@ -20,13 +20,36 @@ export interface ServerGuestSessionCredentials {
   readonly serverUserId: string;
   /** May rotate on refresh or binding; serverUserId remains the ownership key. */
   readonly sessionId: string;
+  /**
+  * The stable session-family id: one value for the session's whole life,
+  * across every refresh, which a new guest (and any new sign-in) replaces.
+  * It is the `sessionId` the identity service answers to the notifications
+  * Worker's `authenticateNotificationSession`. Optional on the wire (`null`
+  * reads as absent): when a backend omits it, the coordinator derives one
+  * (see `createGuestSessionCoordinator`). A backend that omits it and starts
+  * a new family at an account binding must give that binding a new
+  * `sessionId`.
+  */
+  readonly sessionFamilyId?: string;
   readonly identityLevel: 'guest' | 'authenticated';
   readonly accessToken: string;
   readonly refreshToken: string;
   readonly accessExpiresAt: string;
 }
 /** Identity view: neither bearer token is returned to game code. */
-export type ServerGuestSessionView = Omit<ServerGuestSessionCredentials, 'accessToken' | 'refreshToken'>;
+export interface ServerGuestSessionView {
+  readonly serverUserId: string;
+  /** May rotate on refresh or binding. */
+  readonly sessionId: string;
+  /**
+  * The stable session-family id: the backend's, or the one the coordinator
+  * derived when the backend sent none. Use it, not `sessionId`, wherever a
+  * session must keep one id across refreshes (the notifications client).
+  */
+  readonly sessionFamilyId: string;
+  readonly identityLevel: 'guest' | 'authenticated';
+  readonly accessExpiresAt: string;
+}
 export type AccountBindingOutcome = {
   readonly status: 'bound' | 'already-bound';
   readonly session: ServerGuestSessionCredentials;
@@ -61,6 +84,17 @@ export declare class GuestSessionCoordinatorError extends Error {
 }
 export interface GuestSessionCoordinator {
   start(): Promise<ServerGuestSessionView>;
+  /** The active session's view, or `undefined` before `start()` settles, after a failure, and after logout. */
+  current(): ServerGuestSessionView | undefined;
+  /**
+  * Calls `listener` with the new view each time a session becomes active:
+  * `start()`, each `refresh()`, and a bound `bindAccount()`. A refresh in
+  * the same family repeats the family id. Returns the unsubscribe. A
+  * listener that throws does not fail the operation. Nothing is announced
+  * when a session stops being active (a failed save, logout): read
+  * `current()` for that.
+  */
+  onSession(listener: (session: ServerGuestSessionView) => void): () => void;
   refresh(): Promise<ServerGuestSessionView>;
   bindAccount(input: {
     readonly externalProof: string;
@@ -74,6 +108,28 @@ export interface GuestSessionCoordinator {
 /**
 * Serializes token mutation and closes synchronously on logout. Native secure
 * storage failures never fall back to ordinary game storage or mint a new guest.
+*
+* The session-family id is the backend's `sessionFamilyId` whenever it sends
+* one. A backend that omits it gets a derived id, which only ever changes in
+* the safe direction (a new id where the backend's family might be new):
+* - `issueGuest` starts a family at the new `sessionId`;
+* - a refresh keeps the family, however the `sessionId` rotates;
+* - a bound account keeps it while the `sessionId` stays, and starts one at
+*   the new `sessionId` when that changes (so such a backend must change
+*   the `sessionId` when a binding starts a new family);
+* - a restore from secure storage keeps the family saved with the refresh
+*   token (`<credentialKey>.family`), or starts one at the restored
+*   `sessionId` when none can be read;
+* - logout removes the saved family with the token.
+* The derived id is not the identity service's id, and does not need to be: the
+* notifications runtime only compares it with the id it registered under,
+* and registers again when it changes. Saving the family is best effort:
+* it is written before the token, so an interrupted save never pairs an
+* older family with a newer token, and a family that cannot be saved is
+* removed, so the next restore starts one. Only a store that fails both that
+* save and that removal, and then saves the token, can leave an older family
+* next to it; the token is saved regardless, since losing it would lose the
+* guest.
 */
 export declare function createGuestSessionCoordinator(input: {
   readonly backend: GuestSessionBackend;
@@ -82,3 +138,55 @@ export declare function createGuestSessionCoordinator(input: {
   readonly credentialKey?: string;
   readonly now?: () => number;
 }): GuestSessionCoordinator;
+/**
+* A guest session as the game-services clients read a server-backed
+* session: the starter's `StarterServerSession`, and the notifications
+* client's identity and header resolver.
+*/
+export interface GuestServerSession {
+  /**
+  * The active session, or `undefined` while none is: `playerId` is the
+  * server user, and `sessionId` is the session-family id, which stays the
+  * same across refreshes.
+  */
+  current(): {
+    readonly playerId: string;
+    readonly sessionId: string;
+  } | undefined;
+  /**
+  * Calls `listener` when a session becomes current after the subscription:
+  * the first `start()`, or a binding that starts a new family. A refresh in
+  * the same family is not announced. Returns the unsubscribe.
+  */
+  onAuthenticated(listener: (session: {
+    readonly playerId: string;
+    readonly sessionId: string;
+  }) => void): () => void;
+  /**
+  * The `Authorization` header. An expired access token is refreshed first,
+  * and a failed refresh throws its error (`GUEST_SESSION_BACKEND_FAILED`,
+  * `GUEST_SESSION_OWNERSHIP_CONFLICT`, ...). A token that expires within
+  * `refreshAheadMs` is answered at once while a refresh runs in the
+  * background: once per token, and at most once per
+  * `guestServerSessionRefreshAheadIntervalMs`, so a backend whose tokens
+  * live shorter than the lead is not refreshed on every request; a failed
+  * background refresh is retried when the token has expired.
+  */
+  getHeaders(): Promise<Readonly<Record<'authorization', string>>>;
+}
+/** How long before its access token expires `createGuestServerSession` refreshes a session: one minute. */
+export declare const defaultGuestServerSessionRefreshAheadMs = 60000;
+/** The least time between two background refreshes of `createGuestServerSession`. */
+export declare const guestServerSessionRefreshAheadIntervalMs = 10000;
+/**
+* Reads a `GuestSessionCoordinator` as a server-backed session, with the
+* session-family id as the session id, which the notifications client and
+* the Worker need (it must not change on refresh). The game still starts
+* the coordinator, binds accounts, and logs out through it. If you gave
+* `createGuestSessionCoordinator` a `now`, pass the same function here, so
+* both read expiry on one clock.
+*/
+export declare function createGuestServerSession(coordinator: GuestSessionCoordinator, options?: {
+  readonly refreshAheadMs?: number;
+  readonly now?: () => number;
+}): GuestServerSession;

package/dist/guest-session.js

@@ -11,6 +11,28 @@ const defaultCredentialKey = 'mpgd.guest.refresh';
 /**
  * Serializes token mutation and closes synchronously on logout. Native secure
  * storage failures never fall back to ordinary game storage or mint a new guest.
+ *
+ * The session-family id is the backend's `sessionFamilyId` whenever it sends
+ * one. A backend that omits it gets a derived id, which only ever changes in
+ * the safe direction (a new id where the backend's family might be new):
+ * - `issueGuest` starts a family at the new `sessionId`;
+ * - a refresh keeps the family, however the `sessionId` rotates;
+ * - a bound account keeps it while the `sessionId` stays, and starts one at
+ *   the new `sessionId` when that changes (so such a backend must change
+ *   the `sessionId` when a binding starts a new family);
+ * - a restore from secure storage keeps the family saved with the refresh
+ *   token (`<credentialKey>.family`), or starts one at the restored
+ *   `sessionId` when none can be read;
+ * - logout removes the saved family with the token.
+ * The derived id is not the identity service's id, and does not need to be: the
+ * notifications runtime only compares it with the id it registered under,
+ * and registers again when it changes. Saving the family is best effort:
+ * it is written before the token, so an interrupted save never pairs an
+ * older family with a newer token, and a family that cannot be saved is
+ * removed, so the next restore starts one. Only a store that fails both that
+ * save and that removal, and then saves the token, can leave an older family
+ * next to it; the token is saved regardless, since losing it would lose the
+ * guest.
  */
 export function createGuestSessionCoordinator(input) {
     if (typeof input.installationId !== 'string' || input.installationId.trim() === '') {
@@ -20,8 +42,12 @@ export function createGuestSessionCoordinator(input) {
     if (credentialKey.trim() === '') {
         throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
     }
+    const familyKey = `${credentialKey}.family`;
     const now = input.now ?? Date.now;
     let current;
+    /** The family id last written to secure storage, as far as this coordinator knows. */
+    let savedFamily;
+    const listeners = new Set();
     let status = 'idle';
     let tail = Promise.resolve();
     let startInFlight;
@@ -65,7 +91,46 @@ export function createGuestSessionCoordinator(input) {
             throw new GuestSessionCoordinatorError('GUEST_SESSION_BACKEND_FAILED');
         }
     }
+    /** The family saved with the stored refresh token, or `undefined` when none can be read. */
+    async function loadStoredFamily() {
+        try {
+            const stored = await input.credentials.load({ key: familyKey });
+            return typeof stored === 'string' && stored.trim() !== '' ? stored : undefined;
+        }
+        catch {
+            // A family that cannot be read starts a new one: at worst one more registration.
+            return undefined;
+        }
+    }
+    /**
+     * Removes the saved family. A failed removal leaves the key: harmless at
+     * logout (no token is left to pair it with), and in `persist` the one case
+     * where an older family can stay next to a newer token.
+     */
+    async function removeSavedFamily() {
+        savedFamily = undefined;
+        try {
+            await input.credentials.remove({ key: familyKey });
+        }
+        catch {
+            // Nothing more can be done without the native store.
+        }
+    }
     async function persist(next) {
+        // The family goes before the token: a crash or a failure between the two
+        // writes leaves a newer family next to an older token (at worst one more
+        // registration after a restore), never an older family next to a newer
+        // token, which a restore would read for a family the backend may have
+        // replaced. A family that cannot be saved is removed for the same reason.
+        if (savedFamily !== next.sessionFamilyId) {
+            try {
+                await input.credentials.save({ key: familyKey, value: next.sessionFamilyId });
+                savedFamily = next.sessionFamilyId;
+            }
+            catch {
+                await removeSavedFamily();
+            }
+        }
         try {
             await input.credentials.save({ key: credentialKey, value: next.refreshToken });
         }
@@ -83,6 +148,25 @@ export function createGuestSessionCoordinator(input) {
             status = 'active';
         }
     }
+    /** Saves `next`, makes it the active session unless logout closed it, and announces it. */
+    async function activate(next) {
+        await persist(next);
+        assertOpen();
+        const active = view(next);
+        announce(active);
+        return active;
+    }
+    /** Tells the listeners, after an operation made `session` active. */
+    function announce(session) {
+        for (const listener of [...listeners]) {
+            try {
+                listener(session);
+            }
+            catch {
+                // A listener's failure is the game's; the session is active regardless.
+            }
+        }
+    }
     return {
         async start() {
             assertOpen();
@@ -98,12 +182,19 @@ export function createGuestSessionCoordinator(input) {
             startInFlight = enqueue(async () => {
                 assertOpen();
                 const stored = await loadStoredRefreshToken();
-                const next = validateSession(stored === null
-                    ? await fromBackend(() => input.backend.issueGuest({ installationId: input.installationId }))
-                    : await fromBackend(() => input.backend.refresh({ refreshToken: stored })));
-                await persist(next);
-                assertOpen();
-                return view(next);
+                let next;
+                if (stored === null) {
+                    // A new guest is a new family; a family saved for an older token is
+                    // not read. (Defensive: nothing has set savedFamily before a first start.)
+                    savedFamily = undefined;
+                    next = withFamily(validateSession(await fromBackend(() => input.backend.issueGuest({ installationId: input.installationId }))), undefined);
+                }
+                else {
+                    const family = await loadStoredFamily();
+                    savedFamily = family;
+                    next = withFamily(validateSession(await fromBackend(() => input.backend.refresh({ refreshToken: stored }))), family);
+                }
+                return activate(next);
             }).finally(() => { startInFlight = undefined; });
             return startInFlight;
         },
@@ -114,13 +205,11 @@ export function createGuestSessionCoordinator(input) {
             }
             refreshInFlight = enqueue(async () => {
                 const previous = requireCurrent();
-                const next = validateSession(await fromBackend(() => input.backend.refresh({
+                const next = withFamily(validateSession(await fromBackend(() => input.backend.refresh({
                     refreshToken: previous.refreshToken,
-                })));
+                }))), previous.sessionFamilyId);
                 assertSameOwner(previous, next);
-                await persist(next);
-                assertOpen();
-                return view(next);
+                return activate(next);
             }).finally(() => { refreshInFlight = undefined; });
             return refreshInFlight;
         },
@@ -147,16 +236,26 @@ export function createGuestSessionCoordinator(input) {
                 if (result.status !== 'bound' && result.status !== 'already-bound') {
                     throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
                 }
-                const next = validateSession(result.session);
+                const bound = validateSession(result.session);
+                // The same session id is the same session; a new one may be a new family.
+                const next = withFamily(bound, bound.sessionId === previous.sessionId ? previous.sessionFamilyId : undefined);
                 assertSameOwner(previous, next);
                 if (next.identityLevel !== 'authenticated') {
                     throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
                 }
-                await persist(next);
-                assertOpen();
+                await activate(next);
                 return { status: result.status };
             });
         },
+        current() {
+            return status === 'active' && current !== undefined ? view(current) : undefined;
+        },
+        onSession(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
         getHeaders() {
             assertOpen();
             const active = requireCurrent();
@@ -196,6 +295,8 @@ export function createGuestSessionCoordinator(input) {
                 catch {
                     throw new GuestSessionCoordinatorError('GUEST_SESSION_LOGOUT_UNCERTAIN');
                 }
+                // Without its token a saved family is never read (a new guest starts its own).
+                await removeSavedFamily();
                 current = undefined;
             });
             logoutInFlight = attempt;
@@ -211,16 +312,23 @@ function view(session) {
     return {
         serverUserId: session.serverUserId,
         sessionId: session.sessionId,
+        sessionFamilyId: session.sessionFamilyId,
         identityLevel: session.identityLevel,
         accessExpiresAt: session.accessExpiresAt,
     };
 }
+/** The backend's family id, else the family it continues, else a new one at its session id. */
+function withFamily(session, continued) {
+    return { ...session, sessionFamilyId: session.sessionFamilyId ?? continued ?? session.sessionId };
+}
 // A server may already have consumed the previous refresh token. Persist a
 // well-formed rotated token even when the device clock makes access look expired.
 function validateSession(value) {
     if (!isRecord(value)
         || typeof value.serverUserId !== 'string' || value.serverUserId.trim() === ''
         || typeof value.sessionId !== 'string' || value.sessionId.trim() === ''
+        || (value.sessionFamilyId !== undefined && value.sessionFamilyId !== null
+            && (typeof value.sessionFamilyId !== 'string' || value.sessionFamilyId.trim() === ''))
         || (value.identityLevel !== 'guest' && value.identityLevel !== 'authenticated')
         || typeof value.accessToken !== 'string' || value.accessToken.trim() === ''
         || typeof value.refreshToken !== 'string' || value.refreshToken.trim() === ''
@@ -231,6 +339,8 @@ function validateSession(value) {
     return {
         serverUserId: value.serverUserId,
         sessionId: value.sessionId,
+        // `null` reads as absent, as many serializers write an omitted field.
+        ...(typeof value.sessionFamilyId === 'string' ? { sessionFamilyId: value.sessionFamilyId } : {}),
         identityLevel: value.identityLevel,
         accessToken: value.accessToken,
         refreshToken: value.refreshToken,
@@ -245,3 +355,69 @@ function assertSameOwner(previous, next) {
         throw new GuestSessionCoordinatorError('GUEST_SESSION_OWNERSHIP_CONFLICT');
     }
 }
+/** How long before its access token expires `createGuestServerSession` refreshes a session: one minute. */
+export const defaultGuestServerSessionRefreshAheadMs = 60_000;
+/** The least time between two background refreshes of `createGuestServerSession`. */
+export const guestServerSessionRefreshAheadIntervalMs = 10_000;
+/**
+ * Reads a `GuestSessionCoordinator` as a server-backed session, with the
+ * session-family id as the session id, which the notifications client and
+ * the Worker need (it must not change on refresh). The game still starts
+ * the coordinator, binds accounts, and logs out through it. If you gave
+ * `createGuestSessionCoordinator` a `now`, pass the same function here, so
+ * both read expiry on one clock.
+ */
+export function createGuestServerSession(coordinator, options = {}) {
+    const refreshAheadMs = options.refreshAheadMs ?? defaultGuestServerSessionRefreshAheadMs;
+    if (!Number.isFinite(refreshAheadMs) || refreshAheadMs < 0) {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    const now = options.now ?? Date.now;
+    /** The token (by its expiry) a background refresh last ran for, and when. */
+    let refreshedAheadFor;
+    let lastRefreshAheadAt;
+    /** The one mapping: the server user is the player, and the family id is the session id. */
+    const toSession = (active) => ({
+        playerId: active.serverUserId,
+        sessionId: active.sessionFamilyId,
+    });
+    const sessionOf = (active) => active === undefined ? undefined : toSession(active);
+    return {
+        current: () => sessionOf(coordinator.current()),
+        onAuthenticated(listener) {
+            // The session current at subscription is not a new one; its refreshes are not either.
+            let announced = sessionOf(coordinator.current());
+            return coordinator.onSession((active) => {
+                const next = toSession(active);
+                if (announced?.playerId === next.playerId && announced.sessionId === next.sessionId) {
+                    return;
+                }
+                announced = next;
+                listener(next);
+            });
+        },
+        async getHeaders() {
+            const active = coordinator.current();
+            if (active !== undefined) {
+                const expiresAt = Date.parse(active.accessExpiresAt);
+                const at = now();
+                if (expiresAt <= at) {
+                    // Concurrent callers share the coordinator's one refresh.
+                    await coordinator.refresh();
+                }
+                else if (expiresAt - refreshAheadMs <= at
+                    && refreshedAheadFor !== active.accessExpiresAt
+                    // A clock that went back counts as the interval passed.
+                    && (lastRefreshAheadAt === undefined
+                        || at < lastRefreshAheadAt
+                        || at - lastRefreshAheadAt >= guestServerSessionRefreshAheadIntervalMs)) {
+                    refreshedAheadFor = active.accessExpiresAt;
+                    lastRefreshAheadAt = at;
+                    // The token is still valid: answer it now; a failure is retried once it expires.
+                    coordinator.refresh().catch(() => undefined);
+                }
+            }
+            return coordinator.getHeaders();
+        },
+    };
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './commerce-evidence-registry.js';
 export * from './commerce-ledger.js';
 export * from './commerce-reconciler.js';
 export * from './default-client-reward-evidence.js';
+export * from './development-session.js';
 export * from './admob-client-reward.js';
 export * from './contract.js';
 export * from './evidence-verification.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export * from './commerce-evidence-registry.js';
 export * from './commerce-ledger.js';
 export * from './commerce-reconciler.js';
 export * from './default-client-reward-evidence.js';
+export * from './development-session.js';
 export * from './admob-client-reward.js';
 export * from './contract.js';
 export * from './evidence-verification.js';

package/dist/notifications/ait-functional-delivery.d.ts

@@ -133,7 +133,15 @@ export interface CreateAitFunctionalMessageDeliveryProviderOptions {
   readonly timeoutMs?: number;
   /** `FAIL` error codes that mean the recipient has not agreed to the template. */
   readonly agreementErrorCodes?: readonly string[];
-  /** `reachedFailReason` texts (trimmed) that mean the recipient has not agreed to the template. */
+  /**
+  * `reachedFailReason` texts (trimmed) that mean the recipient has not
+  * agreed to the template. Each is 1 to 1,024 characters (UTF-16 code
+  * units) once trimmed: the provider reads at most the first 1,024
+  * characters of a `reachedFailReason` and then trims it, so a longer entry
+  * could never match, and an empty one would match a blank reason. The
+  * provider refuses either at creation. A received reason with leading
+  * whitespace loses as much of its end to that cut.
+  */
   readonly agreementFailReasons?: readonly string[];
   /** Further `FAIL` error codes that mean this recipient cannot receive the message. */
   readonly recipientErrorCodes?: readonly string[];

package/dist/notifications/ait-functional-delivery.js

@@ -78,6 +78,8 @@ const channelFields = {
     friendtalk: 'sentFriendtalk',
 };
 const maximumResponseBodyBytes = 256 * 1_024;
+/** The longest `reachedFailReason` the provider keeps; a longer one is cut to this. */
+const maximumFailReasonLength = 1_024;
 const maximumIdentifierLength = 2_048;
 const maximumTimeoutMs = 60_000;
 /**
@@ -126,7 +128,7 @@ export function createAitFunctionalMessageDeliveryProvider(options) {
     const timeoutMs = normalizeTimeout(options.timeoutMs);
     const agreementErrorCodes = new Set(options.agreementErrorCodes ?? []);
     const recipientErrorCodes = new Set(options.recipientErrorCodes ?? []);
-    const agreementFailReasons = new Set((options.agreementFailReasons ?? []).map((reason) => reason.trim()));
+    const agreementFailReasons = new Set((options.agreementFailReasons ?? []).map((reason, index) => readAgreementFailReason(reason, index)));
     // Documented codes come first (RFC "Delivery providers -> Apps in Toss"),
     // then the deployment's. A list must not turn 4095 into an agreement denial.
     const classifyFailCode = (code, status) => {
@@ -224,6 +226,14 @@ export function createAitFunctionalMessageDeliveryProvider(options) {
         },
     };
 }
+/** One `agreementFailReasons` entry, trimmed, or a `TypeError` for one that could never match. */
+function readAgreementFailReason(reason, index) {
+    const trimmed = typeof reason === 'string' ? reason.trim() : '';
+    if (trimmed.length === 0 || trimmed.length > maximumFailReasonLength) {
+        throw new TypeError(`agreementFailReasons[${index}]: entries must be 1 to ${maximumFailReasonLength} characters once trimmed: a reachedFailReason is read up to ${maximumFailReasonLength} characters, so a longer entry could never match and an empty one would match a blank reason.`);
+    }
+    return trimmed;
+}
 function readSuccess(success, agreementFailReasons) {
     if (!isRecord(success)) {
         return { status: 'ambiguous', providerCode: 'SUCCESS' };
@@ -274,7 +284,9 @@ function readContents(input) {
         const reason = item['reachedFailReason'];
         contents.push({
             contentId: item['contentId'].slice(0, 256),
-            ...(typeof reason === 'string' ? { reachedFailReason: reason.slice(0, 1_024) } : {}),
+            ...(typeof reason === 'string'
+                ? { reachedFailReason: reason.slice(0, maximumFailReasonLength) }
+                : {}),
         });
     }
     return contents;

package/dist/notifications/client.d.ts

@@ -27,9 +27,10 @@ export interface GameServicesNotificationSession {
   * answers to the Worker's `authenticateNotificationSession` for this
   * session's header, the same across token refreshes. A new sign-in starts
   * a new one. A per-token or rotating id is not it (a
-  * `GuestSessionCoordinator` view's `sessionId` may rotate on refresh); with
-  * one, each rotation counts as a new session and sends the registration
-  * again.
+  * `GuestSessionCoordinator` view's `sessionId` may rotate on refresh; its
+  * `sessionFamilyId` is the id, and `createGuestServerSession` passes it);
+  * with one, each rotation counts as a new session and sends the
+  * registration again.
   */
   readonly sessionId: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -219,9 +219,9 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/analytics": "0.4.15",
-    "@mpgd/platform": "0.27.1",
-    "@mpgd/catalog": "0.10.6"
+    "@mpgd/analytics": "0.5.0",
+    "@mpgd/catalog": "0.10.7",
+    "@mpgd/platform": "0.27.2"
   },
   "peerDependencies": {
     "@apple/app-store-server-library": "^3.1.0"
@@ -250,7 +250,7 @@
     "fix": "ttsc fix",
     "build": "cd ../.. && node tools/run-ttsx.mjs tools/package/build-packages.ts @mpgd/game-services",
     "test:packed-transport": "pnpm build && node test/runtime-transport-package-import.mjs && node test/reward-evidence-import.mjs",
-    "test:unit": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-progress.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-publisher-client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-identity.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/service.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/service-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/client-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/scheduler.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/fcm.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/store-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/ait-functional-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-partner-api.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts && node tools/run-ttsx.mjs packages/game-services/src/guest-session.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-reward-evidence.test.ts && node tools/run-ttsx.mjs packages/game-services/src/ad-reward-verifier-registry.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-reward.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-registry-routing.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-registry-server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-ledger-revocation.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-anonymous-auth.test.ts",
+    "test:unit": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-progress.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-publisher-client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-identity.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/service.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/service-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/client-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/scheduler.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/fcm.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/store-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notifications/ait-functional-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-partner-api.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts && node tools/run-ttsx.mjs packages/game-services/src/guest-session.test.ts && node tools/run-ttsx.mjs packages/game-services/src/development-session.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-reward-evidence.test.ts && node tools/run-ttsx.mjs packages/game-services/src/ad-reward-verifier-registry.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-reward.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-registry-routing.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-registry-server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-ledger-revocation.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-anonymous-auth.test.ts",
     "test:recovery": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/monetization-recovery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-recovery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-reconciler.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-reconciler-conformance.test.ts",
     "test": "pnpm test:unit && pnpm test:app-store-server && pnpm test:recovery && pnpm test:packed-transport",
     "test:app-store-server": "vitest run"