banking integration

# valoswiss-banking-integration (35°)

**Macro-categoria**: 🏦 DOMINI SINGOLI (aggregazione bancaria multi-provider)
**Scope**: PSD2/XS2A/Open Finance account aggregation EU+UK+CH, FinTS HBCI per DACH, OAuth2 SCA flow centrale, webhook real-time, fallback browser-agent per banche CH private legacy
**Born**: 2026-05-03 (W1 OBP-API + open-banking-gateway wiring + W2 NestJS module + W3 OAuth2 SCA flow + W4 webhook ingestion + W5 FinTS HBCI DACH + W6 fallback browser-agent + W7 reconciliation portfolio)
**Owner downstream**: ADVISOR (lettura saldi/movimenti cliente) · SUPERVISOR/ADMIN (gestione connessioni + consent + webhook + cost)
**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**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **NestJS module health**
   ```bash
   curl -s http://127.0.0.1:4010/api/banking/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ status:'ok', providers:['obp','adorsys','plaid','truelayer','finapi','akoya','tink'], webhookEndpoint:'active', sca:'oauth2-central' }`.
3. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le 4 model `BankConnection` + `BankAccount` + `BankTransaction` + `BankConsent` + enum `BankConnectionStatus` + enum `BankProvider` + enum `TransactionStatus` siano applicati (migration `banking_integration_w2` idempotent V15).
4. **Consent freshness** (verifica che nessun consent sia scaduto):
   ```bash
   curl -s http://127.0.0.1:4010/api/banking/admin/consents/expired \
     -H "Cookie: valo_token=<admin-token>"
   ```
   Deve ritornare array vuoto. Se non vuoto → trigger consent renewal flow per ogni voce.
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"bankingIntegration": true` subito dopo `portfolio`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'bankingIntegration'` in `defaultModules` per `ADVISOR` + `SUPERVISOR` + `ADMIN` (NON in PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL — dati bancari raw non esposti al cliente).
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `bankingIntegration` con `sidebarSection: 'DATI'`, `requiredRole: 'ADVISOR'`, `personaHint: 'banking'`, icon `🏦`.
8. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §3), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic`.

Se uno qualunque dei 7 punti fallisce, **fermati e annota la deviazione** prima di procedere — la 3-Point Registration V16 è invariante non negoziabile (vedi `feedback_new_module_registration.md`).

---

## §1 · Aree di competenza

### 1.1 Reference repos

| Repo | License | Stars | Ruolo in ValoSwiss |
|---|---|---|---|
| **OpenBankProject/OBP-API** | AGPL 3.0 | 3.1k | PSD2 + XS2A + Open Finance API layer; self-hosted o cloud OBP; gateway multi-bank |
| **adorsys/open-banking-gateway** | Apache 2.0 | 1.2k | PSD2 + XS2A + HBCI/FinTS; TPP gateway; SCA flow; adorsys DACH specialist |
| **ExtraBB/open-psd2** | Apache 2.0 | 340 | lightweight PSD2 parser + XS2A schema validation library |
| **Plaid SDK** | proprietary | — | US + EU: account/transaction aggregation via Plaid Link OAuth; fallback provider |
| **TrueLayer** | proprietary | — | UK + EU: Open Banking aggregation; real-time payment initiation PIS |
| **finAPI** | proprietary | — | DACH specialist: FinTS HBCI + PSD2 + scraping fallback |
| **Akoya** | proprietary | — | US FDX: premium data access network per banche americane |
| **Tink** | proprietary (Visa) | — | EU PSD2 aggregator (Nordea, BNP, ING, UniCredit, PostFinance CH) |

### 1.2 Provider coverage matrix

| Provider | Paesi | Protocollo | SCA | ValoSwiss use case |
|---|---|---|---|---|
| OBP-API + adorsys gateway | EU+UK | PSD2/XS2A REST | OAuth2 PKCE | Primary EU banking layer |
| TrueLayer | UK+EU | Open Banking UK + PSD2 | OAuth2 | UK HNW clienti; real-time payment check |
| Tink (Visa) | EU-15 | PSD2 + proprietary | OAuth2 | PostFinance CH + BNP + ING + UniCredit |
| finAPI | DACH | FinTS HBCI + PSD2 | HBCI PIN/TAN + OAuth2 | UBS, Credit Suisse legacy, Zürcher KB, cantonal banks CH |
| Plaid | US+EU | OAuth2 Link | OAuth2 | clienti US family office; EU limited |
| Akoya | US | FDX standard | OAuth2 | clienti US premium banche americane |
| adorsys gateway | DACH+EU | FinTS HBCI + XS2A | PIN/TAN + decoupled | Fallback DACH banche non-PSD2 |
| browser-agent scraping | CH private | N/A — visual scraping | credential vault | Pictet, Lombard Odier, Julius Baer legacy |

### 1.3 OAuth2 SCA flow centrale

Il flow SCA (Strong Customer Authentication) è gestito centralmente da `BankingIntegrationService.initSCAFlow()`. Nessun modulo downstream gestisce credenziali bancarie direttamente.

```
┌──────────────────────────────────────────────────────────────────────┐
│  Flow OAuth2 SCA centrale (W3)                                        │
│                                                                       │
│  1. ADVISOR richiede connessione banca (POST /api/banking/connect)   │
│  2. NestJS genera state + PKCE code_verifier + code_challenge         │
│  3. Redirect ADVISOR → Authorization URL banca (via provider SDK)    │
│  4. Banca autentica + SCA (OTP SMS / app / token hardware)            │
│  5. Redirect callback → /api/banking/oauth2/callback?code=&state=    │
│  6. NestJS: exchange code → access_token + refresh_token             │
│  7. Token vault-pii encryption + persist BankConsent                  │
│  8. Fetch initial accounts/balances → BankAccount upsert             │
│  9. Subscribe webhook per transaction push (se provider supporta)    │
│ 10. Polling fallback 15min se webhook non disponibile                 │
└──────────────────────────────────────────────────────────────────────┘
```

### 1.4 FinTS HBCI flow (DACH legacy)

```
┌──────────────────────────────────────────────────────────────────────┐
│  FinTS HBCI flow via adorsys gateway (W5)                            │
│                                                                       │
│  1. ADVISOR inserisce IBAN + BIC + credenziali (vault-pii encrypted) │
│  2. NestJS → adorsys gateway POST /v1/bank-accesses                  │
│  3. adorsys inizia FinTS dialog con banca HBCI server                │
│  4. SCA: HBCI PIN/TAN (Chip TAN, SMS TAN, App TAN)                   │
│  5. adorsys ritorna bank-access-id + account list                    │
│  6. NestJS: persist BankConnection + BankAccount                     │
│  7. Polling sync ogni 4h via adorsys /v1/bank-accesses/:id/sync      │
│  8. Transaction delta → BankTransaction upsert idempotente           │
└──────────────────────────────────────────────────────────────────────┘
```

### 1.5 Fallback browser-agent (CH private banks)

Per banche CH private senza PSD2 (Pictet, Lombard Odier, Julius Baer online, EFG, Vontobel):

1. ADMIN configura credenziali banco in `vault-pii` (encrypted, zero-knowledge per NestJS)
2. `BankingIntegrationService.triggerBrowserAgentScrape(bankConnectionId)` chiama `valoswiss-browser-agent`
3. browser-agent esegue login + navigazione + download estratto PDF/CSV
4. PDF → `doc-intelligence` per structured parsing
5. Output → `BankTransaction` upsert idempotente stesso schema PSD2 standard

### 1.6 Persona visibility

- **ADVISOR**: visualizza saldi + movimenti dei propri clienti assegnati; trigger manuale refresh; read-only
- **SUPERVISOR**: cross-tenant view; può aggiungere/rimuovere connessioni bancarie; gestisce consent renewal
- **ADMIN**: full access; webhook management; provider config; browser-agent trigger; cost ledger
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO — dati bancari raw non esposti via UI/API al cliente finale; il cliente vede solo aggregazioni in `portfolio`

---

## §2 · Pattern di codice

### 2.1 Prisma schema (migration `banking_integration_w2` — idempotent V15)

```prisma
enum BankConnectionStatus {
  PENDING_SCA
  ACTIVE
  CONSENT_EXPIRED
  ERROR
  DISCONNECTED
}

