# Threat Model — Vigilant Entities / Amwāl OS

> STRIDE methodology · last refreshed 2026-02-12.
> Maintained alongside the codebase. Update whenever a new privileged
> code path, integration, or trust boundary is added.

## 1. System overview

```
            ┌──────────────────────────────────────┐
            │  Browser  ──  PWA  ──  Mobile (iOS)  │
            └──────────────┬───────────────────────┘
                           │ HTTPS · HSTS preload · TLS 1.3
                           ▼
            ┌──────────────────────────────────────┐
            │  K8s ingress / Cloudflare            │  ← TLS termination
            └──────────────┬───────────────────────┘
                           │ HTTP/1.1
                           ▼
            ┌──────────────────────────────────────┐
            │  FastAPI app (server.py)             │
            │   ├─ RateLimitMiddleware             │  ← first-line throttle
            │   ├─ SecurityHeadersMiddleware       │  ← strict CSP, HSTS
            │   ├─ Dawud heuristic scanner         │  ← injection block
            │   ├─ CORS allowlist                  │
            │   └─ Routes (RBAC enforced)          │
            └────────┬──────────────┬──────────────┘
                     ▼              ▼
            ┌─────────────────┐  ┌───────────────────────┐
            │ MongoDB (motor) │  │  Outbound integrations│
            │ tenant-scoped   │  │  Stripe · Resend ·    │
            │ idx on tenant_id│  │  AWS Bedrock · S3 ·   │
            └─────────────────┘  │  Web Push (VAPID)     │
                                 └───────────────────────┘
```

Trust boundaries:
1. **External ↔ Ingress** — TLS, public internet.
2. **Ingress ↔ App** — internal network, no auth on transport.
3. **App ↔ Mongo** — same VPC, password auth.
4. **App ↔ 3rd-party APIs** — egress allowlist via per-vendor SDK.

## 2. Attacker personas

| ID  | Persona                  | Capability                              | Motivation                   |
|-----|--------------------------|-----------------------------------------|------------------------------|
| AP1 | Opportunistic scanner    | Mass port scan, exploit packs           | Crypto-mining, ransomware    |
| AP2 | Skilled outsider         | Web app pentest skills, OWASP playbook  | Bug bounty, ego, resale      |
| AP3 | Disgruntled ex-employee  | Knows codebase, has old creds (now revoked) | Sabotage, IP theft       |
| AP4 | Current tenant insider   | Holding admin or below                  | Data exfil, lateral tenant   |
| AP5 | Nation-state             | 0-days, supply-chain compromise         | Espionage, geopolitical      |
| AP6 | Curious journalist       | Social engineering, OSINT               | Story / leak                 |

## 3. STRIDE per asset

### 3.1 Authentication credentials

| Threat            | Mitigation                                                        |
|-------------------|-------------------------------------------------------------------|
| **S**poofing      | bcrypt(12), per-device JWT (`did`), MFA-like magic-link step      |
| **T**ampering     | HMAC-SHA256 JWT signature; secret strength check at boot          |
| **R**epudiation   | `account_activity` log per identity event + hash-chained audit    |
| **I**nfo disclosure | No plaintext in logs; PII redaction; mask emails in public flows |
| **D**oS           | Brute-force lockout + rate limit (per IP + per account)           |
| **E**oP           | RBAC enforced on every route; no client-side authorisation        |

### 3.2 Multi-tenant data

| Threat       | Mitigation                                                              |
|--------------|-------------------------------------------------------------------------|
| Cross-tenant data leak | Every collection has `tenant_id` index. All queries scoped via middleware. |
| Tenant ID forgery | Tenant comes from authenticated JWT, never from request body.       |
| Maker cloak abuse | Maker's own actions are intentionally cloaked from `audit_logs`, BUT not from `account_activity` (the maker can audit themselves). |

### 3.3 Audit log integrity

| Threat              | Mitigation                                              |
|---------------------|---------------------------------------------------------|
| Insider edits past row | Hash-chain (`audit_chain.py`) detects on `/api/security/audit/verify`. |
| DBA deletes row     | Same — chain index gap detectable                       |
| DBA truncates collection | Out-of-band backup hash + restore from `BACKUP_RUNBOOK.md` |

### 3.4 Third-party egress (Stripe, Resend, AWS Bedrock)

| Threat            | Mitigation                                                            |
|-------------------|-----------------------------------------------------------------------|
| Vendor compromise | Webhook signature verification (Stripe); minimum-privilege API keys; AWS uses STS-assumed-role with external_id. |
| Exfil via vendor  | Vendor allowlist; tenant data never sent to inference endpoints outside tenant's AWS account. |

### 3.5 The Maker account

The Maker is the most powerful account in the system. Specific guards:
- Cannot self-delete via `/api/auth/me/delete` (would brick deployment).
- All Maker actions are cloaked from `audit_logs` BUT recorded in `account_activity` (visible only to the Maker themselves).
- First-boot Maker gets a random secure password — never a default like `Vigilant@2026`.
- Maker email is allowlisted via `MAKER_EMAIL` env; rotation requires .env change + redeploy.

## 4. Top residual risks

| Risk                                         | Likelihood | Impact | Owner | Mitigation plan       |
|----------------------------------------------|------------|--------|-------|-----------------------|
| Dependency supply-chain compromise (PyPI typosquat) | Med   | High   | DevSec| Pin to hashes; pip-audit |
| Lost Maker email access → permanent lockout   | Low        | Critical | Ops | Document offline-DBA recovery |
| Insider with DBA access bypasses chain check  | Low        | High   | Sec   | Audit-chain on read-only replica; alarms on direct write |
| Browser extension XSS via uploaded SVG logo   | Low        | Med    | Eng   | `Content-Security-Policy` strict; SVGs sanitised on upload |

## 5. Out of scope

- Physical security of the data centre (cloud provider).
- TLS endpoint security (Cloudflare / upstream ingress).
- DDoS at the network layer (handled upstream).

## 6. Review cadence

Quarterly, or whenever:
- A new third-party integration ships.
- A new privileged role is introduced.
- An audit / pen-test report surfaces an unmodeled attack.