# Visione CIE OIDC RP Technical Plan

## Goal
Implement Visione backend as SPID/CIE OIDC Federation Relying Party compatible
with local demo provider contained in `spid-cie-oidc-django/examples/provider`.

Scope target for first real implementation:
- compatibility with demo provider only
- CIE profile only
- Visione backend remains source of truth for application auth
- frontend drives browser redirect flow

## Local Reference Mapping
- Demo OP/federation behavior source:
  - `spid-cie-oidc-django/examples/provider`
  - `spid-cie-oidc-django/spid_cie_oidc/provider`
  - `spid-cie-oidc-django/spid_cie_oidc/entity`
- Demo RP behavior to emulate in Drogon:
  - `spid-cie-oidc-django/spid_cie_oidc/relying_party/views/rp_begin.py`
  - `spid-cie-oidc-django/spid_cie_oidc/relying_party/views/rp_callback.py`

## Current Status
- `common/OidcJwt.*` now owns JWT/JWS/JWK work through `jwt-cpp`
- `common/OidcCrypto.*` isolates OpenSSL-only JWE compact parsing and decrypt
- `POST /api/v1/auth/cie/start` signs the request object with RP signing key
- callback exchanges code with `private_key_jwt`, verifies token JWS and `at_hash`
- `userinfo` GET supports plain JSON and demo-compatible nested JWE -> JWS
- merged OIDC claims persist through `user_external_identities`
- frontend polling contract is active through `GET /api/v1/auth/cie/session/{state}`

## Foundation Added In This Step
- config placeholders in `config.json`
- DB schema for OIDC auth sessions, tokens, federation cache, external identities
- Drogon controller skeleton in `controllers/OidcController.*`
- service skeleton in `services/OidcRpService.*`
- RP config helper in `common/OidcRpConfig.*`
- RP public endpoints reserved:
  - `POST /api/v1/auth/cie/start`
  - `GET /api/v1/auth/cie/callback`
  - `GET /api/v1/auth/cie/session/{state}`
  - `GET /oidc/rp/.well-known/openid-federation`
  - `GET /oidc/rp/resolve`
  - `GET /oidc/rp/jwks.json`

## Residual Backlog
### Phase 1: Dependencies and crypto plumbing
- Done for demo scope:
  - `jwt-cpp` handles JWT parsing, signing and signature verification
  - custom OpenSSL code remains only for JWE decryption in `OidcCrypto`
  - focused unit tests cover JWT helpers and both supported JWE CBC/HMAC modes

### Phase 2: RP metadata and JWKS
- Done for demo flow.
- Residual gap:
  - verify metadata fields against non-demo providers before reuse

### Phase 3: Federation trust resolution
- Current cut:
  - fetches trust-anchor `resolve`
  - extracts OP metadata/JWKS/endpoints
- Not done:
  - full trust-chain signature validation
  - federation cache population/reuse
  - multi-provider or multi-anchor logic

### Phase 4: Authorization start
- Done.
- Demo scope now sent explicitly as `openid cie_demo`.

### Phase 5: Callback and token exchange
- Done for demo provider.
- Residual gap:
  - explicit `exp` / `iat` skew checks still thin
  - no refresh-token lifecycle use yet

### Phase 6: UserInfo and local account link
- Done for demo provider, including JWE decrypt + JWS verify + merged claims.

### Phase 7: Frontend completion contract
- Done.
- Session payload now exposes:
  - public `status`
  - internal `phase`
  - `auth` payload only on success

### Phase 8: Tests and docs
- Unit tests added for:
  - JWT parse/sign/verify
  - `kid` lookup
  - `at_hash` helper
  - JWE decrypt for `A256CBC-HS512`
  - JWE decrypt for `A128CBC-HS256`
  - invalid JWE tag / unsupported enc
  - merged claim precedence and fiscal code normalization
- Still missing:
  - automated integration tests against live demo Django OP

