# Security Architecture

## 1. Principles
- **Zero trust** — authenticate + authorize every request, never rely on network location
- **Least privilege** — RBAC + scoped API keys + short-lived tokens
- **Defense in depth** — WAF → API gateway → app auth → row-level security → audit
- **Data sovereignty** — tenant-configurable data residency; AI agents run on-prem (offline)
- **Auditable by default** — every change captured with actor, timestamp, before/after

## 2. Authentication
### Primary path: SSO (SAML 2.0 + OIDC)
Pre-built providers (see [`08-integrations.md`](08-integrations.md)):
- Azure AD / Entra ID, Okta, Google Workspace, Auth0, Ping, OneLogin, ADFS, Keycloak, AWS Cognito, generic SAML/OIDC

### Fallback: Local accounts
- PBKDF2-HMAC-SHA256 password hashing, 600,000 iterations (OWASP Password Storage Cheat
  Sheet current minimum), self-describing stored format so the iteration count can be raised
  again later without invalidating existing hashes — see `PasswordHasher.cs` (decisions/0126)
- Mandatory MFA (TOTP, WebAuthn/FIDO2 preferred, SMS last resort)
- Password policy configurable per tenant
- Forced rotation only on indicators of compromise (NIST guidance)

### Token model
- Access token: JWT, 15-min TTL
- Refresh token: opaque, 30-day TTL, rotated on every use, one-time use
- Device binding for mobile (attestation on iOS/Android)

## 3. Authorization
### RBAC + ABAC hybrid
Roles group permissions; permissions gated by attributes (entity, location, category, amount).

### Built-in roles (customizable)
- Super Admin, Admin, Auditor
- Asset Manager, IT Asset Controller, Financial Controller
- Store Keeper, Custodian, Mobile Operator, Viewer

### DOA (Delegation of Authority) engine
- Matrix by transaction type × amount × entity × role
- Multi-level approval chains with parallel/serial branches
- Auto-escalation on timeout
- Segregation of duties enforced (initiator ≠ approver)

## 4. Data Protection
| Layer | Control |
|---|---|
| In transit | TLS 1.3 only; HSTS; certificate pinning on mobile |
| At rest | AES-256 on SQL (TDE) + Azure Blob / S3 SSE |
| Secrets | Azure Key Vault / HashiCorp Vault |
| PII (employee numbers, names) | Column-level encryption + masked views |
| Backups | Encrypted, geo-redundant, 1-hour RPO |
| File uploads | AV scan + MIME sniff + extension allowlist + max size |

## 5. Multi-Tenancy
- Single database, row-level security via `TenantId` column on every table
- Tenant context injected from JWT `tid` claim; cannot be spoofed
- Per-tenant encryption keys (optional premium tier)
- Tenant isolation verified by automated tests on every PR

## 6. Audit & Compliance
- Immutable append-only audit log (event-sourced)
- Retention: 7 years default, configurable
- Export: SIEM (Splunk, Sentinel, Elastic) via syslog/HTTPS
- IFRS compliance for depreciation and impairment
- SOC 2 Type II controls from day one (logging, change mgmt, access review)
- GDPR / UAE PDPL: right to access, rectification, erasure endpoints

## 7. Mobile Security
- Biometric unlock (FaceID/TouchID/Android biometrics)
- Offline DB encrypted (SQLCipher)
- Certificate pinning
- Auto-logout on idle
- Jailbreak/root detection → block
- Remote wipe of offline cache on lost device

## 8. AI Security
- All AI agents run on-premise (air-gapped option)
- No prompts or data leave tenant network
- Prompt injection filters on all OCR/NL inputs
- Output sandbox — agents can suggest but never auto-execute mutations without human approval

## 9. Supply Chain
- SBOM for every release (CycloneDX)
- SCA on every PR (Snyk / Dependabot / Renovate)
- SAST (SonarCloud / CodeQL)
- DAST (OWASP ZAP) on staging
- Image signing (cosign) on container pushes
- Reproducible builds

## 10. Incident Response
- 24/7 on-call rotation during prod
- Runbook-driven IR playbook
- Breach notification SLA: ≤ 72 hours (GDPR/PDPL)
- Annual tabletop + red team

## 11. Threat Model (high level)
| Threat | Mitigation |
|---|---|
| Credential stuffing | MFA + account lockout + rate limit |
| Session hijack | Short JWT TTL + device binding + IP anomaly alerts |
| Privilege escalation | RBAC + segregation of duties + audit review |
| Data exfiltration | DLP on file exports + audit on bulk downloads |
| Insider threat | Break-glass audit + dual-control on sensitive ops |
| API abuse | Rate limits + API key rotation + anomaly detection |
| Mobile theft | Remote wipe + biometric + encrypted offline DB |
| Supply chain | SBOM + signed images + pinned deps |
| OCR prompt injection | Input sanitization + human approval on OCR-drafted FAR |