Enhance WHMCS integration with mTLS support and product mapping features. Added mTLS configuration options, updated API endpoints for mTLS status and fingerprint registration, and implemented product validation API. Updated database schema and documentation accordingly.

docs/IMPLEMENTATION_STATUS.md

@@ -2,7 +2,40 @@
 
 Last updated: 2026-06-26
 
-## Current phase: WHMCS Addon Dashboard ✅
+## Current phase: WHMCS hardening — mTLS + Product mappings ✅
+
+### mTLS integration API
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Optional enforcement | Done | `INTEGRATION_MTLS_ENABLED=true` |
+| Fingerprint binding | Done | Per `WhmcsInstallation` |
+| Guard | Done | HMAC + mTLS layered |
+| API | Done | `GET/PUT .../mtls/*` |
+| PHP clients | Done | Addon + server module curl mTLS |
+| nginx example | Done | `deploy/nginx/integration-mtls.conf.example` |
+| Docs | Done | `docs/integrations/whmcs/mtls.md` |
+
+### Product mapping UI
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Addon mappings page | Done | WHMCS product → GameCloud plan |
+| Validation API | Done | `POST /catalog/validate-plan` |
+| WHMCS table | Done | `mod_hexagamecloud_product_mappings` |
+| Server module hook | Done | `ProductMapping.php` resolver |
+| Docs | Done | `docs/integrations/whmcs/product-mappings.md` |
+
+### Abnahmekriterium
+
+- [x] Addon maps WHMCS products to validated GameCloud plan slugs
+- [x] Provisioning uses mapping when active
+- [x] mTLS can be enabled without breaking dev (HMAC-only default)
+- [ ] Manual E2E: nginx mTLS + WHMCS provision
+
+---
+
+## WHMCS Addon Dashboard ✅
 
 ### WHMCS Addon module completed
 
@@ -266,4 +299,4 @@ Server entry fields:
 
 ### Next phase: Post-MVP hardening
 
-- Penetration test, product mapping UI in addon, mTLS for integration API
+- Penetration test, configurable option mappings, IP allowlist for integration API

docs/integrations/whmcs/mtls.md

@@ -0,0 +1,62 @@
+# 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.

docs/integrations/whmcs/product-mappings.md

@@ -0,0 +1,31 @@
+# WHMCS product mappings
+
+Map WHMCS products (`servertype=hexagamecloud`) to GameCloud plan slugs without relying on product config option text fields alone.
+
+## Addon UI
+
+**Addons → HexaHost GameCloud → Mappings**
+
+1. Select a WHMCS product
+2. Choose a GameCloud plan from the live catalog (`GET /catalog/plans`)
+3. Set default Minecraft version and software family
+4. Save — validated via `POST /catalog/validate-plan`
+
+Mappings are stored in `mod_hexagamecloud_product_mappings`.
+
+## Server module behavior
+
+On `CreateAccount` and `ChangePackage`, the provisioning module resolves:
+
+- `planSlug` from mapping table (active row) or falls back to config option 1
+- `minecraftVersion` / `softwareFamily` from mapping defaults or config options
+
+Shared resolver: `integrations/whmcs/lib/ProductMapping.php`
+
+## Dry-run validation
+
+Before saving, the addon calls GameCloud to ensure the plan slug exists and is active. Invalid slugs are rejected — WHMCS product names alone are never used for mapping keys.
+
+## Import / export
+
+Mappings are WHMCS-local. Export the `mod_hexagamecloud_product_mappings` table for backup when migrating WHMCS hosts.