feat(android-terminal): Phase C — PIN screen with offline bcrypt verify

Two-pane landscape: scrollable staff list on the left, PIN dots + numeric
keypad on the right. Footer shows online/offline + pending-sync count.

Going with cached-hashes for offline-capable PIN verify (decision logged
in chat). The threat model already accepts the device — a stolen tablet
holds a 1-year store-scoped JWT, so leaking 4-digit bcrypt hashes is
incremental. Hashes only ever leave the server when the requester is a
paired POS tablet, gated by the new endpoint refusing user JWTs.

Backend:
- GET /api/v1/store/loyalty/pins/for-device — returns PINs WITH pin_hash
  for terminal-device JWTs only; user JWTs receive 403.
- PinForDeviceResponse / PinForDeviceListResponse schemas.
- 2 integration tests in TestPinsForDevice (10/10 pass total).

Android:
- PinForDeviceItem / PinForDeviceListResponse Moshi models.
- LoyaltyApi.listPinsForDevice().
- StaffPinRepository.verifyPin(plain) — at.favre.lib bcrypt verify
  against cached hashes; filters active + unlocked rows in one pass.
- PendingTransactionDao.getPendingCount() switched to Flow<Int> so the
  badge auto-updates when transactions sync.
- PinViewModel state machine — loads pins on init, accumulates digits,
  bcrypt-verifies on length >= 4, fires verified/errorMessage. Combines
  pending-sync count + online state into the same StateFlow.
- PinScreen rewrite: avatar-circle staff list, 6-dot PIN display,
  spinner during verify, error label on wrong PIN, status footer.

Open follow-up (intentional, post-launch): tablet doesn't yet report
failed attempts back to the server's lockout counter. Path is clear —
small POST /pins/{id}/record-failed-attempt endpoint plus a call from
attemptVerify's failure branch.

Verified by ./gradlew assembleDebug — clean build.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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

@@ -30,6 +30,8 @@ from app.modules.loyalty.schemas import (
     CardResponse,
     MerchantStatsResponse,
     PinCreate,
+    PinForDeviceListResponse,
+    PinForDeviceResponse,
     PinListResponse,
     PinResponse,
     PinUpdate,
@@ -346,6 +348,47 @@ def list_pins(
     )
 
 
+@router.get("/pins/for-device", response_model=PinForDeviceListResponse)
+def list_pins_for_device(
+    current_user: User = Depends(get_current_store_api),
+    db: Session = Depends(get_db),
+):
+    """List staff PINs *with* their bcrypt ``pin_hash`` for offline verify.
+
+    Reserved for paired POS tablets — the ``Authorization`` header must
+    carry a device JWT. User JWTs are rejected with 403. Hashes only ever
+    leave the server when the requester has been blessed by a merchant
+    owner via the device pairing flow, and the device is the same source
+    of truth that can be revoked from /merchants/loyalty/devices.
+    """
+    if current_user.terminal_device_id is None:
+        raise AuthorizationException(
+            "This endpoint is only available to paired POS terminal devices"
+        )
+
+    store_id = current_user.token_store_id
+    program = program_service.require_program_by_store(db, store_id)
+    pins = pin_service.list_pins(db, program.id, store_id=store_id)
+
+    return PinForDeviceListResponse(
+        pins=[
+            PinForDeviceResponse(
+                id=p.id,
+                name=p.name,
+                staff_id=p.staff_id,
+                is_active=p.is_active,
+                is_locked=p.is_locked,
+                locked_until=p.locked_until,
+                last_used_at=p.last_used_at,
+                created_at=p.created_at,
+                pin_hash=p.pin_hash,
+            )
+            for p in pins
+        ],
+        total=len(pins),
+    )
+
+
 @router.post("/pins", response_model=PinResponse, status_code=201)
 def create_pin(
     data: PinCreate,

app/modules/loyalty/schemas/__init__.py

@@ -42,6 +42,8 @@ from app.modules.loyalty.schemas.pin import (
     PinCreateForMerchant,
     PinDetailListResponse,
     PinDetailResponse,
+    PinForDeviceListResponse,
+    PinForDeviceResponse,
     PinListResponse,
     PinResponse,
     PinUpdate,
@@ -135,6 +137,8 @@ __all__ = [
     "PinCreateForMerchant",
     "PinUpdate",
     "PinResponse",
+    "PinForDeviceResponse",
+    "PinForDeviceListResponse",
     "PinDetailResponse",
     "PinListResponse",
     "PinDetailListResponse",

app/modules/loyalty/schemas/pin.py

@@ -99,6 +99,23 @@ class PinDetailListResponse(BaseModel):
     total: int
 
 
+class PinForDeviceResponse(PinResponse):
+    """Pin response for a paired terminal device.
+
+    Includes the bcrypt ``pin_hash`` so the tablet can verify a typed
+    PIN locally without a network round-trip. This shape is ONLY served
+    by the device-only endpoint (``GET /pins/for-device``) — every other
+    pin endpoint stays hash-less.
+    """
+
+    pin_hash: str
+
+
+class PinForDeviceListResponse(BaseModel):
+    pins: list[PinForDeviceResponse]
+    total: int
+
+
 class PinVerifyRequest(BaseModel):
     """Schema for verifying a staff PIN."""
 

app/modules/loyalty/tests/integration/test_terminal_devices.py

@@ -257,3 +257,55 @@ class TestActingDeviceAudit:
         )
         assert tx is not None
         assert tx.acting_terminal_device_id is None
+
+
+@pytest.mark.integration
+@pytest.mark.api
+@pytest.mark.loyalty
+class TestPinsForDevice:
+    """GET /pins/for-device exposes hashes only to paired devices."""
+
+    def test_device_token_receives_hashes(
+        self, client, loyalty_merchant_headers, loyalty_store_setup, db
+    ):
+        from app.modules.loyalty.models import StaffPin
+
+        store = loyalty_store_setup["store"]
+        program = loyalty_store_setup["program"]
+        pin = StaffPin(
+            merchant_id=store.merchant_id,
+            program_id=program.id,
+            store_id=store.id,
+            name="Test Cashier",
+            staff_id="cash01",
+        )
+        pin.set_pin("4321")
+        db.add(pin)
+        db.commit()
+        db.refresh(pin)
+
+        paired = client.post(
+            f"{MERCHANT_BASE}/devices",
+            json={"store_id": store.id, "label": "PIN test"},
+            headers=loyalty_merchant_headers,
+        ).json()
+        token = paired["setup_token"]
+
+        response = client.get(
+            f"{STORE_BASE}/pins/for-device",
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        assert response.status_code == 200, response.text
+        payload = response.json()
+        assert payload["total"] >= 1
+        target = next(p for p in payload["pins"] if p["id"] == pin.id)
+        assert target["pin_hash"].startswith("$2") and len(target["pin_hash"]) > 50
+
+    def test_user_token_is_rejected(
+        self, client, loyalty_store_headers
+    ):
+        response = client.get(
+            f"{STORE_BASE}/pins/for-device",
+            headers=loyalty_store_headers,
+        )
+        assert response.status_code == 403, response.text