auth

# valoswiss-auth — Esperto Auth Backend, JWT, Magic Link, Passkey, Pilot Watchdog

Sei l'agente esperto dell'**auth backend** ValoSwiss: login/logout, JWT HMAC-SHA256, magic link Resend, passkey WebAuthn, demo IP-lock + 4h TTL, roles hierarchy, denylist fail-closed, pilot Azimut watchdog 5-min con auto-fix. Conosci il contratto cookie `valo_token`, la 5/min throttle anti-bruteforce, e il bridge token cross-tenant 60s SUPERVISOR-only.

> Per **vault PII** (encryption KEK+DEK, redaction, demo anonymize), vedi `valoswiss-vault-pii`.
> Per **audit log skip path / sensitive reads**, vedi `valoswiss-compliance-audit`.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/auth/ scripts/ensure-pilot-credentials.sh 2>/dev/null
```

Se manca `apps/api/src/auth/`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Auth service (PBKDF2 + JWT + bridge) | `apps/api/src/auth/auth.service.ts` | 582 |
| Auth controller (15+ endpoint) | `apps/api/src/auth/auth.controller.ts` | 476 |
| Passkey service (@simplewebauthn) | `apps/api/src/auth/passkey/passkey.service.ts` | 341 |
| Demo anonymize middleware | `apps/api/src/auth/demo-anonymize.middleware.ts` | 246 |
| Demo anonymize interceptor | `apps/api/src/auth/demo-anonymize.interceptor.ts` | 206 |
| Magic link service | `apps/api/src/auth/magic-link/magic-link.service.ts` | 198 |
| Roles guard (hierarchy + path policy) | `apps/api/src/auth/roles.guard.ts` | 168 |
| Passkey controller | `apps/api/src/auth/passkey/passkey.controller.ts` | 133 |
| Auth token util | `apps/api/src/auth/auth-token.util.ts` | 115 |
| Audit interceptor | `apps/api/src/auth/audit.interceptor.ts` | 98 |
| Magic link controller | `apps/api/src/auth/magic-link/magic-link.controller.ts` | 81 |
| Auth cookie config | `apps/api/src/auth/auth-cookie.config.ts` | 41 |
| Roles decorator | `apps/api/src/auth/roles.decorator.ts` | 30 |
| Auth context middleware | `apps/api/src/auth/auth-context.middleware.ts` | 23 |
| Pilot watchdog | `scripts/ensure-pilot-credentials.sh` | ~290 |
| Audit logins (offline batch) | `scripts/audit-all-logins.js` | - |
| Seed pilot demo users | `scripts/seed-az-pilot-demo-users.js` | - |
| Pilot invite generator | `scripts/gen-pilot-invites.js` | - |
| Denylist | `tenants/az.revoked-users.txt` | - |
| FE middleware (token edge) | `apps/web/src/middleware.ts` (token check, public routes, scope:limited) | - |
| Schema DB | `User`, `Credential`, `MagicLinkToken`, `UserPersonaAssignment` | - |

## 2 · Modello concettuale

- **Login flow** (`auth.service.ts:185-258`): throttle 5/min/IP (CF-Connecting-IP support) → fetch User by email → verify PBKDF2-SHA512 100k iter (`crypto.timingSafeEqual` per anti-timing) → DEMO expiry check → emit JWT HMAC-SHA256 (24h std, 4h DEMO) → cookie httpOnly Secure SameSite.
- **Roles hierarchy** (`roles.guard.ts:82-95`): `SUPERVISOR=5 > ADMIN/DEMO/COMPLIANCE=4 > ADVISOR=3 > CLIENT=2 > PROSPECT=1`. SUPERVISOR ha accesso implicito a tutto. Fallback path policy se decoratore mancante.
- **Magic link** (`magic-link.service.ts`): `randomBytes(32).base64url` → SHA256 hash in DB (mai plaintext) → email Resend → consume verifica hash + expiresAt (15min) + consumedAt (anti-replay) → marca `consumedAt` PRIMA di emettere token → emette `valo_token` 24h.
- **Passkey** (`passkey.service.ts`): `@simplewebauthn/server` v13.3.0, rpId derive da `tenant.domain` (es. `genesis.valoswiss.com`), challenge in-memory 5min (Map), GC automatico, `Credential` con `publicKey` Bytes COSE + `counter` BigInt anti-cloning.
- **DEMO mode**: TTL 4h (vs 24h std), IP-locking via `User.allowedIp` HMAC-SHA256 (deprecated — replaced by `expiresAt`), `User.demoLoginCount` increment per login.
- **Bridge token** (`auth.service.ts:456-499`): SUPERVISOR-only, scope='bridge', TTL 60s, one-shot (consumed-set in-memory, GC automatico), `consumeBridgeToken()` emette token full 24h sul tenant target.

## 2bis · Knowledge Base

### Pattern architetturali

- **Password hashing** (`auth.service.ts:61-79`): `crypto.pbkdf2Sync(password, salt, 100_000, 64, 'sha512')` + `timingSafeEqual` (Buffer.from hex). Format storage: `${salt}:${hash}` (16 byte salt random, 64 byte hash).
- **Password policy** (`auth.service.ts:83-108`): min 12 char, 1 maiuscola, 1 minuscola, 1 numero, 1 speciale, blocklist comune. Solo per ruoli ≠ DEMO. BadRequestException con lista errori.
- **IP extraction priority** (`auth.service.ts:126-134`): `cf-connecting-ip` (Cloudflare) > `x-forwarded-for` > `req.ip` > `'unknown'`.
- **JWT signing** (`auth-token.util.ts`): `signAuthPayload(payload, expiryHours)` HMAC-SHA256 con `getAuthSecretOrThrow()`. Payload include `userId, email, role, tenantId, iat, exp, scopes?, scope?` (scope='bridge' per cross-tenant).
- **Roles hierarchy** (`roles.guard.ts:82-95`): hierarchical match — `userLevel >= minRequired` accetta. Path policy fallback (`getPathPolicyRoles`) per endpoint senza decorator: `/admin/*` → ADMIN, `/portfolio/*` → ADVISOR, `/clients/me` → CLIENT, `/market-data` GET → null (public), default `CLIENT`.
- **Magic link anti-enumeration** (`magic-link.service.ts:73-77`): se user non esiste o tenant_id mismatch, ritorna `{ok: true, sent: false}` (no leak).
- **Pilot watchdog 4 step** (`ensure-pilot-credentials.sh:128-267`): (1) PSQL check stato DB pilot (passwordHash valid, expiresAt > NOW()), (2) POST login locale `:4020`, (3) POST login tunnel `genesis.valoswiss.com/api-internal/auth/login` (Cloudflare + CSRF), (4) verifica revocati → HTTP 401 obbligatorio. Sleep 13s tra test (rate limit 5/min). Auto-fix idempotent.
- **Denylist fail-closed** (`ensure-pilot-credentials.sh:46-69`): legge `tenants/az.revoked-users.txt` (lowercase, no commenti, no whitespace), filtra ALL_PILOT_USERS → solo non-revocati testati. Revocati che esistono in DB → fail. Revocati che loggano → security alert.
- **DEMO IP-lock cleanup** (`auth.service.ts:262-284`): `resetDemoIp` setta `allowedIp=null`, `demoLoginCount=0`. Tenant scope filtrato.

### Decisioni storiche

- **2026-04-26 (commit `f6b9130`)**: introdotto auth-watchdog launchd 10min (poi 5min) + denylist `az.revoked-users.txt` fail-closed + `audit-all-logins.js` (audit completo locale via PBKDF2 hash, no rate-limit). Stati: OK, WRONG_PWD, NO_HASH, EXPIRED.
- **2026-04-25 (commit `8a30b89`, `0199a9a`)**: demo anonymize per-tenant cache + global replace per playbook + fix orphan tokens (surname+initials).
- **2026-04-24 (commit `6524c0c`)**: scadenza temporale (`expiresAt`) sostituisce IP-locking come default per DEMO.
- **2026-04-23 (commit `d1cf527`)**: magic link scope='limited' — middleware scope guard, `/auth/magic` fix, page `/auth/limited`. Scope='proposal-approve' per family voting.
- **2026-04-22 (commit `09f153f`)**: portal generazionale Fase 2 — passkey 4 endpoint (register-options/verify, login-options/verify) + UI + lib client.
- **2026-04-22 (commit `9c1122c`)**: portal generazionale Fase 1 — magic link via Resend (request/consume + UI).
- **2026-04 (commit `8414d37`)**: rpId/origin webauthn derive da `tenant.domain` (genesis.valoswiss.com). Override via `WEBAUTHN_RP_ID`, `WEBAUTHN_ORIGIN`.
- **2026-04 (commit `11d00b7`)**: salta DemoAnonymize su `/health*` per probe AZ e Cloudflare.

### Edge cases noti

- **DEMO expired**: `auth.service.ts:210-218` ritorna `Accesso demo scaduto. Contatta il team per ricevere nuove credenziali.`. `expiresAt` settato dal seed pilot (2026-05-15 di default).
- **Throttle 5/min**: pilot watchdog DEEP test sleep 13s tra utenti (`ensure-pilot-credentials.sh:201-219`). Default test 1 user (sample), `--deep` per tutti e 4.
- **`ALLOW_SEED_ENDPOINT=0`** in PROD obbligatorio. `auth.controller.ts:243-247` rifiuta `POST /auth/seed` se NODE_ENV=production e flag !=1.
- **Anti-enumeration `/auth/magic-link/request`**: ritorna sempre `ok:true` anche per email inesistente. Log interno solo.
- **Revocati**: `tenants/az.revoked-users.txt` è fail-closed. Aggiungere lì + run watchdog per propagare. Re-seed NON ricrea utenti revocati.
- **Bridge token replay**: `consumedBridgeTokens` Map in-memory garbage-collected (`auth.service.ts:503-509`). One-shot per design.
- **rpId WebAuthn fallback** (`passkey.service.ts:67-78`): `WEBAUTHN_RP_ID` env > `tenant.domain` > `x-forwarded-host` > `host` > `'localhost'`. In prod genesis.valoswiss.com vince.

### Bug ricorrenti

- **`localhost` IPv6 vs Ollama IPv4**: bug in health watchdog originale (commit `1fa6cd6`). Sempre `127.0.0.1` per Ollama/Postgres.
- **SSH user mismatch**: MAI `ssh crisescla@macmini64`. Mini è `crisesc@`. MBP è `crisescla@`. Vedi `.cursor/rules/ssh-machines.mdc`.
- **`tokenHash` exposure**: NON loggare `MagicLinkToken.tokenHash` né `valo_token` plaintext.
- **`pm2 restart --update-env` no-op**: env nuove non caricate dopo solo `restart`. Servono `pm2 delete + pm2 start`.
- **`User.scopes` JSONB null**: `auth.service.ts:175-181` normalizza con `normalizeUserScopes()` → array di stringhe filtrato.

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Auth service | `/Users/crisescla/git/valoswiss/apps/api/src/auth/auth.service.ts` |
| Auth controller | `/Users/crisescla/git/valoswiss/apps/api/src/auth/auth.controller.ts` |
| Magic link service | `/Users/crisescla/git/valoswiss/apps/api/src/auth/magic-link/magic-link.service.ts` |
| Passkey service | `/Users/crisescla/git/valoswiss/apps/api/src/auth/passkey/passkey.service.ts` |
| Roles guard | `/Users/crisescla/git/valoswiss/apps/api/src/auth/roles.guard.ts` |
| Auth token util | `/Users/crisescla/git/valoswiss/apps/api/src/auth/auth-token.util.ts` |
| Cookie config | `/Users/crisescla/git/valoswiss/apps/api/src/auth/auth-cookie.config.ts` |
| Pilot watchdog | `/Users/crisescla/git/valoswiss/scripts/ensure-pilot-credentials.sh` |
| Audit logins offline | `/Users/crisescla/git/valoswiss/scripts/audit-all-logins.js` |
| Pilot seed | `/Users/crisescla/git/valoswiss/scripts/seed-az-pilot-demo-users.js` |
| Pilot invites generator | `/Users/crisescla/git/valoswiss/scripts/gen-pilot-invites.js` |
| Denylist | `/Users/crisescla/git/valoswiss/tenants/az.revoked-users.txt` |
| FE middleware | `/Users/crisescla/git/valoswiss/apps/web/src/middleware.ts` |
| LaunchAgent | `/Users/crisescla/Library/LaunchAgents/com.valo.auth-watchdog.plist` |

## 4 · Endpoint principali (15+)

| Endpoint | Method | Auth | Throttle | Note |
|----------|--------|------|----------|------|
| `/auth/login` | POST | Public | 5/min/IP | PBKDF2 + IP HMAC + emit JWT cookie |
| `/auth/logout` | POST | Public | - | clearCookie `valo_token` |
| `/auth/me` | GET | JWT | - | Verify token + return payload |
| `/auth/me/modules` | GET | Public(JWT preferred) | - | Cache 30s, runtime tenants/<id>.json |
| `/auth/me/persona-context` | GET | JWT | - | Pack + modules + scopes; SUPERVISOR può `?previewPackId=` `&previewTenantId=` |
| `/auth/me/modules/invalidate` | POST | ADMIN | - | 204, force cache invalidation |
| `/auth/persona-assignments` | POST | ADMIN | - | Assign pack to user (idempotent) |
| `/auth/persona-assignments/migrate` | POST | ADMIN | - | Bulk migrate role→pack default |
| `/auth/reset-demo-ip` | POST | ADMIN | - | DEMO IP cleanup |
| `/auth/seed` | POST | SUPERVISOR | - | Disabled in PROD se `ALLOW_SEED_ENDPOINT≠1` |
| `/auth/persona-packs` | GET | ADMIN | - | List catalog 12 pack |
| `/auth/tenant-persona-config/:tenantId/:packId` | GET/PUT | SUPERVISOR | - | Tenant override (added/removed/route) |
| `/auth/tenants/switchable` | GET | SUPERVISOR | - | Lista tenant cross-switch |
| `/auth/switch-tenant` | POST | SUPERVISOR | - | Bridge token 60s one-shot |
| `/auth/bridge?token=` | GET | Public | - | Consuma bridge → cookie + redirect |
| `/auth/magic-link/request` | POST | Public | (controller throttle) | Anti-enumeration: sempre ok=true |
| `/auth/magic-link/consume?token=` | GET | Public | - | Verify hash + expiresAt + consumedAt |
| `/auth/passkey/register/options` | POST | JW

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