@mpgd/game-services 0.28.0 → 0.29.0

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

@@ -39,6 +39,12 @@ export interface AppStoreTransactionPayload {
   readonly expiresDate?: number;
   readonly revocationDate?: number;
   readonly isUpgraded?: boolean;
+  /**
+  * Apple's `inAppOwnershipType`: `PURCHASED` for the buyer's own
+  * transaction, `FAMILY_SHARED` for a family member's access. Only
+  * `PURCHASED` (or an absent value) is granted.
+  */
+  readonly inAppOwnershipType?: string;
 }
 export type AppStoreSignedTransactionVerificationResult = {
   readonly status: 'verified';
@@ -86,7 +92,35 @@ export interface CreateAppStoreEvidenceVerifierOptions {
   * 'ignore' }` fetches by id for every request.
   */
   readonly signedTransactionEvidence?: AppStoreSignedTransactionEvidencePolicy;
+  /**
+  * Whether a Production deployment grants transactions Apple signed in the
+  * sandbox (App Review, TestFlight, and sandbox testers buy in the sandbox
+  * against the production build). Defaults to `{ mode: 'reject' }`, which
+  * answers `APP_STORE_ENVIRONMENT_MISMATCH`. `{ mode: 'grant', ... }` follows
+  * Apple's production-first order: the transaction is verified against
+  * production, and only when the verified client JWS says `Sandbox` (or,
+  * for a request without a client JWS, production answers
+  * `APP_STORE_TRANSACTION_NOT_FOUND`) is it verified again with the sandbox
+  * verifier and Server API. A client JWS the production verifier accepted
+  * stays a production transaction: a production miss for it is pending, not
+  * a sandbox lookup. The grant's verification id and ledger payload carry
+  * `Sandbox`, so it stays apart from production revenue. Only valid on a
+  * `Production` verifier.
+  */
+  readonly sandboxPurchases?: AppStoreSandboxPurchasePolicy;
 }
+export type AppStoreSandboxPurchasePolicy = {
+  readonly mode: 'reject';
+} | {
+  readonly mode: 'grant';
+  /**
+  * A verifier scoped to the sandbox environment and the same bundle, for
+  * example `createAppleSignedTransactionVerifier({ environment: 'Sandbox', ... })`.
+  */
+  readonly signedTransactionVerifier: AppStoreSignedTransactionVerifier;
+  /** Defaults to the verifier's `serverApi`, which selects the sandbox host per call. */
+  readonly serverApi?: AppStoreServerApiClient;
+};
 export type AppStoreSignedTransactionEvidencePolicy = {
   readonly mode: 'ignore';
 } | {

package/dist/app-store-verifier.js

@@ -133,6 +133,7 @@ export function createAppStoreGameServicesEvidenceVerifier(options) {
     assertNonEmptyString(options.bundleId, 'bundleId');
     assertAppStoreEnvironment(options.environment);
     assertSignedTransactionEvidencePolicy(options.signedTransactionEvidence);
+    assertSandboxPurchasePolicy(options.sandboxPurchases, options.environment);
     const clockSkewMs = readNonNegativeSafeInteger(options.clockSkewMs ?? 5 * 60 * 1000, 'clockSkewMs');
     const now = options.now ?? (() => new Date().toISOString());
     return {
@@ -167,9 +168,17 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
     if (evidence.status === 'rejected') {
         return { status: 'rejected', reason: evidence.reason };
     }
+    const sandbox = readSandboxGrantPolicy(options);
+    let environment = options.environment;
     let offlineTransaction;
     if (evidence.status === 'present') {
-        const offline = await verifySignedTransaction(evidence.signedTransaction, input, options);
+        let offline = await verifySignedTransaction(evidence.signedTransaction, input, options, environment);
+        if (sandbox !== undefined && isSandboxSignal(offline)) {
+            // Production first: only a JWS the production verifier places in the
+            // sandbox is verified again, in full, by the sandbox verifier.
+            environment = 'Sandbox';
+            offline = await verifySignedTransaction(evidence.signedTransaction, input, options, environment);
+        }
         if (offline.status !== 'verified') {
             return offline;
         }
@@ -187,30 +196,23 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
     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' };
+        let transactionResult = await fetchTransactionInfo(input, options, environment);
+        if (sandbox !== undefined
+            && environment === 'Production'
+            // A client JWS already verified in production is a production
+            // transaction: a miss there is replication lag, not the sandbox.
+            && offlineTransaction === undefined
+            && transactionResult.status === 'pending'
+            && transactionResult.reason === 'APP_STORE_TRANSACTION_NOT_FOUND') {
+            // Apple keeps sandbox transaction ids out of production: a production
+            // miss is looked up in the sandbox before it is reported as pending.
+            environment = 'Sandbox';
+            transactionResult = await fetchTransactionInfo(input, options, environment);
         }
         if (transactionResult.status !== 'found') {
             return { status: transactionResult.status, reason: transactionResult.reason };
         }
-        const fresh = await verifySignedTransaction(transactionResult.signedTransactionInfo, input, options);
+        const fresh = await verifySignedTransaction(transactionResult.signedTransactionInfo, input, options, environment);
         if (fresh.status !== 'verified') {
             return fresh;
         }
@@ -218,6 +220,12 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
             && fresh.payload.transactionId !== offlineTransaction.transactionId) {
             return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_ID_MISMATCH' };
         }
+        if (offlineTransaction !== undefined
+            && fresh.payload.environment !== offlineTransaction.environment) {
+            // Transaction ids are unique per environment only: the decision is
+            // taken in the environment the client JWS was verified in.
+            return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_ENVIRONMENT_MISMATCH' };
+        }
         transaction = fresh.payload;
     }
     const expectedAccountToken = await resolveExpectedAppAccountToken(input, options);
@@ -236,12 +244,26 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
         // 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);
+    let rejection = validateTransaction(input, transaction, options.bundleId, environment, expectedAccountToken.value, nowMs, clockSkewMs);
+    // A restored non-consumable bound to an earlier player's appAccountToken
+    // (a new device, an erased device, a logout) is reported, not refused,
+    // when every other check passes: the backend's restore sharing policy
+    // decides (RFC "Restore sharing"). The client's StoreKit-verified JWS is
+    // required, so a transaction id alone never shares a purchase.
+    const foreignBinding = rejection === 'APP_STORE_ACCOUNT_TOKEN_MISMATCH'
+        && input.request.intent === 'restore'
+        && input.product.type === 'non_consumable'
+        && offlineTransaction !== undefined;
+    if (foreignBinding) {
+        rejection = validateTransaction(input, transaction, options.bundleId, environment, undefined, nowMs, clockSkewMs);
+    }
     if (rejection !== undefined) {
         return { status: 'rejected', reason: rejection };
     }
     return {
-        status: 'verified',
+        ...(foreignBinding
+            ? { status: 'restorable', reason: 'APP_STORE_ACCOUNT_TOKEN_MISMATCH' }
+            : { status: 'verified' }),
         verificationId: createVerificationId(transaction),
         verifiedAt: new Date(nowMs).toISOString(),
         payload: {
@@ -258,6 +280,93 @@ async function verifyAppStorePurchase(input, options, now, clockSkewMs) {
 const defaultSignedTransactionEvidencePolicy = {
     mode: 'server-api',
 };
+function readSandboxGrantPolicy(options) {
+    return options.environment === 'Production' && options.sandboxPurchases?.mode === 'grant'
+        ? options.sandboxPurchases
+        : undefined;
+}
+/**
+ * The verifier and Server API client for one environment: the configured
+ * pair for the deployment's own environment, the sandbox policy's pair for
+ * the sandbox of a production deployment that opted in, and no verifier
+ * otherwise. The only place a sandbox port is selected.
+ */
+function resolveEnvironmentPorts(options, environment) {
+    if (environment === options.environment) {
+        return {
+            signedTransactionVerifier: options.signedTransactionVerifier,
+            serverApi: options.serverApi,
+        };
+    }
+    const sandbox = environment === 'Sandbox' ? readSandboxGrantPolicy(options) : undefined;
+    return sandbox === undefined
+        ? { serverApi: options.serverApi }
+        : {
+            signedTransactionVerifier: sandbox.signedTransactionVerifier,
+            serverApi: sandbox.serverApi ?? options.serverApi,
+        };
+}
+/**
+ * Whether the production verifier placed a JWS in the sandbox: Apple's
+ * adapter refuses it with `APP_STORE_ENVIRONMENT_MISMATCH` after the
+ * signature check, and a custom verifier may return the decoded `Sandbox`
+ * payload. Either way it is verified again by the sandbox verifier before
+ * anything is read from it.
+ */
+function isSandboxSignal(result) {
+    return result.status === 'verified'
+        ? result.payload.environment === 'Sandbox'
+        : result.reason === 'APP_STORE_ENVIRONMENT_MISMATCH';
+}
+async function fetchTransactionInfo(input, options, environment) {
+    const { serverApi } = resolveEnvironmentPorts(options, environment);
+    let transactionResult;
+    try {
+        transactionResult = await serverApi.getTransactionInfo({
+            transactionId: input.request.platformTransactionId,
+            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' };
+    }
+    return transactionResult;
+}
+function assertSandboxPurchasePolicy(input, environment) {
+    if (input === undefined) {
+        return;
+    }
+    assertRecord(input, 'sandboxPurchases');
+    if (input.mode === 'reject') {
+        return;
+    }
+    if (input.mode !== 'grant') {
+        throw new Error('sandboxPurchases.mode must be reject or grant.');
+    }
+    if (environment !== 'Production') {
+        throw new Error('sandboxPurchases applies only to a Production verifier.');
+    }
+    assertRecord(input.signedTransactionVerifier, 'sandboxPurchases.signedTransactionVerifier');
+    if (typeof input.signedTransactionVerifier.verifyAndDecode !== 'function') {
+        throw new Error('sandboxPurchases.signedTransactionVerifier must verify sandbox JWS.');
+    }
+    if (input.serverApi !== undefined) {
+        assertRecord(input.serverApi, 'sandboxPurchases.serverApi');
+        if (typeof input.serverApi.getTransactionInfo !== 'function') {
+            throw new Error('sandboxPurchases.serverApi must implement getTransactionInfo.');
+        }
+    }
+}
 function assertSignedTransactionEvidencePolicy(input) {
     if (input === undefined) {
         return;
@@ -273,12 +382,16 @@ function assertSignedTransactionEvidencePolicy(input) {
     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) {
+async function verifySignedTransaction(signedTransaction, input, options, environment) {
+    const { signedTransactionVerifier: verifier } = resolveEnvironmentPorts(options, environment);
+    if (verifier === undefined) {
+        return { status: 'rejected', reason: 'APP_STORE_ENVIRONMENT_MISMATCH' };
+    }
     let signatureResult;
     try {
-        signatureResult = await options.signedTransactionVerifier.verifyAndDecode({
+        signatureResult = await verifier.verifyAndDecode({
             signedTransaction,
-            environment: options.environment,
+            environment,
             bundleId: options.bundleId,
             signal: input.signal,
         });
@@ -315,21 +428,35 @@ async function resolveExpectedAppAccountToken(input, options) {
         return { status: 'pending', reason: 'APP_STORE_ACCOUNT_BINDING_UNAVAILABLE' };
     }
 }
-function validateTransaction(input, transaction, options, expectedAccountToken, nowMs, clockSkewMs) {
+function validateTransaction(input, transaction, bundleId, environment, 
+/** Undefined skips the account binding check (a restore across players). */
+expectedAccountToken, nowMs, clockSkewMs) {
     if (transaction.transactionId !== input.request.platformTransactionId) {
         return 'APP_STORE_TRANSACTION_ID_MISMATCH';
     }
-    if (transaction.bundleId !== options.bundleId) {
+    if (transaction.bundleId !== bundleId) {
         return 'APP_STORE_BUNDLE_ID_MISMATCH';
     }
     if (transaction.productId !== input.platformProductId) {
         return 'APP_STORE_PRODUCT_ID_MISMATCH';
     }
-    if (transaction.environment !== options.environment) {
+    if (transaction.environment !== environment) {
         return 'APP_STORE_ENVIRONMENT_MISMATCH';
     }
-    if (transaction.appAccountToken === undefined
-        || normalizeAppAccountToken(transaction.appAccountToken) !== expectedAccountToken) {
+    if (transaction.inAppOwnershipType === 'FAMILY_SHARED') {
+        // A family member's access to the organizer's non-consumable: it carries
+        // no app account token of this player, and refusing it explicitly keeps
+        // one purchase from granting several players. Leave Family Sharing off
+        // for the game's In-App Purchases in App Store Connect.
+        return 'APP_STORE_FAMILY_SHARED_UNSUPPORTED';
+    }
+    if (transaction.inAppOwnershipType !== undefined
+        && transaction.inAppOwnershipType !== 'PURCHASED') {
+        return 'APP_STORE_OWNERSHIP_UNSUPPORTED';
+    }
+    if (expectedAccountToken !== undefined
+        && (transaction.appAccountToken === undefined
+            || normalizeAppAccountToken(transaction.appAccountToken) !== expectedAccountToken)) {
         return 'APP_STORE_ACCOUNT_TOKEN_MISMATCH';
     }
     if (toCatalogProductType(transaction.type) !== input.product.type) {
@@ -467,6 +594,9 @@ export function assertAppStoreTransactionPayload(input) {
     assertOptionalNonNegativeSafeInteger(input.expiresDate, 'expiresDate');
     assertOptionalNonNegativeSafeInteger(input.revocationDate, 'revocationDate');
     assertOptionalBoolean(input.isUpgraded, 'isUpgraded');
+    if (input.inAppOwnershipType !== undefined) {
+        assertNonEmptyString(input.inAppOwnershipType, 'inAppOwnershipType');
+    }
     return input;
 }
 async function readBoundedJson(response, maxResponseBytes, signal) {

package/dist/commerce-ledger.d.ts

@@ -52,6 +52,61 @@ export type RevokeEntitlementGrantResult = {
 * authority identity reused for another grant is a conflict, not a success.
 */
 export declare function revokeEntitlementGrant(store: GameServicesStore, input: EntitlementLedgerRevocation): Promise<RevokeEntitlementGrantResult>;
+/**
+* The purchase grant a provider verification id names (the
+* `evidenceVerificationId` the purchase verifier recorded), through the
+* store's index when it has one. Store notification handlers start here:
+* a refund names the store's transaction, never a ledger entry.
+*/
+export declare function findPurchaseGrantByEvidenceVerificationId(store: GameServicesStore, evidenceVerificationId: string): Promise<ProductGrantTransaction | undefined>;
+/** Longest run of holder slots one purchase may have; more is a ledger error. */
+export declare const maxPurchaseHolderSlots = 10000;
+/**
+* Every grant of one purchase (RFC "Restore sharing"): `first`, the grant its
+* store verification id names, and `shared`, the grants verified restores
+* wrote for other players, in slot order. A share is written at `nextSlot`,
+* one past the highest slot read, so two concurrent writers that read the
+* same holders collide on one evidence id and the holder cap holds. Slots
+* can have gaps (the retention purge deletes a deleted player's record after
+* its period); a store with `findEntitlementTransactionsByEvidencePrefix`
+* lists them in one indexed read, gaps included.
+*/
+export interface PurchaseHolders {
+  readonly first?: ProductGrantTransaction;
+  readonly shared: readonly ProductGrantTransaction[];
+  readonly nextSlot: number;
+}
+export declare function listPurchaseHolders(store: GameServicesStore, purchaseVerificationId: string): Promise<PurchaseHolders>;
+/**
+* The evidence id of a purchase's `slot`-th shared grant (1 for the first
+* share): unique per slot, so a slot is written once. It starts with the
+* purchase's verification id, so a store lists a purchase's shares with one
+* indexed prefix read.
+*/
+export declare function createPurchaseHolderEvidenceVerificationId(purchaseVerificationId: string, slot: number): string;
+/**
+* The store verification id of the purchase a grant records: the purchase's
+* own id for a shared grant (whose ledger evidence id names its slot),
+* otherwise the grant's evidence id. Finalizers (a Play acknowledge) and
+* refunds are keyed by it.
+*/
+export declare function readPurchaseVerificationId(transaction: ProductGrantTransaction): string | undefined;
+/**
+* Whether a verified restore across players wrote this grant: a shared
+* grant, or a purchase's first grant written for a player the store did not
+* bind it to (`restoredAcrossAccounts`).
+*/
+export declare function isRestoredAcrossPlayers(transaction: ProductGrantTransaction): boolean;
+/** The revoke reasons a store event writes: they end the purchase for every holder. */
+export declare const purchaseWideRevocationReasons: ReadonlySet<string>;
+/**
+* The store event (refund, chargeback, voided purchase) that ended a
+* purchase, read from its holders' revoke entries, the first grant's first;
+* undefined while the purchase is live. An `admin` entry ends one holder only.
+*/
+export declare function findPurchaseWideRevocation(store: GameServicesStore, holders: readonly ProductGrantTransaction[]): Promise<EntitlementRevocationTransaction | undefined>;
+/** The evidence id of the entry that reverses `holder` for a store event whose own id is `eventId`. */
+export declare function holderRevocationEvidenceId(eventId: string, holder: ProductGrantTransaction): string;
 /** Whether a grant was reversed by a `revoke` entry; false on a store without revocations. */
 export declare function isEntitlementGrantReversed(store: GameServicesStore, ledgerEntryId: string): Promise<boolean>;
 /**

package/dist/commerce-ledger.js

@@ -109,6 +109,21 @@ export async function revokeEntitlementGrant(store, input) {
     }
     try {
         const result = await store.recordEntitlementRevocation(revocation);
+        if (grant.source === 'purchase' && purchaseWideRevocationReasons.has(revocation.reason)) {
+            // A store event (refund, chargeback, voided purchase) is about the
+            // purchase: every player a verified restore shared it with loses it
+            // too (RFC "Restore sharing"). Replays finish a fan-out an earlier
+            // attempt left part-way. An admin entry stays on the grant it names.
+            try {
+                await revokeOtherPurchaseHolders(store, grant, revocation);
+            }
+            catch (error) {
+                // The named grant is reversed; the other holders are not yet. A plain
+                // error makes the store event's handler retry (a redelivery or the
+                // next sweep), never report the event settled as a conflict.
+                throw new Error('Revoking the other holders of the purchase failed.', { cause: error });
+            }
+        }
         return {
             status: 'revoked',
             ledgerEntryId: result.ledgerEntryId,
@@ -125,6 +140,189 @@ export async function revokeEntitlementGrant(store, input) {
         throw error;
     }
 }
+/**
+ * The purchase grant a provider verification id names (the
+ * `evidenceVerificationId` the purchase verifier recorded), through the
+ * store's index when it has one. Store notification handlers start here:
+ * a refund names the store's transaction, never a ledger entry.
+ */
+export async function findPurchaseGrantByEvidenceVerificationId(store, evidenceVerificationId) {
+    const grant = await findPurchaseGrantRecord(store, evidenceVerificationId);
+    if (grant !== undefined || store.findEntitlementTransactionsByEvidencePrefix === undefined) {
+        return grant;
+    }
+    // The first grant can be gone (the retention purge deleted a deleted
+    // player's record) while restore sharing's shares of the purchase remain:
+    // a store event then reaches them through one of those (RFC "Restore
+    // sharing"), and a refund's fan-out through it reaches the rest.
+    return (await listPurchaseHolders(store, evidenceVerificationId)).shared[0];
+}
+async function findPurchaseGrantRecord(store, evidenceVerificationId) {
+    const grant = store.findEntitlementTransactionByEvidenceVerificationId === undefined
+        ? (await store.listEntitlementTransactions()).find((transaction) => {
+            return transaction.source === 'purchase'
+                && (transaction.evidenceVerificationId
+                    ?? transaction.payload.evidenceVerificationId) === evidenceVerificationId;
+        })
+        : await store.findEntitlementTransactionByEvidenceVerificationId({
+            source: 'purchase',
+            evidenceVerificationId,
+        });
+    return grant?.source === 'purchase' ? grant : undefined;
+}
+/** Longest run of holder slots one purchase may have; more is a ledger error. */
+export const maxPurchaseHolderSlots = 10_000;
+export async function listPurchaseHolders(store, purchaseVerificationId) {
+    // Shares first, the first grant after: a share written after this read
+    // takes the slot this caller would take (and collides), and a first grant
+    // written meanwhile is seen, so a writer's holder count is exact.
+    const holderPrefix = purchaseHolderEvidencePrefix(purchaseVerificationId);
+    const listByPrefix = store.findEntitlementTransactionsByEvidencePrefix;
+    const shared = [];
+    if (listByPrefix !== undefined) {
+        const found = await listByPrefix.call(store, {
+            source: 'purchase',
+            prefix: holderPrefix,
+            limit: maxPurchaseHolderSlots + 1,
+        });
+        if (found.length > maxPurchaseHolderSlots) {
+            throw new Error('A purchase has more holder slots than maxPurchaseHolderSlots.');
+        }
+        for (const grant of found) {
+            const slot = readPurchaseHolderSlot(grant.evidenceVerificationId, holderPrefix);
+            if (grant.source === 'purchase' && slot !== undefined) {
+                shared.push({ slot, grant });
+            }
+        }
+    }
+    else {
+        // Without the indexed read, slots are read one by one up to the first
+        // free one: correct while no slot is purged (the retention purge runs
+        // only on stores that implement the indexed read).
+        for (let slot = 1; slot <= maxPurchaseHolderSlots + 1; slot += 1) {
+            if (slot > maxPurchaseHolderSlots) {
+                throw new Error('A purchase has more holder slots than maxPurchaseHolderSlots.');
+            }
+            const grant = await findPurchaseGrantRecord(store, createPurchaseHolderEvidenceVerificationId(purchaseVerificationId, slot));
+            if (grant === undefined) {
+                break;
+            }
+            shared.push({ slot, grant });
+        }
+    }
+    shared.sort((left, right) => left.slot - right.slot);
+    const first = await findPurchaseGrantRecord(store, purchaseVerificationId);
+    return {
+        ...(first === undefined ? {} : { first }),
+        shared: shared.map((entry) => entry.grant),
+        nextSlot: (shared.at(-1)?.slot ?? 0) + 1,
+    };
+}
+function purchaseHolderEvidencePrefix(purchaseVerificationId) {
+    return `${purchaseVerificationId}#mpgd-holder:`;
+}
+function readPurchaseHolderSlot(evidenceVerificationId, prefix) {
+    if (evidenceVerificationId === undefined || !evidenceVerificationId.startsWith(prefix)) {
+        return undefined;
+    }
+    const text = evidenceVerificationId.slice(prefix.length);
+    return /^[1-9][0-9]{0,8}$/u.test(text) ? Number(text) : undefined;
+}
+/**
+ * The evidence id of a purchase's `slot`-th shared grant (1 for the first
+ * share): unique per slot, so a slot is written once. It starts with the
+ * purchase's verification id, so a store lists a purchase's shares with one
+ * indexed prefix read.
+ */
+export function createPurchaseHolderEvidenceVerificationId(purchaseVerificationId, slot) {
+    if (!Number.isSafeInteger(slot) || slot < 1 || slot > 999_999_999) {
+        throw new RangeError('A holder slot is a positive integer.');
+    }
+    return `${purchaseHolderEvidencePrefix(purchaseVerificationId)}${String(slot)}`;
+}
+/**
+ * The store verification id of the purchase a grant records: the purchase's
+ * own id for a shared grant (whose ledger evidence id names its slot),
+ * otherwise the grant's evidence id. Finalizers (a Play acknowledge) and
+ * refunds are keyed by it.
+ */
+export function readPurchaseVerificationId(transaction) {
+    const shared = transaction.payload.holderOfEvidenceVerificationId;
+    if (typeof shared === 'string' && shared.length > 0) {
+        return shared;
+    }
+    const recorded = transaction.evidenceVerificationId ?? transaction.payload.evidenceVerificationId;
+    return typeof recorded === 'string' && recorded.length > 0 ? recorded : undefined;
+}
+/**
+ * Whether a verified restore across players wrote this grant: a shared
+ * grant, or a purchase's first grant written for a player the store did not
+ * bind it to (`restoredAcrossAccounts`).
+ */
+export function isRestoredAcrossPlayers(transaction) {
+    const shared = transaction.payload.holderOfEvidenceVerificationId;
+    return (typeof shared === 'string' && shared.length > 0)
+        || transaction.payload.restoredAcrossAccounts === true;
+}
+/** The revoke reasons a store event writes: they end the purchase for every holder. */
+export const purchaseWideRevocationReasons = new Set([
+    'refund',
+    'chargeback',
+    'voided',
+]);
+/**
+ * The store event (refund, chargeback, voided purchase) that ended a
+ * purchase, read from its holders' revoke entries, the first grant's first;
+ * undefined while the purchase is live. An `admin` entry ends one holder only.
+ */
+export async function findPurchaseWideRevocation(store, holders) {
+    const order = new Map(holders.map((holder, index) => [holder.ledgerEntryId, index]));
+    return (await findEntitlementRevocationsChunked(store, holders.map((holder) => holder.ledgerEntryId)))
+        .filter((entry) => purchaseWideRevocationReasons.has(entry.reason))
+        .sort((left, right) => (order.get(left.revokesLedgerEntryId) ?? 0) - (order.get(right.revokesLedgerEntryId) ?? 0))[0];
+}
+/** The evidence id of the entry that reverses `holder` for a store event whose own id is `eventId`. */
+export function holderRevocationEvidenceId(eventId, holder) {
+    return `${eventId}#${holder.evidenceVerificationId ?? holder.ledgerEntryId}`;
+}
+async function revokeOtherPurchaseHolders(store, named, revocation) {
+    const purchaseVerificationId = readPurchaseVerificationId(named);
+    const record = store.recordEntitlementRevocation;
+    if (purchaseVerificationId === undefined || record === undefined) {
+        return;
+    }
+    // Read the holders again after each pass: a restore that wrote a share
+    // while this pass ran either sees an entry this pass wrote (and revokes
+    // itself) or is found by the next read. A pass that writes nothing ends.
+    for (let pass = 0; pass < 10; pass += 1) {
+        const holders = await listPurchaseHolders(store, purchaseVerificationId);
+        const others = [...(holders.first === undefined ? [] : [holders.first]), ...holders.shared]
+            .filter((holder) => holder.ledgerEntryId !== named.ledgerEntryId);
+        const reversed = new Set((await findEntitlementRevocationsChunked(store, others.map((holder) => holder.ledgerEntryId)))
+            .map((entry) => entry.revokesLedgerEntryId));
+        const active = others.filter((holder) => !reversed.has(holder.ledgerEntryId));
+        if (active.length === 0) {
+            return;
+        }
+        for (const holder of active) {
+            await record.call(store, {
+                ...revocation,
+                playerId: holder.playerId,
+                revokesLedgerEntryId: holder.ledgerEntryId,
+                // The store event's own identity names one entry; each holder's is
+                // derived from it and the holder's evidence id (never its ledger id,
+                // which embeds the player id account deletion detaches), so a replay
+                // finds the same entries.
+                ...(revocation.evidenceVerificationId === undefined
+                    ? {}
+                    : {
+                        evidenceVerificationId: holderRevocationEvidenceId(revocation.evidenceVerificationId, holder),
+                    }),
+            });
+        }
+    }
+    throw new Error('The purchase kept gaining holders while its refund was applied.');
+}
 /** Whether a grant was reversed by a `revoke` entry; false on a store without revocations. */
 export async function isEntitlementGrantReversed(store, ledgerEntryId) {
     const revocations = await findEntitlementRevocationsChunked(store, [ledgerEntryId]);

package/dist/commerce-reconciler.js

@@ -497,6 +497,11 @@ export function createCommerceReconciler(input) {
             idempotencyKey: record.idempotencyKey,
             purchasedAt: purchase.purchasedAt ?? now(),
             evidence: purchase.evidence,
+            // A purchase the store reported without this journal starting it (a
+            // reinstall, a new device, Restore Purchases) is a restore: the backend
+            // may grant this player a non-consumable bound to another guest (RFC
+            // "Restore sharing"). A purchase the game started never asks for it.
+            ...(record.origin === 'discovered' ? { intent: 'restore' } : {}),
         };
     };
     // Reconciler step 2: match a reported purchase to a journal record.

