[phase-3] fix adversarial-pass P1: refunded/revoked are terminal — refund wins regardless of order

The blanket upsert set status unconditionally, so an out-of-order
DID_RENEW — or the client's legitimate post-refund /verify report from
the Transaction.updates listener — flipped a refunded lineage back to
active. Now:
- upsert_entitlement: terminal statuses are sticky in the ON CONFLICT
  clause (dates may refresh; status can never be lifted).
- set_status: refuses to leave a terminal state (returns False + WARNING)
  unless the explicit allow_terminal_override — a deliberate,
  human-reviewed reversal — is passed.
- REFUND_REVERSED is acknowledged and logged for manual review, never
  auto-reactivated (a replayed reversal after a second refund must not
  re-entitle).
- 4 new ordering tests lock both attack vectors end to end.

Suite: 582 passed.

Author: Neo

gateway/server.py

@@ -1032,6 +1032,15 @@ async def handle_iap_asn(self, request: web.Request) -> web.Response:
                 await self._entitlements.set_status(original_id, "revoked")
                 await self._entitlements.mark_transaction(
                     tx["transaction_id"], "revoked")
+            elif notification_type == "REFUND_REVERSED":
+                # Deliberately NOT auto-reactivated: terminal states are
+                # sticky (a replayed reversal after a second refund must not
+                # re-entitle). Rare enough to be a human decision — the
+                # operator flips it with set_status(allow_terminal_override).
+                logger.warning(
+                    "iap asn: REFUND_REVERSED for lineage %s — terminal "
+                    "state kept; manual review required to reactivate.",
+                    original_id)
             else:
                 logger.info("iap asn: %s acknowledged without a state flip",
                             notification_type or "<missing type>")

runtime/monetization/entitlement_store.py

@@ -12,6 +12,15 @@
   flips the row to ``refunded``, revoke to ``revoked``, expiry to
   ``expired``; a renewal writes the fresh ``expires_date`` back to ``active``.
 
+``refunded``/``revoked`` are TERMINAL: Apple delivers notifications with no
+ordering guarantee, and after a refund the client still (correctly) reports
+the next renewal JWS to /iap/verify — so the blanket upsert refuses to lift a
+terminal status, and ``set_status`` refuses to leave one without an explicit
+``allow_terminal_override``. Refund wins regardless of arrival order.
+(A rare REFUND_REVERSED is deliberately NOT auto-reactivated — the ASN
+handler logs it for manual review; fail-closed means toward less
+entitlement, never more.)
+
 This is the server-side entitlement PRIMITIVE — a queryable fact table.
 Nothing here gates existing routes; adopting it as a gate is a later,
 deliberate decision. Writes happen only from routes that verified the JWS
@@ -58,6 +67,9 @@
 #: statuses an entitlement row can hold.
 STATUSES = ("active", "expired", "refunded", "revoked")
 
+#: terminal statuses — once set, only an explicit override can leave them.
+TERMINAL_STATUSES = ("refunded", "revoked")
+
 
 class EntitlementStore:
     """CRUD over verified-IAP tables. Reads are fail-safe (empty on DB
@@ -145,7 +157,10 @@ async def upsert_entitlement(
         environment: str = "",
     ) -> None:
         """Create/refresh a subscription lineage row. A blank ``user_key``
-        never overwrites a known one (webhooks carry no session)."""
+        never overwrites a known one (webhooks carry no session), and a
+        TERMINAL status (refunded/revoked) is sticky: a late-arriving renewal
+        or a post-refund client /verify report can update dates but can NEVER
+        lift the row back to active. Refund wins regardless of order."""
         await self._ensure_tables()
         if not original_transaction_id:
             raise ValueError("original_transaction_id required")
@@ -163,7 +178,9 @@ async def upsert_entitlement(
                                 ELSE iap_entitlements.user_key END,
                 product_id = excluded.product_id,
                 tier = excluded.tier,
-                status = excluded.status,
+                status = CASE WHEN iap_entitlements.status IN ('refunded', 'revoked')
+                              THEN iap_entitlements.status
+                              ELSE excluded.status END,
                 purchase_date = excluded.purchase_date,
                 expires_date = excluded.expires_date,
                 environment = excluded.environment,
@@ -174,17 +191,29 @@ async def upsert_entitlement(
         )
 
     async def set_status(self, original_transaction_id: str, status: str,
-                         *, expires_date: float | None = None) -> bool:
-        """Flip an entitlement row's status (ASN: refund/revoke/expire/renew).
-        Returns False when no such lineage exists."""
+                         *, expires_date: float | None = None,
+                         allow_terminal_override: bool = False) -> bool:
+        """Flip an entitlement row's status (ASN: refund/revoke/expire).
+        Returns False when no such lineage exists — or when the row sits in a
+        TERMINAL state (refunded/revoked) and the new status would leave it;
+        only an explicit ``allow_terminal_override=True`` (a deliberate,
+        human-reviewed reversal) may do that."""
         await self._ensure_tables()
         if status not in STATUSES:
             raise ValueError(f"invalid status {status!r}")
         rows = await self._db.fetchall(
-            "SELECT 1 FROM iap_entitlements WHERE original_transaction_id = ?",
+            "SELECT status FROM iap_entitlements WHERE original_transaction_id = ?",
             (original_transaction_id,))
         if not rows:
             return False
