# 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