CI deploy f7ddbcd

amanpay/notifications/service.py

@@ -22,6 +22,7 @@ import hashlib
 import logging
 import os
 import secrets
+import threading
 from dataclasses import dataclass, field
 from typing import Dict, List, Optional
 
@@ -173,6 +174,13 @@ class NotificationService:
     def __init__(self) -> None:
         self._prefs: Dict[str, _Prefs] = {}
         self._subs: Dict[str, dict] = {}
+        # Serializes the read-check-write in respond() so two concurrent responses
+        # (FastAPI runs sync handlers in a threadpool) can't both pass the pending
+        # check — first terminal transition wins. For a future shared Redis-backed
+        # store this critical section must move to a Lua compare-and-set (cf. the
+        # `_CONSUME` script in storage/kv.py); the single respond() entry point keeps
+        # that swap localized.
+        self._respond_lock = threading.Lock()
         self.console = ConsoleProvider()
         self.sms = SMSProvider()
         self.call = CallProvider()
@@ -228,7 +236,7 @@ class NotificationService:
         # PENDING_TTL bounds the confirmation window (timeout handling).
         from amanpay.storage.kv import get_kv
         get_kv().set(f"oob:{cid}", {"code": code, "amount": amount, "merchant": merchant,
-                                    "approved": None, "ts": now},
+                                    "approved": None, "finalized_at": None, "ts": now},
                      ttl=self.PENDING_TTL, now=now)
         msg = (f"AmanPay: confirm payment of ${amount:.2f} to {merchant}. "
                f"Code {code}. If this wasn't you, deny it in the app.")
@@ -250,19 +258,51 @@ class NotificationService:
 
     def respond(self, confirmation_id: str, approve: bool,
                 code: Optional[str] = None, now: float = 0.0) -> Dict:
-        """Approve/deny a pending confirmation. If a code is given it must match
-        (dynamic linking) — proves the response is bound to this exact payment."""
+        """Approve/deny a confirmation, enforcing TERMINAL-STATE IMMUTABILITY.
+
+        - unknown/expired id -> {success: False, status: "expired"}.
+        - already finalized, SAME decision -> idempotent: returns the UNCHANGED final
+          state (success: True, idempotent: True) — decision + finalized_at preserved.
+        - already finalized, CONFLICTING decision -> {success: False, conflict: True,
+          error_code: "oob_already_finalized"} (route maps to HTTP 409); state unchanged.
+        - pending -> requires the dynamic-link code, then finalizes (first writer wins).
+
+        The whole read-check-write runs under a lock so concurrent approve/deny can't
+        both succeed. If a code is given it must match (dynamic linking)."""
         from amanpay.storage.kv import get_kv
-        kv = get_kv()
-        pend = kv.get(f"oob:{confirmation_id}", now=now)
-        if pend is None:
-            return {"success": False, "reason": "unknown or expired confirmation"}
-        if code is not None and code.upper() != pend["code"]:
-            return {"success": False, "reason": "code mismatch (dynamic-link failed)"}
-        pend["approved"] = bool(approve)
-        kv.set(f"oob:{confirmation_id}", pend, ttl=self.PENDING_TTL, now=now)
-        return {"success": True, "approved": pend["approved"],
-                "amount": pend["amount"], "merchant": pend["merchant"]}
+        approve = bool(approve)
+        key = f"oob:{confirmation_id}"
+        with self._respond_lock:
+            kv = get_kv()
+            pend = kv.get(key, now=now)
+            if pend is None:
+                return {"success": False, "status": "expired",
+                        "reason": "unknown or expired confirmation"}
+            finalized = pend.get("approved")
+            if finalized is not None:
+                current = "approved" if finalized else "rejected"
+                if approve == finalized:
+                    # Idempotent retry — return the existing final state, unchanged.
+                    return {"success": True, "approved": finalized, "status": current,
+                            "amount": pend["amount"], "merchant": pend["merchant"],
+                            "finalized_at": pend.get("finalized_at"), "idempotent": True}
+                # Conflicting response after a terminal state — reject, do not mutate.
+                return {"success": False, "conflict": True,
+                        "error_code": "oob_already_finalized", "status": current,
+                        "confirmation_id": confirmation_id,
+                        "finalized_at": pend.get("finalized_at"),
+                        "reason": "confirmation already finalized"}
+            # Still pending — enforce dynamic linking, then finalize.
+            if code is not None and code.upper() != pend["code"]:
+                return {"success": False, "status": "pending",
+                        "reason": "code mismatch (dynamic-link failed)"}
+            pend["approved"] = approve
+            pend["finalized_at"] = now
+            kv.set(key, pend, ttl=self.PENDING_TTL, now=now)
+            return {"success": True, "approved": approve,
+                    "status": "approved" if approve else "rejected",
+                    "amount": pend["amount"], "merchant": pend["merchant"],
+                    "finalized_at": now, "idempotent": False}
 
     def is_approved(self, confirmation_id: Optional[str], now: float = 0.0) -> bool:
         if not confirmation_id:

