OMT-SM/docs/THREAT_MODEL.md

# Threat Model — OMT / Recharge Cell Shop

> **Purpose.** Document, before any code is written, every realistic way an
> employee (or a colluding pair) can steal money or goods from the shop, and
> the specific control the system must enforce to block each path. Every later
> migration, RLS policy, trigger, and UI rule must trace back to a row in this
> table.
>
> This file is **append-only** in spirit: when a new theft vector is
> discovered, add a row; do not delete history.

## Actors

| Actor      | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `cashier`  | Operates a till during a shift. Highest fraud-risk role.       |
| `manager`  | Approves voids, refunds, overrides. Can collude with cashier.  |
| `owner`    | Read-everything. Surprise inspections. Sets prices/fees.       |
| `auditor`  | Read-only third party (accountant).                            |
| `customer` | May be an accomplice (fake refund, fake cancellation).         |

## Trust boundaries

1. **Browser/POS ↔ Supabase**: client is hostile. Never trust client-supplied
   prices, fees, FX rates, timestamps, user IDs, or shift IDs.
2. **App role ↔ Postgres**: even the service role must not be able to `DELETE`
   from the ledger or rewrite hashes. Enforce with table grants + triggers.
3. **Shop ↔ Provider (OMT / Alfa / touch / Bank)**: the provider's statement
   is the source of truth for reconciliation. Any local row not present on the
   provider statement is suspect.

## Theft vectors and required controls

| #  | Vector                                                                                         | Control (must exist before go-live)                                                                                              | Enforced in     |
| -- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| 1  | Pocket cash, never enter the transaction                                                       | Mandatory printed receipt, sequential `reference_no` per shop, customer SMS with reference, gap-detection report                 | DB + server     |
| 2  | Enter transaction, then edit / delete it after customer leaves                                 | Append-only ledger; `UPDATE`/`DELETE` revoked; void requires reason + manager PIN; row hash chain                                | DB triggers     |
| 3  | Recharge own/friend's number flagged as "test"                                                 | No "test" flag exists; every recharge debits stock or e-float                                                                    | Schema          |
| 4  | Sell a scratch card, keep cash, claim "lost card"                                              | Voucher serial scanned on intake **and** on sale; loss requires manager approval; variance assigned to cashier                   | DB + UI         |
| 5  | Use shop OMT terminal to send to themselves at zero / reduced fee                              | Fee schedule server-side and immutable per cashier; OMT statement reconciliation; alert on cashier as sender or beneficiary      | DB + recon job  |
| 6  | Manipulate FX rate (e.g. "I gave 89,000 LBP/USD instead of 90,000")                            | `fx_rates` populated by scheduled job; cashier selects, never types; rate stamped on each txn                                    | DB + cron       |
| 7  | Skim cash from drawer, blame "shortfall"                                                       | Blind closing count (declared before expected revealed); per-cashier variance trend; chronic shortage alert                      | UI + report     |
| 8  | Collect customer cash, "deposit later", never deposit                                          | Forced shift close before leaving; aging-outstanding alert > N hours; bank-deposit reconciliation                                | DB + recon      |
| 9  | Share login with a colleague                                                                   | Per-user PIN re-prompt, device binding, session timeout, no shared accounts                                                      | Auth            |
| 10 | Print fake receipts on a second printer                                                        | Receipt carries server-signed QR (JWT of `txn_id`); spot-scan by owner returns DB row or "FAKE"                                  | Server          |
| 11 | Refund/void to themselves                                                                      | Void/refund requires manager PIN on same device; cashier cannot self-approve; daily void report per cashier                      | DB + UI         |
| 12 | Sell recharge below price ("friend discount")                                                  | Price list server-controlled; cashier UI has no price field; override only by manager and logged                                 | DB + UI         |
| 13 | Take goods (phones/accessories) without sale                                                   | Per-shift inventory count; CCTV ↔ txn time sync; variance report                                                                 | UI + ops        |
| 14 | Tamper with the closing count                                                                  | Declared count entered first and locked; expected revealed only after; both stored                                               | DB              |
| 15 | Accomplice customer "cancels" after cash handed                                                | Cancellations require manager + reason + photo of voided receipt; CCTV cross-check                                               | UI + ops        |
| 16 | Structure large transfers under multiple fake walk-in identities                               | KYC threshold per (customer, day) and (beneficiary, week); customer record mandatory ≥ threshold                                 | DB + AML report |
| 17 | Off-hours transaction when nobody is watching                                                  | Shift hours per shop; after-hours flag + alert                                                                                   | DB + alert      |
| 18 | Manager–cashier collusion to mass-void real sales                                              | Void rate per (cashier, manager) pair trended; owner-only weekly review; voids count against shift variance                      | Report          |
| 19 | Replay an old OMT receipt to a new customer                                                    | `external_ref` unique per provider; duplicate detection on insert                                                                | DB constraint   |
| 20 | Cashier opens a second, undeclared till on the same device                                     | One open shift per `till_id`; device fingerprint pinned to till                                                                  | DB + auth       |
| 21 | Cashier marks recharge "failed at provider" and keeps cash                                     | Provider e-recharge response stored as `external_ref` and reconciled; "failed" requires provider failure id                      | DB + recon      |
| 22 | Cashier "exchanges currency" at a worse rate than recorded, pocketing the spread               | FX swap is a typed `cash_movement` with both legs at the system rate; deviation requires manager override                        | DB              |
| 23 | Cashier deletes their browser data to "lose" pending offline transactions                      | Offline queue persisted with server-issued idempotency key; missing key sequences flagged on reconnect                           | Client + server |
| 24 | Insider (developer/DBA) silently edits the database                                            | Hash chain on ledger; daily hash anchor exported off-site; restricted DB roles; audit of all DDL and privileged SQL              | DB + ops        |
| 25 | Backdated transaction to fit a doctored shift count                                            | `occurred_at` server-side `now()`; cashier cannot set; backdate only by owner role with reason                                   | DB              |

## Non-negotiables (no go-live without these)

1. RLS on every table; no table is publicly readable or writable.
2. `INSERT`-only ledger with row hash chain; `DELETE` revoked from every role.
3. All money writes go through `SECURITY DEFINER` Postgres functions, not raw
   table writes.
4. Server-controlled prices, fees, and FX rates. No cashier-typed money rules.
5. Blind cash close per shift, with declared-vs-expected variance stored.
6. External reconciliation (OMT, Alfa, touch, bank) before any month-close.
7. Per-user account, device-bound, with PIN re-prompt for sensitive ops.
8. Receipt with signed QR linking back to the ledger row.

## Review cadence

- Every new feature PR must reference at least one row above (or add one).
- Quarterly walk-through: pick 5 random rows, demonstrate the control still
  works on a staging environment.