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/troubleshooting.md

@@ -0,0 +1,101 @@
+# WHMCS troubleshooting
+
+Common integration failures between WHMCS and HexaHost GameCloud.
+
+## Diagnostic tools
+
+| Tool | Location |
+|------|----------|
+| WHMCS module log | Utilities → Logs → Module Log |
+| GameCloud addon dashboard | Addons → HexaHost GameCloud |
+| API health | `GET https://api.example.net/api/v1/health/live` |
+| OpenAPI | `/api/v1/docs` — [API README](../../api/README.md) |
+| Reconciliation | Addon → Reconciliation tab |
+
+## Authentication errors
+
+### `Invalid signature` / 401
+
+- Confirm `WHMCS_API_SECRET` matches exactly on both sides (no trailing newline)
+- Check `WHMCS_INTEGRATION_ID` matches addon **Integration ID**
+- Verify server clock (NTP): `X-HGC-Timestamp` skew > 5 min fails
+- Ensure **GameCloud API URL** has no trailing slash
+
+### mTLS / certificate errors
+
+- `INTEGRATION_MTLS_ENABLED=true` but fingerprint not registered → register in addon **mTLS** tab
+- Wrong CA bundle on WHMCS → point to GameCloud CA PEM
+- Reverse proxy not forwarding `X-HGC-Client-Cert-Fingerprint` → see [mtls](../mtls.md)
+
+## Provisioning failures
+
+### `CreateAccount` returns error string
+
+1. Read WHMCS module log full message
+2. Common causes:
+   - Invalid plan slug — fix [product mapping](../product-mappings.md)
+   - Catalog plan inactive
+   - No eligible game node (`NO_NODE_AVAILABLE`)
+   - Invalid Minecraft version for software family
+
+### Server stuck Pending in WHMCS
+
+- GameCloud provision may have succeeded — check addon dashboard service count
+- Run reconciliation dry-run
+- Manual SSO to panel to verify server exists
+
+## Lifecycle sync
+
+### Suspend / unsuspend not applied
+
+- WHMCS module action failed silently — check module log
+- GameCloud worker backlog — check Redis / worker logs
+- Event poll not running — verify WHMCS cron active
+
+### Terminate left data on node
+
+- Terminate API may have failed mid-flight — admin force-terminate in panel
+- Node offline during terminate — retry when node ONLINE
+
+## SSO issues
+
+See dedicated [SSO guide](../sso.md). Typical fixes:
+
+- `APP_URL` mismatch between GameCloud and expected redirect
+- Clock skew
+- Service not linked to correct `externalServiceId`
+
+## Usage billing gaps
+
+- Usage export cron not running
+- Mismatch between WHMCS service ID and GameCloud external ID — reconciliation
+
+## Network
+
+```bash
+# From WHMCS host
+curl -v https://api.example.net/api/v1/health/live
+openssl s_client -connect api.example.net:443 -servername api.example.net
+```
+
+Firewall must allow outbound 443 from WHMCS to GameCloud API.
+
+## Enable debug logging
+
+WHMCS: enable module debug in **System Settings → General Settings** (temporarily).
+
+GameCloud: set `LOG_LEVEL=debug` on API, reproduce, revert to `info`.
+
+## Escalation data to collect
+
+- WHMCS service ID and timestamp of failure
+- Module log entry (redact secrets)
+- GameCloud request ID from API response header if present
+- Integration ID and API version
+
+## Related
+
+- [Security](security.md)
+- [Configuration](configuration.md)
+- [Incident response](../../operations/incident-response.md)
+- [Reconciliation](../reconciliation.md)