package/dist/evidence-verification.d.ts

@@ -24,6 +24,25 @@ export type EvidenceVerificationDecision = {
   readonly ledgerEntryId: string;
   /** The ledger target the entry was written under when it is not the request's target. */
   readonly ledgerTarget?: string;
+} | {
+  /**
+  * The store verified a restored non-consumable, but its account
+  * binding (Google Play `obfuscatedAccountId` / `obfuscatedProfileId`,
+  * StoreKit `appAccountToken`) names another account than the
+  * requesting player's, or none: the player reinstalled or moved to a
+  * new device and is a new guest (RFC "Restore sharing"). Every other
+  * check passed. The reference verifiers answer it only for a request
+  * with `intent: 'restore'` of a non-consumable; the backend then grants
+  * the player its own share under its `restoreSharing` policy, or
+  * answers `rejected` with `reason` (the binding mismatch) when the
+  * policy refuses. Fields are those of `verified`.
+  */
+  readonly status: 'restorable';
+  readonly reason: string;
+  readonly verificationId: string;
+  readonly verifiedAt: string;
+  readonly payload?: EntitlementLedgerPayload;
+  readonly platformEvidenceId?: string | null;
 } | {
   readonly status: 'pending';
   readonly reason?: string;

package/dist/google-play-publisher-client.d.ts

@@ -1,4 +1,5 @@
 import type { GooglePlayProductPurchaseClient } from './google-play-purchase.js';
+import type { GooglePlayVoidedPurchasesClient } from './google-play-store-server.js';
 export interface GooglePlayPublisherClientOptions {
   /** Supplies an androidpublisher-scoped OAuth access token for each request. */
   readonly getAccessToken: (signal: AbortSignal) => Promise<string> | string;
@@ -8,4 +9,4 @@ export interface GooglePlayPublisherClientOptions {
 * Google Play purchase verification and post-ledger finalization transport.
 * The caller owns OAuth credential rotation and must never expose this client to the game.
 */
-export declare function createGooglePlayPublisherClient(options: GooglePlayPublisherClientOptions): GooglePlayProductPurchaseClient;
+export declare function createGooglePlayPublisherClient(options: GooglePlayPublisherClientOptions): GooglePlayProductPurchaseClient & GooglePlayVoidedPurchasesClient;