@mpgd/game-services 0.19.1 → 0.21.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/app-store-verifier-conformance.d.ts

@@ -1,4 +1,23 @@
-import type { AppStoreEnvironment, AppStoreInAppPurchaseType, AppStoreTransactionPayload } from './app-store-verifier.js';
+import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
+import { type AppStoreEnvironment, type AppStoreInAppPurchaseType, type AppStoreTransactionPayload } from './app-store-verifier.js';
+/** The placeholder JWS the signed-transaction evidence fixture carries; never a real signature. */
+export declare const appStoreConformanceSignedTransaction = "conformance.signed-transaction.jws";
+export interface CreateAppStoreSignedTransactionEvidenceFixtureInput {
+  readonly signedTransaction?: string;
+  readonly transactionId?: string;
+  readonly originalTransactionId?: string;
+  readonly bundleId?: string;
+}
+/**
+* Builds the `app-store.signed-transaction.v1` evidence envelope a commerce v2
+* StoreKit client submits, with a placeholder JWS by default. Pair it with a
+* fake `AppStoreSignedTransactionVerifier` that answers
+* `createAppStoreTransactionConformanceFixture` for that string and, under the
+* default `server-api` policy, a fake Server API whose `signedTransactionInfo`
+* decodes to the transaction's current status; the fixture is not signed
+* evidence and contains no Apple credentials.
+*/
+export declare function createAppStoreSignedTransactionEvidenceFixture(input?: CreateAppStoreSignedTransactionEvidenceFixtureInput): PlatformEvidenceEnvelope;
 export interface CreateAppStoreTransactionConformanceFixtureInput {
   readonly transactionId?: string;
   readonly originalTransactionId?: string;

package/dist/app-store-verifier-conformance.js

@@ -1,3 +1,25 @@
+import { createAppStoreSignedTransactionEvidence, } from './app-store-verifier.js';
+/** The placeholder JWS the signed-transaction evidence fixture carries; never a real signature. */
+export const appStoreConformanceSignedTransaction = 'conformance.signed-transaction.jws';
+/**
+ * Builds the `app-store.signed-transaction.v1` evidence envelope a commerce v2
+ * StoreKit client submits, with a placeholder JWS by default. Pair it with a
+ * fake `AppStoreSignedTransactionVerifier` that answers
+ * `createAppStoreTransactionConformanceFixture` for that string and, under the
+ * default `server-api` policy, a fake Server API whose `signedTransactionInfo`
+ * decodes to the transaction's current status; the fixture is not signed
+ * evidence and contains no Apple credentials.
+ */
+export function createAppStoreSignedTransactionEvidenceFixture(input = {}) {
+    return createAppStoreSignedTransactionEvidence({
+        signedTransaction: input.signedTransaction ?? appStoreConformanceSignedTransaction,
+        transactionId: input.transactionId ?? '2000000000000001',
+        ...(input.originalTransactionId === undefined
+            ? {}
+            : { originalTransactionId: input.originalTransactionId }),
+        ...(input.bundleId === undefined ? {} : { bundleId: input.bundleId }),
+    });
+}
 /**
  * Builds deterministic decoded JWS data for verifier and provider-adapter
  * conformance tests. The fixture is not signed evidence and contains no Apple

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

@@ -1,3 +1,4 @@
+import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
 import type { GameServicesEvidenceVerifier } from './evidence-verification.js';
 export type AppStoreEnvironment = 'Production' | 'Sandbox';
 export declare const appStoreServerApiBaseUrls: Readonly<{
@@ -72,7 +73,44 @@ export interface CreateAppStoreEvidenceVerifierOptions {
   }) => string | Promise<string>;
   readonly now?: () => string;
   readonly clockSkewMs?: number;
+  /**
+  * How `app-store.signed-transaction.v1` request evidence is used. Defaults
+  * to `{ mode: 'server-api' }`: the client JWS is verified offline to
+  * establish authenticity and bind the transaction id, and the grant decision
+  * is then taken on the transaction's current status fetched from the App
+  * Store Server API (`Get Transaction Info`), so a refund that happened after
+  * the client cached its JWS is seen. `{ mode: 'offline-only', maxSignedAgeMs }`
+  * decides on the client JWS alone and is only for deployments without Server
+  * API access: a JWS is a snapshot, so a transaction refunded after it was
+  * signed is accepted until `signedDate` falls out of the window. `{ mode:
+  * 'ignore' }` fetches by id for every request.
+  */
+  readonly signedTransactionEvidence?: AppStoreSignedTransactionEvidencePolicy;
 }
