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.

2026-07-05 18:39:53 +02:00
parent bf36cb3159
commit 50cd4b3ffd
225 changed files with 17824 additions and 436 deletions
--- a/docs/integrations/whmcs/addons.md
+++ b/docs/integrations/whmcs/addons.md
@@ -0,0 +1,56 @@
+# WHMCS addon products
+
+Bill optional GameCloud features as WHMCS addon products linked to the main Minecraft service.
+
+## Supported addon types
+
+| WHMCS addon | GameCloud feature | Module action |
+|-------------|-------------------|---------------|
+| Extra backup retention | Extended backup slots | Usage / plan metadata sync |
+| Dedicated IP (future) | Reserved port/IP on node | Manual / Phase 10 |
+| Priority support | No technical change | Billing only |
+
+Technical addons call GameCloud APIs during `CreateAccount` / `TerminateAccount` on the addon service or via usage records — see [usage billing](../usage-billing.md).
+
+## Setup
+
+**Setup → Products/Services → Product Addons → Create New Addon**
+
+1. Assign to Minecraft parent products
+2. Module: **HexaHost GameCloud** (if addon provisioning implemented) or **None** for pure billing markers
+3. Map addon ID in GameCloud addon module **Mappings** (addon tab) when available
+
+## Linking to parent service
+
+GameCloud correlates via:
+
+- `externalServiceId` — parent WHMCS service ID
+- `externalAddonId` — addon service ID (usage export)
+
+Ensure parent service is provisioned before addon activation.
+
+## Lifecycle
+
+| WHMCS event | Expected behavior |
+|-------------|-------------------|
+| Addon ordered | Enable feature flag on server |
+| Addon suspended | Disable feature; do not delete data |
+| Addon terminated | Revert limits; purge addon-specific data |
+
+## Metered addons
+
+For usage-based billing (playtime, storage overage):
+
+1. GameCloud worker aggregates usage
+2. WHMCS polls via addon module or server module metric export
+3. WHMCS generates invoices — [usage billing](../usage-billing.md)
+
+## Reconciliation
+
+Orphaned addons (parent terminated, addon active) appear in **Reconciliation** dashboard. Run dry-run before live fix.
+
+## Related
+
+- [Products](products.md)
+- [Usage billing](../usage-billing.md)
+- [Reconciliation](../reconciliation.md)
--- a/docs/integrations/whmcs/configurable-options.md
+++ b/docs/integrations/whmcs/configurable-options.md
@@ -0,0 +1,64 @@
+# WHMCS configurable options
+
+Map WHMCS configurable options to GameCloud server parameters at provision and upgrade time.
+
+## Overview
+
+Configurable options let customers choose RAM tiers, Minecraft versions, or software types at order time. The server module reads selected options during `CreateAccount` and `ChangePackage`.
+
+**Preferred approach:** Use addon product mappings for plan slugs; use configurable options for customer-visible upgrades that WHMCS invoices.
+
+## Standard option layout
+
+| Option name | Type | Maps to |
+|-------------|------|---------|
+| Plan | Dropdown | GameCloud plan slug (via mapping resolver) |
+| Minecraft Version | Dropdown | `minecraftVersion` |
+| Software | Dropdown | `softwareFamily` |
+| Extra Backup Slot | Quantity | WHMCS addon product — see [addons](addons.md) |
+
+Option order matters if using fallback config option indices in legacy setups. Mappings table overrides text fields when an active row exists.
+
+## Dropdown values
+
+### Software family
+
+Values must match GameCloud enum exactly:
+
+`VANILLA`, `PAPER`, `PURPUR`, `FABRIC`, `FORGE`, `NEOFORGE`, `QUILT`
+
+### Minecraft version
+
+Use semver strings present in GameCloud catalog. Invalid versions fail provisioning with module log error.
+
+## Upgrade path
+
+When a customer upgrades via WHMCS configurable option change:
+
+1. WHMCS invokes `ChangePackage`
+2. Module sends new `planSlug` to GameCloud
+3. GameCloud resizes limits; may require server restart
+
+Communicate restart requirement in WHMCS product description.
+
+## Validation
+
+The addon **Mappings** page validates plan slugs before save. Configurable option text is **not** validated until order time — typos cause provisioning failures.
+
+## Pricing
+
+WHMCS handles all pricing. GameCloud never stores invoice amounts in WHMCS mode (`BILLING_PROVIDER=whmcs`).
+
+## Example: RAM upgrade option
+
+1. WHMCS configurable option group "Upgrades"
+2. Option "RAM Tier" with values mapping to plan slugs `starter`, `pro`, `enterprise`
+3. Product mapping links WHMCS product + option combination to slug via `ProductMapping.php` resolver
+
+For complex matrices, use separate WHMCS products instead of many conditional options.
+
+## Related
+
+- [Products](products.md)
+- [Product mappings](../product-mappings.md)
+- [Troubleshooting](troubleshooting.md)
--- a/docs/integrations/whmcs/configuration.md
+++ b/docs/integrations/whmcs/configuration.md
@@ -0,0 +1,77 @@
+# WHMCS configuration
+
+Global and per-product settings for the HexaHost GameCloud WHMCS integration.
+
+## Addon module (global)
+
+**Setup → Addon Modules → HexaHost GameCloud → Configure**
+
+| Setting | GameCloud env | Description |
+|---------|---------------|-------------|
+| GameCloud API URL | `API_URL` | Base URL, e.g. `https://api.example.net` — no trailing slash |
+| Integration ID | `WHMCS_INTEGRATION_ID` | Unique installation identifier |
+| API Secret | `WHMCS_API_SECRET` | HMAC shared secret (≥ 32 chars) |
+| Use mTLS client certificate | `INTEGRATION_MTLS_ENABLED` | Enable client cert — see [mtls](../mtls.md) |
+| Client certificate path | — | PEM path readable by PHP |
+| Client private key path | — | PEM path, restricted permissions |
+| CA bundle path | — | Trust anchor for GameCloud API |
+| Auto-reconcile on daily cron | — | Dry-run reconciliation after event poll |
+| Event poll batch size | — | Default 50 |
+
+## GameCloud side
+
+```env
+BILLING_PROVIDER=whmcs
+WHMCS_INTEGRATION_ID=prod-whmcs-main
+WHMCS_API_SECRET=<generated-secret>
+WHMCS_WEBHOOK_SECRET=<optional-for-future-webhooks>
+INTEGRATION_MTLS_ENABLED=true
+APP_URL=https://panel.example.net
+API_URL=https://api.example.net
+```
+
+Restart `api` after credential changes.
+
+## Server module (per product)
+
+Each WHMCS product using module `hexagamecloud` needs:
+
+1. **Module Name:** HexaHost GameCloud
+2. **Server:** Server entry pointing to API hostname
+3. **Config options** or addon mappings — see [products](products.md) and [product mappings](../product-mappings.md)
+
+### Default config options
+
+| Option | Purpose |
+|--------|---------|
+| GameCloud Plan Slug | Fallback plan if no mapping row |
+| Minecraft Version | Default version at provision |
+| Software Family | VANILLA, PAPER, etc. |
+
+Prefer **addon mappings** over raw config option text for production.
+
+## Cron
+
+WHMCS daily cron invokes:
+
+- Pending event poll from GameCloud
+- Optional reconciliation dry-run
+
+Ensure WHMCS cron runs at least every 5 minutes for timely suspensions; daily hook handles bulk sync.
+
+## Reverse proxy
+
+If WHMCS reaches GameCloud through nginx/Traefik, preserve headers for mTLS fingerprint forwarding. Example: `deploy/nginx/integration-mtls.conf.example`.
+
+## Staging checklist
+
+- [ ] Integration ID unique per environment
+- [ ] Test order on hidden WHMCS product
+- [ ] SSO login to panel works ([sso](../sso.md))
+- [ ] Suspend / unsuspend updates server state within 60s
+
+## Related
+
+- [Installation](installation.md)
+- [Security](security.md)
+- [Troubleshooting](troubleshooting.md)
--- a/docs/integrations/whmcs/installation.md
+++ b/docs/integrations/whmcs/installation.md
@@ -0,0 +1,93 @@
+# WHMCS installation
+
+Install the HexaHost GameCloud provisioning and addon modules on WHMCS 8.x+.
+
+## Prerequisites
+
+- WHMCS with SSL (HTTPS admin and client area)
+- GameCloud control plane deployed (`deploy/compose/compose.prod.yml`)
+- `BILLING_PROVIDER=whmcs` on GameCloud
+- Matching credentials prepared (`WHMCS_INTEGRATION_ID`, `WHMCS_API_SECRET`)
+
+## Package contents
+
+Source tree: `integrations/whmcs/`
+
+| Component | WHMCS path |
+|-----------|------------|
+| Server module | `/modules/servers/hexagamecloud/` |
+| Addon module | `/modules/addons/hexagamecloud/` |
+| Hooks | `/includes/hooks/hexagamecloud.php` |
+
+Build a distributable ZIP:
+
+```bash
+cd integrations/whmcs/packaging
+./build-package.sh
+```
+
+## Installation steps
+
+### 1. Copy server module
+
+```bash
+cp -r integrations/whmcs/modules/servers/hexagamecloud /path/to/whmcs/modules/servers/
+```
+
+**Setup → Products/Services → Servers → Create New Server**
+
+- Type: **HexaHost GameCloud**
+- Hostname: `api.example.net` (GameCloud API host only — no path)
+- Username / Password: leave empty (credentials are per-product module settings)
+
+### 2. Copy addon module
+
+```bash
+cp -r integrations/whmcs/modules/addons/hexagamecloud /path/to/whmcs/modules/addons/
+```
+
+**Setup → Addon Modules → HexaHost GameCloud → Activate**
+
+Configure global settings — see [configuration](configuration.md).
+
+### 3. Install hooks
+
+```bash
+cp integrations/whmcs/hooks/hexagamecloud.php /path/to/whmcs/includes/hooks/
+```
+
+Hooks enable daily event polling and optional auto-reconciliation.
+
+### 4. Configure GameCloud
+
+On the control plane `.env.prod`:
+
+```env
+BILLING_PROVIDER=whmcs
+WHMCS_INTEGRATION_ID=prod-whmcs-main
+WHMCS_API_SECRET=<same-as-addon>
+INTEGRATION_MTLS_ENABLED=true
+```
+
+Restart API after changes.
+
+### 5. Verify connectivity
+
+In WHMCS: **Addons → HexaHost GameCloud → Dashboard**
+
+Expected: green health, catalog plan count, zero pending critical events.
+
+## File permissions
+
+WHMCS web user must read module PHP files. Do not make `lib/` or `templates/` web-writable.
+
+## Multi-environment
+
+Use separate `WHMCS_INTEGRATION_ID` values for staging and production GameCloud installations. Never point staging WHMCS at production GameCloud.
+
+## Related
+
+- [Configuration](configuration.md)
+- [Products](products.md)
+- [Security](security.md)
+- [Addon module](../addon-module.md)
--- a/docs/integrations/whmcs/products.md
+++ b/docs/integrations/whmcs/products.md
@@ -0,0 +1,71 @@
+# WHMCS products
+
+Creating WHMCS products that provision HexaHost GameCloud Minecraft servers.
+
+## Product setup
+
+**Setup → Products/Services → Create New Product**
+
+| Field | Value |
+|-------|-------|
+| Product type | Other |
+| Module | HexaHost GameCloud (`hexagamecloud`) |
+| Server group | Server entry with GameCloud API hostname |
+
+## Plan mapping
+
+Each product must resolve to a GameCloud **plan slug** (defines RAM, CPU, backup slots, etc.).
+
+**Recommended:** Configure via addon **Mappings** tab — [product mappings](../product-mappings.md)
+
+**Fallback:** Set config option **GameCloud Plan Slug** on the product module settings.
+
+Validate slugs against live catalog:
+
+```http
+GET /api/v1/catalog/plans
+```
+
+Only active plans appear in the addon mapping dropdown.
+
+## Example products
+
+| WHMCS product name | Plan slug | Target audience |
+|--------------------|-----------|-----------------|
+| Minecraft Starter | `starter` | 2 GB RAM, 10 slots |
+| Minecraft Pro | `pro` | 4 GB RAM, backup included |
+| Minecraft Enterprise | `enterprise` | Custom limits |
+
+Plan slugs are defined in GameCloud admin/catalog — not in WHMCS.
+
+## Software defaults
+
+Set per mapping or config options:
+
+- **Minecraft Version** — e.g. `1.21.1`
+- **Software Family** — `VANILLA`, `PAPER`, `PURPUR`, `FABRIC`, `FORGE`, etc.
+
+Customers may change software via panel after provision if plan allows.
+
+## Billing cycle
+
+WHMCS owns billing cycles. GameCloud receives `externalServiceId` and syncs lifecycle (suspend on overdue invoice via WHMCS module actions or events).
+
+Usage-based overages: see [usage billing](../usage-billing.md).
+
+## Client area
+
+The server module renders status and **Login to Panel** (SSO). Domain field is used as display name default (`server-{serviceId}` if empty).
+
+## Testing
+
+1. Create admin-only product group
+2. Place test order with 100% discount
+3. Confirm `CreateAccount` success in module log
+4. SSO into panel and verify server RUNNING or STARTING
+
+## Related
+
+- [Configurable options](configurable-options.md)
+- [Addons](addons.md)
+- [Installation](installation.md)
--- a/docs/integrations/whmcs/security.md
+++ b/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)
--- a/docs/integrations/whmcs/troubleshooting.md
+++ b/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)
--- a/docs/integrations/whmcs/upgrades.md
+++ b/docs/integrations/whmcs/upgrades.md
@@ -0,0 +1,74 @@
+# WHMCS module upgrades
+
+Upgrade paths for `integrations/whmcs` server and addon modules alongside GameCloud API releases.
+
+## Version compatibility
+
+Check release notes for minimum pairs:
+
+| GameCloud API | Server module | Addon module |
+|---------------|---------------|--------------|
+| 1.0.x | 1.0.x | 1.0.x |
+| 1.1.x | 1.1.x | 1.1.0+ (SQL migrations) |
+
+Module metadata declares `APIVersion` in `hexagamecloud_MetaData()`.
+
+## Upgrade order
+
+1. **GameCloud API** — deploy new control plane ([upgrades](../../operations/upgrades.md))
+2. **Database migrations** — addon SQL in `modules/addons/hexagamecloud/sql/upgrade-*.sql`
+3. **WHMCS addon module** — copy files, run upgrade hook
+4. **WHMCS server module** — copy files (usually no DB change)
+5. **Verify** — dashboard health, test suspend/unsuspend
+
+Never upgrade WHMCS modules before the API when release notes specify API-first ordering.
+
+## Addon SQL migrations
+
+WHMCS runs `hexagamecloud_upgrade()` on version bump. Manual apply if needed:
+
+```bash
+mysql whmcs < integrations/whmcs/modules/addons/hexagamecloud/sql/upgrade-1.1.0.sql
+```
+
+Back up WHMCS database before upgrade.
+
+## File deployment
+
+```bash
+# From packaging script output or git
+cp -r integrations/whmcs/modules/addons/hexagamecloud /path/to/whmcs/modules/addons/
+cp -r integrations/whmcs/modules/servers/hexagamecloud /path/to/whmcs/modules/servers/
+cp integrations/whmcs/hooks/hexagamecloud.php /path/to/whmcs/includes/hooks/
+```
+
+Clear WHMCS template cache if admin UI looks stale.
+
+## Zero-downtime considerations
+
+- Running game servers unaffected by module file update
+- Brief API restart during GameCloud upgrade may delay WHMCS module calls — retry logic in `ApiClient.php` handles transient 502
+- Place WHMCS in maintenance mode only if API breaking change requires it
+
+## Rollback
+
+1. Restore previous module files from backup
+2. Roll back GameCloud images if API incompatible
+3. Restore WHMCS DB if SQL migration ran
+
+Product mappings table is forward-compatible unless release notes say otherwise.
+
+## Packaging
+
+```bash
+cd integrations/whmcs/packaging
+./build-package.sh
+```
+
+Distribute ZIP to production WHMCS via change-controlled deploy.
+
+## Related
+
+- [Installation](installation.md)
+- [Troubleshooting](troubleshooting.md)
+- [Control plane upgrades](../../operations/upgrades.md)