vctp2/todo.md

# VCTP Auth Design TODO (LDAP + JWT)

## 1. Goal
Add authentication and authorization to VCTP for sensitive endpoints, using the LDAP bind + JWT pattern from `cbs2` as a reference, adapted to VCTP's `net/http` architecture.

## 2. Reference Findings from `cbs2`

### 2.1 Where auth lives in `cbs2`
- Login handler: `/tmp/cbs2/server/handler/auth.go`
- JWT middleware: `/tmp/cbs2/server/handler/middlewares.go`
- Token utilities: `/tmp/cbs2/utils/token/token.go`
- LDAP bind + group lookup: `/tmp/cbs2/internal/ldap/ldap.go`
- Route protection split (public vs protected): `/tmp/cbs2/server/router/router.go`
- Settings fields for LDAP/JWT: `/tmp/cbs2/internal/settings/settings.go` and `/tmp/cbs2/src/cbs.yml`

### 2.2 Pattern to reuse
- LDAP username/password bind for authentication.
- LDAP group membership check for authorization at login.
- Signed JWT access token with expiry.
- Middleware that validates `Authorization: Bearer <token>`.
- Router-level grouping for protected routes.

### 2.3 Things to improve (do not copy as-is)
- Avoid hardcoded fallback JWT secret (present in `cbs2` middleware).
- Avoid logging sensitive token/key values.
- Avoid weak/ambiguous claim model; use explicit issuer/audience/subject/exp/iat.
- Keep strict method/endpoint policy in one place instead of ad-hoc checks.

## 3. Proposed VCTP Auth Architecture

### 3.1 New packages/modules
1. `internal/auth/ldap.go`
- LDAP setup/connection helpers.
- `AuthenticateAndFetchGroups(username, password) ([]string, error)`.

2. `internal/auth/jwt.go`
- JWT issue and verify.
- Claims struct with:
  - `sub` (username)
  - `roles` (derived roles)
  - `groups` (optional raw LDAP groups)
  - `iss`, `aud`, `iat`, `exp`, `nbf`, `jti`

3. `server/middleware/auth.go`
- `RequireAuth(...)` for token validation.
- `RequireRole(...)` for endpoint authorization.
- Context injection for user identity and roles.

4. `server/handler/auth.go`
- `POST /api/auth/login`
- Optional `GET /api/auth/me` for debugging/whoami.

### 3.2 Route protection model
Define a central policy map in router startup (single source of truth):

- Public (no auth):
  - `/assets/*`, `/favicon*`, `/swagger*` (optional decision), `/` (optional decision)
- Authenticated read-only (viewer role):
  - `/vcenters*`, `/snapshots/*`, `/vm/trace`, `/api/report/*`, `/metrics` (optional decision)
- Privileged write/admin (admin role):
  - `/api/snapshots/*` mutating endpoints
  - `/api/vcenters/cache/rebuild`
  - `/api/encrypt`
  - legacy mutating endpoints (`/api/event/*`, `/api/import/vm`, `/api/inventory/vm/*`, `/api/cleanup/*`)
- Debug endpoints (`/debug/pprof/*`):
  - disabled by default via config
  - if enabled, require admin

## 4. VCTP Settings Additions
Add under `settings:` in `internal/settings/settings.go` and `src/vctp.yml`:

1. `auth_enabled: false`
2. `auth_mode: "disabled"` (`disabled|optional|required`)
3. `auth_jwt_signing_key: ""` (base64-encoded, required when auth enabled)
4. `auth_token_lifespan_minutes: 120`
5. `auth_jwt_issuer: "vctp"`
6. `auth_jwt_audience: "vctp-api"`
7. `auth_clock_skew_seconds: 60`
8. `ldap_groups: []`
9. `ldap_bind_address: ""`
10. `ldap_base_dn: ""`
11. `ldap_trust_cert_file: ""`
12. `ldap_disable_validation: false`
13. `ldap_insecure: false`
14. `enable_pprof: false`

## 5. Role Mapping
Use LDAP group DN mapping to roles (config-driven):

- `auth_group_role_mappings` map/list, e.g.:
  - group DN -> `admin`
  - group DN -> `viewer`

Default behavior:
- No mapped group: deny login.
- Multiple matches: union roles.

## 6. API Contract

### 6.1 Login
`POST /api/auth/login`
- Request: `{ "username": "...", "password": "..." }`
- Success: `{ "access_token": "...", "expires_at": <unix>, "token_type": "Bearer" }`
- Failure: `401` with generic message (no user/group leakage)

### 6.2 Auth header
- `Authorization: Bearer <jwt>`

### 6.3 Error behavior
- Missing/invalid token: `401`
- Valid token but insufficient role: `403`

## 7. Rollout Plan

### Phase 1: Foundation
1. Implement settings fields and validation.
2. Implement LDAP and JWT services.
3. Add `/api/auth/login`.
4. Add unit tests for token generation/validation and LDAP auth abstraction.

### Phase 2: Middleware + policy
1. Add auth middleware for `net/http`.
2. Protect sensitive routes via central policy map.
3. Keep `auth_mode=optional` initially for safe rollout.

### Phase 3: Enforce + harden
1. Switch production to `auth_mode=required`.
2. Gate/disable pprof by config.
3. Add structured audit logs for auth events.
4. Update Swagger security docs and README.

## 8. Validation and Tests
1. Unit tests
- JWT: expired token, wrong signature, wrong issuer/audience, clock skew.
- Role extraction and mapping.

2. Integration tests (handler/middleware)
- Unauthenticated access blocked on protected endpoints.
- Viewer can read but cannot mutate.
- Admin can mutate.

3. Regression checks
- Existing legacy endpoint gating (`enable_legacy_api`) still behaves correctly after auth layering.

## 9. Open Decisions
1. Should `/metrics` require auth in your deployment? No there is no need for auth for this endpoint
2. Should UI pages (`/`, `/vcenters`, `/snapshots/*`, `/vm/trace`) require login or stay public? These should stay public
3. Should Swagger UI be public, authenticated, or disabled in production? These should stay public
4. Do you want short-lived access tokens only, or access + refresh token flow? Short lived access tokens please, 2 hours is good enough

## 10. Implementation Notes for VCTP
1. Reuse `cbs2` LDAP flow shape, but avoid its fallback secret behavior.
2. Keep all secret material redacted in logs.
3. Validate required auth settings at startup when `auth_enabled=true`.
4. Prefer fail-closed: if auth is enabled and misconfigured, abort startup.