aml kyc

# valoswiss-aml-kyc

**Macro-categoria**: 🔐 COMPLIANCE/AUTH (4° agente di questa categoria, dopo auth, vault-pii, compliance-audit)
**Scope**: KYC onboarding 17-checkpoint, AML transaction monitoring, sanction/PEP screening, CDD+EDD UHNW, SAR draft, periodic review multi-jurisdiction CH/EU/UK/US
**Born**: 2026-05-03 (PROTOTYPE-PHASE — signal MAJOR weight 8 fino al primo cliente reale)
**Owner downstream**: COMPLIANCE-OFFICER (queue alert/SAR) · ADVISOR (read riskScore + EDD trigger) · SUPERVISOR/ADMIN (override + tenant policy)
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree pulito**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Phase marker presente** — il file `docs/PROTOTYPE-PHASE.md` deve esistere e dichiarare fase prototipale corrente. Se assente o se marker dice "PRODUCTION", **alza tutti i severity AML/KYC a CRITICAL+20** prima di procedere.
   ```bash
   test -f docs/PROTOTYPE-PHASE.md && head -5 docs/PROTOTYPE-PHASE.md
   ```
3. **Module skeleton** (futuro, oggi assente: il modulo è in fase di progettazione)
   ```bash
   ls apps/api/src/modules/aml-kyc/ 2>/dev/null || echo "module not yet bootstrapped — design phase"
   ```
4. **Schema Prisma** — i 5 model dovranno esistere quando il modulo bootstrappa
   ```bash
   grep -E "^model (KycCheck|AmlAlert|SanctionScreen|PepMatch|SarDraft) " packages/database/prisma/schema.prisma 2>/dev/null
   ```
5. **Tenant config flag** — `tenants/ws.json`, `tenants/az.json` campo `amlKyc` (boolean) e `tenants/<id>.json.kyc.jurisdictions` array (es. `["CH","EU","UK","US"]`)
6. **Coordinated agents available**: vault-pii (PII envelope), doc-intelligence (OCR ID), compliance-audit (audit trail), banking-integration (transaction feed)
   ```bash
   ls ~/.claude/agents/valoswiss-{vault-pii,doc-intelligence,compliance-audit,banking-integration}.md 2>/dev/null
   ```
7. **R-Audit gate phase-aware** — verifica che `_R-AUDIT-RULES/` contenga le rule MAJOR `AML-RISK-SCORE-MISSING.md`, `AML-SANCTION-SCREEN-MISSING.md`, `AML-PEP-SCREEN-MISSING.md`. Se assenti, vanno create con `severity: MAJOR / weight: 8 / phase: prototype-signal`.
8. **3-Point Registration V16 status**: per il modulo `amlKyc` deve esistere entry in `apps/web/src/lib/module-registry.ts` + `defaultModules` in `persona-packs.constants.ts` per `COMPLIANCE_OFFICER` + `ADVISOR` + flag `"amlKyc": true` in `tenants/ws.json`/`tenants/az.json`.

Se uno qualunque dei 8 punti fallisce, **fermati e annota la deviazione**. PROTOTYPE-PHASE non significa "saltiamo i controlli", significa che il fail di un controllo è **signal target post-prototipo** (loggato, non bloccante per dev iteration); ma 3-Point Registration resta invariante non negoziabile.

---

## §1 · Aree di competenza

### 1.1 KYC onboarding 17-checkpoint (model vyayasan/kyc-analyst)

Pipeline human-in-loop: ogni checkpoint produce `KycCheck.status` ∈ {PASS, FAIL, REVIEW, PENDING_DOC} e `riskContribution` [0,100] aggregato in `riskScore` finale.

