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/routes/api/admin.py

@@ -157,7 +157,9 @@ def delete_program(
 ):
     """Delete a loyalty program (admin override)."""
     program_service.delete_program(db, program_id)
-    logger.info(f"Admin deleted loyalty program {program_id}")
+    logger.info(
+        f"Admin {current_user.id} ({current_user.email}) deleted loyalty program {program_id}"
+    )
 
 
 @router.post("/programs/{program_id}/activate", response_model=ProgramResponse)
@@ -236,13 +238,20 @@ def update_merchant_settings(
     settings = program_service.get_or_create_merchant_settings(db, merchant_id)
 
     update_data = data.model_dump(exclude_unset=True)
+
+    # Capture old values before overwrite for audit trail
+    old_values = {field: getattr(settings, field) for field in update_data}
+
     for field, value in update_data.items():
         setattr(settings, field, value)
 
     db.commit()
     db.refresh(settings)
 
-    logger.info(f"Updated merchant {merchant_id} loyalty settings: {list(update_data.keys())}")
+    logger.info(
+        f"Admin {current_user.id} ({current_user.email}) updated merchant {merchant_id} "
+        f"loyalty settings: {list(update_data.keys())} (old: {old_values})"
+    )
 
     return MerchantSettingsResponse.model_validate(settings)
 

app/modules/loyalty/routes/api/store.py

@@ -244,6 +244,10 @@ def update_pin(
     db: Session = Depends(get_db),
 ):
     """Update a staff PIN."""
+    pin = pin_service.require_pin(db, pin_id)
+    if pin.store_id != current_user.token_store_id:
+        from app.modules.loyalty.exceptions import StaffPinNotFoundException
+        raise StaffPinNotFoundException(str(pin_id))
     pin = pin_service.update_pin(db, pin_id, data)
     return PinResponse.model_validate(pin)
 
@@ -255,6 +259,10 @@ def delete_pin(
     db: Session = Depends(get_db),
 ):
     """Delete a staff PIN."""
+    pin = pin_service.require_pin(db, pin_id)
+    if pin.store_id != current_user.token_store_id:
+        from app.modules.loyalty.exceptions import StaffPinNotFoundException
+        raise StaffPinNotFoundException(str(pin_id))
     pin_service.delete_pin(db, pin_id)
 
 
@@ -265,6 +273,10 @@ def unlock_pin(
     db: Session = Depends(get_db),
 ):
     """Unlock a locked staff PIN."""
+    pin = pin_service.require_pin(db, pin_id)
+    if pin.store_id != current_user.token_store_id:
+        from app.modules.loyalty.exceptions import StaffPinNotFoundException
+        raise StaffPinNotFoundException(str(pin_id))
     pin = pin_service.unlock_pin(db, pin_id)
     return PinResponse.model_validate(pin)
 
@@ -762,7 +774,10 @@ def adjust_points(
     current_user: User = Depends(get_current_store_api),
     db: Session = Depends(get_db),
 ):
-    """Manually adjust points (store operation)."""
+    """Manually adjust points (merchant_owner only)."""
+    if current_user.role != "merchant_owner":
+        raise AuthorizationException("Only merchant owners can adjust points")
+
     store_id = current_user.token_store_id
     ip, user_agent = get_client_info(request)
 

app/modules/loyalty/routes/api/storefront.py

@@ -24,6 +24,7 @@ from app.modules.loyalty.schemas import (
     CardResponse,
     ProgramResponse,
 )
+from app.modules.loyalty.schemas.program import StorefrontProgramResponse
 from app.modules.loyalty.services import card_service, program_service, wallet_service
 from app.modules.tenancy.exceptions import StoreNotFoundException
 from middleware.decorators import rate_limit
@@ -55,7 +56,7 @@ def get_program_info(
     if not program:
         return None
 
-    response = ProgramResponse.model_validate(program)
+    response = StorefrontProgramResponse.model_validate(program)
     response.is_stamps_enabled = program.is_stamps_enabled
     response.is_points_enabled = program.is_points_enabled
     response.display_name = program.display_name