@mpgd/game-services 0.32.0 → 0.33.0

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

@@ -1,4 +1,4 @@
-import { type AppStoreEnvironment, type AppStoreTransactionPayload } from './app-store-verifier.js';
+import { type AppStoreEnvironment, type AppStoreRevocationRecorder, type AppStoreTransactionPayload } from './app-store-verifier.js';
 import type { GameServicesStore } from './server.js';
 /**
 * App Store Server Notifications V2 for one-time purchases: the store-side
@@ -70,6 +70,15 @@ export interface HandleAppStoreServerNotificationInput {
   * most `maxUnmatchedRefundRetryMs` (6 hours).
   */
   readonly unmatchedRefundRetryMs?: number;
+  /**
+  * Records every `REFUND` and `REVOKE` of the customer's own one-time
+  * purchase, before the ledger is read, whether or not a grant exists yet.
+  * Required in practice for a verifier in `offline-only` mode, which reads
+  * the same registry: a refund that arrives before the first grant leaves
+  * no grant to reverse, and the client may still hold a JWS signed before
+  * it. A recorder outage (`AppStoreDependencyUnavailableError`) is `retry`.
+  */
+  readonly revocations?: AppStoreRevocationRecorder;
 }
 /** Default of `unmatchedRefundRetryMs`. */
 export declare const defaultUnmatchedRefundRetryMs: number;
@@ -135,6 +144,9 @@ export type AppStoreServerNotificationOutcome =
 export declare const maxAppStoreServerNotificationBytes: number;
 /**
 * Verifies one App Store Server Notification and applies it to the ledger.
+* With `revocations`, every `REFUND` and `REVOKE` of the customer's own
+* one-time purchase is recorded there first, so an offline-only purchase
+* verifier refuses a JWS signed before it even when no grant existed yet.
 * `REFUND` and `REVOKE` for a granted one-time purchase append one `revoke`
 * entry, keyed by the notification's `notificationUUID` so a redelivery
 * answers the first entry. Every other type, a transaction this ledger never
@@ -149,7 +161,8 @@ export declare const maxAppStoreServerNotificationBytes: number;
 * A refund for a grant this ledger does not hold is `retry` while it is
 * recent (`unmatchedRefundRetryMs`, a purchase may be committing a grant it
 * verified before the refund) and `ignored` after; a purchase request that
-* starts after the refund is refused by the verifier's Server API mode.
+* starts after the refund is refused by the verifier's Server API mode, or,
+* in offline-only mode, by the `revocations` record.
 * A thrown error (a store outage, an abort) is not an outcome: the host must
 * answer it with a 5xx so Apple redelivers.
 */

package/dist/app-store-server-notifications.js

@@ -1,5 +1,6 @@
 import { findEntitlementRevocationsChunked, findPurchaseGrantByEvidenceVerificationId, revokeEntitlementGrant, } from './commerce-ledger.js';
-import { AppStoreDependencyUnavailableError, createAppStoreVerificationId, } from './app-store-verifier.js';
+import { createAppStoreGrantVerificationId } from './app-store-verification-id.js';
+import { AppStoreDependencyUnavailableError, } from './app-store-verifier.js';
 /** Default of `unmatchedRefundRetryMs`. */
 export const defaultUnmatchedRefundRetryMs = 60 * 60 * 1000;
 /** Upper bound of `unmatchedRefundRetryMs`. */
@@ -19,6 +20,9 @@ const revocationReasons = {
 };
 /**
  * Verifies one App Store Server Notification and applies it to the ledger.
+ * With `revocations`, every `REFUND` and `REVOKE` of the customer's own
+ * one-time purchase is recorded there first, so an offline-only purchase
+ * verifier refuses a JWS signed before it even when no grant existed yet.
  * `REFUND` and `REVOKE` for a granted one-time purchase append one `revoke`
  * entry, keyed by the notification's `notificationUUID` so a redelivery
  * answers the first entry. Every other type, a transaction this ledger never
@@ -33,7 +37,8 @@ const revocationReasons = {
  * A refund for a grant this ledger does not hold is `retry` while it is
  * recent (`unmatchedRefundRetryMs`, a purchase may be committing a grant it
  * verified before the refund) and `ignored` after; a purchase request that
- * starts after the refund is refused by the verifier's Server API mode.
+ * starts after the refund is refused by the verifier's Server API mode, or,
+ * in offline-only mode, by the `revocations` record.
  * A thrown error (a store outage, an abort) is not an outcome: the host must
  * answer it with a 5xx so Apple redelivers.
  */
@@ -102,14 +107,43 @@ export async function handleAppStoreServerNotification(input) {
     }
     // The grant's identity is the one the purchase verifier recorded:
     // non-consumables by their original transaction, consumables by their own.