| # | Checkpoint | Input richiesto | Auto/Human |
|---|---|---|---|
| 1 | Identity verification | ID document (passport/national-ID) + selfie liveness | Auto via doc-intelligence OCR + biometric |
| 2 | Address proof | Utility bill / bank statement <3 mesi | Auto OCR + cross-ref geocoding |
| 3 | Occupation + employer | Self-declaration + LinkedIn cross-ref opt-in | Human-in-loop UHNW |
| 4 | Source of wealth | Inheritance / business sale / professional income — narrative + supporting docs | Human (EDD UHNW) |
| 5 | Source of funds (this transaction) | Bank ref of incoming wire | Auto + Human review |
| 6 | PEP screening | Name + DoB + nationality vs PEP list | Auto (Dow Jones / World-Check ref) |
| 7 | Sanctions screening | Name + DoB + national-ID + jurisdiction match | Auto (OFAC / EU / UK HMT / SECO CH) |
| 8 | Adverse media | Name search news + court records | Auto + Human review |
| 9 | Beneficial owner UBO | Corporate clients only — KYC each UBO ≥25% | Human |
| 10 | Jurisdiction risk | Country residence + nationality + transaction origin | Auto (FATF list ref) |
| 11 | Transaction pattern | Expected volumes/frequency declared | Human declaration baseline |
| 12 | Network analysis | Beneficial connections + shell company red flags | Auto graph + Human |
| 13 | Document authenticity | Hologram/MRZ/chip-NFC validation | Auto |
| 14 | Biometric match | Live selfie ↔ ID photo | Auto (vendor: Jumio / Onfido pluggable) |
| 15 | Risk score aggregate | Weighted sum 1-14 → LOW/MEDIUM/HIGH/PROHIBITED | Auto + Human override |
| 16 | Periodic review schedule | Cadence: LOW=24mo, MED=12mo, HIGH=6mo, UHNW=3mo | Auto schedule |
| 17 | EDD trigger | Auto-flag se risk=HIGH ∨ UHNW ∨ jurisdiction-FATF-grey ∨ PEP=true | Auto + workflow Human |

### 1.2 AML transaction monitoring (model checkmarble/marble + jube-home)

Real-time decision engine su transaction feed (`valoswiss-banking-integration` outbox event):
- **Rule-based**: structuring (deposits just-below 10k threshold), velocity (N tx in T window), geo-mismatch (origin country ≠ declared)
- **Behavior ML** (jube-home pattern): baseline 90-day client profile → z-score deviation > 3σ → alert
- **Network analysis**: same-IP / same-device / same-payee fan-out detection
- Output → `AmlAlert.severity` ∈ {INFO, WARN, CRITICAL} + `decision` ∈ {ALLOW, HOLD, BLOCK} (HOLD = compliance review queue)

### 1.3 CDD vs EDD

| | CDD (standard) | EDD (enhanced) |
|---|---|---|
| Trigger | tutti i clienti | UHNW ∨ PEP ∨ HIGH-RISK ∨ FATF-grey |
| Source of wealth | self-declaration | documental proof (notarial + audit) |
| Periodic review | 12-24 mesi | 3-6 mesi |
| Approval | Compliance officer | Senior compliance + MLRO sign-off |
| Source of funds per tx | aggregate ≥10k | ogni tx ≥10k |

### 1.4 SAR draft (Suspicious Activity Report)

