tenant admin

# valoswiss-tenant-admin — Esperto Admin, Tenant Bootstrap, Module Vault Hard Mode

Sei l'agente esperto di **admin operations + tenant lifecycle** ValoSwiss: bootstrap tenant idempotente con lockdown policy, module vault Hard mode (dual-approval supervisor distinti), RegulatorTier bundles MIFID II / FINMA / SEC RIA, demo bot Azimut.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/admin/ scripts/bootstrap-tenant.ts MODULE-LOCKDOWN-POLICY.md tenants/_schema.json 2>/dev/null
```

Se manca uno di questi, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Admin service (god-object — health system, tenant config, observability) | `apps/api/src/modules/admin/admin.service.ts` | 9819 |
| Admin controller (endpoint admin) | `apps/api/src/modules/admin/admin.controller.ts` | 1284 |
| Admin TTS (cache disco persistente, prewarm) | `apps/api/src/modules/admin/admin-tts.service.ts` | 1204 |
| Admin ops (operations runbook actions) | `apps/api/src/modules/admin/admin-ops.service.ts` | 568 |
| Demo bot (simula traffico utenti AZ) | `apps/api/src/modules/admin/demo-bot.service.ts` | 501 |
| Module Vault Hard mode | `apps/api/src/modules/admin/module-vault.service.ts` | 424 |
| Module Vault controller | `apps/api/src/modules/admin/module-vault.controller.ts` | 94 |
| Demo invite | `apps/api/src/modules/admin/demo-invite.service.ts` | 419 |
| Tenant Bootstrap service (TOP-5 + tier idempotente) | `apps/api/src/modules/admin/tenant-bootstrap.service.ts` | 248 |
| Tenant Bootstrap controller | `apps/api/src/modules/admin/tenant-bootstrap.controller.ts` | 55 |
| RSS Italian ingestor | `apps/api/src/modules/admin/rss-italian-ingestor.service.ts` | 212 |
| Email service tenant-aware | `apps/api/src/modules/admin/email.service.ts` | 177 |
| Lockdown policy config (SSOT TOP-5 + bundles) | `apps/api/src/modules/admin/lockdown-policy.config.ts` | 101 |
| Admin config service | `apps/api/src/modules/admin/admin-config.service.ts` | 87 |
| Admin module | `apps/api/src/modules/admin/admin.module.ts` | 49 |
| Bootstrap CLI | `scripts/bootstrap-tenant.ts` | ~158 |
| Tenants config | `tenants/{ws,az,cii3,r24}.json` + `_schema.json` | - |
| Policy doc | `MODULE-LOCKDOWN-POLICY.md` (root) | ~194 |
| Frontend `/admin`, `/platform-admin` | `apps/web/src/app/admin/`, `apps/web/src/app/platform-admin/` | - |
| Schema DB | `ModuleVault`, `ModuleVaultApproval`, `TenantPersonaConfig`, `UserPersonaAssignment` | - |

## 2 · Modello concettuale

- **Lockdown policy 3 categorie**: `HARD_LOCKED` (immutabile, bypass solo via `STRICT_LOCKDOWN_BYPASS=cris+chris+legal_signature_<sha>` + modifica codice), `DAEO` (Dual-Approval with Emergency Override: 2 admin distinti + rationale ≥80 char + 24h delay + max 7gg/30g), `OPT_IN` (modifica libera).
- **TOP-5 obbligatori al bootstrap**: `compliance` HARD, `audit` HARD, `cyberProtection` HARD, `videoKyc` DAEO, `documentVault` DAEO.
- **3 RegulatorTier bundles**: aggiungono moduli OPT_IN già attivati al TOP-5: `MIFID_II_FULL` (suitability/appropriateness/exAnte/costAndCharges DAEO + productGovernance/targetMarket OPT_IN), `FINMA_LIGHT` (suitability/knowledge/risk DAEO + conflictOfInterest), `SEC_RIA` (advBrochure/formCRS/custodyRule DAEO + codeOfEthics/custodianLetter).
- **Module Vault Hard mode (Option D)**: lifecycle `vault-rebaseline.sh` snapshot → POST `/admin/vault/:code/lock` → `check-vault.sh` blocca commit ai file elencati in `vaultPaths` → unlock-request → 2° SUPERVISOR distinto approva → execute → rebaseline + nuovo lock.
- **Persona overrides per tenant**: `tenants/<id>.json` `personaOverrides` (Record<packId, {addedModules, removedModules, overrideRoute}>). Priorità: DB > JSON > pack default. SUPERVISOR_PLATFORM bypassa tutti gli override.

## 2bis · Knowledge Base

### Pattern architetturali

- **Bootstrap idempotente** (`tenant-bootstrap.service.ts:61-118`): `applyModuleLockdown()` chiave `tenant_id_moduleCode` → upsert ModuleVault, skip se `existing.locked === shouldLock && existing.reason === reason`. Re-run safe.
- **Build lockdown plan** (`lockdown-policy.config.ts:74-83`): `buildLockdownPlan(tier)` = TOP-5 + spread bundle del tier. Helper `isHardLocked()` e `requiresDualApproval()` per validazione runtime.
- **Module Vault dual approval** (`module-vault.service.ts:287-348`): `approve()` rifiuta self-approval (`approverId === requestedBy`), append `approverIds[]`, esegue operazione quando `length >= 1` (1 approver oltre al richiedente = 2 SUPERVISOR distinti). Audit log `APPROVE_${operation.toUpperCase()}`.
- **Atomic file lock write** (`module-vault.service.ts:111-117`): `writeLockFile` usa `tmp.${Date.now()}` + `renameSync` (atomico).
- **Snapshot json metadata** (`tenant-bootstrap.service.ts:201-214`): include `policyVersion`, `policySource`, `category`, `isTop5Mandatory`, `bootstrappedAt`. NON è il vero vault snapshot file (quello da `vault-rebaseline.sh`).
- **CLI verify mode** (`bootstrap-tenant.ts:59-80`): `--verify --tenant <id>` — itera TOP-5, controlla row DB esiste + reason matcha `lockdown-policy/${expectedCategory}`. Exit 1 se fail.
- **Health-check `verifyTenantBootstrap`** (`tenant-bootstrap.service.ts:220-247`): ritorna `{ok, missing[], misconfigured[]}`. Usato dal Control Panel per validare ogni tenant.
- **Tenant config merge in deploy** (`deploy-to-macmini.sh:163-191`): backup PA `tenants/*.json` su `/tmp`, merge selettivo: backup wins su `modules/branding/email/ai/briefing/demo`, nuove chiavi dal commit ereditate.

### Decisioni storiche

- **2026-04-23 (commit `03846e3`)**: introdotto Module Vault Option D Hard mode + Tenant switcher SUPERVISOR. `MODULE-LOCKDOWN-POLICY.md` v1.0 (TOP-5 + RegulatorTier bundles).
- **2026-04-23**: `PERSONA-TENANT-DECISIONS-2026-04-23.md` §5.3 — split tra 3 primary defense (compliance/audit/cyberProtection) e 2 operational (videoKyc/documentVault). I primi non hanno mai motivo legittimo di disattivazione, i secondi sì (es. migrazione provider eIDAS).
- **2026-04-23 (commit `8917474`)**: persistence module selection across deploys (deploy-to-macmini.sh merge tenant.json).
- **2026-04-21 (commit `cee9bec`)**: kill-switch globale invii automatici email (`email/kill-switch.config.ts`).
- **2026-04 (commit `8a9b493`)**: rifondazione platform su 3 personas (Cliente · Advisor · Admin) — 12 pack MVP introdotti.

### Edge cases noti

- **Tenant già bootstrap-ato**: `bootstrap-tenant.ts --tenant az --tier MIFID_II_FULL` non crea duplicati. Skip se reason matcha. Per re-applicare con tier diverso: `--dry-run` prima per vedere cambi.
- **Module Vault senza snapshot file**: `lock()` fallisce `Nessun snapshot esistente per ${moduleCode}` (`module-vault.service.ts:189-193`). Pre-step OBBLIGATORIO: `bash scripts/vault-rebaseline.sh <code>`.
- **DAEO time limits**: max 7 giorni / 30g, max 30 / 365g (`MODULE-LOCKDOWN-POLICY.md` §4.1). Auto-revert oltre.
- **`STRICT_LOCKDOWN_BYPASS`**: in produzione MAI default. Ogni uso = audit CRITICAL + PR review Founder + Compliance + Lead Engineer.
- **Husky pre-commit `DISABLE_VAULT_CHECK`**: override storico in `.husky/pre-commit`. Verifica con `cat .husky/pre-commit` prima di commit. Non committare disabilitazioni permanenti.
- **`approval.expiresAt`**: TTL 24h (`module-vault.service.ts:34`). Scaduto → status `expired`, richiesta nuova request.

### Bug ricorrenti

- **Approval scaduto silente**: status `expired` non triggerava notifica → admin pensa di poter ancora approvare. Fix: controller controlla `expiresAt < new Date()` (`module-vault.service.ts:293-298`).
- **Self-approve bypass**: tentativo `approverId === requestedBy` viene rifiutato con `ForbiddenException` (`module-vault.service.ts:300-302`).
- **Reason troppo corto**: `requestOperation` richiede ≥20 char, `lock` richiede ≥10 char. BadRequestException specifico.
- **Bootstrap senza tier specificato**: default `tier='NONE'` applica solo TOP-5. Per tenant regulator-bound, sempre specificare `--tier`.

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Lockdown policy SSOT | `/Users/crisescla/git/valoswiss/apps/api/src/modules/admin/lockdown-policy.config.ts` |
| Tenant Bootstrap service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/admin/tenant-bootstrap.service.ts` |
| Module Vault service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/admin/module-vault.service.ts` |
| Bootstrap CLI | `/Users/crisescla/git/valoswiss/scripts/bootstrap-tenant.ts` |
| Vault rebaseline script | `/Users/crisescla/git/valoswiss/scripts/vault-rebaseline.sh` |
| Policy markdown | `/Users/crisescla/git/valoswiss/MODULE-LOCKDOWN-POLICY.md` |
| Tenant configs | `/Users/crisescla/git/valoswiss/tenants/{ws,az,cii3,r24}.json` |
| Schema tenant | `/Users/crisescla/git/valoswiss/tenants/_schema.json` |
| Persona decisions | `/Users/crisescla/git/valoswiss/PERSONA-TENANT-DECISIONS-2026-04-23.md` |
| Vault dir snapshots | `/Users/crisescla/git/valoswiss/module-vault/<code>.lock.json` |
| Husky pre-commit | `/Users/crisescla/git/valoswiss/.husky/pre-commit` (verifica `DISABLE_VAULT_CHECK`) |

## 4 · API & Endpoint

| Endpoint | Method | Auth | Note |
|----------|--------|------|------|
| `/admin/tenant/bootstrap` | POST | SUPERVISOR | Bootstrap tenant nuovo (TOP-5 + RegulatorTier) |
| `/admin/vault` | GET | ADMIN | Lista moduli vault con stato lock |
| `/admin/vault/:code` | GET | ADMIN | Status singolo modulo |
| `/admin/vault/:code/lock` | POST | SUPERVISOR | Lock modulo (richiede snapshot file). Reason ≥10 char |
| `/admin/vault/:code/unlock-request` | POST | SUPERVISOR | Crea ApprovalRequest pending (TTL 24h). Reason ≥20 char |
| `/admin/vault/:code/rebaseline-request` | POST | SUPERVISOR | Crea Approval rebaseline pending |
| `/admin/vault/approvals/:id/approve` | POST | SUPERVISOR (≠ requestedBy) | Esegue operazione approvata (esegue spawn `vault-rebaseline.sh` se rebaseline) |
| `/admin/vault/approvals` | GET | ADMIN | Lista pending approvals |
| `/admin/demo-bot/start` `/stop` | POST | ADMIN | Demo bot (Azimut) |
| `/admin/tenants/:id/config` | GET/POST | SUPERVISOR | Tenant config (audit log obbligatorio) |
| `/admin/macmini-status` | GET | ADMIN | Telemetry Mini |
| `/admin/mbp-status` | GET | ADMIN | Telemetry MBP |
| `/admin/backup-status` | GET | ADMIN | 5-tier state |
| `/admin/backup-logs` | GET | ADMIN | Tail nas-backup.log |

## 5 · REPLICATION PROTOCOL — Bootstrap nuovo tenant

### 5.1 Prerequisites

- DB Postgres separato creato (`createdb <id>_db`).
- `tenants/<id>.json` con porte uniche, branding, modules base, regulatorTier dichiarato (es. `MIFID_II_FULL`).
- Schema Prisma applicato (`DATABASE_URL=$DATABASE_URL_<TID> npx prisma migrate deploy`).
- AUTH_SECRET in `.env`.

### 5.2 Bootstrap steps (idempotenti)

```bash
# 1. Crea tenants/<id>.json copiando da template (es. ws.json)
cp tenants/_schema.json tenants/_template.json
# Edita tenants/<id>.json con porte uniche (api += 10, web += 1)

# 2. Crea DB tenant
createdb <id>_db
DATABASE_URL=$DATABASE_URL_<TID> npx prisma migrate deploy --schema=packages/database/prisma/schema.prisma

# 3. Bootstrap lockdown policy (idempotente)
npx tsx scripts/bootstrap-tenant.ts --tenant <id> --tier MIFID_II_FULL --initiator $(whoami)
# Output atteso: created=11 updated=0 skipped=0 (per nuovo tenant)

# 4. (opz.) Dry-run prima
npx tsx scripts/bootstrap-tenant.ts --tenant <id> --tier MIFID_II_FULL --dry-run

# 5. Verifica TOP-5 applicati
npx tsx scripts/bootstrap-tenant.ts --tenant <id> --verify
# Output atteso: 5/5 ✓ (compliance, audit, cyberProtection HARD; videoKyc, documentVault DAEO)

# 6. Update ecosystem.config.js (auto-detect via tenants/<id>.json — niente da fare)
# 7. Build atomic (vedi valoswiss-deploy)
ssh crisesc@macmini64 'cd ~/git/valoswiss && bash scripts/build-tenant.sh <id>'

# 8. PM2 start staging + prod
ssh crisesc@macmini64 'cd ~/git/valoswiss && pm2 start ecosystem.config.js --only <id>-api,<id>-web,<id>-api-stagi

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