+export type AppStoreSignedTransactionEvidencePolicy = {
+  readonly mode: 'ignore';
+} | {
+  readonly mode: 'server-api';
+} | {
+  readonly mode: 'offline-only';
+  /** Maximum age of the JWS `signedDate` at verification time; older evidence is rejected. */
+  readonly maxSignedAgeMs: number;
+};
+/**
+* Evidence schema of a commerce v2 App Store purchase (RFC B3): the payload's
+* `signedTransaction` is the StoreKit-verified JWS the client received. The
+* server verifies it offline and, by default, confirms the transaction's
+* current status through the Server API before a grant.
+*/
+export declare const appStoreSignedTransactionEvidenceSchema = "app-store.signed-transaction.v1";
+export interface AppStoreSignedTransactionEvidencePayload {
+  readonly signedTransaction: string;
+  readonly transactionId: string;
+  readonly originalTransactionId?: string;
+  readonly bundleId?: string;
+}
+/** Builds the `app-store.signed-transaction.v1` envelope a client submits with `verifyPurchase`. */
+export declare function createAppStoreSignedTransactionEvidence(payload: AppStoreSignedTransactionEvidencePayload): PlatformEvidenceEnvelope;
 export interface AppStoreFetchResponse {
   readonly status: number;
   readonly body: ReadableStream<Uint8Array> | null;

package/dist/app-store-verifier.js

@@ -16,6 +16,56 @@ class AppStoreResponseTooLargeError extends Error {
         this.name = 'AppStoreResponseTooLargeError';
     }
 }
