@mpgd/game-services 0.15.3 → 0.16.0

package/README.md

@@ -71,9 +71,91 @@ and retry policy are not redesigned by this observer API.
 The root `pnpm test` pipeline includes compiled client JS and public declaration
 consumption checks alongside the client and target conformance suites.
 
+## Runtime backend transport
+
+`createGameServicesRuntime` accepts `httpTransport` for its HTTP JSON backend
+path. This is a `GameServicesBackendTransport` with fixed Game Services
+endpoints, not a general `fetch` implementation. It is never used for the
+`orpc` path. A production runtime still requires a valid public HTTPS
+`baseUrl`; supplying a custom transport does not enable a local backend or
+silently fall back to the default network path.
+
+```ts
+import { createGameServicesRuntime } from '@mpgd/game-services/runtime';
+import type { GameServicesBackendTransport } from '@mpgd/game-services/client';
+
+declare const gateway: Parameters<typeof createGameServicesRuntime>[0]['gateway'];
+declare const nativeJsonTransport: GameServicesBackendTransport;
+declare const currentAccessToken: () => string;
+
+const runtime = createGameServicesRuntime({
+  gateway,
+  playerId: 'game-player',
+  authorityMode: 'production',
+  baseUrl: 'https://api.example.com',
+  transport: 'http',
+  httpTransport: nativeJsonTransport,
+  getHeaders: () => ({ authorization: `Bearer ${currentAccessToken()}` }),
+});
+```
+
+`headers` remains available for static values. `getHeaders` is evaluated for
+every backend request, including default HTTP and oRPC requests, so session
+rotation does not retain an old token. An injected HTTP transport receives
+those headers only with a Game Services endpoint request and must itself
+enforce its configured HTTPS origin, redirect policy, and response limits;
+the runtime cannot inspect a transport's internal network destinations.
+Static headers are overridden by refreshed headers, then by explicit
+per-request headers, with names compared case-insensitively. If `getHeaders`
+fails, the runtime throws a sanitized
+`GameServicesHeaderResolutionError` **before** sending the request; this is
+distinct from an uncertain network outcome.
+Non-2xx HTTP transport responses still become `GameServicesBackendError` and
+are not retried through default fetch. Invalid responses and thrown native
+transport errors become `GameServicesBackendTransportError` without embedding
+the original exception, which might contain credentials. A failed request can
+still have completed on the server: reconcile it before retrying a purchase
+or reward claim. Do not forward these headers to an unrelated origin or copy
+them into analytics or logs.
+
 All published entrypoints use explicit internal ESM module paths and are smoke-tested
 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
+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
+token rotation, expiry, replay response, idempotent revocation, and database
+transactions. The session ID may rotate during refresh or binding, but the
+server user ID must remain the same; the
+injected contract is not a production identity provider by itself.
+
+The coordinator loads and saves the refresh token only through secure native
+credential storage. A load failure never silently starts a new guest, and a
+failed save cannot expose a new access token as active. Concurrent refreshes
+share one backend call; logout closes header access immediately and waits for
+in-flight token changes before revoking the latest token and removing the
+credential. Failed revocation or native removal leaves the credential intact
+and allows a later logout retry; callers must treat an uncertain logout as a
+server-side session that may still be live. Backend and native load errors are
+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.
+
+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
+server-verified guest-progress handoff. A platform player ID and store purchase
+binding remain distinct from the server user and external provider subject.
+The tests use a fake backend and secure-storage port; they do not prove an
+OAuth provider, durable session database, or device Keychain/Keystore is
+correctly configured.
+
 Headless consumers can import operation input/result/progress types and the two-method
 `GameServicesOperationClient` port from `@mpgd/game-services/operations`. This entrypoint
 has no runtime implementation and its declarations require no DOM or fetch globals.

package/dist/client.d.ts

