@mpgd/capacitor-storekit 0.1.1 → 0.1.3

package/README.md

@@ -25,6 +25,19 @@ bundle, product, environment and account binding before the ledger grant.
 The recovery helper calls native `finishTransaction` only after a
 verified response with a ledger entry ID. If finish fails, it reports
 `finishPending: true`; repeat recovery with the original purchase identity.
+`provider.finishGrantedTransaction` accepts only a transaction and ledger
+entry pair that `recoverStoreKitPurchases` recorded from a backend answer in
+the current session. The pair is consumed before the native call, so
+overlapping finishes (for example startup recovery and a `transactionUpdated`
+recovery) share one native call, and a failed native finish restores the pair
+for a retry. Calling it, or the native `finishTransaction` plugin method, with
+any other value is rejected so an unfinished purchase keeps its recovery
+signal. This guard prevents arbitrary or accidental finish calls with
+unverified ledger IDs and binds finishing to the recovery flow; it is **not**
+a trust boundary against code that controls the `backend` object it passes to
+`recoverStoreKitPurchases`. The real control is server-side: the authenticated
+`recoverPurchase` implementation must verify Apple evidence before it grants,
+and finishing a transaction never grants anything by itself.
 An unknown backend result stays pending and never triggers a
 new purchase sheet automatically.
 

package/dist/definitions.d.ts

@@ -42,7 +42,16 @@ export interface CapacitorStoreKitPlugin {
   sync(): Promise<{
     readonly synced: boolean;
   }>;
-  /** Call only after the authenticated backend confirms the ledger grant. */
+  /**
+  * Call only after the authenticated backend confirms the ledger grant.
+  * Native validation is intentionally shallow and finishing never grants
+  * anything. The TypeScript provider's finishGrantedTransaction binds this
+  * call to the recoverStoreKitPurchases flow so games cannot finish a
+  * purchase accidentally or with an arbitrary ledger ID; games must not call
+  * this plugin method directly. That binding is not a trust boundary against
+  * code that controls the recovery backend object: the authenticated
+  * server-side recoverPurchase verification is the real control.
+  */
   finishTransaction(input: {
     readonly transactionId: string;
     readonly ledgerEntryId: string;

package/dist/provider.d.ts

@@ -47,6 +47,19 @@ export interface CapacitorStoreKitProvider {
   }>>;
   getAppAccountToken(): Promise<string>;
   getRecoverableTransactions(): Promise<StoreKitRecoverySnapshot>;
+  /**
+  * Finish a transaction the backend already granted. The provider accepts
+  * only a transaction and ledger entry pair that recoverStoreKitPurchases
+  * recorded from a backend answer in this session, and consumes the pair
+  * before the native call so overlapping finishes share one native call;
+  * any other pair is rejected so an unfinished purchase keeps its recovery
+  * signal. A failed native finish restores the pair for a retry.
+  *
+  * The guard prevents arbitrary or accidental finish calls with unverified
+  * ledger IDs. It is not a trust boundary against code that controls the
+  * backend object given to recoverStoreKitPurchases; the authenticated
+  * server-side recoverPurchase implementation is the real control.
+  */
   finishGrantedTransaction(input: {
     readonly transactionId: string;
     readonly ledgerEntryId: string;

package/dist/provider.js

@@ -3,6 +3,20 @@ import { CapacitorStoreKit } from './plugin.js';
 const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const productPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 const transactionPattern = /^[1-9][0-9]{0,19}$/u;
+/**
+ * Grants recorded by recoverStoreKitPurchases per provider instance:
+ * transaction ID to the ledger entry ID the recovery backend returned. The map
+ * binds finishGrantedTransaction to that recovery flow so a game cannot finish
+ * an unfinished purchase by accident, or with an arbitrary ledger string, and
+ * so each recorded pair reaches the native finish call at most once.
+ *
+ * This is not a trust boundary against a caller who controls the backend
+ * object passed to recoverStoreKitPurchases: such a caller can record any
+ * pair. The real control stays server-side, in the authenticated
+ * recoverPurchase implementation that verifies Apple evidence before it
+ * grants, and in the native plugin never granting anything on finish.
+ */
+const verifiedGrants = new WeakMap();
 /** Submit unfinished purchases to the backend before asking StoreKit to finish. */
 export async function recoverStoreKitPurchases(input) {
     if (input.playerId.trim() === '') {
@@ -43,6 +57,7 @@ export async function recoverStoreKitPurchases(input) {
             if (verification.ledgerEntryId === undefined || verification.ledgerEntryId.trim() === '') {
                 return { productId: item.productId, transactionId, status: 'pending', verification };
             }
+            verifiedGrants.get(input.provider)?.set(transactionId, verification.ledgerEntryId);
             try {
                 const finished = await input.provider.finishGrantedTransaction({
                     transactionId,
@@ -209,7 +224,23 @@ export function createCapacitorStoreKitProvider(options) {
             return failure(input.id, 'STOREKIT_UNAVAILABLE', true);
         }
     }
-    return {
+    const grants = new Map();
+    const inFlight = new Map();
+    async function finishReserved(transactionId, ledgerEntryId) {
+        let finished = false;
+        try {
+            finished = (await sdk.finishTransaction({ transactionId, ledgerEntryId })).finished;
+        }
+        finally {
+            // Restore the pair after a rejected or failed native finish so recovery
+            // can retry it, unless a newer recovery recorded the transaction again.
+            if (!finished && !grants.has(transactionId)) {
+                grants.set(transactionId, ledgerEntryId);
+            }
+        }
+        return finished;
+    }
+    const provider = {
         id: 'apple-storekit',
         features: ['nativeIap'],
         methods: [
@@ -247,10 +278,31 @@ export function createCapacitorStoreKitProvider(options) {
                 || input.ledgerEntryId.trim() === '') {
                 throw new TypeError('StoreKit finish requires a verified grant and transaction ID.');
             }
-            const response = await sdk.finishTransaction(input);
-            return response.finished;
+            const { transactionId, ledgerEntryId } = input;
+            const active = inFlight.get(transactionId);
+            if (active !== undefined && active.ledgerEntryId === ledgerEntryId) {
+                return active.promise;
+            }
+            if (grants.get(transactionId) !== ledgerEntryId) {
+                throw new TypeError('StoreKit finish requires the ledger entry the backend returned for this transaction via recoverStoreKitPurchases.');
+            }
+            // Consume the pair synchronously, before the first await, so an
+            // overlapping finish for the same transaction cannot reach native twice.
+            grants.delete(transactionId);
+            const promise = finishReserved(transactionId, ledgerEntryId);
+            inFlight.set(transactionId, { ledgerEntryId, promise });
+            try {
+                return await promise;
+            }
+            finally {
+                if (inFlight.get(transactionId)?.promise === promise) {
+                    inFlight.delete(transactionId);
+                }
+            }
         },
     };
+    verifiedGrants.set(provider, grants);
+    return provider;
 }
 function convertOutcome(outcome, mapping, expectedAccountToken) {
     if (outcome.status !== 'purchased') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-storekit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Opt-in StoreKit 2 one-time purchase collector for mpgd Capacitor games.",
   "license": "MIT",
   "repository": {
@@ -45,10 +45,10 @@
     "@capacitor/core": "8.5.2",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-capacitor": "0.6.0",
+    "@mpgd/adapter-capacitor": "0.6.2",
     "@mpgd/bridge": "0.10.0",
-    "@mpgd/game-services": "0.17.0",
-    "@mpgd/platform": "0.14.0"
+    "@mpgd/platform": "0.14.0",
+    "@mpgd/game-services": "0.17.2"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",