@mpgd/game-services 0.15.3 → 0.17.0

package/dist/client.js

@@ -1,6 +1,8 @@
 import { createORPCClient } from '@orpc/client';
 import { RPCLink } from '@orpc/client/fetch';
 import { createAnalyticsReporter } from '@mpgd/analytics';
+import { isAdMobClientRewardEvidence } from './admob-client-reward.js';
+import { isAuthoritativeMicrosoftStoreCompletion } from './authoritative-purchase.js';
 import { observeGameServicesOperation } from './operation-progress.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
@@ -19,8 +21,42 @@ 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 requestNow = input.requestNow ?? now;
     const analytics = createAnalyticsReporter({
         target: input.target,
         sessionId: input.analyticsSessionId ?? input.playerId,
@@ -55,7 +91,7 @@ export function createGameServicesClient(input) {
                 if (target === 'verse8') {
                     const status = purchase.status === 'completed' ? 'rejected' : purchase.status;
                     await analytics.track({
-                        name: 'purchase_rejected',
+                        name: purchase.status === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                         properties: {
                             productId: purchaseInput.productId,
                             status,
@@ -90,7 +126,7 @@ export function createGameServicesClient(input) {
                 }
                 if (purchase.status !== 'completed' || purchase.transactionId === undefined) {
                     await analytics.track({
-                        name: 'purchase_rejected',
+                        name: purchase.status === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                         properties: {
                             productId: purchaseInput.productId,
                             status: purchase.status,
@@ -111,14 +147,14 @@ export function createGameServicesClient(input) {
                     productId: purchaseInput.productId,
                     platformTransactionId: purchase.transactionId,
                     idempotencyKey: purchaseInput.idempotencyKey,
-                    purchasedAt: now(),
+                    purchasedAt: requestNow(),
                     ...(purchase.evidence === undefined ? {} : { evidence: purchase.evidence }),
                 };
                 progress.serverRequested();
                 const verification = await input.backend.purchases.verifyPurchase(verificationRequest);
                 progress.serverResult(verification.verified);
                 const result = {
-                    status: verification.verified ? 'granted' : 'rejected',
+                    status: verification.verified ? 'granted' : (verification.disposition ?? 'rejected'),
                     purchase,
                     verification,
                     ...(verification.ledgerEntryId === undefined
@@ -126,7 +162,7 @@ export function createGameServicesClient(input) {
                         : { ledgerEntryId: verification.ledgerEntryId }),
                 };
                 await analytics.track({
-                    name: verification.verified ? 'purchase_granted' : 'purchase_rejected',
+                    name: verification.verified ? 'purchase_granted' : verification.disposition === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                     properties: {
                         productId: purchaseInput.productId,
                         status: result.status,
@@ -163,9 +199,10 @@ export function createGameServicesClient(input) {
                 progress.platformRequested();
                 const reward = await input.gateway.ads.showRewarded(rewardInput);
                 progress.platformResult(reward.status);
-                if (reward.status !== 'completed' || !reward.rewardGranted) {
+                if ((reward.status !== 'completed' || !reward.rewardGranted)
+                    && !isAdMobClientRewardEvidence(reward)) {
                     await analytics.track({
-                        name: 'rewarded_ad_rejected',
+                        name: reward.status === 'pending' ? 'rewarded_ad_pending' : 'rewarded_ad_rejected',
                         properties: {
                             placementId: rewardInput.placementId,
                             status: reward.status,
@@ -188,20 +225,20 @@ export function createGameServicesClient(input) {
                         ? {}
                         : { platformImpressionId: reward.ledgerEntryId }),
                     idempotencyKey: rewardInput.idempotencyKey,
-                    completedAt: now(),
+                    completedAt: requestNow(),
                     ...(reward.evidence === undefined ? {} : { evidence: reward.evidence }),
                 };
                 progress.serverRequested();
                 const claim = await input.backend.adRewards.claimAdReward(claimRequest);
                 progress.serverResult(claim.granted);
                 const result = {
-                    status: claim.granted ? 'granted' : 'rejected',
+                    status: claim.granted ? 'granted' : (claim.disposition ?? 'rejected'),
                     reward,
                     claim,
                     ...(claim.ledgerEntryId === undefined ? {} : { ledgerEntryId: claim.ledgerEntryId }),
                 };
                 await analytics.track({
-                    name: claim.granted ? 'rewarded_ad_granted' : 'rewarded_ad_rejected',
+                    name: claim.granted ? 'rewarded_ad_granted' : claim.disposition === 'pending' ? 'rewarded_ad_pending' : 'rewarded_ad_rejected',
                     properties: {
                         placementId: rewardInput.placementId,
                         status: result.status,
@@ -297,10 +334,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 +358,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);
@@ -364,12 +406,6 @@ function purchaseRejectionReason(purchase) {
     }
     return undefined;
 }
-function isAuthoritativeMicrosoftStoreCompletion(target, purchase) {
-    return target === 'microsoft-store'
-        && purchase.status === 'completed'
-        && purchase.transactionId !== undefined
-        && purchase.authoritativeGrant?.ledgerEntryId === purchase.transactionId;
-}
 function isGameServicesCommerceTarget(target) {
     return target === 'microsoft-store'
         || target === 'android'
@@ -389,11 +425,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/google-play-publisher-client.d.ts

@@ -0,0 +1,11 @@
+import type { GooglePlayProductPurchaseClient } from './google-play-purchase.js';
+export interface GooglePlayPublisherClientOptions {
+  /** Supplies an androidpublisher-scoped OAuth access token for each request. */
+  readonly getAccessToken: (signal: AbortSignal) => Promise<string> | string;
+  readonly fetch?: typeof fetch;
+}
+/**
+* Google Play purchase verification and post-ledger finalization transport.
+* The caller owns OAuth credential rotation and must never expose this client to the game.
+*/
+export declare function createGooglePlayPublisherClient(options: GooglePlayPublisherClientOptions): GooglePlayProductPurchaseClient;

package/dist/google-play-publisher-client.js

@@ -0,0 +1,113 @@
+const publisherOrigin = 'https://androidpublisher.googleapis.com';
+/**
+ * Google Play purchase verification and post-ledger finalization transport.
+ * The caller owns OAuth credential rotation and must never expose this client to the game.
+ */
+export function createGooglePlayPublisherClient(options) {
+    const requestFetch = options.fetch ?? fetch;
+    async function request(method, path, signal) {
+        const accessToken = await options.getAccessToken(signal);
+        if (accessToken.length === 0 || /[\s\x00-\x1f\x7f]/u.test(accessToken)) {
+            throw new TypeError('Google Play Publisher access token is invalid.');
+        }
+        let response;
+        try {
+            response = await requestFetch(`${publisherOrigin}${path}`, {
+                method,
+                headers: { Authorization: `Bearer ${accessToken}` },
+                redirect: 'error',
+                signal,
+            });
+        }
+        catch {
+            if (signal.aborted) {
+                throw new DOMException('Google Play Publisher request was cancelled.', 'AbortError');
+            }
+            // Fetch errors can contain the request URL (including the purchase token).
+            throw new Error('Google Play Publisher request failed.');
+        }
+        if (!response.ok) {
+            await discardBody(response);
+            // Do not forward an error body or URL: both can contain purchase credentials.
+            throw new Error(`Google Play Publisher request failed (HTTP ${response.status}).`);
+        }
+        return response;
+    }
+    return {
+        async getProductPurchaseV2({ packageName, purchaseToken, signal }) {
+            const path = `${purchasePath(packageName)}/productsv2/tokens/${pathPart(purchaseToken)}`;
+            const response = await request('GET', path, signal);
+            try {
+                return await readBoundedJson(response);
+            }
+            catch {
+                if (signal.aborted) {
+                    throw new DOMException('Google Play Publisher request was cancelled.', 'AbortError');
+                }
+                throw new Error('Google Play Publisher returned invalid purchase JSON.');
+            }
+        },
+        async acknowledgeProductPurchase({ packageName, productId, purchaseToken, signal }) {
+            const path = `${purchasePath(packageName)}/products/${pathPart(productId)}`
+                + `/tokens/${pathPart(purchaseToken)}:acknowledge`;
+            await discardBody(await request('POST', path, signal));
+        },
+        async consumeProductPurchase({ packageName, productId, purchaseToken, signal }) {
+            const path = `${purchasePath(packageName)}/products/${pathPart(productId)}`
+                + `/tokens/${pathPart(purchaseToken)}:consume`;
+            await discardBody(await request('POST', path, signal));
+        },
+    };
+}
+function purchasePath(packageName) {
+    return `/androidpublisher/v3/applications/${pathPart(packageName)}/purchases`;
+}
+function pathPart(value) {
+    if (value.length === 0
+        || value === '.'
+        || value === '..'
+        || value.trim() !== value
+        || /[\x00-\x1f\x7f]/u.test(value)) {
+        throw new TypeError('Google Play Publisher path parameter is invalid.');
+    }
+    return encodeURIComponent(value);
+}
+async function discardBody(response) {
+    await response.body?.cancel().catch(() => undefined);
+}
+async function readBoundedJson(response) {
+    const body = response.body;
+    if (body === null) {
+        throw new Error('Missing Google Play Publisher response body.');
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                break;
+            }
+            size += next.value.byteLength;
+            if (size > 1024 * 1024) {
+                throw new Error('Google Play Publisher response exceeds maximum size.');
+            }
+            chunks.push(next.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+}

package/dist/google-play-purchase.d.ts

@@ -38,3 +38,5 @@ export interface GooglePlayProductPurchaseBoundary extends GameServicesPurchaseG
   verifyPurchase(input: VerifyPurchaseEvidenceInput): ReturnType<GameServicesEvidenceVerifier['verifyPurchase']>;
 }
 export declare function createGooglePlayProductPurchaseBoundary(input: CreateGooglePlayProductPurchaseBoundaryInput): GooglePlayProductPurchaseBoundary;
+/** A non-secret transaction ID for purchases whose Google order ID is absent or delayed. */
+export declare function createGooglePlayTokenTransactionId(purchaseToken: string): Promise<string>;

package/dist/google-play-purchase.js

@@ -45,10 +45,7 @@ export function createGooglePlayProductPurchaseBoundary(input) {
                 purchaseToken,
                 expectedProductId: verificationInput.platformProductId,
                 expectedProductType: verificationInput.product.type,
-                orderMatch: {
-                    mode: 'if-present',
-                    orderId: verificationInput.request.platformTransactionId,
-                },
+                orderMatch: createGooglePlayObservedOrderMatch(verificationInput.request.platformTransactionId, await createGooglePlayTokenTransactionId(purchaseToken)),
                 accountBinding,
                 allowConsumed: false,
                 signal: verificationInput.signal,
@@ -146,7 +143,7 @@ async function finalizeGooglePlayPurchase(input, packageName, purchaseToken, pro
             purchaseToken,
             expectedProductId: finalizationInput.platformProductId,
             expectedProductType: productType,
-            orderMatch: createGooglePlayFinalizationOrderMatch(verifiedContext, finalizationInput.request.platformTransactionId),
+            orderMatch: createGooglePlayFinalizationOrderMatch(verifiedContext, finalizationInput.request.platformTransactionId, await createGooglePlayTokenTransactionId(purchaseToken)),
             accountBinding,
             allowConsumed: true,
             signal: finalizationInput.signal,
@@ -369,15 +366,32 @@ async function inspectGooglePlayPurchase(input) {
         },
     };
 }
-function createGooglePlayFinalizationOrderMatch(verifiedContext, clientOrderId) {
+function createGooglePlayFinalizationOrderMatch(verifiedContext, clientOrderId, tokenTransactionId) {
     if (verifiedContext === undefined) {
-        return { mode: 'if-present', orderId: clientOrderId };
+        return createGooglePlayObservedOrderMatch(clientOrderId, tokenTransactionId);
     }
     if (verifiedContext.orderId === undefined) {
         return { mode: 'token-only' };
     }
     return { mode: 'exact', orderId: verifiedContext.orderId };
 }
+function createGooglePlayObservedOrderMatch(observedTransactionId, tokenTransactionId) {
+    return observedTransactionId === tokenTransactionId
+        ? { mode: 'token-only' }
+        : { mode: 'if-present', orderId: observedTransactionId };
+}
+/** A non-secret transaction ID for purchases whose Google order ID is absent or delayed. */
+export async function createGooglePlayTokenTransactionId(purchaseToken) {
+    if (readOptionalIdentifier(purchaseToken, 4096) === undefined) {
+        throw new TypeError('Google Play purchase token is invalid.');
+    }
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) {
+        throw new Error('Web Crypto is required to hash Google Play purchase tokens.');
+    }
+    const digest = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(purchaseToken)));
+    return `play-token-sha256:${[...digest].map((value) => value.toString(16).padStart(2, '0')).join('')}`;
+}
 function readGooglePlayVerifiedContext(payload, packageName, productId, purchaseTokenDigest) {
     if (payload?.googlePlayPackageName !== packageName
         || payload.googlePlayProductId !== productId

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;