@@ -30,6 +30,8 @@ export interface GameServicesBackendTransportRequest<TBody = unknown> {
   readonly method: 'POST';
   readonly endpoint: GameServicesBackendEndpoint;
   readonly body: TBody;
+  /** Resolved for this request only; custom transports must not forward elsewhere. */
+  readonly headers?: Readonly<Record<string, string>>;
 }
 export interface GameServicesBackendTransportResponse<TBody = unknown> {
   readonly status: number;
@@ -45,12 +47,15 @@ export interface CreateGameServicesFetchBackendTransportInput {
   readonly baseUrl: string;
   readonly fetch?: GameServicesFetch;
   readonly headers?: Record<string, string>;
+  readonly getHeaders?: GameServicesHeaderResolver;
 }
 export interface CreateGameServicesOrpcClientInput {
   readonly url: string;
   readonly fetch?: typeof fetch;
   readonly headers?: Record<string, string>;
+  readonly getHeaders?: GameServicesHeaderResolver;
 }
+export type GameServicesHeaderResolver = () => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
 export type GameServicesFetch = (url: string, init: {
   readonly method: 'POST';
   readonly headers: Record<string, string>;
@@ -67,6 +72,20 @@ export declare class GameServicesBackendError extends Error {
   readonly body: unknown;
   constructor(endpoint: GameServicesBackendEndpoint, status: number, body: unknown);
 }
+export declare class GameServicesBackendTransportError extends Error {
+  readonly endpoint: GameServicesBackendEndpoint;
+  constructor(endpoint: GameServicesBackendEndpoint);
+}
+/** Credentials could not be resolved; no backend request was dispatched. */
+export declare class GameServicesHeaderResolutionError extends Error {
+  constructor();
+}
+/** Resolve rotating credentials once and preserve static → dynamic → request precedence. */
+export declare function resolveGameServicesRequestHeaders(input: {
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  readonly getHeaders?: GameServicesHeaderResolver | undefined;
+  readonly requestHeaders?: Readonly<Record<string, string>> | undefined;
+}): Promise<Readonly<Record<string, string>>>;
 export interface GameServicesClient extends GameServicesOperationClient {
   submitLeaderboardScore(input: GameServicesLeaderboardInput): Promise<GameServicesLeaderboardResult>;
 }

package/dist/client.js

@@ -19,6 +19,39 @@ export class GameServicesBackendError extends Error {
         this.body = body;
     }
 }
+export class GameServicesBackendTransportError extends Error {
+    endpoint;
+    constructor(endpoint) {
+        super(`GameServices backend transport failed: ${endpoint}`);
+        this.name = 'GameServicesBackendTransportError';
+        this.endpoint = endpoint;
+    }
+}
+/** Credentials could not be resolved; no backend request was dispatched. */
+export class GameServicesHeaderResolutionError extends Error {
+    constructor() {
+        super('Game Services request headers could not be resolved before dispatch.');
+        this.name = 'GameServicesHeaderResolutionError';
+    }
+}
+/** Resolve rotating credentials once and preserve static → dynamic → request precedence. */
+export async function resolveGameServicesRequestHeaders(input) {
+    let dynamicHeaders;
+    try {
+        dynamicHeaders = await input.getHeaders?.();
+    }
+    catch {
+        // Resolver exceptions can contain credentials; expose a stable outcome.
+        throw new GameServicesHeaderResolutionError();
+    }
+    const merged = new Map();
+    for (const layer of [input.headers, dynamicHeaders, input.requestHeaders]) {
+        for (const [name, value] of Object.entries(layer ?? {})) {
+            merged.set(name.toLowerCase(), value);
+        }
+    }
+    return Object.fromEntries(merged);
+}
 export function createGameServicesClient(input) {
     const now = input.now ?? (() => new Date().toISOString());
     const analytics = createAnalyticsReporter({
@@ -297,10 +330,15 @@ export function createGameServicesFetchBackendTransport(input) {
     const fetcher = input.fetch ?? readGlobalFetch();
     return {
         async send(request) {
+            const headers = await resolveGameServicesRequestHeaders({
+                headers: input.headers,
+                getHeaders: input.getHeaders,
+                requestHeaders: request.headers,
+            });
             const response = await fetcher(joinUrl(input.baseUrl, request.endpoint), {
                 method: request.method,
                 headers: {
-                    ...(input.headers ?? {}),
+                    ...headers,
                     'content-type': 'application/json',
                 },
                 body: JSON.stringify(request.body),
@@ -316,10 +354,10 @@ export function createGameServicesOrpcClient(input) {
     const link = new RPCLink({
         origin: input.url,
         ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
-        ...(input.headers === undefined
+        ...(input.headers === undefined && input.getHeaders === undefined
             ? {}
             : {
-                headers: () => input.headers,
+                headers: () => resolveGameServicesRequestHeaders(input),
             }),
     });
     return createORPCClient(link);
@@ -389,11 +427,26 @@ function isGameServicesLeaderboardTarget(target) {
         || target === 'reddit';
 }
 async function sendGameServicesBackendRequest(transport, endpoint, body) {
-    const response = await transport.send({
-        method: 'POST',
-        endpoint,
-        body,
-    });
+    let response;
+    try {
+        response = await transport.send({
+            method: 'POST',
+            endpoint,
+            body,
+        });
+    }
+    catch (error) {
+        if (error instanceof GameServicesHeaderResolutionError) {
+            throw error;
+        }
+        // Do not leak SDK or native transport exceptions (which can contain
+        // request headers); the caller must reconcile uncertain server outcomes.
+        throw new GameServicesBackendTransportError(endpoint);
+    }
+    if (!Number.isInteger(response?.status) || response.status < 100 || response.status > 599
+        || !Object.hasOwn(response, 'body')) {
+        throw new GameServicesBackendTransportError(endpoint);
+    }
     if (response.status < 200 || response.status >= 300) {
         throw new GameServicesBackendError(endpoint, response.status, response.body);
     }

package/dist/guest-session.d.ts

@@ -0,0 +1,84 @@
+import type { SecureCredentialStore } from '@mpgd/platform';
+/** These identifiers are deliberately not interchangeable authentication claims. */
+export interface GuestInstallationIdentity {
+  readonly installationId: string;
+}
+export interface VerifiedExternalAccount {
+  readonly provider: string;
+  readonly subject: string;
+}
+export interface NativeGamePlayerIdentity {
+  readonly platform: 'game-center' | 'play-games';
+  readonly platformPlayerId: string;
+}
+export interface StorePurchaseAccountBinding {
+  readonly store: 'app-store' | 'google-play';
+  readonly bindingId: string;
+}
+/** Only a trusted server may issue this opaque-token response. */
+export interface ServerGuestSessionCredentials {
+  readonly serverUserId: string;
+  /** May rotate on refresh or binding; serverUserId remains the ownership key. */
+  readonly sessionId: 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 type AccountBindingOutcome = {
+  readonly status: 'bound' | 'already-bound';
+  readonly session: ServerGuestSessionCredentials;
+} | {
+  readonly status: 'conflict';
+};
+/**
+* Implement on the game backend. Refresh/revoke must authenticate the opaque
+* refresh token, and bindAccount must verify both it and the external proof,
+* atomically deduplicate by idempotencyKey, and return conflict for an account
+* already owned by another server user. An installationId is never authority.
+*/
+export interface GuestSessionBackend {
+  issueGuest(input: GuestInstallationIdentity): Promise<ServerGuestSessionCredentials>;
+  refresh(input: {
+    readonly refreshToken: string;
+  }): Promise<ServerGuestSessionCredentials>;
+  revoke(input: {
+    readonly refreshToken: string;
+  }): Promise<void>;
+  bindAccount(input: {
+    readonly refreshToken: string;
+    readonly externalProof: string;
+    readonly idempotencyKey: string;
+  }): Promise<AccountBindingOutcome>;
+}
+export type GuestSessionCoordinatorErrorCode = 'GUEST_SESSION_CLOSED' | 'GUEST_SESSION_NOT_READY' | 'GUEST_SESSION_INVALID_INPUT' | 'GUEST_SESSION_INVALID_RESPONSE' | 'GUEST_SESSION_OWNERSHIP_CONFLICT' | 'GUEST_SESSION_BACKEND_FAILED' | 'GUEST_SESSION_CREDENTIAL_LOAD_FAILED' | 'GUEST_SESSION_CREDENTIAL_SAVE_FAILED' | 'GUEST_SESSION_LOGOUT_UNCERTAIN';
+/** Error messages intentionally contain no token, proof, or installation ID. */
+export declare class GuestSessionCoordinatorError extends Error {
+  readonly code: GuestSessionCoordinatorErrorCode;
+  constructor(code: GuestSessionCoordinatorErrorCode);
+}
+export interface GuestSessionCoordinator {
+  start(): Promise<ServerGuestSessionView>;
+  refresh(): Promise<ServerGuestSessionView>;
+  bindAccount(input: {
+    readonly externalProof: string;
+    readonly idempotencyKey: string;
+  }): Promise<{
+    readonly status: 'bound' | 'already-bound' | 'conflict';
+  }>;
+  getHeaders(): Readonly<Record<'authorization', string>>;
+  logout(): Promise<void>;
+}
+/**
+* Serializes token mutation and closes synchronously on logout. Native secure
+* storage failures never fall back to ordinary game storage or mint a new guest.
+*/
+export declare function createGuestSessionCoordinator(input: {
+  readonly backend: GuestSessionBackend;
+  readonly credentials: SecureCredentialStore;
+  readonly installationId: string;
+  readonly credentialKey?: string;
+  readonly now?: () => number;
+}): GuestSessionCoordinator;

package/dist/guest-session.js

@@ -0,0 +1,247 @@
+/** Error messages intentionally contain no token, proof, or installation ID. */
+export class GuestSessionCoordinatorError extends Error {
+    code;
+    constructor(code) {
+        super(`Guest session operation failed: ${code}.`);
+        this.name = 'GuestSessionCoordinatorError';
+        this.code = code;
+    }
+}
+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.
+ */
+export function createGuestSessionCoordinator(input) {
+    if (typeof input.installationId !== 'string' || input.installationId.trim() === '') {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    const credentialKey = input.credentialKey ?? defaultCredentialKey;
+    if (credentialKey.trim() === '') {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    const now = input.now ?? Date.now;
+    let current;
+    let status = 'idle';
+    let tail = Promise.resolve();
+    let startInFlight;
+    let refreshInFlight;
+    let logoutInFlight;
+    function enqueue(operation) {
+        const next = tail.then(operation, operation);
+        tail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    function assertOpen() {
+        if (status === 'closed') {
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_CLOSED');
+        }
+    }
+    function requireCurrent() {
+        if (status !== 'active' || current === undefined) {
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_NOT_READY');
+        }
+        return current;
+    }
+    async function loadStoredRefreshToken() {
+        try {
+            const stored = await input.credentials.load({ key: credentialKey });
+            if (stored !== null && (typeof stored !== 'string' || stored === '')) {
+                throw new Error('Invalid stored refresh token.');
+            }
+            return stored;
+        }
+        catch {
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_CREDENTIAL_LOAD_FAILED');
+        }
+    }
+    async function fromBackend(operation) {
+        try {
+            return await operation();
+        }
+        catch {
+            // Backend exceptions can contain URLs, proofs, or tokens. The public
+            // coordinator surface intentionally exposes only a stable error code.
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_BACKEND_FAILED');
+        }
+    }
+    async function persist(next) {
+        try {
+            await input.credentials.save({ key: credentialKey, value: next.refreshToken });
+        }
+        catch {
+            // Keep the latest token only for an explicit revoke; never expose it as
+            // an active session after native persistence failed.
+            current = next;
+            if (status !== 'closed') {
+                status = 'failed';
+            }
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_CREDENTIAL_SAVE_FAILED');
+        }
+        current = next;
+        if (status !== 'closed') {
+            status = 'active';
+        }
+    }
+    return {
+        async start() {
+            assertOpen();
+            if (status === 'active' && current !== undefined) {
+                return Promise.resolve(view(current));
+            }
+            if (startInFlight !== undefined) {
+                return startInFlight;
+            }
+            if (status === 'failed') {
+                return Promise.reject(new GuestSessionCoordinatorError('GUEST_SESSION_NOT_READY'));
+            }
+            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);
+            }).finally(() => { startInFlight = undefined; });
+            return startInFlight;
+        },
+        async refresh() {
+            assertOpen();
+            if (refreshInFlight !== undefined) {
+                return refreshInFlight;
+            }
+            refreshInFlight = enqueue(async () => {
+                const previous = requireCurrent();
+                const next = validateSession(await fromBackend(() => input.backend.refresh({
+                    refreshToken: previous.refreshToken,
+                })));
+                assertSameOwner(previous, next);
+                await persist(next);
+                assertOpen();
+                return view(next);
+            }).finally(() => { refreshInFlight = undefined; });
+            return refreshInFlight;
+        },
+        async bindAccount(binding) {
+            assertOpen();
+            if (typeof binding.externalProof !== 'string' || binding.externalProof.trim() === ''
+                || typeof binding.idempotencyKey !== 'string' || binding.idempotencyKey.trim() === '') {
+                throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+            }
+            return enqueue(async () => {
+                const previous = requireCurrent();
+                const result = await fromBackend(() => input.backend.bindAccount({
+                    refreshToken: previous.refreshToken,
+                    externalProof: binding.externalProof,
+                    idempotencyKey: binding.idempotencyKey,
+                }));
+                if (typeof result !== 'object' || result === null || !('status' in result)) {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+                }
+                if (result.status === 'conflict') {
+                    assertOpen();
+                    return { status: 'conflict' };
+                }
+                if (result.status !== 'bound' && result.status !== 'already-bound') {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+                }
+                const next = validateSession(result.session);
+                assertSameOwner(previous, next);
+                if (next.identityLevel !== 'authenticated') {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+                }
+                await persist(next);
+                assertOpen();
+                return { status: result.status };
+            });
+        },
+        getHeaders() {
+            assertOpen();
+            const active = requireCurrent();
+            if (Date.parse(active.accessExpiresAt) <= now()) {
+                throw new GuestSessionCoordinatorError('GUEST_SESSION_NOT_READY');
+            }
+            return { authorization: `Bearer ${active.accessToken}` };
+        },
+        logout() {
+            if (logoutInFlight !== undefined) {
+                return logoutInFlight;
+            }
+            status = 'closed';
+            const attempt = enqueue(async () => {
+                let token = current?.refreshToken;
+                if (token === undefined) {
+                    try {
+                        token = (await input.credentials.load({ key: credentialKey })) ?? undefined;
+                    }
+                    catch {
+                        // Keep the credential intact so a later logout can retry the load.
+                        throw new GuestSessionCoordinatorError('GUEST_SESSION_LOGOUT_UNCERTAIN');
+                    }
+                }
+                if (token !== undefined) {
+                    try {
+                        await input.backend.revoke({ refreshToken: token });
+                    }
+                    catch {
+                        // Do not delete a still-live refresh token on revoke failure.
+                        throw new GuestSessionCoordinatorError('GUEST_SESSION_LOGOUT_UNCERTAIN');
+                    }
+                }
+                try {
+                    await input.credentials.remove({ key: credentialKey });
+                }
+                catch {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_LOGOUT_UNCERTAIN');
+                }
+                current = undefined;
+            });
+            logoutInFlight = attempt;
+            void attempt.catch(() => {
+                // A failed revoke or remove can be retried on this closed coordinator.
+                logoutInFlight = undefined;
+            });
+            return logoutInFlight;
+        },
+    };
+}
+function view(session) {
+    return {
+        serverUserId: session.serverUserId,
+        sessionId: session.sessionId,
+        identityLevel: session.identityLevel,
+        accessExpiresAt: session.accessExpiresAt,
+    };
+}
+// 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.identityLevel !== 'guest' && value.identityLevel !== 'authenticated')
+        || typeof value.accessToken !== 'string' || value.accessToken.trim() === ''
+        || typeof value.refreshToken !== 'string' || value.refreshToken.trim() === ''
+        || typeof value.accessExpiresAt !== 'string'
+        || !Number.isFinite(Date.parse(value.accessExpiresAt))) {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+    }
+    return {
+        serverUserId: value.serverUserId,
+        sessionId: value.sessionId,
+        identityLevel: value.identityLevel,
+        accessToken: value.accessToken,
+        refreshToken: value.refreshToken,
+        accessExpiresAt: value.accessExpiresAt,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertSameOwner(previous, next) {
+    if (previous.serverUserId !== next.serverUserId) {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_OWNERSHIP_CONFLICT');
+    }
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
 export * from './contract.js';
 export * from './evidence-verification.js';
+export * from './guest-session.js';
 export * from './google-play-purchase.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
 export * from './contract.js';
 export * from './evidence-verification.js';
+export * from './guest-session.js';
 export * from './google-play-purchase.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';

package/dist/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { AnalyticsSink } from '@mpgd/analytics';
 import type { PlatformGateway, PlatformTarget } from '@mpgd/platform';
-import { type GameServicesBackendApi, type GameServicesClient } from './client.js';
+import { type GameServicesBackendApi, type GameServicesBackendTransport, type GameServicesClient, type GameServicesHeaderResolver } from './client.js';
 import type { GameServicesLedgerTarget } from './types.js';
 export type GameServicesAuthorityMode = 'production' | 'non-production';
 export type GameServicesRuntimeMode = 'disabled' | 'local' | 'http' | 'orpc';
@@ -12,23 +12,33 @@ export interface GameServicesRuntime {
   readonly target?: GameServicesLedgerTarget;
   readonly client?: GameServicesClient;
 }
-export interface CreateGameServicesRuntimeInput {
+interface CreateGameServicesRuntimeCommonInput {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
   readonly authorityMode: GameServicesAuthorityMode;
   readonly target?: PlatformTarget | string;
   readonly deploymentTarget?: string;
   readonly baseUrl?: string;
-  readonly transport?: 'http' | 'orpc';
   /** Static headers sent with every authoritative game-services request. */
   readonly headers?: Record<string, string>;
+  /** Resolve rotating credentials at request time, not runtime creation time. */
+  readonly getHeaders?: GameServicesHeaderResolver;
   readonly allowLocalBackend?: boolean;
   readonly localBackend?: GameServicesBackendApi;
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
   readonly now?: () => string;
 }
+export type CreateGameServicesRuntimeInput = CreateGameServicesRuntimeCommonInput & ({
+  readonly transport?: 'http';
+  /** A JSON endpoint transport, not a replacement for the Fetch API. */
+  readonly httpTransport?: GameServicesBackendTransport;
+} | {
+  readonly transport: 'orpc';
+  readonly httpTransport?: never;
+});
 export declare function createGameServicesRuntime(input: CreateGameServicesRuntimeInput): GameServicesRuntime;
 export declare function resolveGameServicesLedgerTarget(target: PlatformTarget | string): GameServicesLedgerTarget | null;
 export declare function resolveGameServicesAuthorityMode(profile: string): GameServicesAuthorityMode;
 export declare function resolveGameServicesTransport(transport: string | undefined): 'http' | 'orpc';
+export {};

package/dist/runtime.js

@@ -1,12 +1,18 @@
-import { createGameServicesClient, createGameServicesFetchBackendTransport, createGameServicesHttpBackendApi, createGameServicesOrpcBackendApi, createGameServicesOrpcClient, } from './client.js';
+import { createGameServicesClient, createGameServicesFetchBackendTransport, createGameServicesHttpBackendApi, createGameServicesOrpcBackendApi, createGameServicesOrpcClient, resolveGameServicesRequestHeaders, } from './client.js';
 export function createGameServicesRuntime(input) {
     assertAuthorityMode(input.authorityMode);
     assertTransport(input.transport);
+    if (input.transport === 'orpc' && input.httpTransport !== undefined) {
+        throw new Error('Game Services httpTransport cannot be used with oRPC.');
+    }
     const target = resolveGameServicesLedgerTarget(input.target ?? input.gateway.target);
     if (target === null) {
         return disabledRuntime('unsupported_target');
     }
     const baseUrl = normalizeBaseUrl(input.baseUrl);
+    if (input.httpTransport !== undefined && baseUrl === undefined) {
+        throw new Error('Game Services httpTransport requires an authoritative baseUrl.');
+    }
     let backend;
     let mode;
     if (baseUrl !== undefined) {
@@ -22,12 +28,10 @@ export function createGameServicesRuntime(input) {
             ? createGameServicesOrpcBackendApi(createGameServicesOrpcClient({
                 url: baseUrl,
                 ...(input.headers === undefined ? {} : { headers: input.headers }),
+                ...(input.getHeaders === undefined ? {} : { getHeaders: input.getHeaders }),
             }))
             : createGameServicesHttpBackendApi({
-                transport: createGameServicesFetchBackendTransport({
-                    baseUrl,
-                    ...(input.headers === undefined ? {} : { headers: input.headers }),
-                }),
+                transport: withRuntimeHeaders(input.httpTransport ?? createGameServicesFetchBackendTransport({ baseUrl }), input),
             });
     }
     else {
@@ -63,6 +67,21 @@ export function createGameServicesRuntime(input) {
         }),
     };
 }
+function withRuntimeHeaders(transport, input) {
+    return {
+        async send(request) {
+            const headers = await resolveGameServicesRequestHeaders({
+                headers: input.headers,
+                getHeaders: input.getHeaders,
+                requestHeaders: request.headers,
+            });
+            return transport.send({
+                ...request,
+                headers,
+            });
+        },
+    };
+}
 export function resolveGameServicesLedgerTarget(target) {
     if (target === 'browser'
         || target === 'microsoft-store'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -73,6 +73,10 @@
       "types": "./dist/google-play-purchase.d.ts",
       "default": "./dist/google-play-purchase.js"
     },
+    "./guest-session": {
+      "types": "./dist/guest-session.d.ts",
+      "default": "./dist/guest-session.js"
+    },
     "./microsoft-store-identity": {
       "types": "./dist/microsoft-store-identity.d.ts",
       "default": "./dist/microsoft-store-identity.js"
@@ -138,11 +142,12 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/analytics": "0.3.14",
-    "@mpgd/catalog": "0.7.4",
-    "@mpgd/platform": "0.12.2"
+    "@mpgd/analytics": "0.3.15",
+    "@mpgd/platform": "0.13.0",
+    "@mpgd/catalog": "0.7.5"
   },
   "devDependencies": {
+    "@opentelemetry/api": "1.9.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2"
   },
@@ -156,6 +161,9 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "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/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/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"
+    "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",
+    "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/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/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",
+    "test": "pnpm test:unit && pnpm test:packed-transport"
   }
 }