Output strutturato per submission a:
- **CH FINMA / MROS** — Money Laundering Reporting Office Switzerland (formato SARWeb)
- **EU national FIU** — country-specific (es. Banca d'Italia UIF per IT branch)
- **UK NCA** — National Crime Agency (formato SAR Online)
- **US FinCEN** — Form 8300 / SAR-SAR Form via BSA E-Filing

Draft generato come `SarDraft` row con narrative templated; review human obbligatoria; submission manuale (NO auto-file — compliance officer signs).

### 1.5 Multi-jurisdiction toggle

`tenants/<id>.json` campo `kyc.jurisdictions: string[]` — array di codici ISO. Es:
- `ws` (boutique CH) → `["CH"]` baseline + `["EU"]` se cliente EU resident
- `az` (banca-affilata IT) → `["CH","EU"]` per clienti dual + `["IT"]` per FIU UIF
- `cii3` (UHNW MENA) → `["CH","EU","UK","US","UAE"]` (CDD+EDD universale)

Ogni checkpoint legge `jurisdictions` da context e attiva sub-rule specifiche (es. PEP list source: `OFAC` for US, `HMT` for UK, `SECO` for CH).

---

## §2 · Modello concettuale (architettura PROTOTYPE-PHASE → PRODUCTION)

```
┌──────────────────────────────────────────────────────────────────────────────┐
│  Frontend Next.js (apps/web)                                                 │
│   ├─ /aml-kyc/onboarding/[clientId]      [COMPLIANCE_OFFICER, ADVISOR]       │
│   │   wizard 17-step, progress bar, doc upload, narrative input              │
│   ├─ /aml-kyc/queue                       [COMPLIANCE_OFFICER]               │
│   │   review queue (REVIEW + PENDING_DOC + EDD-triggered)                    │
│   ├─ /aml-kyc/alerts                      [COMPLIANCE_OFFICER]               │
│   │   AML transaction alert dashboard (HOLD queue + INFO history)            │
│   ├─ /aml-kyc/sar/[id]                    [MLRO]                             │
│   │   SAR draft editor + jurisdiction toggle + submission audit              │
│   └─ /aml-kyc/risk-score/[clientId]       [ADVISOR, COMPLIANCE_OFFICER]      │
│       breakdown 17-checkpoint + score evolution timeline                     │
└──────────────────────────────────────────────────────────────────────────────┘
                                    │ cookie valo_token
                                    ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  NestJS API :4010 / :4020 (apps/api/src/modules/aml-kyc/)                    │
│   ├─ aml-kyc.module.ts                                                       │
│   ├─ aml-kyc.controller.ts (Roles COMPLIANCE_OFFICER, ADVISOR, MLRO, SUP/ADM)│
│   │   POST /aml-kyc/onboarding/start                                         │
│   │   POST /aml-kyc/onboarding/:clientId/checkpoint/:n                       │
│   │   POST /aml-kyc/check/sanction                                           │
│   │   POST /aml-kyc/check/pep                                                │
│   │   POST /aml-kyc/check/adverse-media                                      │
│   │   GET  /aml-kyc/risk-score/:clientId                                     │
│   │   POST /aml-kyc/sar/draft                                                │
│   │   GET  /aml-kyc/queue (REVIEW status)                                    │
│   │   POST /aml-kyc/edd/trigger/:clientId                                    │
│   ├─ services/onboarding-orchestrator.service.ts                             │
│   │   esegue 17 checkpoint sequenziali, persiste KycCheck row per ognuno     │
│   ├─ services/sanction-screening.service.ts                                  │
│   │   provider abstraction: World-Check (Refinitiv) / Dow Jones / open-data  │
│   │   refs OFAC/EU/UK-HMT/SECO list — fuzzy match Levenshtein <3              │
│   ├─ services/pep-screening.service.ts                                       │
│   │   PEP list provider + family/associate match (1° + 2° grado)             │
│   ├─ services/adverse-media.service.ts                                       │
│   │   news search + court records + LLM summarizer (cascade Tier C)          │
│   ├─ services/risk-score-aggregator.service.ts                               │
│   │   weighted sum 17-checkpoint → riskScore [0,100] + tier LOW/MED/HIGH/PROH│
│   ├─ services/transaction-monitor.service.ts                                 │
│   │   real-time engine: rule-based + behavior ML + network analysis          │
│   │   listen banking-integration outbox (pg_notify 'tx-feed')                │
│   ├─ services/sar-drafter.service.ts                                         │
│   │   templated narrative + jurisdiction-specific format                     │
│   ├─ services/edd-orchestrator.service.ts                                    │
│   │   workflow EDD escalation + senior compliance review queue               │
│   ├─ aml-kyc.cron.ts — daily 02:00 CET                                       │
│   │   periodic-review-sweeper: reload riskScore stale (>cadence threshold)   │
│   │   sanction-list-refresher: weekly OFAC/EU/UK/SECO snapshot               │
│   └─ types/zod schemas (KycCheckpointInput, SarDraftInput, AmlAlertEvent)    │
└──────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
   ┌──────────────────────────────┐  ┌──────────────────────────────┐
   │ valoswiss-vault-pii          │  │ valoswiss-doc-intelligence   │
   │ envelope encryption KEK+DEK  │  │ OCR ID + biometric           │
   │ (PII storage all KYC docs)   │  │ + document authenticity      │
   └──────────────────────────────┘  └──────────────────────────────┘
                                    │
                                    ▼
   ┌──────────────────────────────┐  ┌──────────────────────────────┐
   │ valoswiss-banking-integration│  │ valoswiss-compliance-audit   │
   │ transaction feed outbox      │  │ AuditLog forensic trail      │
   │ pg_notify 'tx-feed'          │  │ ipHash SHA256 + retention 10y│
   └──────────────────────────────┘  └──────────────────────────────┘

[Postgres]
  KycCheck             — 17 row per clientId
  AmlAlert             — transaction-level


…[truncato — apri il file MD per testo completo]