@mpgd/game-services 0.15.3 → 0.17.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/admob-client-reward.d.ts

@@ -0,0 +1,3 @@
+/** This schema records SDK callback evidence, never an authoritative grant. */
+export declare const admobClientRewardEvidenceSchema = "mpgd.admob.client-reward.v1";
+export declare function isAdMobClientRewardEvidence(value: unknown): boolean;

package/dist/admob-client-reward.js

@@ -0,0 +1,21 @@
+/** This schema records SDK callback evidence, never an authoritative grant. */
+export const admobClientRewardEvidenceSchema = 'mpgd.admob.client-reward.v1';
+export function isAdMobClientRewardEvidence(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const reward = value;
+    const evidence = reward.evidence;
+    if ((reward.status !== 'completed' && reward.status !== 'pending')
+        || reward.rewardGranted !== false
+        || reward.ledgerEntryId !== undefined
+        || typeof evidence !== 'object' || evidence === null || Array.isArray(evidence)) {
+        return false;
+    }
+    const envelope = evidence;
+    const payload = envelope.payload;
+    return envelope.schema === admobClientRewardEvidenceSchema
+        && typeof payload === 'object' && payload !== null && !Array.isArray(payload)
+        && typeof payload.adUnitId === 'string'
+        && payload.adUnitId.length > 0;
+}

package/dist/admob-ssv.d.ts

@@ -2,6 +2,8 @@ import type { AdPlacementEntry } from '@mpgd/catalog';
 import type { GameServicesEvidenceVerifier } from './evidence-verification.js';
 import type { ClaimAdRewardRequest } from './types.js';
 export declare const admobSsvCustomDataSchema = "mpgd.admob.ssv.binding.v1";
