Phase D

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