# WHMCS integration mTLS

GameCloud integration requests use **HMAC signatures** always. In production you can additionally require a **client TLS certificate**.

## Enable on GameCloud

```env
INTEGRATION_MTLS_ENABLED=true
```

When enabled, every `/api/v1/integrations/whmcs/*` request must:

1. Pass HMAC validation (unchanged)
2. Present a client certificate whose SHA-256 fingerprint matches the installation record

## Register client fingerprint

```http
PUT /api/v1/integrations/whmcs/mtls/fingerprint
X-HGC-Client-Cert-Fingerprint: <optional when registering via proxy>
```

```json
{
  "fingerprint": "ab12…",
  "subject": "whmcs-integration-client"
}
```

Or use the WHMCS addon page **mTLS → Register fingerprint**.

Generate fingerprint:

```bash
openssl x509 -in client.crt -outform DER | openssl dgst -sha256
```

## Reverse proxy (recommended)

Terminate mTLS at nginx and forward the fingerprint:

```nginx
ssl_verify_client optional;
proxy_set_header X-HGC-Client-Cert-Fingerprint $ssl_client_fingerprint;
proxy_set_header X-HGC-Client-Cert-Subject $ssl_client_s_dn;
```

See `deploy/nginx/integration-mtls.conf.example`.

## WHMCS PHP client

In the addon module enable **Use mTLS client certificate** and set paths to:

- Client certificate PEM
- Client private key PEM
- CA bundle (GameCloud or internal CA)

The PHP client sends `X-HGC-Client-Cert-Fingerprint` when configured.

## Development

Leave `INTEGRATION_MTLS_ENABLED=false` (default). HMAC-only auth matches local dev workflow.