+/** Maximum field length accepted by the shipped game-services SSV receiver. */
+export declare const admobSsvMaximumBindingFieldLength = 256;
 export declare const defaultAdMobSsvMaximumCallbackAgeMs = 86400000;
 export declare const defaultAdMobSsvMaximumFutureSkewMs = 300000;
 export interface AdMobSsvCustomDataBinding {

package/dist/admob-ssv.js

@@ -1,5 +1,7 @@
 import { Point, verify as verifySecp256k1 } from '@noble/secp256k1';
 export const admobSsvCustomDataSchema = 'mpgd.admob.ssv.binding.v1';
+/** Maximum field length accepted by the shipped game-services SSV receiver. */
+export const admobSsvMaximumBindingFieldLength = 256;
 export const defaultAdMobSsvMaximumCallbackAgeMs = 86_400_000;
 export const defaultAdMobSsvMaximumFutureSkewMs = 300_000;
 const signatureMarker = '&signature=';

package/dist/app-store-recovery.d.ts

@@ -0,0 +1,38 @@
+import { type ProductCatalog } from '@mpgd/catalog';
+import { type AppStoreEnvironment } from './app-store-verifier.js';
+import type { PurchaseVerificationApi } from './client.js';
+import type { GameServicesEvidenceVerifier } from './evidence-verification.js';
+import type { GameServicesStore } from './server.js';
+import type { VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
+export type AppStoreRecoveryRequest = Omit<VerifyPurchaseRequest, 'target' | 'idempotencyKey' | 'evidence'> & {
+  readonly target: 'ios';
+};
+export interface AppStoreRestoredTransactionIdentity {
+  readonly originalTransactionId?: string;
+  readonly productType?: 'consumable' | 'non_consumable';
+}
+export interface CreateAppStoreRecoveryBackendOptions {
+  /** Bind this instance to a player authenticated by the game server. */
+  readonly playerId: string;
+  readonly deploymentTarget?: string;
+  readonly purchases: PurchaseVerificationApi;
+  readonly store: GameServicesStore;
+  /** Required to re-verify restored non-consumables whose current transaction ID changed. */
+  readonly restoredNonConsumables?: {
+    readonly catalog: ProductCatalog;
+    readonly evidenceVerifier: GameServicesEvidenceVerifier;
+    readonly bundleId: string;
+    readonly environment: AppStoreEnvironment;
+    readonly timeoutMs?: number;
+  };
+  /** Look up the original, durable checkout key; never derive one from the transaction ID. */
+  readonly resolveOriginalIdempotencyKey?: (input: AppStoreRecoveryRequest & AppStoreRestoredTransactionIdentity) => Promise<string | undefined>;
+}
+export interface AppStoreRecoveryBackend {
+  recoverPurchase(input: AppStoreRecoveryRequest & AppStoreRestoredTransactionIdentity): Promise<VerifyPurchaseResponse>;
+}
+/**
+* Connect StoreKit recovery to the existing authoritative purchase ledger.
+* This is a server-side helper, not an authentication or Apple verifier.
+*/
+export declare function createAppStoreRecoveryBackend(options: CreateAppStoreRecoveryBackendOptions): AppStoreRecoveryBackend;

package/dist/app-store-recovery.js

@@ -0,0 +1,271 @@
+import { resolveProductPlatformId } from '@mpgd/catalog';
+import { createAppStoreVerificationId, isAppStoreVerificationId, } from './app-store-verifier.js';
+/**
+ * Connect StoreKit recovery to the existing authoritative purchase ledger.
+ * This is a server-side helper, not an authentication or Apple verifier.
+ */
+export function createAppStoreRecoveryBackend(options) {
+    if (options.playerId.trim() === '') {
+        throw new TypeError('App Store recovery requires an authenticated player ID.');
+    }
+    const restoreTimeoutMs = options.restoredNonConsumables?.timeoutMs;
+    if (restoreTimeoutMs !== undefined
+        && (!Number.isSafeInteger(restoreTimeoutMs) || restoreTimeoutMs <= 0)) {
+        throw new TypeError('Restored App Store verification timeout must be positive.');
+    }
+    return {
+        async recoverPurchase(input) {
+            if (input?.target !== 'ios' || input.playerId !== options.playerId
+                || typeof input.productId !== 'string' || input.productId.trim() === ''
+                || typeof input.platformTransactionId !== 'string'
+                || input.platformTransactionId.trim() === ''
+                || typeof input.purchasedAt !== 'string' || input.purchasedAt.trim() === ''
+                || (options.deploymentTarget !== undefined
+                    && input.deploymentTarget !== undefined
+                    && input.deploymentTarget !== options.deploymentTarget)) {
+                return rejected('APP_STORE_RECOVERY_IDENTITY_MISMATCH');
+            }
+            let request = {
+                ...input,
+                ...(options.deploymentTarget === undefined
+                    ? {}
+                    : { deploymentTarget: options.deploymentTarget }),
+            };
+            try {
+                const restoreConfig = options.restoredNonConsumables;
+                if (input.productType === 'non_consumable'
+                    && input.originalTransactionId !== undefined
+                    && input.originalTransactionId !== input.platformTransactionId
+                    && restoreConfig !== undefined) {
+                    const candidateId = createAppStoreVerificationId({
+                        environment: restoreConfig.environment,
+                        bundleId: restoreConfig.bundleId,
+                        transactionId: input.originalTransactionId,
+                    });
+                    const candidate = await findByVerificationId(options.store, candidateId);
+                    if (candidate !== undefined) {
+                        if (candidate.source !== 'purchase'
+                            || candidate.playerId !== request.playerId
+                            || candidate.grantId !== request.productId
+                            || candidate.payload.target !== 'ios'
+                            || candidate.payload.productType !== 'non_consumable'
+                            || candidate.payload.appStoreOriginalTransactionId
+                                !== input.originalTransactionId) {
+                            return rejected('APP_STORE_RECOVERY_IDENTITY_MISMATCH');
+                        }
+                        if (typeof candidate.payload.deploymentTarget === 'string') {
+                            if (request.deploymentTarget !== undefined
+                                && request.deploymentTarget !== candidate.payload.deploymentTarget) {
+                                return rejected('APP_STORE_RECOVERY_IDENTITY_MISMATCH');
+                            }
+                            request = { ...request, deploymentTarget: candidate.payload.deploymentTarget };
+                        }
+                    }
+                    else if (options.deploymentTarget === undefined) {
+                        // A request-supplied target is not a server-bound deployment identity.
+                        return pending('APP_STORE_RECOVERY_DEPLOYMENT_TARGET_REQUIRED');
+                    }
+                }
+                const restoredVerificationId = await verifyRestoredNonConsumable(input, request, options);
+                if (typeof restoredVerificationId !== 'string') {
+                    return restoredVerificationId;
+                }
+                const platformGrant = await findByPlatformEvidence(options.store, request.platformTransactionId);
+                const originalGrant = restoredVerificationId === ''
+                    ? undefined
+                    : await findByVerificationId(options.store, restoredVerificationId);
+                if (platformGrant !== undefined && originalGrant !== undefined
+                    && platformGrant.ledgerEntryId !== originalGrant.ledgerEntryId) {
+                    return rejected('APP_STORE_RECOVERY_IDENTITY_MISMATCH');
+                }
+                const existing = platformGrant ?? originalGrant;
+                if (existing !== undefined
+                    && !matchesRecovery(existing, request, restoredVerificationId)) {
+                    return rejected('APP_STORE_RECOVERY_IDENTITY_MISMATCH');
+                }
+                let key = existing?.idempotencyKey;
+                if (key === undefined) {
+                    key = await options.resolveOriginalIdempotencyKey?.(request);
+                }
+                if (key === undefined || key.trim() === '') {
+                    return pending('APP_STORE_ORIGINAL_PURCHASE_NOT_FOUND');
+                }
+                const keyedGrant = await findByIdempotency(options.store, options.playerId, key);
+                if (keyedGrant !== undefined
+                    && !matchesRecovery(keyedGrant, request, restoredVerificationId)) {
+                    return rejected('APP_STORE_RECOVERY_IDENTITY_MISMATCH');
+                }
+                const priorGrant = existing ?? keyedGrant;
+                if (request.deploymentTarget === undefined
+                    && typeof priorGrant?.payload.deploymentTarget === 'string') {
+                    request = { ...request, deploymentTarget: priorGrant.payload.deploymentTarget };
+                }
+                // A stored grant lets the backend's normal retry path return its original entry.
+                const response = await options.purchases.verifyPurchase({
+                    ...request,
+                    idempotencyKey: key,
+                });
+                if (!response.verified) {
+                    return response;
+                }
+                if (response.ledgerEntryId === undefined) {
+                    return pending('APP_STORE_RECOVERY_LEDGER_UNAVAILABLE');
+                }
+                const recorded = await options.store.getEntitlementTransaction(response.ledgerEntryId);
+                if (recorded === undefined) {
+                    return pending('APP_STORE_RECOVERY_LEDGER_UNAVAILABLE');
+                }
+                return matchesRecovery(recorded, request, restoredVerificationId)
+                    ? response
+                    : rejected('APP_STORE_RECOVERY_IDENTITY_MISMATCH');
+            }
+            catch {
+                return pending('APP_STORE_RECOVERY_DEPENDENCY_UNAVAILABLE');
+            }
+        },
+    };
+}
+async function verifyRestoredNonConsumable(input, request, options) {
+    if (input.productType !== 'non_consumable'
+        || input.originalTransactionId === undefined
+        || input.originalTransactionId === input.platformTransactionId) {
+        return '';
+    }
+    const config = options.restoredNonConsumables;
+    if (config === undefined) {
+        return pending('APP_STORE_RESTORE_VERIFIER_REQUIRED');
+    }
+    const product = config.catalog.products.find((item) => item.id === request.productId);
+    if (product?.type !== 'non_consumable') {
+        return rejected('APP_STORE_RECOVERY_PRODUCT_TYPE_MISMATCH');
+    }
+    const platformProductId = resolveProductPlatformId(product, request.deploymentTarget ?? request.target);
+    if (platformProductId === undefined) {
+        return rejected('APP_STORE_RECOVERY_PRODUCT_UNAVAILABLE');
+    }
+    const timeoutMs = config.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    let timeoutHandle;
+    const timeout = new Promise((resolve) => {
+        timeoutHandle = setTimeout(() => {
+            resolve({ status: 'pending', reason: 'APP_STORE_RESTORE_VERIFICATION_TIMEOUT' });
+            controller.abort();
+        }, timeoutMs);
+    });
+    // This probe calls only the evidence verifier; it never writes a ledger grant.
+    let decision;
+    try {
+        decision = await Promise.race([
+            config.evidenceVerifier.verifyPurchase({
+                request: { ...request, idempotencyKey: 'app-store-recovery-evidence-probe' },
+                product,
+                platformProductId,
+                signal: controller.signal,
+                timeoutMs,
+            }),
+            timeout,
+        ]);
+    }
+    finally {
+        if (timeoutHandle !== undefined) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    if (decision.status === 'pending') {
+        return pending(decision.reason ?? 'APP_STORE_RESTORE_VERIFICATION_PENDING');
+    }
+    if (decision.status === 'rejected') {
+        return rejected(decision.reason);
+    }
+    const originalTransactionId = decision.payload?.appStoreOriginalTransactionId;
+    const environment = decision.payload?.appStoreEnvironment;
+    const bundleId = decision.payload?.appStoreBundleId;
+    if (decision.payload?.appStoreTransactionType !== 'Non-Consumable'
+        || originalTransactionId !== input.originalTransactionId
+        || (environment !== 'Production' && environment !== 'Sandbox')
+        || environment !== config.environment
+        || bundleId !== config.bundleId
+        || decision.verificationId !== createAppStoreVerificationId({
+            environment,
+            bundleId,
+            transactionId: originalTransactionId,
+        })) {
+        return rejected('APP_STORE_RESTORE_EVIDENCE_MISMATCH');
+    }
+    return decision.verificationId;
+}
+async function findByPlatformEvidence(store, platformTransactionId) {
+    const identity = {
+        source: 'purchase',
+        target: 'ios',
+        platformEvidenceId: platformTransactionId,
+    };
+    if (store.findEntitlementTransactionByPlatformEvidence !== undefined) {
+        return store.findEntitlementTransactionByPlatformEvidence(identity);
+    }
+    return (await store.listEntitlementTransactions()).find((transaction) => {
+        return transaction.source === identity.source
+            && transaction.payload.target === identity.target
+            && transaction.payload.platformTransactionId === identity.platformEvidenceId;
+    });
+}
+async function findByIdempotency(store, playerId, idempotencyKey) {
+    const identity = { source: 'purchase', playerId, idempotencyKey };
+    if (store.findEntitlementTransactionByIdempotency !== undefined) {
+        return store.findEntitlementTransactionByIdempotency(identity);
+    }
+    return (await store.listEntitlementTransactions()).find((transaction) => {
+        return transaction.source === identity.source
+            && transaction.playerId === identity.playerId
+            && transaction.idempotencyKey === identity.idempotencyKey;
+    });
+}
+async function findByVerificationId(store, evidenceVerificationId) {
+    const identity = { source: 'purchase', evidenceVerificationId };
+    if (store.findEntitlementTransactionByEvidenceVerificationId !== undefined) {
+        return store.findEntitlementTransactionByEvidenceVerificationId(identity);
+    }
+    return (await store.listEntitlementTransactions()).find((transaction) => {
+        return transaction.source === identity.source
+            && (transaction.evidenceVerificationId
+                ?? transaction.payload.evidenceVerificationId) === identity.evidenceVerificationId;
+    });
+}
+function matchesRecovery(transaction, request, restoredVerificationId = '') {
+    const verificationId = transaction.evidenceVerificationId
+        ?? transaction.payload.evidenceVerificationId;
+    const environment = transaction.payload.appStoreEnvironment;
+    const bundleId = transaction.payload.appStoreBundleId;
+    const originalTransactionId = transaction.payload.appStoreOriginalTransactionId;
+    const grantTransactionId = restoredVerificationId === ''
+        ? request.platformTransactionId
+        : originalTransactionId;
+    return transaction.source === 'purchase'
+        && transaction.playerId === request.playerId
+        && transaction.grantId === request.productId
+        && transaction.payload.target === 'ios'
+        && (request.deploymentTarget === undefined
+            || transaction.payload.deploymentTarget === request.deploymentTarget)
+        && (restoredVerificationId === ''
+            ? transaction.payload.platformTransactionId === request.platformTransactionId
+            : transaction.payload.productType === 'non_consumable'
+                && transaction.payload.appStoreOriginalTransactionId
+                    === request.originalTransactionId
+                && verificationId === restoredVerificationId)
+        && typeof verificationId === 'string'
+        && isAppStoreVerificationId(verificationId)
+        && (environment === 'Production' || environment === 'Sandbox')
+        && typeof bundleId === 'string'
+        && typeof grantTransactionId === 'string'
+        && verificationId === createAppStoreVerificationId({
+            environment,
+            bundleId,
+            transactionId: grantTransactionId,
+        });
+}
+function pending(reason) {
+    return { verified: false, disposition: 'pending', alreadyProcessed: false, reason };
+}
+function rejected(reason) {
+    return { verified: false, disposition: 'rejected', alreadyProcessed: false, reason };
+}

package/dist/app-store-verifier.d.ts

@@ -84,4 +84,11 @@ export type AppStoreFetch = (url: string, init: {
 }) => Promise<AppStoreFetchResponse>;
 export declare function createAppStoreServerApiClient(options: CreateAppStoreServerApiClientOptions): AppStoreServerApiClient;
 export declare function createAppStoreGameServicesEvidenceVerifier(options: CreateAppStoreEvidenceVerifierOptions): GameServicesEvidenceVerifier;
+export declare function createAppStoreVerificationId(input: {
+  readonly environment: AppStoreEnvironment;
+  readonly bundleId: string;
+  readonly transactionId: string;
+}): string;
+/** Identify IDs emitted by this verifier without duplicating its encoding format. */
+export declare function isAppStoreVerificationId(verificationId: string): boolean;
 export declare function assertAppStoreTransactionPayload(input: unknown): AppStoreTransactionPayload;

package/dist/app-store-verifier.js

@@ -248,13 +248,51 @@ function createVerificationId(transaction) {
     const grantTransactionId = transaction.type === 'Non-Consumable'
         ? transaction.originalTransactionId
         : transaction.transactionId;
+    return createAppStoreVerificationId({
+        environment: transaction.environment,
+        bundleId: transaction.bundleId,
+        transactionId: grantTransactionId,
+    });
+}
+export function createAppStoreVerificationId(input) {
     return [
         'app-store',
-        transaction.environment,
-        transaction.bundleId,
-        grantTransactionId,
+        input.environment,
+        input.bundleId,
+        input.transactionId,
     ].map(encodeVerificationIdSegment).join(':');
 }
+/** Identify IDs emitted by this verifier without duplicating its encoding format. */
+export function isAppStoreVerificationId(verificationId) {
+    const parts = verificationId.split(':');
+    if (parts.length !== 8) {
+        return false;
+    }
+    const values = [];
+    for (let index = 0; index < parts.length; index += 2) {
+        const rawLength = parts[index];
+        const encoded = parts[index + 1];
+        if (rawLength === undefined || encoded === undefined
+            || !/^(0|[1-9][0-9]*)$/u.test(rawLength)) {
+            return false;
+        }
+        try {
+            const value = decodeURIComponent(encoded);
+            if (value.length !== Number(rawLength)
+                || encodeVerificationIdSegment(value) !== `${rawLength}:${encoded}`) {
+                return false;
+            }
+            values.push(value);
+        }
+        catch {
+            return false;
+        }
+    }
+    return values[0] === 'app-store'
+        && (values[1] === 'Production' || values[1] === 'Sandbox')
+        && typeof values[2] === 'string' && values[2].length > 0
+        && typeof values[3] === 'string' && /^[1-9][0-9]{0,19}$/u.test(values[3]);
+}
 function encodeVerificationIdSegment(value) {
     return `${value.length}:${encodeURIComponent(value)}`;
 }

package/dist/authoritative-purchase.d.ts

@@ -0,0 +1,9 @@
+import type { PurchaseResult } from '@mpgd/platform';
+/**
+* Internal: the Microsoft Store adapter completes the ledger grant before it returns this
+* checkout result, so no further backend verification is requested for it.
+*/
+export declare function isAuthoritativeMicrosoftStoreCompletion(target: string, purchase: PurchaseResult): purchase is PurchaseResult & {
+  readonly status: 'completed';
+  readonly transactionId: string;
+};

package/dist/authoritative-purchase.js

@@ -0,0 +1,10 @@
+/**
+ * Internal: the Microsoft Store adapter completes the ledger grant before it returns this
+ * checkout result, so no further backend verification is requested for it.
+ */
+export function isAuthoritativeMicrosoftStoreCompletion(target, purchase) {
+    return target === 'microsoft-store'
+        && purchase.status === 'completed'
+        && purchase.transactionId !== undefined
+        && purchase.authoritativeGrant?.ledgerEntryId === purchase.transactionId;
+}

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>;
 }
@@ -79,6 +98,8 @@ export interface CreateGameServicesClientInput {
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
   readonly now?: () => string;
+  /** Override backend evidence timestamps without backdating analytics events. */
+  readonly requestNow?: () => string;
 }
 export interface GameServicesLeaderboardInput extends LeaderboardScoreInput {
 }