-    const grantVerificationId = createAppStoreVerificationId({
-        environment: transaction.environment,
-        bundleId: transaction.bundleId,
-        transactionId: transaction.type === 'Non-Consumable'
-            ? transaction.originalTransactionId
-            : transaction.transactionId,
-    });
+    const grantVerificationId = createAppStoreGrantVerificationId(transaction);
     const now = input.now ?? (() => new Date().toISOString());
+    if (reason !== undefined && input.revocations !== undefined) {
+        // Recorded before the ledger is read, so a grant that does not exist
+        // yet is refused by an offline-only verifier instead of only retried.
+        try {
+            await input.revocations.recordRevocation({
+                record: {
+                    verificationId: grantVerificationId,
+                    environment: transaction.environment,
+                    bundleId: transaction.bundleId,
+                    transactionId: transaction.transactionId,
+                    originalTransactionId: transaction.originalTransactionId,
+                    productId: transaction.productId,
+                    reason,
+                    // Apple's signed dates, never the handling time: a redelivery of
+                    // an undated refund must not move the cutoff past a reversal. An
+                    // unrepresentable date is kept unparseable, which refuses every JWS.
+                    revokedAt: readTimestamp(transaction.revocationDate ?? notification.signedDate)
+                        ?? 'unparseable',
+                    notificationType: notification.notificationType,
+                    notificationUUID,
+                },
+                signal: input.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof AppStoreDependencyUnavailableError) {
+                return {
+                    status: 'retry',
+                    reason: 'APP_STORE_REVOCATION_REGISTRY_UNAVAILABLE',
+                    notificationUUID,
+                };
+            }
+            throw error;
+        }
+    }
     const grant = await findPurchaseGrantByEvidenceVerificationId(input.store, grantVerificationId);
     if (grant === undefined || grant.payload.target !== 'ios') {
         if (grant === undefined

package/dist/app-store-verification-id.d.ts

@@ -0,0 +1,25 @@
+/**
+* The App Store grant identity, shared by the purchase verifier (the
+* verification id its grants record) and the server notification handler
+* (the grant it reverses and the revocation it records): both must derive
+* the same key from a transaction. Internal: the public names are
+* re-exported from `app-store-verifier`.
+*/
+export declare function createAppStoreVerificationId(input: {
+  readonly environment: 'Production' | 'Sandbox';
+  readonly bundleId: string;
+  readonly transactionId: string;
+}): string;
+/**
+* The verification id of the grant a transaction makes: a non-consumable by
+* its original transaction (restores and re-downloads share one grant), any
+* other type by its own transaction.
+*/
+export declare function createAppStoreGrantVerificationId(transaction: {
+  readonly environment: 'Production' | 'Sandbox';
+  readonly bundleId: string;
+  readonly type: string;
+  readonly transactionId: string;
+  readonly originalTransactionId: string;
+}): string;
+export declare function encodeVerificationIdSegment(value: string): string;

package/dist/app-store-verification-id.js

@@ -0,0 +1,32 @@
+/**
+ * The App Store grant identity, shared by the purchase verifier (the
+ * verification id its grants record) and the server notification handler
+ * (the grant it reverses and the revocation it records): both must derive
+ * the same key from a transaction. Internal: the public names are
+ * re-exported from `app-store-verifier`.
+ */
+export function createAppStoreVerificationId(input) {
+    return [
+        'app-store',
+        input.environment,
+        input.bundleId,
+        input.transactionId,
+    ].map(encodeVerificationIdSegment).join(':');
+}
+/**
+ * The verification id of the grant a transaction makes: a non-consumable by
+ * its original transaction (restores and re-downloads share one grant), any
+ * other type by its own transaction.
+ */
+export function createAppStoreGrantVerificationId(transaction) {
+    return createAppStoreVerificationId({
+        environment: transaction.environment,
+        bundleId: transaction.bundleId,
+        transactionId: transaction.type === 'Non-Consumable'
+            ? transaction.originalTransactionId
+            : transaction.transactionId,
+    });
+}
+export function encodeVerificationIdSegment(value) {
+    return `${value.length}:${encodeURIComponent(value)}`;
+}

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

@@ -1,5 +1,6 @@
 import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
 import type { GameServicesEvidenceVerifier } from './evidence-verification.js';
+import { createAppStoreVerificationId } from './app-store-verification-id.js';
 export type AppStoreEnvironment = 'Production' | 'Sandbox';
 export declare const appStoreServerApiBaseUrls: Readonly<{
   readonly Production: 'https://api.storekit.apple.com';
@@ -85,10 +86,17 @@ export interface CreateAppStoreEvidenceVerifierOptions {
   * 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:
+  * the client cached its JWS is seen. `{ mode: 'offline-only', maxSignedAgeMs,
+  * revocations }` decides on the client JWS and is only for deployments
+  * without Server API access: a JWS is a snapshot, so a transaction refunded
+  * after it was signed still reads as purchased. Before a grant it therefore
+  * asks `revocations`, the store of refunds and revocations App Store Server
+  * Notifications recorded (`handleAppStoreServerNotification({ revocations })`),
+  * and refuses a JWS signed at or before a revocation found there (plus
+  * `clockSkewMs`) with `APP_STORE_TRANSACTION_REVOKED`; a JWS signed later
+  * without a `revocationDate` shows a refund Apple reversed and passes. A
+  * refund Apple has not notified yet is still accepted until `signedDate`
+  * falls out of the window; the notification then reverses the grant. `{ mode:
   * 'ignore' }` fetches by id for every request.
   */
   readonly signedTransactionEvidence?: AppStoreSignedTransactionEvidencePolicy;
@@ -129,7 +137,93 @@ export type AppStoreSignedTransactionEvidencePolicy = {
   readonly mode: 'offline-only';
   /** Maximum age of the JWS `signedDate` at verification time; older evidence is rejected. */
   readonly maxSignedAgeMs: number;
+  /**
+  * Required. The revocations this backend learned from App Store Server
+  * Notifications, read before every offline-only grant: a client can keep
+  * a JWS signed before a refund, and a refund that reached the backend
+  * before the first grant has no ledger grant to reverse. A record
+  * refuses only a JWS signed at or before its `revokedAt` plus
+  * `clockSkewMs`, so a refund Apple later reversed grants again from a
+  * fresh JWS. It must read
+  * the durable store the notification handler's `revocations` recorder
+  * writes, across every instance that verifies purchases.
+  */
+  readonly revocations: AppStoreRevocationLookup;
 };
+/** Why Apple ended a one-time purchase: `REFUND` is `refund`, `REVOKE` is `voided`. */
+export type AppStoreRevocationReason = 'refund' | 'voided';
+/**
+* A refund or revocation of a one-time purchase, recorded from a verified App
+* Store Server Notification whether or not the ledger holds a grant for it.
+*/
+export interface AppStoreRevocationRecord {
+  /**
+  * The grant identity the purchase verifier records
+  * (`createAppStoreVerificationId`): the original transaction id of a
+  * non-consumable, the transaction id of a consumable. The lookup key.
+  */
+  readonly verificationId: string;
+  readonly environment: AppStoreEnvironment;
+  readonly bundleId: string;
+  readonly transactionId: string;
+  readonly originalTransactionId: string;
+  readonly productId: string;
+  readonly reason: AppStoreRevocationReason;
+  /**
+  * When Apple revoked it: the transaction's `revocationDate`, else the
+  * notification's `signedDate`. Both are Apple's signed values, so a
+  * redelivery of the same notification records the same time. A
+  * record may be dropped once `revokedAt` is older than the verifier's
+  * `maxSignedAgeMs` plus `clockSkewMs`: every JWS the record refuses
+  * (signed at or before `revokedAt` plus `clockSkewMs`) is then stale.
+  */
+  readonly revokedAt: string;
+  readonly notificationType: string;
+  readonly notificationUUID: string;
+}
+/**
+* Reads recorded revocations for the offline-only verifier. Answer the record
+* for `verificationId`, or `undefined` when none is recorded. Throw
+* `AppStoreDependencyUnavailableError` only for a transient storage outage
+* (the purchase stays `pending`); any other error propagates.
+*/
+export interface AppStoreRevocationLookup {
+  findRevocation(input: {
+    readonly verificationId: string;
+    readonly environment: AppStoreEnvironment;
+    readonly bundleId: string;
+    readonly transactionId: string;
+    readonly originalTransactionId: string;
+    readonly signal: AbortSignal;
+  }): Promise<AppStoreRevocationRecord | undefined>;
+}
+/**
+* Durably records a revocation, keeping per `verificationId` the record with
+* the latest `revokedAt`: a purchase can be refunded, reversed, and revoked
+* again, and the lookup must refuse every JWS signed before the latest
+* revocation. A record whose `revokedAt` does not parse counts as the
+* latest. A record no later than the kept one (a redelivery, or an older
+* notification arriving late) keeps it and answers `alreadyRecorded: true`.
+* Throw `AppStoreDependencyUnavailableError` only for a transient storage
+* outage (the notification is answered `retry`, so Apple redelivers).
+*/
+export interface AppStoreRevocationRecorder {
+  recordRevocation(input: {
+    readonly record: AppStoreRevocationRecord;
+    readonly signal: AbortSignal;
+  }): Promise<{
+    readonly alreadyRecorded: boolean;
+  }>;
+}
+export interface AppStoreRevocationRegistry extends AppStoreRevocationLookup, AppStoreRevocationRecorder {
+}
+/**
+* A process-local `AppStoreRevocationRegistry` for tests and single-process
+* hosts. It forgets everything on restart and is not shared between
+* instances (a Worker isolate is one), so a deployment that verifies
+* purchases offline needs a durable registry of its own.
+*/
+export declare function createInMemoryAppStoreRevocationRegistry(): AppStoreRevocationRegistry;
 /**
 * Evidence schema of a commerce v2 App Store purchase (RFC B3): the payload's
 * `signedTransaction` is the StoreKit-verified JWS the client received. The
@@ -156,11 +250,7 @@ export type AppStoreFetch = (url: string, init: {
 }) => Promise<AppStoreFetchResponse>;
 export declare function createAppStoreServerApiClient(options: CreateAppStoreServerApiClientOptions): AppStoreServerApiClient;
 export declare function createAppStoreGameServicesEvidenceVerifier(options: CreateAppStoreEvidenceVerifierOptions): GameServicesEvidenceVerifier;
-export declare function createAppStoreVerificationId(input: {
-  readonly environment: AppStoreEnvironment;
-  readonly bundleId: string;
-  readonly transactionId: string;
-}): string;
+export { createAppStoreVerificationId };
 /** Identify IDs emitted by this verifier without duplicating its encoding format. */
 export declare function isAppStoreVerificationId(verificationId: string): boolean;
 export declare function assertAppStoreTransactionPayload(input: unknown): AppStoreTransactionPayload;

package/dist/app-store-verifier.js

@@ -1,3 +1,4 @@
+import { createAppStoreGrantVerificationId, createAppStoreVerificationId, encodeVerificationIdSegment, } from './app-store-verification-id.js';
 export const appStoreServerApiBaseUrls = Object.freeze({
     Production: 'https://api.storekit.apple.com',
     Sandbox: 'https://api.storekit-sandbox.apple.com',
@@ -16,6 +17,42 @@ class AppStoreResponseTooLargeError extends Error {
         this.name = 'AppStoreResponseTooLargeError';
     }
 }
+/**
+ * A process-local `AppStoreRevocationRegistry` for tests and single-process
+ * hosts. It forgets everything on restart and is not shared between
+ * instances (a Worker isolate is one), so a deployment that verifies
+ * purchases offline needs a durable registry of its own.
+ */
+export function createInMemoryAppStoreRevocationRegistry() {
+    const records = new Map();
+    return {
+        async findRevocation(input) {
+            return records.get(input.verificationId);
+        },
+        async recordRevocation(input) {
+            assertNonEmptyString(input.record.verificationId, 'record.verificationId');
+            const kept = records.get(input.record.verificationId);
+            if (kept !== undefined && !isLaterRevocation(input.record, kept)) {
+                return { alreadyRecorded: true };
+            }
+            records.set(input.record.verificationId, { ...input.record });
+            return { alreadyRecorded: false };
+        },
+    };
+}
+/**
+ * Whether `record` revokes later than `kept`, the order a registry keeps
+ * records in. An unparseable `revokedAt` is the latest (it refuses every
+ * JWS), and one unparseable record never replaces another.
+ */
+function isLaterRevocation(record, kept) {
+    const recordMs = Date.parse(record.revokedAt);
+    const keptMs = Date.parse(kept.revokedAt);
+    if (!Number.isFinite(keptMs)) {
+        return false;
+    }
+    return !Number.isFinite(recordMs) || recordMs > keptMs;
+}
 /**
  * Evidence schema of a commerce v2 App Store purchase (RFC B3): the payload's
  * `signedTransaction` is the StoreKit-verified JWS the client received. The
@@ -158,9 +195,9 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
     // 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.
+    // the Server API (default), or on the JWS within a freshness window and
+    // the revocations notifications recorded (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' }
@@ -240,8 +277,8 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
     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.
+        // The JWS never shows a refund Apple has not notified yet; a JWS older
+        // than the window is not fresh enough to decide a grant on.
         return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_STALE' };
     }
     let rejection = validateTransaction(input, transaction, options.bundleId, environment, expectedAccountToken.value, nowMs, clockSkewMs);
@@ -263,6 +300,21 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
     if (rejection !== undefined) {
         return { status: 'rejected', reason: rejection };
     }
+    const verificationId = createAppStoreGrantVerificationId(transaction);
+    if (offlineTransaction !== undefined && policy.mode === 'offline-only') {
+        // The client JWS cannot show a refund after it was signed: a refund the
+        // backend already heard of refuses a JWS signed before it, as a fresh
+        // Server API status would. A refund before the first grant has no ledger
+        // grant to reverse, so without this check it would grant with nothing
+        // behind it. A JWS signed after it without a `revocationDate` shows that
+        // Apple reversed the refund, and passes. It runs before the account
+        // binding answers, so a refund refuses every presenter, as the Server
+        // API's `revocationDate` does.
+        const revocation = await findRecordedRevocation(policy.revocations, verificationId, transaction, clockSkewMs, input.signal);
+        if (revocation !== undefined) {
+            return revocation;
+        }
+    }
     if (tokenMismatch && !foreignBinding) {
         // A transaction without an appAccountToken (bought outside the app, or
         // by a build that set none) is no account's: refused for every player.
@@ -283,7 +335,7 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
                     : 'APP_STORE_ACCOUNT_TOKEN_MISMATCH',
             }
             : { status: 'verified' }),
-        verificationId: createVerificationId(transaction),
+        verificationId,
         verifiedAt: new Date(nowMs).toISOString(),
         payload: {
             appStoreBundleId: transaction.bundleId,
@@ -299,6 +351,42 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
 const defaultSignedTransactionEvidencePolicy = {
     mode: 'server-api',
 };
+/**
+ * The offline-only refusal for a revocation the backend recorded, or
+ * `undefined` when none applies. A record refuses a JWS signed at or before
+ * its `revokedAt` (widened by `clockSkewMs`, so skew errs toward refusing):
+ * that JWS is a snapshot from before the refund. A JWS signed later already
+ * shows the revocation in its own `revocationDate` (refused by the payload
+ * checks), unless Apple reversed the refund, so it passes. A record whose
+ * `revokedAt` does not parse refuses every JWS.
+ */
+async function findRecordedRevocation(revocations, verificationId, transaction, clockSkewMs, signal) {
+    let record;
+    try {
+        record = await revocations.findRevocation({
+            verificationId,
+            environment: transaction.environment,
+            bundleId: transaction.bundleId,
+            transactionId: transaction.transactionId,
+            originalTransactionId: transaction.originalTransactionId,
+            signal,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof AppStoreDependencyUnavailableError)) {
+            throw error;
+        }
+        return { status: 'pending', reason: 'APP_STORE_REVOCATION_LOOKUP_UNAVAILABLE' };
+    }
+    if (record === undefined) {
+        return undefined;
+    }
+    const revokedAtMs = typeof record.revokedAt === 'string' ? Date.parse(record.revokedAt) : NaN;
+    if (Number.isFinite(revokedAtMs) && transaction.signedDate > revokedAtMs + clockSkewMs) {
+        return undefined;
+    }
+    return { status: 'rejected', reason: 'APP_STORE_TRANSACTION_REVOKED' };
+}
 function readSandboxGrantPolicy(options) {
     return options.environment === 'Production' && options.sandboxPurchases?.mode === 'grant'
         ? options.sandboxPurchases
@@ -396,6 +484,14 @@ function assertSignedTransactionEvidencePolicy(input) {
     }
     if (input.mode === 'offline-only') {
         readPositiveSafeInteger(input.maxSignedAgeMs, 'signedTransactionEvidence.maxSignedAgeMs');
+        if (typeof input.revocations !== 'object'
+            || input.revocations === null
+            || typeof input.revocations.findRevocation
+                !== 'function') {
+            // A client JWS cannot show a later refund; without the recorded
+            // revocations a refund before the first grant would still grant.
+            throw new Error('signedTransactionEvidence.revocations must implement findRevocation for offline-only.');
+        }
         return;
     }
     throw new Error('signedTransactionEvidence.mode must be ignore, server-api, or offline-only.');
@@ -511,24 +607,7 @@ expectedAccountToken, nowMs, clockSkewMs) {
     }
     return undefined;
 }
-function createVerificationId(transaction) {
-    const grantTransactionId = transaction.type === 'Non-Consumable'
-        ? transaction.originalTransactionId
-        : transaction.transactionId;
-    return createAppStoreVerificationId({
-        environment: transaction.environment,
-        bundleId: transaction.bundleId,
-        transactionId: grantTransactionId,
-    });
-}
-export function createAppStoreVerificationId(input) {
-    return [
-        'app-store',
-        input.environment,
-        input.bundleId,
-        input.transactionId,
-    ].map(encodeVerificationIdSegment).join(':');
-}
+export { createAppStoreVerificationId };
 /** Identify IDs emitted by this verifier without duplicating its encoding format. */
 export function isAppStoreVerificationId(verificationId) {
     const parts = verificationId.split(':');
@@ -560,9 +639,6 @@ export function isAppStoreVerificationId(verificationId) {
         && typeof values[2] === 'string' && values[2].length > 0
         && typeof values[3] === 'string' && /^[1-9][0-9]{0,19}$/u.test(values[3]);
 }
-function encodeVerificationIdSegment(value) {
-    return `${value.length}:${encodeURIComponent(value)}`;
-}
 function toCatalogProductType(type) {
     switch (type) {
         case 'Consumable':

package/dist/client.js

@@ -165,7 +165,9 @@ export function createGameServicesClient(input) {
                         }
                     };
                     const unsubscribe = reconciler.subscribe((event) => {
-                        if (event.type === 'failure' || event.record.idempotencyKey !== key) {
+                        if (event.type === 'failure'
+                            || event.type === 'revoked-finish'
+                            || event.record.idempotencyKey !== key) {
                             return;
                         }
                         if (event.type === 'transition') {

package/dist/commerce-reconciler.d.ts

@@ -91,6 +91,12 @@ export declare function summarizeCommercePurchaseOperation(record: CommercePurch
 /** A `verifying` record the backend answered as another account's purchase. */
 export declare function isParkedForAnotherAccount(record: CommercePurchaseOperationRecord): boolean;
 /**
+* Backend refusals that answer for a revoked purchase: the App Store verifier
+* read the refund (`APP_STORE_TRANSACTION_REVOKED`), or the ledger had
+* already reversed the grant this request names (`LEDGER_GRANT_REVERSED`).
+*/
+export declare const commerceRevokedRejectionReasons: ReadonlySet<string>;
+/**
 * Only `granted` and `finishing` records that hold the backend's ledger entry
 * id and a store transaction may be finished. The StoreKit SDK keeps no
 * finish allow-list of its own (the removed v1 driver paired transactions in
@@ -139,6 +145,19 @@ export type CommerceReconcilerEvent = {
   readonly record: CommercePurchaseOperationRecord;
   readonly reason: string;
   readonly response?: VerifyPurchaseResponse;
+} | {
+  /**
+  * A transaction the store revoked (refunded) while it was unfinished
+  * was asked to finish without a grant (`FinishTransactionInput.revoked`),
+  * and the store answered `finished`. `idempotencyKey` names this
+  * player's record the backend answered for; absent, the reconciler
+  * held no record of it, and the store's own-account revoked consumable
+  * was finished without a verify (nothing is journaled or granted).
+  */
+  readonly type: 'revoked-finish';
+  readonly transactionId: string;
+  readonly idempotencyKey?: string;
+  readonly finished: boolean;
 } | {
   readonly type: 'failure';
   readonly stage: CommerceReconcilerFailureStage;

package/dist/commerce-reconciler.js

@@ -69,6 +69,34 @@ function releasesSharedKey(record) {
             && !record.response.verified
             && isStoreAccountMismatchReason(record.response.reason));
 }
+/**
+ * Backend refusals that answer for a revoked purchase: the App Store verifier
+ * read the refund (`APP_STORE_TRANSACTION_REVOKED`), or the ledger had
+ * already reversed the grant this request names (`LEDGER_GRANT_REVERSED`).
+ */
+export const commerceRevokedRejectionReasons = new Set([
+    'APP_STORE_TRANSACTION_REVOKED',
+    'LEDGER_GRANT_REVERSED',
+]);
+/**
+ * A record the backend answered for a refund with no grant standing: its
+ * grant reversed by the ledger (`revoked`), or the purchase refused as
+ * revoked (`rejected` with a reason in `commerceRevokedRejectionReasons`). A
+ * store transaction of such a record that the store reports revoked may be
+ * finished without a grant (`FinishTransactionInput.revoked`). A refusal for
+ * any other reason keeps the transaction unfinished.
+ */
+function answeredWithoutGrant(record) {
+    if (record.state === 'revoked') {
+        return true;
+    }
+    const response = record.response;
+    return record.state === 'rejected'
+        && response !== undefined
+        && !response.verified
+        && typeof response.reason === 'string'
+        && commerceRevokedRejectionReasons.has(response.reason);
+}
 function isRetryableBeforeLaunch(record) {
     return record.state === 'requested' && record.error?.retryable === true
         && record.purchase === undefined && record.request === undefined;
@@ -775,6 +803,182 @@ export function createCommerceReconciler(input) {
             fail('finish', error, record.idempotencyKey);
         }
     };
+    /**
+     * Consumables a `client`-finish store reported revoked this session (the
+     * App Store refunded them while they were unfinished, so StoreKit keeps
+     * them unfinished and redelivers them until `finish()`), by transaction
+     * id, with their record's idempotency key, or `undefined` for one this
+     * player holds no record of. `finishRevokedReported` finishes one, without
+     * any grant, once its record holds the backend's answer (`answeredWithoutGrant`),
+     * or at once without a record. Until then it waits: a grant the ledger
+     * still holds keeps the transaction unfinished, as before.
+     */
+    const revokedReports = new Map();
+    /** Transactions this session already asked the store to finish as revoked. */
+    const revokedFinishAsked = new Set();
+    /**
+     * Notes a store report of a revoked purchase whose record this player
+     * holds. Only a `client`-finish consumable on a provider that declares
+     * `acceptsRevokedFinish` is noted: any other store, kind, or provider keeps
+     * the revoked report as a no-op, and only the ledger moves a record to
+     * `revoked` (step 5).
+     */
+    const revokedFinishApplies = (kind, transactionId) => kind === 'consumable'
+        && capabilities?.lifecycle.finish === 'client'
+        && provider.finishTransaction !== undefined
+        && provider.acceptsRevokedFinish === true
+        && !revokedFinishAsked.has(transactionId);
+    const noteRevoked = (record, purchase, kind) => {
+        if (record.purchase === undefined
+            || !samePurchase(record.purchase, purchase)
+            // A `finished` record's transaction was finished: the report is the
+            // store's refund notice of a finished consumable (`Transaction.updates`),
+            // with nothing left unfinished. Step 5 revokes the record if the
+            // ledger reversed it; a later report of a still-unfinished one is
+            // noted then.
+            || record.state === 'finished'
+            || !revokedFinishApplies(record.productKind ?? kind, record.purchase.transactionId)) {
+            return;
+        }
+        revokedReports.set(record.purchase.transactionId, record.idempotencyKey);
+    };
+    /**
+     * Whether a store purchase is bound to this player's own account: the
+     * purchase carries a binding, this player's binding reads, and the two are
+     * the same kind and value. Stricter than `accountOf`, which calls an
+     * unbound purchase or an unread binding this player's.
+     */
+    const boundToThisPlayer = async (purchase) => {
+        const bound = purchase.accountBinding;
+        if (bound?.value === undefined || input.accountBinding === undefined) {
+            return false;
+        }
+        let own;
+        try {
+            own = await input.accountBinding();
+        }
+        catch {
+            return false;
+        }
+        if (own?.value === undefined || own.kind !== bound.kind) {
+            return false;
+        }
+        return bound.kind === 'app-account-token'
+            ? own.value.toLowerCase() === bound.value.toLowerCase()
+            : own.value === bound.value;
+    };
+    /**
+     * A revoked purchase this player holds no record of (the journal dropped
+     * it, it was lost, or the store answer was never journaled). A refunded
+     * consumable gives nobody anything and the backend learns of the refund
+     * from the store (App Store Server Notifications), so it is finished
+     * without a verify, never journaled or granted: verifying it could grant
+     * from a signed transaction saved before the refund. Only a consumable
+     * bound to this player's own account, on a provider that finishes revoked
+     * transactions; a record found under its derived key (a journal without the
+     * transaction index) takes the record's path instead.
+     */
+    const noteUnrecordedRevoked = async (purchase, kind) => {
+        if (!revokedFinishApplies(kind, purchase.transactionId)
+            // Already noted this session (the store redelivers it): no second
+            // derived-key hash and journal read.
+            || revokedReports.has(purchase.transactionId)) {
+            return;
+        }
+        const idempotencyKey = await createDerivedPurchaseIdempotencyKey({
+            store: purchase.store,
+            transactionId: purchase.transactionId,
+            token: purchase.token,
+        });
+        let found;
+        try {
+            found = await readRecord(idempotencyKey);
+        }
+        catch {
+            // Another player's record holds the key: not this player's to finish.
+            return;
+        }
+        if (found !== undefined) {
+            if (found.purchase !== undefined && samePurchase(found.purchase, purchase)) {
+                noteRevoked(found, purchase, kind);
+            }
+            return;
+        }
+        if (!(await boundToThisPlayer(purchase))) {
+            return;
+        }
+        revokedReports.set(purchase.transactionId, undefined);
+    };
+    /**
+     * Finishes the revoked transactions `noteRevoked` kept, once their record
+     * holds the backend's answer, with `revoked: true` and the answer as the
+     * ledger entry id (the reversed grant's entry, or the refused key). Nothing
+     * is granted and the record is not rewritten: it is already terminal. The
+     * store finishes only a transaction it still lists as revoked. Asked once
+     * per session; a transport failure is asked again on a later pass (after
+     * the retry interval, unless the pass is explicit), and a refusal is
+     * reported as a `finish` failure (for StoreKit: a native build from before
+     * the revoked finish; the next launch asks again).
+     */
+    const finishRevokedReported = async (explicit) => {
+        const finishTransaction = provider.finishTransaction;
+        for (const [transactionId, idempotencyKey] of [...revokedReports]) {
+            const record = idempotencyKey === undefined ? undefined : records.get(idempotencyKey);
+            if (idempotencyKey !== undefined) {
+                if (record === undefined || record.purchase?.transactionId !== transactionId) {
+                    revokedReports.delete(transactionId);
+                    continue;
+                }
+                if (!answeredWithoutGrant(record)) {
+                    if (isTerminalCommercePurchaseState(record.state) && record.state !== 'finished') {
+                        // Refused for another reason (or ended otherwise): it stays unfinished.
+                        revokedReports.delete(transactionId);
+                    }
+                    // Otherwise still verifying, granted, finishing, or finished: the
+                    // backend has not answered for the refund yet (step 3 or 5 will).
+                    continue;
+                }
+            }
+            const retryKey = idempotencyKey ?? transactionId;
+            const waitUntil = retryAt.get(retryKey);
+            if (!explicit && waitUntil !== undefined && nowMs() < waitUntil) {
+                continue;
+            }
+            if (finishTransaction === undefined || sessionBlocked(idempotencyKey)) {
+                return;
+            }
+            revokedReports.delete(transactionId);
+            revokedFinishAsked.add(transactionId);
+            try {
+                const { finished } = await finishTransaction.call(provider, {
+                    transactionId,
+                    ...(record?.ledgerEntryId === undefined ? {} : { ledgerEntryId: record.ledgerEntryId }),
+                    isConsumable: true,
+                    revoked: true,
+                });
+                emit({
+                    type: 'revoked-finish',
+                    transactionId,
+                    ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+                    finished,
+                });
+                if (!finished) {
+                    // Not counted as asked: the store could not finish it now (a native
+                    // build from before the revoked finish, or a list that does not
+                    // carry it yet). The next report of the transaction asks again.
+                    revokedFinishAsked.delete(transactionId);
+                    fail('finish', new Error(`The store did not finish the revoked transaction ${transactionId}.`), idempotencyKey);
+                }
+            }
+            catch (error) {
+                // Transport-class failure: a later pass asks again.
+                revokedFinishAsked.delete(transactionId);
+                revokedReports.set(transactionId, idempotencyKey);
+                retryLater(retryKey);
+                fail('finish', error, idempotencyKey);
+            }
+        }
+    };
     /**
      * A store report of a record the backend answered as another account's
      * purchase. Only this player's Restore Purchases asks again (a restore
@@ -887,6 +1091,25 @@ export function createCommerceReconciler(input) {
             }
             record = undefined;
         }
+        if (purchase.state === 'revoked') {
+            // A revoked store state never revokes or verifies anything on its own:
+            // only the ledger revokes (step 5). It is matched only to this
+            // player's record of the same transaction, for a finish without a
+            // grant once the backend has answered for it. It is never attached to
+            // the player's open (`launched`) attempt for the product: the store
+            // reported no purchase for that attempt, and the open attempt may be
+            // another purchase still in flight (an Ask to Buy waiting for approval),
+            // which this refund must not end. Finishing the refunded transaction
+            // as unrecorded grants nothing, and the attempt keeps waiting for its
+            // own purchase report or its expiry, as before.
+            if (record !== undefined) {
+                noteRevoked(record, purchase, product.kind);
+            }
+            else {
+                await noteUnrecordedRevoked(purchase, product.kind);
+            }
+            return;
+        }
         const account = record !== undefined || (restoring && product.kind === 'durable')
             ? 'own'
             : await accountOf(purchase);
@@ -917,10 +1140,6 @@ export function createCommerceReconciler(input) {
             }
         }
         if (record === undefined) {
-            if (purchase.state === 'revoked') {
-                // Revoked store states never revoke on their own: only the ledger does (step 5).
-                return;
-            }
             const idempotencyKey = await createDerivedPurchaseIdempotencyKey({
                 store: purchase.store,
                 transactionId: purchase.transactionId,
@@ -1378,6 +1597,10 @@ export function createCommerceReconciler(input) {
             return;
         }
         await revokeReversed();
+        if (sessionBlocked()) {
+            return;
+        }
+        await finishRevokedReported(options.explicit);
     };
     const runUntilIdle = async () => {
         if (running !== undefined) {
@@ -1780,6 +2003,7 @@ export function createCommerceReconciler(input) {
                     deferred.length = 0;
                     records.clear();
                     retryAt.clear();
+                    revokedReports.clear();
                     throw error;
                 }
                 finally {
@@ -1817,6 +2041,7 @@ export function createCommerceReconciler(input) {
             deferred.length = 0;
             records.clear();
             retryAt.clear();
+            revokedReports.clear();
         },
         async reconcile() {
             await withLock(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -231,9 +231,9 @@
     "@orpc/client": "2.0.0-beta.46",
     "@orpc/contract": "2.0.0-beta.46",
     "@orpc/server": "2.0.0-beta.46",
-    "@mpgd/analytics": "0.5.7",
-    "@mpgd/platform": "0.34.0",
-    "@mpgd/catalog": "0.14.1"
+    "@mpgd/analytics": "0.5.8",
+    "@mpgd/catalog": "0.14.2",
+    "@mpgd/platform": "0.35.0"
   },
   "peerDependencies": {
     "@apple/app-store-server-library": "^3.1.0"