## Data Model Notes
### `oidc_authentications`
Stores single login transaction state and provider snapshot.

### `oidc_authentication_tokens`
Stores authorization code and received tokens.

### `oidc_federation_cache`
Stores fetched federation docs with expiry.

### `user_external_identities`
Decouples local user from external subject identifiers.

## Current Decisions
- Keep OTP auth alive in parallel
- Use local `api_tokens` after OIDC success
- Use `fiscal_code` as strongest user reunification key
- Do not expose Visione token in query string
- Prefer external validated libs over handwritten JWT/JWK code

## Ready Criteria For Real Implementation
- foundation schema merged
- config keys finalized
- dependency choice finalized
- endpoint shapes stable enough for frontend

When these are acceptable, next step is real implementation of Phase 1-4.

## Demo CIE Runbook
### Prerequisites
- MySQL and Mailpit running locally through this repo `docker compose`
- RP keys available in `secrets/oidc/demo-rp-jwks.json`
- backend `config.json` aligned with:
  - trust anchor `http://127.0.0.1:8000`
  - provider issuer `http://127.0.0.1:8002/oidc/op`
  - callback `http://127.0.0.1:5555/api/v1/auth/cie/callback`

### Bootstrap local dependencies
```bash
docker compose up -d
cmake -S . -B build_local -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build_local
```

### Bootstrap demo federation authority
```bash
cd spid-cie-oidc-django/examples/federation_authority
cp federation_authority/settingslocal.py.example federation_authority/settingslocal.py
python3 -m pip install --upgrade pip
python3 -m pip install -e ../..
python3 -m pip install "design-django-theme==v1.4.8"
./manage.py migrate
./manage.py loaddata dumps/example.json
./manage.py runserver 0.0.0.0:8000
```

### Bootstrap demo provider
```bash
cd spid-cie-oidc-django/examples/provider
cp provider/settingslocal.py.example provider/settingslocal.py
./manage.py migrate
./manage.py loaddata dumps/example.json
./manage.py runserver 0.0.0.0:8002
```

### Start Visione backend
```bash
./build_local/visione-backend
```

### Start login
```bash
curl -sS -X POST http://127.0.0.1:5555/api/v1/auth/cie/start \
  -H 'Content-Type: application/json' \
  -d '{"provider":"cie_demo","frontend_redirect_uri":"http://localhost:3000/auth/cie/callback"}'
```

Expected result:
- `authorization_url` present
- `state` present
- one row in `oidc_authentications` with phase `AUTHORIZATION_REDIRECT_READY`

### Complete browser flow
1. Open returned `authorization_url`.
2. Authenticate with the demo CIE user configured by the Django fixtures.
3. Accept consent if requested.
4. Provider redirects to backend callback.
5. Backend redirects frontend to `frontend_redirect_uri?state=...`.

### Poll login result
```bash
curl -sS http://127.0.0.1:5555/api/v1/auth/cie/session/<state>
```

Expected success payload:
- `status = "authenticated"`
- `phase = "AUTHENTICATED"`
- `auth.token` present

### Minimal DB verification
```sql
SELECT state,status,authenticated_user_id FROM oidc_authentications ORDER BY id DESC LIMIT 3;
SELECT authentication_id,token_type,scope FROM oidc_authentication_tokens ORDER BY id DESC LIMIT 3;
SELECT user_id,provider,issuer,subject,fiscal_code FROM user_external_identities ORDER BY id DESC LIMIT 3;
SELECT user_id,expires_at FROM api_tokens ORDER BY id DESC LIMIT 3;
```

### Common failures
- `provider_metadata_missing`: federation authority not started or wrong trust anchor URL
- `token_exchange_failed`: provider callback reached but token endpoint unavailable or RP assertion invalid
- `invalid_userinfo_response`: JWE decryption key mismatch or unexpected provider response format
- `at_hash_mismatch`: provider tokens not aligned with received `access_token`