@mpgd/game-services 0.17.0 → 0.17.2

package/dist/admob-client-reward.d.ts

@@ -1,3 +1,27 @@
+import type { RewardedAdResult } from '@mpgd/platform';
 /** 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;
+/**
+* Verse8 Ads SDK callback evidence. Mirrors `verse8AdsRewardEvidenceSchema`
+* from `@mpgd/adapter-verse8`; the adapter owns the schema and the backend
+* verifier consumes it, so the value must stay byte-identical on both sides.
+*/
+export declare const verse8ClientRewardEvidenceSchema = "verse8.ads.reward.v1";
+/**
+* Evidence schemas that a client adapter may return with
+* `status: 'completed' | 'pending'`, `rewardGranted: false`, and no
+* `ledgerEntryId`. They are claim candidates only: the backend ledger decides
+* whether a reward is granted.
+*/
+export declare const clientRewardEvidenceSchemas: readonly ["mpgd.admob.client-reward.v1", "verse8.ads.reward.v1"];
+export type ClientRewardEvidenceSchema = (typeof clientRewardEvidenceSchemas)[number];
+/** True when a rewarded-ad result carries ungranted evidence from an allow-listed schema. */
+export declare function isClientRewardEvidence(value: unknown): boolean;
+export declare function isVerse8ClientRewardEvidence(value: unknown): boolean;
+/**
+* Resolve the platform impression identifier to forward with a backend claim.
+* Authoritative adapters return `ledgerEntryId`; client-evidence adapters
+* expose the impression identifier inside the evidence payload instead.
+*/
+export declare function resolveRewardPlatformImpressionId(reward: RewardedAdResult): string | undefined;

package/dist/admob-client-reward.js

@@ -19,3 +19,66 @@ export function isAdMobClientRewardEvidence(value) {
         && typeof payload.adUnitId === 'string'
         && payload.adUnitId.length > 0;
 }
+/**
+ * Verse8 Ads SDK callback evidence. Mirrors `verse8AdsRewardEvidenceSchema`
+ * from `@mpgd/adapter-verse8`; the adapter owns the schema and the backend
+ * verifier consumes it, so the value must stay byte-identical on both sides.
+ */
+export const verse8ClientRewardEvidenceSchema = 'verse8.ads.reward.v1';
+/**
+ * Evidence schemas that a client adapter may return with
+ * `status: 'completed' | 'pending'`, `rewardGranted: false`, and no
+ * `ledgerEntryId`. They are claim candidates only: the backend ledger decides
+ * whether a reward is granted.
+ */
+export const clientRewardEvidenceSchemas = Object.freeze([
+    admobClientRewardEvidenceSchema,
+    verse8ClientRewardEvidenceSchema,
+]);
+/** True when a rewarded-ad result carries ungranted evidence from an allow-listed schema. */
+export function isClientRewardEvidence(value) {
+    return isAdMobClientRewardEvidence(value) || isVerse8ClientRewardEvidence(value);
+}
+export function isVerse8ClientRewardEvidence(value) {
+    const payload = readUngrantedEvidencePayload(value, verse8ClientRewardEvidenceSchema);
+    return payload !== undefined
+        && isNonEmptyString(payload.requestId)
+        && isNonEmptyString(payload.placementId);
+}
+/**
+ * Resolve the platform impression identifier to forward with a backend claim.
+ * Authoritative adapters return `ledgerEntryId`; client-evidence adapters
+ * expose the impression identifier inside the evidence payload instead.
+ */
+export function resolveRewardPlatformImpressionId(reward) {
+    if (reward.ledgerEntryId !== undefined) {
+        return reward.ledgerEntryId;
+    }
+    if (isVerse8ClientRewardEvidence(reward)) {
+        return reward.evidence?.payload.requestId;
+    }
+    return undefined;
+}
+function readUngrantedEvidencePayload(value, schema) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    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 undefined;
+    }
+    const envelope = evidence;
+    const payload = envelope.payload;
+    if (envelope.schema !== schema
+        || typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return undefined;
+    }
+    return payload;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}

package/dist/admob-ssv.js

