Enhance API with OIDC support, including login and callback endpoints. Update environment variables for OIDC configuration in .env.example. Add new features to the catalog service for listing software families, Minecraft versions, and deployment regions. Implement server management actions such as kill, delete, and update in the servers module. Integrate feature flags for maintenance mode in server operations. Update pnpm-lock.yaml with new dependencies and versions.

docs/integrations/whmcs/security.md

@@ -0,0 +1,79 @@
+# WHMCS integration security
+
+Security controls for the API-only link between WHMCS and HexaHost GameCloud.
+
+## Trust model
+
+- WHMCS is the **commercial system of record** (payments, invoices)
+- GameCloud is the **technical system of record** (servers, nodes)
+- Integration is **one-way authenticated API** — no shared database
+
+## Authentication layers
+
+### 1. HMAC request signing (required)
+
+Every request to `/api/v1/integrations/whmcs/*` includes:
+
+| Header | Purpose |
+|--------|---------|
+| `X-HGC-Integration-Id` | Installation identifier |
+| `X-HGC-Timestamp` | Unix epoch seconds |
+| `X-HGC-Signature` | HMAC-SHA256 of canonical request |
+
+Secret: `WHMCS_API_SECRET` — rotate via [secrets](../../security/secrets.md).
+
+Clock skew tolerance: ± 300 seconds. Sync NTP on both hosts.
+
+### 2. mTLS (production recommended)
+
+When `INTEGRATION_MTLS_ENABLED=true`:
+
+- Client certificate required from WHMCS host
+- Fingerprint registered in GameCloud installation record
+- See [mtls](../mtls.md)
+
+### 3. Network controls
+
+- Allowlist WHMCS egress IP at firewall or Traefik
+- No public exposure of WHMCS admin URL without 2FA
+- API only on HTTPS (`api.example.net`)
+
+## WHMCS hardening
+
+| Control | Recommendation |
+|---------|----------------|
+| Admin 2FA | Required for all staff |
+| File permissions | Module PHP not writable by web user |
+| API Secret storage | WHMCS encrypted settings storage |
+| Module logs | Restrict **Utilities → Logs** access |
+| Hooks file | `includes/hooks/hexagamecloud.php` owned by root/deploy user |
+
+## Least privilege
+
+WHMCS server module credentials are **not** stored in WHMCS server username/password fields — only in addon encrypted settings. GameCloud API keys for customers are separate from integration secret.
+
+## Audit
+
+GameCloud logs integration calls with integration ID and action. WHMCS module log redacts secrets. Correlate by timestamp and `externalServiceId`.
+
+## Incident response
+
+On suspected secret leak:
+
+1. Rotate `WHMCS_API_SECRET` on GameCloud first, then WHMCS addon
+2. Review module log for anomalous provisioning
+3. Run reconciliation dry-run
+4. Re-register mTLS fingerprint if cert compromised
+
+See [incident response](../../operations/incident-response.md).
+
+## Compliance
+
+- PCI: WHMCS handles card data; GameCloud never receives PAN
+- GDPR: Customer PII flows in `upsertClient` — subject to [data retention](../../security/data-retention.md)
+
+## Related
+
+- [Configuration](configuration.md)
+- [mTLS](../mtls.md)
+- [Troubleshooting](troubleshooting.md)