enum BankProvider {
  OBP_API
  ADORSYS
  TRUELAYER
  TINK
  FINAPI
  PLAID
  AKOYA
  BROWSER_AGENT
}

enum TransactionStatus {
  PENDING
  BOOKED
  INFORMATION
  CANCELLED
}

model BankConsent {
  id               String    @id @default(uuid())
  bankConnectionId String    @unique
  connection       BankConnection @relation(fields: [bankConnectionId], references: [id], onDelete: Cascade)
  accessTokenHash  String    // vault-pii encrypted hash (NON token plain!)
  refreshTokenHash String?
  expiresAt        DateTime
  scopes           String[]
  grantedAt        DateTime  @default(now())
  revokedAt        DateTime?
  createdAt        DateTime  @default(now())
  updatedAt        DateTime  @updatedAt
}

model BankConnection {
  id            String               @id @default(uuid())
  tenantSlug    String
  clientUserId  String               // FK → User
  provider      BankProvider
  bankBic       String
  bankName      String
  iban          String?
  status        BankConnectionStatus @default(PENDING_SCA)
  lastSyncAt    DateTime?
  errorMessage  String?
  consent       BankConsent?
  accounts      BankAccount[]
  createdAt     DateTime             @default(now())
  updatedAt     DateTime             @updatedAt

  @@index([tenantSlug, clientUserId])
  @@index([tenantSlug, status])
  @@index([provider, bankBic])
}