@@ -216,10 +216,13 @@ async function verifyAdMobSsvReward(context, input) {
     if (callback.timestampMs < nowMs - context.maximumCallbackAgeMs) {
         return rejected('ADMOB_SSV_CALLBACK_EXPIRED');
     }
+    // SSV never validates the client-reported `platformImpressionId`, so the signed
+    // transaction becomes the platform evidence identity instead of the client value.
     return {
         status: 'verified',
         verificationId: `admob:ssv:${callback.transactionId}`,
         verifiedAt: new Date(callback.timestampMs).toISOString(),
+        platformEvidenceId: callback.transactionId,
         payload: {
             admobSsvTransactionId: callback.transactionId,
             admobSsvAdNetwork: callback.adNetwork,

package/dist/apps-in-toss-evidence-verification-conformance.d.ts

@@ -1,6 +1,6 @@
 import { type AppsInTossPurchaseAuthority, type AppsInTossPurchaseAuthorityInput, type AppsInTossPurchaseAuthorityResult, type AppsInTossRewardAuthority, type AppsInTossRewardAuthorityInput, type AppsInTossRewardAuthorityResult, type CreateAppsInTossProductionEvidenceVerifierInput } from './apps-in-toss-evidence-verification.js';
 import type { GameServicesEvidenceVerifier } from './evidence-verification.js';
-export declare const appsInTossProductionEvidenceConformanceScenarios: readonly ['callback-only-fail-closed', 'purchase-product-grant-callback', 'purchase-authority-retry', 'purchase-pending-order-restore', 'purchase-authority-matching', 'purchase-timestamp-normalization', 'reward-authority-retry-and-replay', 'reward-timestamp-validation', 'authority-errors-and-reward-matching'];
+export declare const appsInTossProductionEvidenceConformanceScenarios: readonly ['callback-only-fail-closed', 'purchase-product-grant-callback', 'purchase-authority-retry', 'purchase-pending-order-restore', 'purchase-authority-matching', 'purchase-subscription-unsupported', 'purchase-timestamp-normalization', 'reward-authority-retry-and-replay', 'reward-timestamp-validation', 'authority-errors-and-reward-matching'];
 export type AppsInTossProductionEvidenceConformanceScenario = (typeof appsInTossProductionEvidenceConformanceScenarios)[number];
 export type CreateAppsInTossProductionEvidenceVerifier = (input?: CreateAppsInTossProductionEvidenceVerifierInput) => GameServicesEvidenceVerifier;
 export interface RunAppsInTossProductionEvidenceConformanceInput {

package/dist/apps-in-toss-evidence-verification-conformance.js

@@ -6,6 +6,7 @@ export const appsInTossProductionEvidenceConformanceScenarios = [
     'purchase-authority-retry',
     'purchase-pending-order-restore',
     'purchase-authority-matching',
+    'purchase-subscription-unsupported',
     'purchase-timestamp-normalization',
     'reward-authority-retry-and-replay',
     'reward-timestamp-validation',
@@ -26,6 +27,17 @@ const catalog = {
                 ait: 'ait.conformance.coins',
             },
         },
+        {
+            id: 'CONFORMANCE_PASS',
+            type: 'subscription',
+            grant: {
+                type: 'entitlement',
+                entitlement: 'conformance_pass',
+            },
+            platformProductIds: {
+                ait: 'ait.conformance.pass',
+            },
+        },
     ],
 };
 const placements = {
@@ -54,6 +66,7 @@ const scenarioRunners = {
     'purchase-authority-retry': runPurchaseAuthorityRetryScenario,
     'purchase-pending-order-restore': runPurchasePendingOrderRestoreScenario,
     'purchase-authority-matching': runPurchaseAuthorityMatchingScenario,
+    'purchase-subscription-unsupported': runPurchaseSubscriptionUnsupportedScenario,
     'purchase-timestamp-normalization': runPurchaseTimestampNormalizationScenario,
     'reward-authority-retry-and-replay': runRewardAuthorityRetryAndReplayScenario,
     'reward-timestamp-validation': runRewardTimestampValidationScenario,
@@ -309,6 +322,30 @@ async function runPurchaseAuthorityMatchingScenario(createVerifier, now) {
     assertEqual(progress.reason, 'AIT_PURCHASE_ORDER_ORDER_IN_PROGRESS', 'in-progress purchase');
     await assertEntitlementCount(context.store, 0, 'purchase mismatches and status');
 }
+async function runPurchaseSubscriptionUnsupportedScenario(createVerifier, now) {
+    const fixture = createAppsInTossProductionEvidenceAuthorityFixture();
+    fixture.enqueuePurchaseResult(resolvedOrder({
+        orderId: 'ait-order-subscription',
+        sku: 'ait.conformance.pass',
+    }));
+    const context = createScenarioContext(createVerifier, now, {
+        purchaseAuthority: fixture.purchaseAuthority,
+    });
+    const subscription = await context.backend.purchases.verifyPurchase(purchaseRequest({
+        productId: 'CONFORMANCE_PASS',
+        platformTransactionId: 'ait-order-subscription',
+        idempotencyKey: 'purchase-subscription',
+        evidence: createAppsInTossPurchaseCallbackEvidence({
+            orderId: 'ait-order-subscription',
+            platformSku: 'ait.conformance.pass',
+            source: 'process-product-grant',
+        }),
+    }));
+    assertEqual(subscription.verified, false, 'subscription purchase must not grant');
+    assertEqual(subscription.reason, 'APPS_IN_TOSS_SUBSCRIPTION_UNSUPPORTED', 'subscription purchase must be rejected explicitly');
+    assertEqual(fixture.purchaseInputs.length, 0, 'unsupported subscriptions must fail before the purchase authority is called');
+    await assertEntitlementCount(context.store, 0, 'unsupported subscription purchase');
+}
 async function runPurchaseTimestampNormalizationScenario(createVerifier, now) {
     const fixture = createAppsInTossProductionEvidenceAuthorityFixture();
     fixture.enqueuePurchaseResult(resolvedOrder({

package/dist/apps-in-toss-evidence-verification.js

@@ -150,6 +150,11 @@ async function verifyAppsInTossPurchase(authority, input) {
     if (request.target !== 'ait') {
         return rejected('AIT_PURCHASE_TARGET_REQUIRED');
     }
+    // One-time order status cannot express renewal, expiry, or revocation. Reject
+    // explicitly instead of relying on the adapter hiding SUBSCRIPTION products.
+    if (input.product.type === 'subscription') {
+        return rejected('APPS_IN_TOSS_SUBSCRIPTION_UNSUPPORTED');
+    }
     if (request.evidence?.schema !== appsInTossPurchaseCallbackEvidenceSchema) {
         return rejected('AIT_PURCHASE_EVIDENCE_SCHEMA_INVALID');
     }

package/dist/client.js

@@ -1,8 +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 { isClientRewardEvidence, resolveRewardPlatformImpressionId, } from './admob-client-reward.js';
 import { observeGameServicesOperation } from './operation-progress.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
@@ -200,7 +200,7 @@ export function createGameServicesClient(input) {
                 const reward = await input.gateway.ads.showRewarded(rewardInput);
                 progress.platformResult(reward.status);
                 if ((reward.status !== 'completed' || !reward.rewardGranted)
-                    && !isAdMobClientRewardEvidence(reward)) {
+                    && !isClientRewardEvidence(reward)) {
                     await analytics.track({
                         name: reward.status === 'pending' ? 'rewarded_ad_pending' : 'rewarded_ad_rejected',
                         properties: {
@@ -214,6 +214,7 @@ export function createGameServicesClient(input) {
                         reward,
                     };
                 }
+                const platformImpressionId = resolveRewardPlatformImpressionId(reward);
                 const claimRequest = {
                     target,
                     ...(input.deploymentTarget === undefined || input.deploymentTarget === target
@@ -221,9 +222,9 @@ export function createGameServicesClient(input) {
                         : { deploymentTarget: input.deploymentTarget }),
                     playerId: input.playerId,
                     placementId: rewardInput.placementId,
-                    ...(reward.ledgerEntryId === undefined
+                    ...(platformImpressionId === undefined
                         ? {}
-                        : { platformImpressionId: reward.ledgerEntryId }),
+                        : { platformImpressionId }),
                     idempotencyKey: rewardInput.idempotencyKey,
                     completedAt: requestNow(),
                     ...(reward.evidence === undefined ? {} : { evidence: reward.evidence }),

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
+export * from './admob-client-reward.js';
 export * from './contract.js';
 export * from './evidence-verification.js';
 export * from './guest-session.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
+export * from './admob-client-reward.js';
 export * from './contract.js';
 export * from './evidence-verification.js';
 export * from './guest-session.js';

package/dist/monetization-recovery.js

@@ -1,6 +1,6 @@
-import { isAdMobClientRewardEvidence } from './admob-client-reward.js';
 import { isAuthoritativeMicrosoftStoreCompletion } from './authoritative-purchase.js';
 import { createGameServicesClient } from './client.js';
+import { isClientRewardEvidence, resolveRewardPlatformImpressionId, } from './admob-client-reward.js';
 import { forwardGameServicesProgress, observeGameServicesOperation, } from './operation-progress.js';
 /**
  * Client-side recovery coordinates UI callbacks and authoritative backend calls.
@@ -620,11 +620,11 @@ function assertRewardRequest(record, input) {
     const request = record.request;
     if (request === undefined || record.platform === undefined
         || ((record.platform.status !== 'completed' || !record.platform.rewardGranted)
-            && !isAdMobClientRewardEvidence(record.platform))
+            && !isClientRewardEvidence(record.platform))
         || request.playerId !== record.playerId || request.playerId !== input.playerId
         || request.target !== record.target || request.placementId !== record.input.placementId
         || request.idempotencyKey !== record.input.idempotencyKey
-        || request.platformImpressionId !== record.platform.ledgerEntryId
+        || request.platformImpressionId !== resolveRewardPlatformImpressionId(record.platform)
         || request.deploymentTarget !== (input.deploymentTarget === input.target
             ? undefined : input.deploymentTarget)) {
         throw new Error('Journaled ad claim is not bound to its platform result.');

package/dist/server.d.ts

@@ -4,6 +4,7 @@ import { type GameServicesBackendApi, type GameServicesBackendTransport, type Ga
 import { type GameServicesHealthResponse } from './contract.js';
 import { type GameServicesEvidenceVerifier, type GameServicesPurchaseGrantFinalizer } from './evidence-verification.js';
 import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerResult, type GameServicesAdRewardTarget, type GameServicesStoreTarget, type LeaderboardScoreTransaction, type ProductGrantTransaction, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types.js';
+export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
 type CorsHeaders = Record<string, string>;
 export interface CreateGameServicesBackendInput {
   readonly catalog: ProductCatalog;
@@ -19,14 +20,26 @@ export interface CreateGameServicesBackendInput {
   readonly evidenceVerificationTimeoutMs?: number;
   readonly purchaseGrantFinalizationTimeoutMs?: number;
   readonly purchaseGrantFinalizer?: GameServicesPurchaseGrantFinalizer;
+  /**
+  * Receives unexpected (non-validation) failures such as store errors before the
+  * transport answers with the generic `INTERNAL_ERROR` code. Defaults to `console.error`.
+  * The hook is diagnostics only: if it throws or returns a rejecting promise, the failure
+  * is logged and the generic error response is still returned.
+  */
+  readonly onInternalError?: GameServicesInternalErrorHandler;
 }
+export type GameServicesInternalErrorHandler = (error: unknown) => void;
 export type GameServicesDeploymentTargetBindings = Readonly<Partial<Record<GameServicesAdRewardTarget | GameServicesStoreTarget, string>>>;
 export interface GameServicesBackendApiHandler {
   readonly version?: string;
   handle(request: GameServicesBackendTransportRequest): Promise<GameServicesBackendTransportResponse>;
 }
+/** Stable error codes emitted by the backend API handler and the HTTP fetch handler. */
+export type GameServicesBackendErrorCode = 'INVALID_REQUEST' | 'INVALID_JSON' | 'PAYLOAD_TOO_LARGE' | 'METHOD_NOT_ALLOWED' | 'UNKNOWN_ENDPOINT' | 'INTERNAL_ERROR';
 export interface GameServicesBackendErrorResponse {
-  readonly error: string;
+  readonly error: GameServicesBackendErrorCode;
+  /** Present only for `INVALID_REQUEST`; never carries internal failure details. */
+  readonly message?: string;
 }
 export interface GameServicesStore {
   recordEntitlementGrant(input: EntitlementLedgerGrant): Promise<EntitlementLedgerResult>;
@@ -57,6 +70,11 @@ export interface CreateGameServicesFetchHandlerOptions {
   readonly corsHeaders?: CorsHeaders;
   readonly healthPath?: string;
   readonly version?: string;
+  /** Request bodies above this byte size are rejected with 413. */
+  readonly maxBodyBytes?: number;
+}
+export interface CreateGameServicesRouterOptions {
+  readonly onInternalError?: GameServicesInternalErrorHandler;
 }
 export interface CreateGameServicesRpcFetchHandlerOptions extends CreateGameServicesFetchHandlerOptions {
   readonly prefix?: string;
@@ -99,7 +117,7 @@ export declare function createInMemoryGameServicesStore(): InMemoryGameServicesS
 export declare function createGameServicesBackend(input: CreateGameServicesBackendInput): GameServicesBackendApi;
 export declare function createGameServicesBackendApiHandler(input: CreateGameServicesBackendInput): GameServicesBackendApiHandler;
 export declare function createInProcessGameServicesBackendTransport(handler: GameServicesBackendApiHandler): GameServicesBackendTransport;
-export declare function createGameServicesRouter(backend: GameServicesBackendApi): {
+export declare function createGameServicesRouter(backend: GameServicesBackendApi, options?: CreateGameServicesRouterOptions): {
   health: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<void, void>, import("@orpc/contract").Schema<GameServicesHealthResponse, GameServicesHealthResponse>, object>;
   commerce: {
     verifyPurchase: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<VerifyPurchaseRequest, VerifyPurchaseRequest>, import("@orpc/contract").Schema<VerifyPurchaseResponse, VerifyPurchaseResponse>, object>;

package/dist/server.js

@@ -1,11 +1,13 @@
-import { implement } from '@orpc/server';
-import { RPCHandler } from '@orpc/server/fetch';
+import { implement, ORPCError } from '@orpc/server';
+import { BodyLimitHandlerPlugin, RPCHandler } from '@orpc/server/fetch';
 import { createAnalyticsReporter } from '@mpgd/analytics';
 import { resolveAdPlacementPlatformId, resolveProductPlatformId, } from '@mpgd/catalog';
 import { gameServicesBackendEndpoints, } from './client.js';
 import { gameServicesContract } from './contract.js';
 import { createRejectingGameServicesEvidenceVerifier, } from './evidence-verification.js';
 import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertGameServicesDeploymentTarget, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types.js';
+import { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
+export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
 export class InMemoryGameServicesStore {
     entitlementTransactionsByKey = new Map();
     entitlementTransactionsByEvidence = new Map();
@@ -233,11 +235,42 @@ export function createGameServicesBackendApiHandler(input) {
                 return await routeGameServicesRequest(request.endpoint, request.body, backend);
             }
             catch (error) {
-                return errorResponse(400, error instanceof Error ? error.message : 'BAD_REQUEST');
+                if (error instanceof GameServicesRequestValidationError) {
+                    return errorResponse(400, 'INVALID_REQUEST', error.message);
+                }
+                reportInternalError(input.onInternalError, error);
+                return errorResponse(500, 'INTERNAL_ERROR');
             }
         },
     };
 }
+/**
+ * Invokes the diagnostics hook in isolation: a throwing hook, or one that returns a
+ * rejecting promise (assignable to the `void`-returning handler type), must never replace
+ * the generic `INTERNAL_ERROR` response or escape as an unhandled rejection.
+ */
+function reportInternalError(handler, error) {
+    if (handler === undefined) {
+        console.error('GameServices backend internal error:', error);
+        return;
+    }
+    try {
+        const result = handler(error);
+        if (isPromiseLike(result)) {
+            result.then(undefined, (hookError) => {
+                console.error('GameServices backend onInternalError handler rejected:', hookError);
+            });
+        }
+    }
+    catch (hookError) {
+        console.error('GameServices backend onInternalError handler threw:', hookError);
+    }
+}
+function isPromiseLike(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && typeof value.then === 'function');
+}
 export function createInProcessGameServicesBackendTransport(handler) {
     return {
         async send(request) {
@@ -245,29 +278,49 @@ export function createInProcessGameServicesBackendTransport(handler) {
         },
     };
 }
-export function createGameServicesRouter(backend) {
+export function createGameServicesRouter(backend, options = {}) {
     const contract = implement(gameServicesContract).$context();
+    // oRPC already hides non-ORPCError messages behind INTERNAL_SERVER_ERROR; validation
+    // failures are surfaced as BAD_REQUEST so clients get a stable 400 instead of a 500.
+    const invoke = async (task) => {
+        try {
+            return await task();
+        }
+        catch (error) {
+            if (error instanceof GameServicesRequestValidationError) {
+                throw new ORPCError('BAD_REQUEST', { message: error.message });
+            }
+            reportInternalError(options.onInternalError, error);
+            throw error;
+        }
+    };
     return contract.router({
         health: contract.health.handler(() => createHealthResponse(backend.version)),
         commerce: contract.commerce.router({
             verifyPurchase: contract.commerce.verifyPurchase.handler(({ input }) => {
-                return backend.purchases.verifyPurchase(input);
+                return invoke(() => backend.purchases.verifyPurchase(input));
             }),
         }),
         ads: contract.ads.router({
             claimReward: contract.ads.claimReward.handler(({ input }) => {
-                return backend.adRewards.claimAdReward(input);
+                return invoke(() => backend.adRewards.claimAdReward(input));
             }),
         }),
         leaderboard: contract.leaderboard.router({
             recordScore: contract.leaderboard.recordScore.handler(({ input }) => {
-                return backend.leaderboard.recordScore(input);
+                return invoke(() => backend.leaderboard.recordScore(input));
             }),
         }),
     });
 }
 export function createGameServicesRpcFetchHandler(router, options = {}) {
-    const rpcHandler = new RPCHandler(router);
+    const rpcHandler = new RPCHandler(router, {
+        plugins: [
+            new BodyLimitHandlerPlugin({
+                maxBodySize: resolveMaxBodyBytes(options.maxBodyBytes),
+            }),
+        ],
+    });
     const prefix = options.prefix ?? '/rpc';
     const healthPath = options.healthPath ?? '/health';
     return async (request) => {
@@ -292,6 +345,7 @@ export function createGameServicesRpcFetchHandler(router, options = {}) {
 }
 export function createGameServicesHttpFetchHandler(handler, options = {}) {
     const healthPath = options.healthPath ?? '/health';
+    const maxBodyBytes = resolveMaxBodyBytes(options.maxBodyBytes);
     return async (request) => {
         const requestUrl = new URL(request.url);
         if (requestUrl.pathname === healthPath) {
@@ -306,19 +360,39 @@ export function createGameServicesHttpFetchHandler(handler, options = {}) {
         if (!isGameServicesBackendEndpoint(requestUrl.pathname)) {
             return jsonResponse({ error: 'UNKNOWN_ENDPOINT' }, 404, options.corsHeaders);
         }
+        let body;
+        try {
+            body = await readRequestJson(request, maxBodyBytes);
+        }
+        catch (error) {
+            if (error instanceof RequestPayloadTooLargeError) {
+                return jsonResponse({ error: 'PAYLOAD_TOO_LARGE' }, 413, options.corsHeaders);
+            }
+            return jsonResponse({ error: 'INVALID_JSON' }, 400, options.corsHeaders);
+        }
         try {
             const response = await handler.handle({
                 method: 'POST',
                 endpoint: requestUrl.pathname,
-                body: await readRequestJson(request),
+                body,
             });
             return jsonResponse(response.body, response.status, options.corsHeaders);
         }
         catch (error) {
-            return jsonResponse({ error: error instanceof Error ? error.message : 'BAD_REQUEST' }, 400, options.corsHeaders);
+            // The bundled API handler never throws, but a custom handler must not leak its
+            // failure details to clients either.
+            reportInternalError(undefined, error);
+            return jsonResponse({ error: 'INTERNAL_ERROR' }, 500, options.corsHeaders);
         }
     };
 }
+function resolveMaxBodyBytes(maxBodyBytes) {
+    const resolved = maxBodyBytes ?? gameServicesRequestLimits.maxBodyBytes;
+    if (!Number.isInteger(resolved) || resolved <= 0) {
+        throw new Error('maxBodyBytes must be a positive integer.');
+    }
+    return resolved;
+}
 const gameServicesDeploymentTargetPlatforms = new Set([
     'microsoft-store',
     'android',
@@ -341,7 +415,7 @@ function bindRequestDeploymentTarget(request, bindings) {
     const deploymentTarget = bindings[request.target] ?? request.target;
     if (request.deploymentTarget !== undefined
         && request.deploymentTarget !== deploymentTarget) {
-        throw new Error(`deploymentTarget must match the backend binding for ${request.target}.`);
+        throw new GameServicesRequestValidationError(`deploymentTarget must match the backend binding for ${request.target}.`);
     }
     return deploymentTarget === request.target || request.deploymentTarget === deploymentTarget
         ? request
@@ -427,7 +501,8 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
                 : verification.reason,
         });
     }
-    const verificationPayload = createPurchaseVerificationPayload(verification);
+    const verificationPayload = createVerificationPayload(verification, 'platformTransactionId');
+    const platformTransactionId = resolvePlatformEvidenceId(verification, request.platformTransactionId);
     const grant = await recordEntitlementGrantWithEvidence(context.store, {
         playerId: request.playerId,
         grantId: product.id,
@@ -445,11 +520,7 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
             productId: request.productId,
             productType: product.type,
             platformProductId,
-            ...(verification.platformEvidenceId === null
-                ? {}
-                : {
-                    platformTransactionId: verification.platformEvidenceId ?? request.platformTransactionId,
-                }),
+            ...(platformTransactionId === undefined ? {} : { platformTransactionId }),
             purchasedAt: request.purchasedAt,
             evidenceVerificationId: verification.verificationId,
             evidenceVerifiedAt: verification.verifiedAt,
@@ -714,8 +785,13 @@ async function claimAdRewardForRetry(request, retryIdentity, context) {
                 : verification.reason,
         });
     }
+    // The client-reported impression id only becomes part of the globally unique platform
+    // evidence identity when the verifier vouches for it (or replaces it with its own
+    // authority id). Otherwise an attacker could pre-register another player's impression id
+    // and have that player's legitimate claim rejected as EVIDENCE_ALREADY_PROCESSED.
+    const platformImpressionId = resolvePlatformEvidenceId(verification, request.platformImpressionId);
     const payload = {
-        ...verification.payload,
+        ...createVerificationPayload(verification, 'platformImpressionId'),
         target: request.target,
         ...(request.deploymentTarget === undefined
             ? {}
@@ -730,8 +806,8 @@ async function claimAdRewardForRetry(request, retryIdentity, context) {
     if (placement.reward.type === 'currency') {
         payload.currency = placement.reward.currency;
     }
-    if (request.platformImpressionId !== undefined) {
-        payload.platformImpressionId = request.platformImpressionId;
+    if (platformImpressionId !== undefined) {
+        payload.platformImpressionId = platformImpressionId;
     }
     const result = await recordEntitlementGrantWithEvidence(context.store, {
         playerId: request.playerId,
@@ -800,12 +876,23 @@ async function verifyEvidence(verify, timeoutMs) {
         return { status: 'rejected', reason: 'EVIDENCE_VERIFIER_ERROR' };
     }
 }
-function createPurchaseVerificationPayload(verification) {
+/**
+ * Resolves the platform evidence identity stored in the ledger: the verifier's authority id
+ * when it supplies one, the client value when the verifier validated the request without
+ * replacing it (`undefined`), and nothing at all when the verifier suppresses it (`null`).
+ */
+function resolvePlatformEvidenceId(verification, clientPlatformEvidenceId) {
+    if (verification.platformEvidenceId === null) {
+        return undefined;
+    }
+    return verification.platformEvidenceId ?? clientPlatformEvidenceId;
+}
+function createVerificationPayload(verification, platformEvidenceField) {
     if (verification.platformEvidenceId !== null || verification.payload === undefined) {
         return verification.payload;
     }
-    const { platformTransactionId: suppressedPlatformTransactionId, ...payload } = verification.payload;
-    void suppressedPlatformTransactionId;
+    const { [platformEvidenceField]: suppressedPlatformEvidenceId, ...payload } = verification.payload;
+    void suppressedPlatformEvidenceId;
     return payload;
 }
 function assertEvidenceVerificationDecision(decision) {
@@ -1068,11 +1155,12 @@ function okResponse(body) {
         body,
     };
 }
-function errorResponse(status, error) {
+function errorResponse(status, error, message) {
     return {
         status,
         body: {
             error,
+            ...(message === undefined ? {} : { message }),
         },
     };
 }
@@ -1141,13 +1229,51 @@ function encodeIdSegment(value) {
 function isGameServicesBackendEndpoint(pathname) {
     return Object.values(gameServicesBackendEndpoints).includes(pathname);
 }
-async function readRequestJson(request) {
-    const text = await request.text();
+class RequestPayloadTooLargeError extends Error {
+    constructor() {
+        super('Request payload exceeds the configured body limit.');
+        this.name = 'RequestPayloadTooLargeError';
+    }
+}
+async function readRequestJson(request, maxBodyBytes) {
+    const text = await readRequestText(request, maxBodyBytes);
     if (text.length === 0) {
         return {};
     }
     return JSON.parse(text);
 }
+/** Reads the body incrementally so an oversized payload is rejected before it is buffered. */
+async function readRequestText(request, maxBodyBytes) {
+    const declaredLength = Number(request.headers.get('content-length') ?? '');
+    if (Number.isFinite(declaredLength) && declaredLength > maxBodyBytes) {
+        throw new RequestPayloadTooLargeError();
+    }
+    if (request.body === null) {
+        return '';
+    }
+    const reader = request.body.getReader();
+    const chunks = [];
+    let receivedBytes = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        receivedBytes += value.byteLength;
+        if (receivedBytes > maxBodyBytes) {
+            await reader.cancel();
+            throw new RequestPayloadTooLargeError();
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(receivedBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
 function jsonResponse(body, status, corsHeaders) {
     const headers = new Headers({
         'content-type': 'application/json; charset=utf-8',

package/dist/types.d.ts

@@ -75,11 +75,23 @@ export interface LeaderboardScoreTransaction extends RecordLeaderboardScoreReque
   readonly ledgerEntryId: string;
   readonly recordedAt: string;
 }
+/**
+* Validates an untrusted purchase verification request. Failures throw
+* `GameServicesRequestValidationError` so transports can answer with a stable 400.
+*/
 export declare function assertVerifyPurchaseRequest(input: VerifyPurchaseRequest): VerifyPurchaseRequest;
 export declare function assertVerifyPurchaseResponse(input: VerifyPurchaseResponse): VerifyPurchaseResponse;
 export declare function assertPurchaseGrantFinalization(input: PurchaseGrantFinalization): PurchaseGrantFinalization;
+/**
+* Validates an untrusted ad reward claim. Failures throw
+* `GameServicesRequestValidationError` so transports can answer with a stable 400.
+*/
 export declare function assertClaimAdRewardRequest(input: ClaimAdRewardRequest): ClaimAdRewardRequest;
 export declare function assertClaimAdRewardResponse(input: ClaimAdRewardResponse): ClaimAdRewardResponse;
+/**
+* Validates an untrusted leaderboard score submission. Failures throw
+* `GameServicesRequestValidationError` so transports can answer with a stable 400.
+*/
 export declare function assertRecordLeaderboardScoreRequest(input: RecordLeaderboardScoreRequest): RecordLeaderboardScoreRequest;
 export declare function assertRecordLeaderboardScoreResponse(input: RecordLeaderboardScoreResponse): RecordLeaderboardScoreResponse;
 export declare function assertEntitlementLedgerGrant(input: EntitlementLedgerGrant): EntitlementLedgerGrant;

package/dist/types.js

@@ -1,14 +1,21 @@
+import { assertOwnEnumerablePropertyLimit, gameServicesRequestLimits, toGameServicesRequestValidationError, } from './validation.js';
+/**
+ * Validates an untrusted purchase verification request. Failures throw
+ * `GameServicesRequestValidationError` so transports can answer with a stable 400.
+ */
 export function assertVerifyPurchaseRequest(input) {
-    assertRecord(input, 'VerifyPurchaseRequest');
-    assertStoreTarget(input.target);
-    assertOptionalGameServicesDeploymentTarget(input.deploymentTarget);
-    assertNonEmptyString(input.playerId, 'playerId');
-    assertNonEmptyString(input.productId, 'productId');
-    assertNonEmptyString(input.platformTransactionId, 'platformTransactionId');
-    assertNonEmptyString(input.idempotencyKey, 'idempotencyKey');
-    assertNonEmptyString(input.purchasedAt, 'purchasedAt');
-    assertOptionalEvidenceEnvelope(input.evidence);
-    return input;
+    return validateRequest(() => {
+        assertRecord(input, 'VerifyPurchaseRequest');
+        assertStoreTarget(input.target);
+        assertOptionalGameServicesDeploymentTarget(input.deploymentTarget);
+        assertRequestString(input.playerId, 'playerId');
+        assertRequestString(input.productId, 'productId');
+        assertRequestString(input.platformTransactionId, 'platformTransactionId');
+        assertRequestString(input.idempotencyKey, 'idempotencyKey');
+        assertRequestString(input.purchasedAt, 'purchasedAt');
+        assertOptionalEvidenceEnvelope(input.evidence);
+        return input;
+    });
 }
 export function assertVerifyPurchaseResponse(input) {
     assertRecord(input, 'VerifyPurchaseResponse');
@@ -43,17 +50,23 @@ export function assertPurchaseGrantFinalization(input) {
     }
     return input;
 }
+/**
+ * Validates an untrusted ad reward claim. Failures throw
+ * `GameServicesRequestValidationError` so transports can answer with a stable 400.
+ */
 export function assertClaimAdRewardRequest(input) {
-    assertRecord(input, 'ClaimAdRewardRequest');
-    assertAdRewardTarget(input.target);
-    assertOptionalGameServicesDeploymentTarget(input.deploymentTarget);
-    assertNonEmptyString(input.playerId, 'playerId');
-    assertNonEmptyString(input.placementId, 'placementId');
-    assertOptionalNonEmptyString(input.platformImpressionId, 'platformImpressionId');
-    assertNonEmptyString(input.idempotencyKey, 'idempotencyKey');
-    assertNonEmptyString(input.completedAt, 'completedAt');
-    assertOptionalEvidenceEnvelope(input.evidence);
-    return input;
+    return validateRequest(() => {
+        assertRecord(input, 'ClaimAdRewardRequest');
+        assertAdRewardTarget(input.target);
+        assertOptionalGameServicesDeploymentTarget(input.deploymentTarget);
+        assertRequestString(input.playerId, 'playerId');
+        assertRequestString(input.placementId, 'placementId');
+        assertOptionalRequestString(input.platformImpressionId, 'platformImpressionId');
+        assertRequestString(input.idempotencyKey, 'idempotencyKey');
+        assertRequestString(input.completedAt, 'completedAt');
+        assertOptionalEvidenceEnvelope(input.evidence);
+        return input;
+    });
 }
 export function assertClaimAdRewardResponse(input) {
     assertRecord(input, 'ClaimAdRewardResponse');
@@ -64,15 +77,22 @@ export function assertClaimAdRewardResponse(input) {
     assertOptionalNonEmptyString(input.reason, 'reason');
     return input;
 }
+/**
+ * Validates an untrusted leaderboard score submission. Failures throw
+ * `GameServicesRequestValidationError` so transports can answer with a stable 400.
+ */
 export function assertRecordLeaderboardScoreRequest(input) {
+    return validateRequest(() => validateRecordLeaderboardScoreRequest(input));
+}
+function validateRecordLeaderboardScoreRequest(input) {
     assertRecord(input, 'RecordLeaderboardScoreRequest');
     assertLeaderboardTarget(input.target);
-    assertNonEmptyString(input.playerId, 'playerId');
-    assertNonEmptyString(input.leaderboardId, 'leaderboardId');
+    assertRequestString(input.playerId, 'playerId');
+    assertRequestString(input.leaderboardId, 'leaderboardId');
     assertFiniteNumber(input.score, 'score');
-    assertNonEmptyString(input.runId, 'runId');
-    assertNonEmptyString(input.submittedAt, 'submittedAt');
-    assertOptionalNonEmptyString(input.platformSubmissionId, 'platformSubmissionId');
+    assertRequestString(input.runId, 'runId');
+    assertRequestString(input.submittedAt, 'submittedAt');
+    assertOptionalRequestString(input.platformSubmissionId, 'platformSubmissionId');
     return input;
 }
 export function assertRecordLeaderboardScoreResponse(input) {
@@ -119,7 +139,7 @@ export function assertProductGrantTransaction(input) {
     return input;
 }
 export function assertLeaderboardScoreTransaction(input) {
-    assertRecordLeaderboardScoreRequest(input);
+    validateRecordLeaderboardScoreRequest(input);
     assertNonEmptyString(input.ledgerEntryId, 'ledgerEntryId');
     assertNonEmptyString(input.recordedAt, 'recordedAt');
     return input;
@@ -180,11 +200,31 @@ function assertLeaderboardTarget(input) {
         throw new Error('target must be browser, microsoft-store, android, ios, ait, or reddit.');
     }
 }
+function validateRequest(validate) {
+    try {
+        return validate();
+    }
+    catch (error) {
+        throw toGameServicesRequestValidationError(error);
+    }
+}
 function assertNonEmptyString(input, label) {
     if (typeof input !== 'string' || input.length === 0) {
         throw new Error(`${label} must be a non-empty string.`);
     }
 }
+/** Client-supplied identifiers feed ledger keys, so they are bounded as well as non-empty. */
+function assertRequestString(input, label) {
+    assertNonEmptyString(input, label);
+    if (input.length > gameServicesRequestLimits.maxStringLength) {
+        throw new Error(`${label} must not exceed ${String(gameServicesRequestLimits.maxStringLength)} characters.`);
+    }
+}
+function assertOptionalRequestString(input, label) {
+    if (input !== undefined) {
+        assertRequestString(input, label);
+    }
+}
 function assertOptionalNonEmptyString(input, label) {
     if (input !== undefined) {
         assertNonEmptyString(input, label);
@@ -261,6 +301,7 @@ function assertOptionalEvidenceEnvelope(input) {
         return;
     }
     assertRecord(input, 'evidence');
-    assertNonEmptyString(input.schema, 'evidence.schema');
+    assertRequestString(input.schema, 'evidence.schema');
     assertPayload(input.payload);
+    assertOwnEnumerablePropertyLimit(input.payload, gameServicesRequestLimits.maxEvidencePayloadEntries, 'evidence.payload');
 }

package/dist/validation.d.ts

@@ -1 +1,19 @@
+/** Hard limits applied to untrusted client requests before they reach ledger keys. */
+export declare const gameServicesRequestLimits: {
+  /** Maximum length of any identifier or timestamp string in a client request. */
+  readonly maxStringLength: 256;
+  /** Maximum number of entries accepted inside a platform evidence payload. */
+  readonly maxEvidencePayloadEntries: 64;
+  /** Maximum request body size accepted by the HTTP and oRPC fetch handlers. */
+  readonly maxBodyBytes: number;
+};
+/**
+* A client-supplied request failed validation. Handlers map this error to a 400 response
+* with the stable `INVALID_REQUEST` code; every other error is treated as internal.
+*/
+export declare class GameServicesRequestValidationError extends Error {
+  readonly code = "INVALID_REQUEST";
+  constructor(message: string);
+}
+export declare function toGameServicesRequestValidationError(error: unknown): GameServicesRequestValidationError;
 export declare function assertOwnEnumerablePropertyLimit(input: Record<string, unknown>, maximum: number, label: string): void;

package/dist/validation.js

@@ -1,3 +1,29 @@
+/** Hard limits applied to untrusted client requests before they reach ledger keys. */
+export const gameServicesRequestLimits = {
+    /** Maximum length of any identifier or timestamp string in a client request. */
+    maxStringLength: 256,
+    /** Maximum number of entries accepted inside a platform evidence payload. */
+    maxEvidencePayloadEntries: 64,
+    /** Maximum request body size accepted by the HTTP and oRPC fetch handlers. */
+    maxBodyBytes: 64 * 1024,
+};
+/**
+ * A client-supplied request failed validation. Handlers map this error to a 400 response
+ * with the stable `INVALID_REQUEST` code; every other error is treated as internal.
+ */
+export class GameServicesRequestValidationError extends Error {
+    code = 'INVALID_REQUEST';
+    constructor(message) {
+        super(message);
+        this.name = 'GameServicesRequestValidationError';
+    }
+}
+export function toGameServicesRequestValidationError(error) {
+    if (error instanceof GameServicesRequestValidationError) {
+        return error;
+    }
+    return new GameServicesRequestValidationError(error instanceof Error ? error.message : 'Request validation failed.');
+}
 export function assertOwnEnumerablePropertyLimit(input, maximum, label) {
     let propertyCount = 0;
     for (const key in input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {