@mpgd/game-services 0.19.0 → 0.20.0

package/README.md

@@ -4,6 +4,22 @@ Client, contract, backend, and store helpers for authoritative game services.
 See [backend integration](../../docs/GAME_SERVICES_BACKEND.md) for the existing
 verification and ledger boundaries.
 
+## App Store server-side transaction signatures
+
+`@mpgd/game-services/app-store-server` exports
+`createAppleSignedTransactionVerifier`, an `AppStoreSignedTransactionVerifier`
+over the optional `@apple/app-store-server-library@3.1.0` peer. It verifies the
+App Store JWS certificate chain and signature before exposing any decoded
+one-time purchase field, keeps Apple's retryable certificate-status failures
+pending (`AppStoreDependencyUnavailableError`), and rejects invalid signatures,
+subscription payloads, and oversized transactions. Supply DER-encoded Apple
+root certificates, the bundle ID, environment, and production App Apple ID,
+and pass the result as `signedTransactionVerifier` to
+`createAppStoreGameServicesEvidenceVerifier`. Backend only: the peer is not
+installed by game clients, and no other subpath imports it. It moved here from
+`@mpgd/adapter-capacitor/app-store-server`, which stays as a deprecated
+re-export for one release.
+
 ## Registered rewarded-ad evidence
 
 `createGameServicesClient`, `createRecoverableMonetizationClient`, and

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

@@ -0,0 +1,12 @@
+import { type AppStoreEnvironment, type AppStoreSignedTransactionVerifier } from './app-store-verifier.js';
+export interface CreateAppleSignedTransactionVerifierOptions {
+  /** DER-encoded Apple root certificates, supplied by the server operator. */
+  readonly rootCertificates: readonly Uint8Array[];
+  readonly environment: AppStoreEnvironment;
+  readonly bundleId: string;
+  /** Required by Apple's verifier in production. */
+  readonly appAppleId?: number;
+  readonly enableOnlineChecks?: boolean;
+}
+/** Verify the App Store JWS before exposing any decoded purchase fields. */
+export declare function createAppleSignedTransactionVerifier(options: CreateAppleSignedTransactionVerifierOptions): AppStoreSignedTransactionVerifier;

package/dist/app-store-server.js

@@ -0,0 +1,119 @@
+import { Environment, SignedDataVerifier, VerificationException, VerificationStatus, } from '@apple/app-store-server-library';
+import { AppStoreDependencyUnavailableError, } from './app-store-verifier.js';
+/** Verify the App Store JWS before exposing any decoded purchase fields. */
+export function createAppleSignedTransactionVerifier(options) {
+    if (!Array.isArray(options.rootCertificates)
+        || options.rootCertificates.length === 0
+        || options.rootCertificates.some((certificate) => !(certificate instanceof Uint8Array)
+            || certificate.length === 0)) {
+        throw new TypeError('Apple root certificates are required.');
+    }
+    if (options.environment !== 'Production' && options.environment !== 'Sandbox') {
+        throw new TypeError('App Store environment must be Production or Sandbox.');
+    }
+    if (options.bundleId.trim() === '') {
+        throw new TypeError('App Store bundle ID is required.');
+    }
+    if (options.environment === 'Production'
+        && (!Number.isSafeInteger(options.appAppleId) || (options.appAppleId ?? 0) <= 0)) {
+        throw new TypeError('Production App Store verification requires appAppleId.');
+    }
+    if (options.environment === 'Production' && options.enableOnlineChecks === false) {
+        throw new TypeError('Production App Store verification requires online certificate checks.');
+    }
+    const verifier = new SignedDataVerifier(options.rootCertificates.map((certificate) => Buffer.from(certificate)), options.enableOnlineChecks ?? true, options.environment === 'Production' ? Environment.PRODUCTION : Environment.SANDBOX, options.bundleId, options.appAppleId);
+    return {
+        async verifyAndDecode(input) {
+            if (input.environment !== options.environment || input.bundleId !== options.bundleId) {
+                return { status: 'rejected', reason: 'APP_STORE_VERIFIER_SCOPE_MISMATCH' };
+            }
+            if (typeof input.signedTransaction !== 'string'
+                || input.signedTransaction.length === 0
+                || input.signedTransaction.length > 512 * 1024) {
+                return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_INVALID' };
+            }
+            input.signal.throwIfAborted();
+            let decoded;
+            try {
+                decoded = await waitForVerification(verifier.verifyAndDecodeTransaction(input.signedTransaction), input.signal);
+                input.signal.throwIfAborted();
+            }
+            catch (error) {
+                if (input.signal.aborted) {
+                    throw input.signal.reason;
+                }
+                if (error instanceof VerificationException) {
+                    if (error.status === VerificationStatus.RETRYABLE_VERIFICATION_FAILURE) {
+                        throw new AppStoreDependencyUnavailableError('Apple signature checks are temporarily unavailable.', error);
+                    }
+                    return { status: 'rejected', reason: 'APP_STORE_SIGNATURE_INVALID' };
+                }
+                // Only Apple's explicit retryable status is a transient dependency
+                // failure. Unexpected adapter/library faults must reach the caller.
+                throw error;
+            }
+            const payload = decodeOneTimeTransaction(decoded);
+            return payload === undefined
+                ? { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_INVALID' }
+                : { status: 'verified', payload };
+        },
+    };
+}
+async function waitForVerification(operation, signal) {
+    signal.throwIfAborted();
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        onAbort = () => reject(signal.reason ?? new Error('Verification was aborted.'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) {
+            onAbort();
+        }
+    });
+    try {
+        return await Promise.race([operation, aborted]);
+    }
+    finally {
+        if (onAbort !== undefined) {
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
+}
+function decodeOneTimeTransaction(decoded) {
+    if (!nonEmpty(decoded.transactionId)
+        || !nonEmpty(decoded.originalTransactionId)
+        || !nonEmpty(decoded.bundleId)
+        || !nonEmpty(decoded.productId)
+        || !validTimestamp(decoded.purchaseDate)
+        || !validTimestamp(decoded.signedDate)
+        || (decoded.environment !== 'Production' && decoded.environment !== 'Sandbox')
+        || (decoded.type !== 'Consumable' && decoded.type !== 'Non-Consumable')
+        || (decoded.quantity !== undefined
+            && (!Number.isSafeInteger(decoded.quantity) || decoded.quantity <= 0))
+        || (decoded.appAccountToken !== undefined && !nonEmpty(decoded.appAccountToken))
+        || (decoded.revocationDate !== undefined && !validTimestamp(decoded.revocationDate))
+        || (decoded.expiresDate !== undefined && !validTimestamp(decoded.expiresDate))
+        || (decoded.isUpgraded !== undefined && typeof decoded.isUpgraded !== 'boolean')) {
+        return undefined;
+    }
+    return {
+        transactionId: decoded.transactionId,
+        originalTransactionId: decoded.originalTransactionId,
+        bundleId: decoded.bundleId,
+        productId: decoded.productId,
+        purchaseDate: decoded.purchaseDate,
+        signedDate: decoded.signedDate,
+        environment: decoded.environment,
+        type: decoded.type,
+        ...(decoded.quantity === undefined ? {} : { quantity: decoded.quantity }),
+        ...(decoded.appAccountToken === undefined ? {} : { appAccountToken: decoded.appAccountToken }),
+        ...(decoded.revocationDate === undefined ? {} : { revocationDate: decoded.revocationDate }),
+        ...(decoded.expiresDate === undefined ? {} : { expiresDate: decoded.expiresDate }),
+        ...(decoded.isUpgraded === undefined ? {} : { isUpgraded: decoded.isUpgraded }),
+    };
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+function validTimestamp(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}

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

@@ -15,7 +15,8 @@ export function createGooglePlayPublisherClient(options) {
             response = await requestFetch(`${publisherOrigin}${path}`, {
                 method,
                 headers: { Authorization: `Bearer ${accessToken}` },
-                redirect: 'error',
+                // Workers reject redirect: 'error'; a manual 3xx/opaque redirect is never ok and fails below.
+                redirect: 'manual',
                 signal,
             });
         }
@@ -26,7 +27,8 @@ export function createGooglePlayPublisherClient(options) {
             // Fetch errors can contain the request URL (including the purchase token).
             throw new Error('Google Play Publisher request failed.');
         }
-        if (!response.ok) {
+        // Also reject a redirect followed by an injected fetch that ignores redirect: 'manual'.
+        if (!response.ok || response.redirected) {
             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}).`);

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

@@ -38,5 +38,12 @@ 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>;
+/**
+* A non-secret transaction ID for purchases whose Google order ID is absent or
+* delayed: `play-token-sha256:<hex>` of the purchase token.
+*
+* @deprecated Use `createGooglePlayTokenPurchaseKey` from `@mpgd/platform/commerce`;
+* this alias is byte-for-byte the same helper (same key, same `TypeError` for
+* an invalid token) and will be removed in the next major version.
+*/
+export declare const createGooglePlayTokenTransactionId: (purchaseToken: string) => Promise<string>;

package/dist/google-play-purchase.js

@@ -1,3 +1,4 @@
+import { createGooglePlayTokenPurchaseKey } from '@mpgd/platform/commerce';
 export const googlePlayProductPurchaseEvidenceSchema = 'google-play.product-purchase.v2';
 export function createGooglePlayProductPurchaseBoundary(input) {
     const packageName = assertIdentifier(input.packageName, 'packageName', 256);
@@ -45,7 +46,7 @@ export function createGooglePlayProductPurchaseBoundary(input) {
                 purchaseToken,
                 expectedProductId: verificationInput.platformProductId,
                 expectedProductType: verificationInput.product.type,
-                orderMatch: createGooglePlayObservedOrderMatch(verificationInput.request.platformTransactionId, await createGooglePlayTokenTransactionId(purchaseToken)),
+                orderMatch: createGooglePlayObservedOrderMatch(verificationInput.request.platformTransactionId, await createGooglePlayTokenPurchaseKey(purchaseToken)),
                 accountBinding,
                 allowConsumed: false,
                 signal: verificationInput.signal,
@@ -143,7 +144,7 @@ async function finalizeGooglePlayPurchase(input, packageName, purchaseToken, pro
             purchaseToken,
             expectedProductId: finalizationInput.platformProductId,
             expectedProductType: productType,
-            orderMatch: createGooglePlayFinalizationOrderMatch(verifiedContext, finalizationInput.request.platformTransactionId, await createGooglePlayTokenTransactionId(purchaseToken)),
+            orderMatch: createGooglePlayFinalizationOrderMatch(verifiedContext, finalizationInput.request.platformTransactionId, await createGooglePlayTokenPurchaseKey(purchaseToken)),
             accountBinding,
             allowConsumed: true,
             signal: finalizationInput.signal,
@@ -380,18 +381,15 @@ function createGooglePlayObservedOrderMatch(observedTransactionId, tokenTransact
         ? { 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('')}`;
-}
+/**
+ * A non-secret transaction ID for purchases whose Google order ID is absent or
+ * delayed: `play-token-sha256:<hex>` of the purchase token.
+ *
+ * @deprecated Use `createGooglePlayTokenPurchaseKey` from `@mpgd/platform/commerce`;
+ * this alias is byte-for-byte the same helper (same key, same `TypeError` for
+ * an invalid token) and will be removed in the next major version.
+ */
+export const createGooglePlayTokenTransactionId = createGooglePlayTokenPurchaseKey;
 function readGooglePlayVerifiedContext(payload, packageName, productId, purchaseTokenDigest) {
     if (payload?.googlePlayPackageName !== packageName
         || payload.googlePlayProductId !== productId

package/dist/oneplay-purchase-client.js

@@ -17,10 +17,12 @@ export function createOnePlayPurchaseClient(input) {
         try {
             const response = await requestFetch(`${origin}${path}`, {
                 ...init,
-                redirect: 'error',
+                // Workers reject redirect: 'error'; a manual 3xx/opaque redirect is never ok and fails below.
+                redirect: 'manual',
                 signal,
             });
-            if (!response.ok) {
+            // Also reject a redirect followed by an injected fetch that ignores redirect: 'manual'.
+            if (!response.ok || response.redirected) {
                 if (response.status === 401) {
                     cached = undefined;
                 }

package/dist/server.js

@@ -1,7 +1,7 @@
 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 { resolveAdPlacementPlatformId, resolveCatalogCurrencies, resolveProductPlatformId, } from '@mpgd/catalog';
 import { gameServicesBackendEndpoints, } from './client.js';
 import { gameServicesContract } from './contract.js';
 import { createRejectingGameServicesEvidenceVerifier, } from './evidence-verification.js';
@@ -127,6 +127,7 @@ export function createInMemoryGameServicesStore() {
     return new InMemoryGameServicesStore();
 }
 export function createGameServicesBackend(input) {
+    assertDeclaredCatalogCurrencies(input.catalog, input.placements);
     const store = input.store ?? createInMemoryGameServicesStore();
     const now = input.now ?? (() => new Date().toISOString());
     const version = input.version ?? '0.0.0';
@@ -223,6 +224,26 @@ export function createGameServicesBackend(input) {
         },
     };
 }
+/**
+ * Every grant and reward the backend can write comes from the catalog or the
+ * placements, so an undeclared currency is a configuration error at startup
+ * rather than a rejected ledger write on the first purchase.
+ */
+function assertDeclaredCatalogCurrencies(catalog, placements) {
+    const currencies = resolveCatalogCurrencies(catalog);
+    for (const product of catalog.products) {
+        if (product.grant.type === 'currency' && !currencies.has(product.grant.currency)) {
+            throw new Error(`Product ${product.id} grants undeclared currency ${product.grant.currency}; `
+                + `declared currencies: ${[...currencies].join(', ')}.`);
+        }
+    }
+    for (const placement of placements.placements) {
+        if (placement.reward?.type === 'currency' && !currencies.has(placement.reward.currency)) {
+            throw new Error(`Ad placement ${placement.id} rewards undeclared currency ${placement.reward.currency}; `
+                + `declared currencies: ${[...currencies].join(', ')}.`);
+        }
+    }
+}
 export function createGameServicesBackendApiHandler(input) {
     const backend = createGameServicesBackend(input);
     return {

package/dist/types.js

@@ -270,8 +270,11 @@ function assertLedgerSource(input) {
 function assertProductGrant(input) {
     assertRecord(input, 'grant');
     if (input.type === 'currency') {
-        if (input.currency !== 'coin' && input.currency !== 'gem') {
-            throw new Error('grant.currency must be coin or gem.');
+        // The currency list is open; the backend checks it against the catalog's
+        // declared currencies when it is constructed.
+        assertNonEmptyString(input.currency, 'grant.currency');
+        if (input.currency.trim() !== input.currency) {
+            throw new Error('grant.currency must be a trimmed currency code.');
         }
         assertFiniteNumber(input.amount, 'grant.amount');
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -57,6 +57,10 @@
       "types": "./dist/app-store-recovery.d.ts",
       "default": "./dist/app-store-recovery.js"
     },
+    "./app-store-server": {
+      "types": "./dist/app-store-server.d.ts",
+      "default": "./dist/app-store-server.js"
+    },
     "./app-store-verifier-conformance": {
       "types": "./dist/app-store-verifier-conformance.d.ts",
       "default": "./dist/app-store-verifier-conformance.js"
@@ -186,14 +190,24 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/analytics": "0.4.3",
-    "@mpgd/catalog": "0.8.0",
-    "@mpgd/platform": "0.17.0"
+    "@mpgd/analytics": "0.4.5",
+    "@mpgd/platform": "0.19.0",
+    "@mpgd/catalog": "0.9.0"
+  },
+  "peerDependencies": {
+    "@apple/app-store-server-library": "^3.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@apple/app-store-server-library": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@apple/app-store-server-library": "3.1.0",
     "@opentelemetry/api": "1.9.0",
     "ttsc": "0.30.4",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "vitest": "^4.0.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -209,6 +223,7 @@
     "test:packed-transport": "pnpm build && node test/runtime-transport-package-import.mjs && node test/reward-evidence-import.mjs",
     "test:unit": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-progress.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-publisher-client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-identity.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-partner-api.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts && node tools/run-ttsx.mjs packages/game-services/src/guest-session.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-reward-evidence.test.ts && node tools/run-ttsx.mjs packages/game-services/src/ad-reward-verifier-registry.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-reward.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-purchase.test.ts",
     "test:recovery": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/monetization-recovery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-recovery.test.ts",
-    "test": "pnpm test:unit && pnpm test:recovery && pnpm test:packed-transport"
+    "test": "pnpm test:unit && pnpm test:app-store-server && pnpm test:recovery && pnpm test:packed-transport",
+    "test:app-store-server": "vitest run"
   }
 }