# 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)