Phase D

docs/IMPLEMENTATION_STATUS.md

@@ -2,7 +2,42 @@
 
 Last updated: 2026-06-26
 
-## Current phase: Phase 9 — WHMCS integration and production hardening ✅
+## Current phase: WHMCS Phase D — SSO ✅
+
+### WHMCS Phase D completed
+
+| Area | Status | Notes |
+|------|--------|-------|
+| `SsoTicket` model | Done | Hashed token, 60s TTL, single use |
+| Impersonation sessions | Done | `UserSession.isImpersonation` + audit |
+| API create SSO | Done | `POST .../services/:id/sso` |
+| API consume SSO | Done | `POST /auth/sso/consume` → session cookie |
+| Path allowlist | Done | Server panel routes only |
+| Web SSO page | Done | `/auth/sso?ticket=` + impersonation banner |
+| WHMCS PHP SSO | Done | `ServiceSingleSignOn`, `AdminSingleSignOn` |
+| Docs | Done | `docs/integrations/whmcs/sso.md` |
+
+### Abnahmekriterium Phase D
+
+- [x] WHMCS „Server verwalten“ erzeugt einmaliges SSO-Ticket
+- [x] Ticket-Einlösung setzt Session-Cookie und leitet auf Server-Panel weiter
+- [x] Admin-SSO markiert Impersonation-Session sichtbar im Panel
+- [x] Gesperrte/beendete Services erhalten kein SSO-Ticket
+- [ ] Manual E2E: WHMCS client area → panel → server detail
+
+### Local SSO test
+
+1. `pnpm db:migrate && pnpm db:seed` (includes `local-dev-whmcs`)
+2. Provision a service via WHMCS API (`PUT .../clients/1`, `POST .../services`)
+3. `POST /api/v1/integrations/whmcs/services/{externalServiceId}/sso` (signed)
+4. Open `{APP_URL}/auth/sso?ticket={token}` → redirects to `/servers/{id}`
+5. Admin SSO: same flow with `kind=admin` → impersonation banner visible
+
+See [docs/integrations/whmcs/sso.md](integrations/whmcs/sso.md).
+
+---
+
+## Phase 9 — WHMCS integration and production hardening ✅
 
 ### Phase 9 completed
 
@@ -156,4 +191,4 @@ Server entry fields:
 
 ### Next phase: Post-MVP hardening
 
-- Stripe webhooks, SSO (WHMCS Phase D), reconciliation dashboard, penetration test
+- WHMCS Phase E (reconciliation), Phase F (usage billing), Stripe webhooks, penetration test

docs/integrations/whmcs/sso.md

@@ -0,0 +1,51 @@
+# WHMCS single sign-on (Phase D)
+
+HexaHost GameCloud uses one-time SSO tickets to bridge WHMCS and the customer panel without long-lived tokens in URLs.
+
+## Flow
+
+1. WHMCS calls `ServiceSingleSignOn` or `AdminSingleSignOn` in the server module.
+2. The module requests `POST /api/v1/integrations/whmcs/services/:externalServiceId/sso`.
+3. GameCloud stores a hashed ticket (60s TTL, single use) and returns `redirectUrl`.
+4. WHMCS redirects the browser to `{APP_URL}/auth/sso?ticket=...`.
+5. The web app calls `POST /api/v1/integrations/whmcs/auth/sso/consume` — actually `/auth/sso/consume`.
+6. GameCloud sets a normal HTTP-only session cookie and returns an allowlisted `redirectPath`.
+
+## Ticket properties
+
+Stored server-side (hashed):
+
+- GameCloud user and server IDs
+- WHMCS installation, client, user, and service IDs
+- Target path (allowlisted)
+- Issuer (`integrationId`) and audience (`APP_URL`)
+- Nonce (replay protection at ticket layer)
+
+## Admin SSO / impersonation
+
+`kind=admin` creates an impersonation session:
+
+- `UserSession.isImpersonation = true`
+- Metadata includes WHMCS admin user reference
+- Full audit events: `whmcs.sso.admin_created`, `whmcs.sso.admin_consumed`
+- Panel shows an amber support banner
+
+## Allowlisted redirect paths
+
+- `/dashboard`
+- `/servers`
+- `/servers/{serverId}`
+- `/servers/{serverId}/{console|files|properties|players|worlds|backups|addons}`
+
+Arbitrary external URLs are rejected.
+
+## WHMCS configuration
+
+Server module hostname must match `APP_URL` origin used for ticket audience validation.
+
+## Security notes
+
+- Tickets expire after **60 seconds**
+- Each ticket is **single-use**
+- Only the WHMCS integration API (HMAC) can mint tickets
+- Suspended or terminated services cannot obtain SSO tickets