feat(loyalty): production readiness round 2 — 12 security, integrity & correctness fixes

Security:
- Fix TOCTOU race conditions: move balance/limit checks after row lock in redeem_points, add_stamp, redeem_stamps
- Add PIN ownership verification to update/delete/unlock store routes
- Gate adjust_points endpoint to merchant_owner role only

Data integrity:
- Track total_points_voided in void_points
- Add order_reference idempotency guard in earn_points

Correctness:
- Fix LoyaltyProgramAlreadyExistsException to use merchant_id parameter
- Add StorefrontProgramResponse excluding wallet IDs from public API
- Add bounds (±100000) to PointsAdjustRequest.points_delta

Audit & config:
- Add CARD_REACTIVATED transaction type with audit record
- Improve admin audit logging with actor identity and old values
- Use merchant-specific PIN lockout settings with global fallback
- Guard MerchantLoyaltySettings creation with get_or_create pattern

Tests: 27 new tests (265 total) covering all 12 items — unit and integration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app/modules/loyalty/services/points_service.py

@@ -101,6 +101,31 @@ class PointsService:
         if settings and settings.require_order_reference and not order_reference:
             raise OrderReferenceRequiredException()
 
+        # Idempotency guard: if same order_reference already earned points on this card, return existing result
+        if order_reference:
+            existing_tx = (
+                db.query(LoyaltyTransaction)
+                .filter(
+                    LoyaltyTransaction.card_id == card.id,
+                    LoyaltyTransaction.order_reference == order_reference,
+                    LoyaltyTransaction.transaction_type == TransactionType.POINTS_EARNED.value,
+                )
+                .first()
+            )
+            if existing_tx:
+                return {
+                    "success": True,
+                    "message": "Points already earned for this order",
+                    "points_earned": existing_tx.points_delta,
+                    "points_per_euro": program.points_per_euro,
+                    "purchase_amount_cents": existing_tx.purchase_amount_cents or purchase_amount_cents,
+                    "card_id": card.id,
+                    "card_number": card.card_number,
+                    "points_balance": card.points_balance,
+                    "total_points_earned": card.total_points_earned,
+                    "store_id": existing_tx.store_id,
+                }
+
         # Check minimum purchase amount
         if program.minimum_purchase_cents > 0 and purchase_amount_cents < program.minimum_purchase_cents:
             return {
@@ -263,10 +288,6 @@ class PointsService:
         if points_required < program.minimum_redemption_points:
             raise InvalidRewardException(reward_id)
 
-        # Check if enough points
-        if card.points_balance < points_required:
-            raise InsufficientPointsException(card.points_balance, points_required)
-
         # Verify staff PIN if required
         verified_pin = None
         if program.require_staff_pin:
@@ -277,6 +298,10 @@ class PointsService:
         # Re-fetch with row lock to prevent concurrent modification
         card = card_service.get_card_for_update(db, card.id)
 
+        # Check balance AFTER acquiring lock to prevent TOCTOU race
+        if card.points_balance < points_required:
+            raise InsufficientPointsException(card.points_balance, points_required)
+
         # Redeem points
         now = datetime.now(UTC)
         card.points_balance -= points_required
@@ -432,6 +457,7 @@ class PointsService:
         now = datetime.now(UTC)
         actual_voided = min(points_to_void, card.points_balance)
         card.points_balance = max(0, card.points_balance - points_to_void)
+        card.total_points_voided += actual_voided
         card.last_activity_at = now
 
         # Create void transaction