api/dependencies.py

@@ -39,7 +39,7 @@ class ModelState:
         from amanpay.banking.wallet import WalletRegistry
         from amanpay.banking.risk import RiskEngine
         from amanpay.banking.geo import GeoRegistry
-        from amanpay.notifications.service import NotificationService
+        from api import services
         self.passkeys = PasskeyRegistry()
         self.voice = VoiceRegistry()
         self.liveness = LivenessRegistry()
@@ -47,7 +47,10 @@ class ModelState:
         self.wallet = WalletRegistry()
         self.risk = RiskEngine()
         self.geo = GeoRegistry()
-        self.notify = NotificationService()
+        # Share the torch-free notification singleton (the /notify router uses the same
+        # instance) and wire durable-persistence + audit hooks into it.
+        self.notify = services.notifications
+        services.wire(persist=self.persist, audit=self.audit)
         # Datastore: a real SQL DB (SQLite/Postgres) when DATABASE_URL is set —
         # per-user rows, audit log, cascade erasure (P1). Otherwise the HF Dataset
         # store (keeps the zero-config HF Space demo working).

api/main.py

@@ -30,6 +30,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from api.dependencies import state
 from api.observability import (init_sentry, metrics_middleware, metrics_response,
                                record_readiness, setup_logging)
+from api.routers.notifications import router as notifications_router
 from api.routes import router
 
 logging.basicConfig(level=logging.INFO,
@@ -110,6 +111,7 @@ def readyz():
 
 
 app.include_router(router)
+app.include_router(notifications_router)   # torch-free /notify/* endpoints
 
 
 _ROOT = os.path.dirname(os.path.dirname(__file__))

api/routers/notifications.py

@@ -0,0 +1,68 @@
+"""Notification / out-of-band confirmation endpoints — a torch-free router.
+
+Isolated from the monolithic `api.routes` (which imports the biometric models/torch)
+so these endpoints and their API tests run in the lightweight, torch-free environment.
+Paths, methods and request/response contracts are UNCHANGED from the previous
+definitions in `api.routes`."""
+
+from __future__ import annotations
+
+import time
+
+from fastapi import APIRouter, Body
+from fastapi.responses import JSONResponse
+
+from api.services import audit_event, notifications, persist_prefs
+
+router = APIRouter()
+
+
+@router.post("/notify/prefs")
+def notify_set_prefs(body: dict = Body(...)) -> dict:
+    r = notifications.set_prefs(body["user_id"], channels=body.get("channels"),
+                                email=body.get("email"), phone=body.get("phone"))
+    persist_prefs()
+    return r
+
+
+@router.get("/notify/prefs")
+def notify_get_prefs(user_id: str) -> dict:
+    return notifications.get_prefs(user_id)
+
+
+@router.post("/notify/subscribe")
+def notify_subscribe(body: dict = Body(...)) -> dict:
+    """Store a Web Push subscription (from the browser) for the user."""
+    return notifications.subscribe_push(body["user_id"], body["subscription"])
+
+
+@router.post("/notify/request")
+def notify_request(body: dict = Body(...)) -> dict:
+    """Create a demo out-of-band payment confirmation (dynamic-linked to amount+merchant)
+    using the existing notification service, so the React OOB demo can exercise the
+    request -> respond -> status workflow without going through /wallet/pay."""
+    return notifications.send_payment_confirmation(
+        body["user_id"], float(body.get("amount", 0.0)),
+        str(body.get("merchant", "")), now=time.time())
+
+
+@router.get("/notify/status")
+def notify_status(confirmation_id: str) -> dict:
+    """Lifecycle of an OOB confirmation for UI polling: pending/approved/rejected/expired."""
+    return {"confirmation_id": confirmation_id,
+            "status": notifications.confirmation_status(confirmation_id, now=time.time())}
+
+
+@router.post("/notify/respond")
+def notify_respond(body: dict = Body(...)):
+    """Approve/deny an OOB confirmation. Enforces terminal-state immutability: a
+    conflicting response after a terminal state returns HTTP 409 (oob_already_finalized)
+    and leaves the final state unchanged; a same-decision retry is idempotent."""
+    r = notifications.respond(body["confirmation_id"], bool(body.get("approve", False)),
+                              code=body.get("code"), now=time.time())
+    if r.get("conflict"):
+        # Safe security-audit event (no code/secret) for the rejected conflicting transition.
+        audit_event("oob", "oob_conflict_rejected",
+                    {"confirmation_id": r.get("confirmation_id"), "final_state": r.get("status")})
+        return JSONResponse(status_code=409, content=r)
+    return r

api/routes.py

@@ -298,47 +298,9 @@ def pad_verify(body: dict = Body(...)) -> dict:
 
 
 # ---- Notification preferences + out-of-band payment confirmation ----
-@router.post("/notify/prefs")
-def notify_set_prefs(body: dict = Body(...)) -> dict:
-    r = state.notify.set_prefs(body["user_id"], channels=body.get("channels"),
-                               email=body.get("email"), phone=body.get("phone"))
-    state.persist()
-    return r
-
-
-@router.get("/notify/prefs")
-def notify_get_prefs(user_id: str) -> dict:
-    return state.notify.get_prefs(user_id)
-
-
-@router.post("/notify/subscribe")
-def notify_subscribe(body: dict = Body(...)) -> dict:
-    """Store a Web Push subscription (from the browser) for the user."""
-    return state.notify.subscribe_push(body["user_id"], body["subscription"])
-
-
-@router.post("/notify/request")
-def notify_request(body: dict = Body(...)) -> dict:
-    """Create a demo out-of-band payment confirmation (dynamic-linked to amount+merchant)
-    using the existing notification service, so the React OOB demo can exercise the
-    request -> respond -> status workflow without going through /wallet/pay."""
-    return state.notify.send_payment_confirmation(
-        body["user_id"], float(body.get("amount", 0.0)),
-        str(body.get("merchant", "")), now=time.time())
-
-
-@router.get("/notify/status")
-def notify_status(confirmation_id: str) -> dict:
-    """Lifecycle of an OOB confirmation for UI polling: pending/approved/rejected/expired."""
-    return {"confirmation_id": confirmation_id,
-            "status": state.notify.confirmation_status(confirmation_id, now=time.time())}
-
-
-@router.post("/notify/respond")
-def notify_respond(body: dict = Body(...)) -> dict:
-    """User approves/denies a pending out-of-band confirmation (dynamic-linked)."""
-    return state.notify.respond(body["confirmation_id"], bool(body.get("approve", False)),
-                                code=body.get("code"), now=time.time())
+# Notification / out-of-band confirmation endpoints (/notify/*) live in the torch-free
+# api.routers.notifications router (included by api.main), so they and their API tests
+# stay isolated from the biometric-model imports. Paths/contracts are unchanged.
 
 
 # ---- Device-native biometric (platform authenticator: Touch ID / Face ID / fingerprint) ----

api/services.py

@@ -0,0 +1,38 @@
+"""Torch-free application services shared between the model-heavy dependency layer
+and the lightweight routers. Importing this module never pulls torch or the biometric
+models, so the notification/OOB router (and its API tests) stay torch-free.
+
+The `notifications` singleton IS the instance the full app uses (ModelState.notify
+references it), so production and tests share one service + state. Persistence and
+audit are optional hooks the full app wires at startup; they no-op when unwired
+(e.g. in the light CI test app), matching the demo store's behavior."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from amanpay.notifications.service import NotificationService
+
+# Single shared notification/OOB service (referenced by ModelState.notify).
+notifications = NotificationService()
+
+_persist: Optional[Callable[[], None]] = None
+_audit: Optional[Callable[[str, str, dict], None]] = None
+
+
+def wire(persist: Optional[Callable[[], None]] = None,
+         audit: Optional[Callable[[str, str, dict], None]] = None) -> None:
+    """Wire durable-persistence and audit callbacks from the full app (torch side)."""
+    global _persist, _audit
+    _persist = persist
+    _audit = audit
+
+
+def persist_prefs() -> None:
+    if _persist is not None:
+        _persist()
+
+
+def audit_event(user_id: str, action: str, detail: dict) -> None:
+    if _audit is not None:
+        _audit(user_id, action, detail)

build_info.json

@@ -1 +1 @@
-{"commit":"f5b3d10","build_time":"2026-07-12T10:04:06Z","frontend":"1.0.0"}
+{"commit":"f7ddbcd","build_time":"2026-07-12T16:08:09Z","frontend":"1.0.0"}

web/e2e/biometrics.spec.ts

@@ -71,6 +71,21 @@ test('OOB confirmation: request -> approve -> approved', async ({ page }) => {
   await expect(page.getByText('Approved.')).toBeVisible()
 })
 
+test('OOB stale conflicting response keeps the approved state (409 handled)', async ({ page }) => {
+  // Simulate the confirmation already finalized elsewhere -> backend returns 409.
+  await page.route('**/notify/respond', (r) => r.fulfill({
+    status: 409, contentType: 'application/json',
+    body: JSON.stringify({ success: false, conflict: true, error_code: 'oob_already_finalized', status: 'approved' }),
+  }))
+  await page.route('**/notify/status**', (r) => r.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ status: 'approved' }) }))
+  await page.goto('/#/biometrics/oob')
+  await page.getByRole('button', { name: 'Send confirmation' }).click()
+  await page.getByRole('button', { name: 'Approve' }).click()
+  await expect(page.getByText('Approved.')).toBeVisible()          // refreshed to the real terminal state
+  await expect(page.getByText(/already finalized/i)).toBeVisible() // informative, not a failure
+  await expect(page.getByText('Rejected.')).toHaveCount(0)         // did NOT flip to rejected
+})
+
 test('report card shows benchmark-unavailable (not a fabricated available)', async ({ page }) => {
   await page.goto('/#/biometrics/reportcard')
   await expect(page.getByText('Benchmark data unavailable')).toBeVisible()

web/src/i18n/ar.ts

@@ -256,4 +256,5 @@ export const ar: Record<MessageKey, string> = {
   'oob.status.approved': 'تمت الموافقة.',
   'oob.status.rejected': 'مرفوض.',
   'oob.status.expired': 'منتهي الصلاحية.',
+  'oob.alreadyFinalized': 'تم إنهاء هذا التأكيد مسبقًا — يتم عرض نتيجته الحالية.',
 }

web/src/i18n/en.ts

@@ -254,6 +254,7 @@ export const en = {
   'oob.status.approved': 'Approved.',
   'oob.status.rejected': 'Rejected.',
   'oob.status.expired': 'Expired.',
+  'oob.alreadyFinalized': 'This confirmation was already finalized — showing its current result.',
 } as const
 
 export type MessageKey = keyof typeof en

web/src/pages/OobPage.test.tsx

@@ -3,6 +3,7 @@ import { render, screen, fireEvent, waitFor } from '@testing-library/react'
 import { I18nProvider } from '../i18n'
 import { OobPage } from './OobPage'
 import * as oob from '../api/oob'
+import { ApiRequestError } from '../api/client'
 
 vi.mock('../api/oob')
 
@@ -37,4 +38,17 @@ describe('OobPage', () => {
     await waitFor(() => expect(oob.respondConfirmation).toHaveBeenCalledWith('cnf_1', true, 'AB12CD'))
     expect(await screen.findByText('Approved.')).toBeInTheDocument()
   })
+
+  it('handles a 409 already-finalized by refreshing to the terminal state, not a generic error', async () => {
+    renderOob()
+    fireEvent.click(screen.getByRole('button', { name: 'Send confirmation' }))
+    await screen.findByRole('button', { name: 'Approve' })
+    // Simulate a stale/conflicting response: backend already finalized -> 409.
+    vi.spyOn(oob, 'respondConfirmation').mockRejectedValue(new ApiRequestError({ status: 409, message: 'conflict' }))
+    vi.spyOn(oob, 'getConfirmationStatus').mockResolvedValue({ status: 'approved' })
+    fireEvent.click(screen.getByRole('button', { name: 'Approve' }))
+    expect(await screen.findByText('Approved.')).toBeInTheDocument()          // shows the real terminal state
+    expect(screen.getByText(/already finalized/i)).toBeInTheDocument()        // informative, not a failure
+    expect(screen.queryByText(/Something went wrong/i)).toBeNull()            // no generic error
+  })
 })

web/src/pages/OobPage.tsx

@@ -4,6 +4,7 @@ import {
   type OobConfirmation, type OobStatus,
 } from '../api/oob'
 import { Button, Callout, Field, Spinner } from '../components/ui'
+import { ApiRequestError } from '../api/client'
 import { localizeError } from '../utils/errors'
 import { useI18n } from '../i18n'
 import type { MessageKey } from '../i18n/en'
@@ -21,6 +22,7 @@ export function OobPage() {
   const [status, setStatus] = useState<OobStatus | null>(null)
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState<string | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
   const timer = useRef<ReturnType<typeof setInterval> | null>(null)
 
   function stopPolling() { if (timer.current) { clearInterval(timer.current); timer.current = null } }
@@ -28,7 +30,7 @@ export function OobPage() {
 
   async function send() {
     if (busy) return
-    setBusy(true); setError(null); setStatus(null); setConf(null); stopPolling()
+    setBusy(true); setError(null); setNotice(null); setStatus(null); setConf(null); stopPolling()
     try {
       await setNotifyPrefs(userId.trim() || 'alice', channels)
       const c = await requestConfirmation(userId.trim() || 'alice', Number(amount) || 0, merchant.trim())
@@ -44,18 +46,35 @@ export function OobPage() {
     } catch (e) { setError(localizeError(e, t, 'error.generic')) } finally { setBusy(false) }
   }
 
+  async function refreshStatus(): Promise<OobStatus | null> {
+    if (!conf) return null
+    try {
+      const s = (await getConfirmationStatus(conf.confirmation_id)).status
+      setStatus(s); if (TERMINAL.has(s)) stopPolling()
+      return s
+    } catch { return null }
+  }
+
   async function respond(approve: boolean) {
     if (!conf) return
-    setBusy(true); setError(null)
+    setBusy(true); setError(null); setNotice(null)
     try {
       const r = await respondConfirmation(conf.confirmation_id, approve, conf.code)
       if (!r.success) { setError(t('error.generic')); return }
-      const s = (await getConfirmationStatus(conf.confirmation_id)).status
-      setStatus(s); if (TERMINAL.has(s)) stopPolling()
-    } catch (e) { setError(localizeError(e, t, 'error.generic')) } finally { setBusy(false) }
+      await refreshStatus()
+    } catch (e) {
+      // 409 = already finalized (stale page / double click / another tab / late network).
+      // Refresh to the real terminal state and show it — NOT a generic failure.
+      if (e instanceof ApiRequestError && e.status === 409) {
+        setNotice(t('oob.alreadyFinalized'))
+        await refreshStatus()
+        return
+      }
+      setError(localizeError(e, t, 'error.generic'))
+    } finally { setBusy(false) }
   }
 
-  function reset() { stopPolling(); setConf(null); setStatus(null); setError(null) }
+  function reset() { stopPolling(); setConf(null); setStatus(null); setError(null); setNotice(null) }
 
   const statusTone = status === 'approved' ? 'ok' : status === 'pending' ? 'warn' : 'bad'
 
@@ -94,6 +113,7 @@ export function OobPage() {
             <dt>{t('oob.code')}</dt><dd className="mono" dir="ltr">{conf.code}</dd>
           </dl>
           <p className="hint">{t('oob.dynamicLink')}</p>
+          {notice && <Callout tone="info">{notice}</Callout>}
           {status && <Callout tone={statusTone}>{t((`oob.status.${status}`) as MessageKey)}</Callout>}
           {status === 'pending' && (
             <div className="row">