model BankAccount {
  id               String           @id @default(uuid())
  bankConnectionId String
  connection       BankConnection   @relation(fields: [bankConnectionId], references: [id], onDelete: Cascade)
  externalAccountId String          // provider-specific account ID
  iban             String?
  currency         String           // ISO 4217
  accountType      String           // CURRENT | SAVINGS | INVESTMENT | LOAN
  name             String?
  balanceCurrent   Decimal?         @db.Decimal(18, 4)
  balanceAvailable Decimal?         @db.Decimal(18, 4)
  balanceAsOf      DateTime?
  transactions     BankTransaction[]
  createdAt        DateTime         @default(now())
  updatedAt        DateTime         @updatedAt

  @@index([bankConnectionId])
  @@index([iban])
  @@unique([bankConnectionId, externalAccountId])
}

model BankTransaction {
  id              String            @id @default(uuid())
  bankAccountId   String
  account         BankAccount       @relation(fields: [bankAccountId], references: [id], onDelete: Cascade)
  externalTxId    String            // provider-specific tx ID (idempotent upsert key)
  status          TransactionStatus @default(BOOKED)
  amount          Decimal           @db.Decimal(18, 4)
  currency        String
  bookingDate     DateTime?
  valueDate       DateTime?
  creditorName    String?
  debtorName      String?
  remittanceInfo  String?
  purpose         String?
  category        String?           // filled by tax-fees categorization
  merchantName    String?
  merchantCategory String?          // MCC code
  rawJson         Json?             // provider full payload (JSONB)
  createdAt       DateTime          @default(now())
  updatedAt       DateTime          @updatedAt

  @@unique([bankAccountId, externalTxId])  // idempotent upsert
  @@index([bankAccountId, bookingDate(sort: Desc)])
  @@index([bankAccountId, status])
  @@index([tenantSlug: false])  // via relation bankAccountId → bankConnectionId → tenantSlug
}
```

**Wave 1.6 — getter espliciti** su `TenantPrismaService`:
```typescript
// apps/api/src/common/tenant-prisma/tenant-prisma.service.ts
get bankConnection() { return this.client.bankConnection; }
get bankAccount() { return this.client.bankAccount; }
get bankTransaction() { return this.client.bankTransaction; }
get bankConsent() { return this.client.bankConsent; }
```
NON usare legacy cast as-any su prisma — pre-commit triage blocca.

### 2.2 NestJS service — 

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