@mpgd/game-services 0.20.0 → 0.21.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -190,9 +190,9 @@
     "@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.5",
-    "@mpgd/platform": "0.19.0",
-    "@mpgd/catalog": "0.9.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"