+        current = str(rows[0]["status"] if not isinstance(rows[0], tuple)
+                      else rows[0][0])
+        if current in TERMINAL_STATUSES and status not in TERMINAL_STATUSES \
+                and not allow_terminal_override:
+            logger.warning(
+                "iap: refused %s -> %s for lineage %s (terminal state is sticky)",
+                current, status, original_transaction_id)
+            return False
         if expires_date is None:
             await self._db.execute(
                 "UPDATE iap_entitlements SET status = ?, updated_at = ? "

tests/test_iap_verify.py

@@ -299,6 +299,39 @@ async def test_blank_user_key_never_unbinds(self, store):
     async def test_unknown_lineage_flip_returns_false(self, store):
         assert await store.set_status("missing", "refunded") is False
 
+    @pytest.mark.asyncio
+    async def test_refund_is_terminal_against_late_upsert(self, store):
+        """Adversarial-pass P1: a renewal upsert arriving AFTER a refund
+        (out-of-order ASN, or the client's post-refund /verify report) must
+        NOT re-activate the lineage. Refund wins regardless of order."""
+        now = time.time()
+        await store.upsert_entitlement(
+            original_transaction_id="o1", product_id=PRO, tier="pro",
+            user_key="apple:victim", expires_date=now + 86400)
+        await store.set_status("o1", "refunded")
+        # The late renewal: blanket upsert with status='active' + fresh expiry.
+        await store.upsert_entitlement(
+            original_transaction_id="o1", product_id=PRO, tier="pro",
+            status="active", expires_date=now + 30 * 86400)
+        assert (await store.entitlement("o1"))["status"] == "refunded"
+        assert await store.active_tier_for("apple:victim") is None
+
+    @pytest.mark.asyncio
+    async def test_terminal_sticky_in_set_status(self, store):
+        now = time.time()
+        await store.upsert_entitlement(
+            original_transaction_id="o1", product_id=PRO, tier="pro",
+            user_key="apple:u1", expires_date=now + 86400)
+        await store.set_status("o1", "revoked")
+        # A later EXPIRED (or anything non-terminal) cannot soften revoked...
+        assert await store.set_status("o1", "expired") is False
+        assert await store.set_status("o1", "active") is False
+        assert (await store.entitlement("o1"))["status"] == "revoked"
+        # ...but a deliberate, human-reviewed override can.
+        assert await store.set_status(
+            "o1", "active", allow_terminal_override=True) is True
+        assert (await store.entitlement("o1"))["status"] == "active"
+
 
 # ── Routes ──────────────────────────────────────────────────────────
 
@@ -430,6 +463,44 @@ async def test_asn_expired_flips(self, iap_client, chain):
         ent = await iap_client._iap_store.entitlement("1000000000000001")
         assert ent["status"] == "expired"
 
+    @pytest.mark.asyncio
+    async def test_refund_then_renew_stays_refunded(self, iap_client, chain):
+        """End-to-end lock on the adversarial-pass P1: REFUND, then an
+        out-of-order DID_RENEW, then a post-refund client /verify report —
+        the lineage must stay refunded through all three."""
+        await iap_client.post("/api/v1/iap/verify",
+                              json={"signedTransaction": chain.sign(_tx_payload())})
+        r = await iap_client.post(
+            "/api/v1/iap/asn", json=_asn(chain, "REFUND", _tx_payload()))
+        assert r.status == 200
+        # Vector 1: stale DID_RENEW delivered after the refund.
+        renewed = _tx_payload(
+            transactionId="t-late-renew",
+            expiresDate=int(time.time() * 1000) + 60 * 86400 * 1000)
+        r = await iap_client.post(
+            "/api/v1/iap/asn", json=_asn(chain, "DID_RENEW", renewed))
+        assert r.status == 200
+        ent = await iap_client._iap_store.entitlement("1000000000000001")
+        assert ent["status"] == "refunded"
+        # Vector 2: the client's updates listener reports the renewal JWS.
+        r = await iap_client.post(
+            "/api/v1/iap/verify", json={"signedTransaction": chain.sign(renewed)})
+        assert r.status == 200
+        ent = await iap_client._iap_store.entitlement("1000000000000001")
+        assert ent["status"] == "refunded"
+
+    @pytest.mark.asyncio
+    async def test_asn_refund_reversed_does_not_reactivate(self, iap_client, chain):
+        await iap_client.post("/api/v1/iap/verify",
+                              json={"signedTransaction": chain.sign(_tx_payload())})
+        await iap_client.post(
+            "/api/v1/iap/asn", json=_asn(chain, "REFUND", _tx_payload()))
+        r = await iap_client.post(
+            "/api/v1/iap/asn", json=_asn(chain, "REFUND_REVERSED", _tx_payload()))
+        assert r.status == 200  # acknowledged, logged for manual review
+        ent = await iap_client._iap_store.entitlement("1000000000000001")
+        assert ent["status"] == "refunded"
+
     @pytest.mark.asyncio
     async def test_asn_spoof_untrusted_chain_401(self, iap_client):
         spoofer = Chain()  # NOT in the trusted roots