+/**
+ * Evidence schema of a commerce v2 App Store purchase (RFC B3): the payload's
+ * `signedTransaction` is the StoreKit-verified JWS the client received. The
+ * server verifies it offline and, by default, confirms the transaction's
+ * current status through the Server API before a grant.
+ */
+export const appStoreSignedTransactionEvidenceSchema = 'app-store.signed-transaction.v1';
+/** Builds the `app-store.signed-transaction.v1` envelope a client submits with `verifyPurchase`. */
+export function createAppStoreSignedTransactionEvidence(payload) {
+    assertNonEmptyString(payload.signedTransaction, 'signedTransaction');
+    assertNonEmptyString(payload.transactionId, 'transactionId');
+    return {
+        schema: appStoreSignedTransactionEvidenceSchema,
+        payload: {
+            signedTransaction: payload.signedTransaction,
+            transactionId: payload.transactionId,
+            ...(payload.originalTransactionId === undefined
+                ? {}
+                : { originalTransactionId: payload.originalTransactionId }),
+            ...(payload.bundleId === undefined ? {} : { bundleId: payload.bundleId }),
+        },
+    };
+}
+/**
+ * Reads the client JWS from `app-store.signed-transaction.v1` evidence. Any
+ * other schema, or no evidence, is `absent` (the Server API path); a present
+ * envelope whose payload is malformed, or whose `transactionId` differs from
+ * the request, is rejected before any verifier runs.
+ */
+function readSignedTransactionEvidence(request) {
+    const evidence = request.evidence;
+    if (evidence?.schema !== appStoreSignedTransactionEvidenceSchema) {
+        return { status: 'absent' };
+    }
+    const payload = evidence.payload;
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_EVIDENCE_INVALID' };
+    }
+    const { signedTransaction, transactionId } = payload;
+    if (typeof signedTransaction !== 'string'
+        || signedTransaction.length === 0
+        || signedTransaction.length > maxSignedTransactionEvidenceLength) {
+        return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_EVIDENCE_INVALID' };
+    }
+    if (transactionId !== undefined && transactionId !== request.platformTransactionId) {
+        return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_ID_MISMATCH' };
+    }
+    return { status: 'present', signedTransaction };
+}
+const maxSignedTransactionEvidenceLength = 512 * 1024;
 export function createAppStoreServerApiClient(options) {
     const fetch = options.fetch ?? readGlobalFetch();
     const maxResponseBytes = readPositiveSafeInteger(options.maxResponseBytes ?? 128 * 1024, 'maxResponseBytes');
@@ -82,6 +132,7 @@ export function createAppStoreServerApiClient(options) {
 export function createAppStoreGameServicesEvidenceVerifier(options) {
     assertNonEmptyString(options.bundleId, 'bundleId');
     assertAppStoreEnvironment(options.environment);
+    assertSignedTransactionEvidencePolicy(options.signedTransactionEvidence);
     const clockSkewMs = readNonNegativeSafeInteger(options.clockSkewMs ?? 5 * 60 * 1000, 'clockSkewMs');
     const now = options.now ?? (() => new Date().toISOString());
     return {
@@ -103,54 +154,72 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
     if (input.product.type === 'subscription') {
         return { status: 'rejected', reason: 'APP_STORE_SUBSCRIPTION_UNSUPPORTED' };
     }
-    let transactionResult;
-    try {
-        transactionResult = await options.serverApi.getTransactionInfo({
-            transactionId: input.request.platformTransactionId,
-            environment: options.environment,
-            signal: input.signal,
-        });
-    }
-    catch (error) {
-        if (!(error instanceof AppStoreDependencyUnavailableError)) {
-            throw error;
+    // Commerce v2 evidence carries the client's StoreKit-verified JWS. Its
+    // signature establishes authenticity and binds the transaction id; the
+    // grant decision is then taken on the transaction's current status from
+    // the Server API (default), or on the JWS alone within a freshness window
+    // (offline-only). Without evidence (current clients) the transaction is
+    // fetched by id as before.
+    const policy = options.signedTransactionEvidence ?? defaultSignedTransactionEvidencePolicy;
+    const evidence = policy.mode === 'ignore'
+        ? { status: 'absent' }
+        : readSignedTransactionEvidence(input.request);
+    if (evidence.status === 'rejected') {
+        return { status: 'rejected', reason: evidence.reason };
+    }
+    let offlineTransaction;
+    if (evidence.status === 'present') {
+        const offline = await verifySignedTransaction(evidence.signedTransaction, input, options);
+        if (offline.status !== 'verified') {
+            return offline;
         }
-        return { status: 'pending', reason: 'APP_STORE_SERVER_API_UNAVAILABLE' };
-    }
-    try {
-        assertAppStoreServerApiTransactionResult(transactionResult);
-    }
-    catch {
-        return { status: 'pending', reason: 'APP_STORE_SERVER_API_INVALID_RESPONSE' };
-    }
-    if (transactionResult.status !== 'found') {
-        return { status: transactionResult.status, reason: transactionResult.reason };
-    }
-    let signatureResult;
-    try {
-        signatureResult = await options.signedTransactionVerifier.verifyAndDecode({
-            signedTransaction: transactionResult.signedTransactionInfo,
-            environment: options.environment,
-            bundleId: options.bundleId,
-            signal: input.signal,
-        });
-    }
-    catch (error) {
-        if (!(error instanceof AppStoreDependencyUnavailableError)) {
-            throw error;
+        if (offline.payload.transactionId !== input.request.platformTransactionId) {
+            // A client-supplied JWS for another transaction is a stable rejection,
+            // distinct from a Server API answer that disagrees with the request.
+            return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_ID_MISMATCH' };
         }
-        return { status: 'pending', reason: 'APP_STORE_SIGNATURE_VERIFIER_UNAVAILABLE' };
+        offlineTransaction = offline.payload;
     }
-    try {
-        assertAppStoreSignedTransactionVerificationResult(signatureResult);
-    }
-    catch {
-        return { status: 'rejected', reason: 'APP_STORE_SIGNATURE_RESULT_INVALID' };
+    let transaction;
+    if (offlineTransaction !== undefined && policy.mode === 'offline-only') {
+        transaction = offlineTransaction;
     }
-    if (signatureResult.status === 'rejected') {
-        return { status: 'rejected', reason: signatureResult.reason };
+    else {
+        // A JWS is a snapshot: the current status (refund, revocation) is read
+        // from the Server API before any grant.
+        let transactionResult;
+        try {
+            transactionResult = await options.serverApi.getTransactionInfo({
+                transactionId: input.request.platformTransactionId,
+                environment: options.environment,
+                signal: input.signal,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof AppStoreDependencyUnavailableError)) {
+                throw error;
+            }
+            return { status: 'pending', reason: 'APP_STORE_SERVER_API_UNAVAILABLE' };
+        }
+        try {
+            assertAppStoreServerApiTransactionResult(transactionResult);
+        }
+        catch {
+            return { status: 'pending', reason: 'APP_STORE_SERVER_API_INVALID_RESPONSE' };
+        }
+        if (transactionResult.status !== 'found') {
+            return { status: transactionResult.status, reason: transactionResult.reason };
+        }
+        const fresh = await verifySignedTransaction(transactionResult.signedTransactionInfo, input, options);
+        if (fresh.status !== 'verified') {
+            return fresh;
+        }
+        if (offlineTransaction !== undefined
+            && fresh.payload.transactionId !== offlineTransaction.transactionId) {
+            return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_ID_MISMATCH' };
+        }
+        transaction = fresh.payload;
     }
-    const transaction = signatureResult.payload;
     const expectedAccountToken = await resolveExpectedAppAccountToken(input, options);
     if (expectedAccountToken.status !== 'verified') {
         return expectedAccountToken;
@@ -160,6 +229,13 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
     if (!Number.isFinite(nowMs)) {
         return { status: 'pending', reason: 'APP_STORE_VERIFIER_CLOCK_INVALID' };
     }
+    if (offlineTransaction !== undefined
+        && policy.mode === 'offline-only'
+        && nowMs - transaction.signedDate > policy.maxSignedAgeMs) {
+        // Offline-only never sees a later refund; a JWS older than the window is
+        // not fresh enough to decide a grant on.
+        return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_STALE' };
+    }
     const rejection = validateTransaction(input, transaction, options, expectedAccountToken.value, nowMs, clockSkewMs);
     if (rejection !== undefined) {
         return { status: 'rejected', reason: rejection };
@@ -179,6 +255,51 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
         },
     };
 }
+const defaultSignedTransactionEvidencePolicy = {
+    mode: 'server-api',
+};
+function assertSignedTransactionEvidencePolicy(input) {
+    if (input === undefined) {
+        return;
+    }
+    assertRecord(input, 'signedTransactionEvidence');
+    if (input.mode === 'ignore' || input.mode === 'server-api') {
+        return;
+    }
+    if (input.mode === 'offline-only') {
+        readPositiveSafeInteger(input.maxSignedAgeMs, 'signedTransactionEvidence.maxSignedAgeMs');
+        return;
+    }
+    throw new Error('signedTransactionEvidence.mode must be ignore, server-api, or offline-only.');
+}
+/** Verifies one JWS through the signature port and validates the decoded payload shape. */
+async function verifySignedTransaction(signedTransaction, input, options) {
+    let signatureResult;
+    try {
+        signatureResult = await options.signedTransactionVerifier.verifyAndDecode({
+            signedTransaction,
+            environment: options.environment,
+            bundleId: options.bundleId,
+            signal: input.signal,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof AppStoreDependencyUnavailableError)) {
+            throw error;
+        }
+        return { status: 'pending', reason: 'APP_STORE_SIGNATURE_VERIFIER_UNAVAILABLE' };
+    }
+    try {
+        assertAppStoreSignedTransactionVerificationResult(signatureResult);
+    }
+    catch {
+        return { status: 'rejected', reason: 'APP_STORE_SIGNATURE_RESULT_INVALID' };
+    }
+    if (signatureResult.status === 'rejected') {
+        return { status: 'rejected', reason: signatureResult.reason };
+    }
+    return { status: 'verified', payload: signatureResult.payload };
+}
 async function resolveExpectedAppAccountToken(input, options) {
     try {
         const value = await options.resolveAppAccountToken({

package/dist/authoritative-purchase.d.ts

@@ -1,7 +1,30 @@
-import type { PurchaseResult } from '@mpgd/platform';
+import type { PlatformGateway, PurchaseResult } from '@mpgd/platform';
+export interface AdapterSettledGrant {
+  readonly ledgerEntryId: string;
+  readonly alreadyProcessed?: boolean;
+}
+/**
+* Internal: the ledger grant a checkout result already carries, or undefined
+* when the backend must verify. A gateway with a commerce v2 provider decides
+* from the provider's capability block (RFC "Capabilities":
+* `authority.evidence: 'adapter-settled'`) plus the result's
+* `authoritativeGrant`; a provider whose capabilities cannot be read, or that
+* declares any other evidence, answers undefined so the client verifies. A
+* gateway without a v2 provider keeps the deprecated target-name rule until
+* C4 removes it.
+*/
+export declare function findAdapterSettledGrant(input: {
+  readonly gateway: Pick<PlatformGateway, 'commerceV2'>;
+  readonly target: string;
+  readonly purchase: PurchaseResult;
+}): Promise<AdapterSettledGrant | undefined>;
 /**
 * Internal: the Microsoft Store adapter completes the ledger grant before it returns this
 * checkout result, so no further backend verification is requested for it.
+*
+* @deprecated Settlement is declared by the commerce v2 capability block; use
+* `findAdapterSettledGrant`, which reads it on gateways that expose `commerceV2`. Kept for
+* gateways that still install only the v1 `createMicrosoftStoreCommerceAdapter`; C4 removes it.
 */
 export declare function isAuthoritativeMicrosoftStoreCompletion(target: string, purchase: PurchaseResult): purchase is PurchaseResult & {
   readonly status: 'completed';

package/dist/authoritative-purchase.js

@@ -1,6 +1,58 @@
+/**
+ * Internal: the ledger grant a checkout result already carries, or undefined
+ * when the backend must verify. A gateway with a commerce v2 provider decides
+ * from the provider's capability block (RFC "Capabilities":
+ * `authority.evidence: 'adapter-settled'`) plus the result's
+ * `authoritativeGrant`; a provider whose capabilities cannot be read, or that
+ * declares any other evidence, answers undefined so the client verifies. A
+ * gateway without a v2 provider keeps the deprecated target-name rule until
+ * C4 removes it.
+ */
+export async function findAdapterSettledGrant(input) {
+    const { purchase } = input;
+    const grant = purchase.authoritativeGrant;
+    if (purchase.status !== 'completed' || purchase.transactionId === undefined || grant === undefined) {
+        return undefined;
+    }
+    const provider = input.gateway.commerceV2;
+    const settled = provider === undefined
+        ? isAuthoritativeMicrosoftStoreCompletion(input.target, purchase)
+        : (await readEvidenceAuthority(provider)) === 'adapter-settled';
+    if (!settled) {
+        return undefined;
+    }
+    return {
+        ledgerEntryId: grant.ledgerEntryId,
+        ...(grant.alreadyProcessed === undefined ? {} : { alreadyProcessed: grant.alreadyProcessed }),
+    };
+}
+/**
+ * A provider's `authority.evidence` declaration is fixed for its lifetime, so
+ * one successful read serves every later checkout; a failed read is not
+ * cached, and the next checkout probes again.
+ */
+const evidenceAuthorityByProvider = new WeakMap();
+async function readEvidenceAuthority(provider) {
+    const cached = evidenceAuthorityByProvider.get(provider);
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        const { evidence } = (await provider.getCapabilities()).authority;
+        evidenceAuthorityByProvider.set(provider, evidence);
+        return evidence;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Internal: the Microsoft Store adapter completes the ledger grant before it returns this
  * checkout result, so no further backend verification is requested for it.
+ *
+ * @deprecated Settlement is declared by the commerce v2 capability block; use
+ * `findAdapterSettledGrant`, which reads it on gateways that expose `commerceV2`. Kept for
+ * gateways that still install only the v1 `createMicrosoftStoreCommerceAdapter`; C4 removes it.
  */
 export function isAuthoritativeMicrosoftStoreCompletion(target, purchase) {
     return target === 'microsoft-store'

package/dist/client.js

@@ -1,7 +1,7 @@
 import { createORPCClient } from '@orpc/client';
 import { RPCLink } from '@orpc/client/fetch';
 import { createAnalyticsReporter } from '@mpgd/analytics';
-import { isAuthoritativeMicrosoftStoreCompletion } from './authoritative-purchase.js';
+import { findAdapterSettledGrant } from './authoritative-purchase.js';
 import { resolveClientRewardClaim, } from './client-reward-evidence.js';
 import { createDefaultClientRewardEvidenceRegistry } from './default-client-reward-evidence.js';
 import { observeGameServicesOperation } from './operation-progress.js';
@@ -110,19 +110,27 @@ export function createGameServicesClient(input) {
                         purchase,
                     };
                 }
-                if (isAuthoritativeMicrosoftStoreCompletion(target, purchase)) {
+                // A provider that declares adapter settlement already wrote the ledger
+                // grant before returning; the target-name rule remains only for
+                // gateways without a commerce v2 provider (removed in C4).
+                const settledGrant = await findAdapterSettledGrant({
+                    gateway: input.gateway,
+                    target,
+                    purchase,
+                });
+                if (settledGrant !== undefined) {
                     const result = {
                         status: 'granted',
                         purchase,
-                        ledgerEntryId: purchase.transactionId,
+                        ledgerEntryId: settledGrant.ledgerEntryId,
                     };
                     await analytics.track({
                         name: 'purchase_granted',
                         properties: {
                             productId: purchaseInput.productId,
                             status: result.status,
-                            ledgerEntryId: purchase.transactionId,
-                            alreadyProcessed: purchase.authoritativeGrant?.alreadyProcessed,
+                            ledgerEntryId: settledGrant.ledgerEntryId,
+                            alreadyProcessed: settledGrant.alreadyProcessed,
                         },
                     });
                     return result;

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/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.1",
+  "version": "0.21.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.4",
-    "@mpgd/catalog": "0.8.1",
-    "@mpgd/platform": "0.18.0"
+    "@mpgd/catalog": "0.9.1",
+    "@mpgd/platform": "0.20.0",
+    "@mpgd/analytics": "0.4.6"
+  },
+  "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"
   }
 }