RC-7

SECURITY.md

@@ -28,3 +28,44 @@ The USD figure is a local safety estimate based on provider-reported usage and p
 ## Browser headers
 
 Responses include CSP with `script-src 'self'`, `frame-ancestors 'none'`, `X-Frame-Options: DENY`, HSTS, `nosniff`, no-referrer, restricted browser permissions, and no-store caching for auth/admin resources.
+
+## Hosted Customer Service trust boundaries (V4.1)
+
+The optional Customer Service is a separate control plane. Treat its listeners
+as three different trust zones: 8090 public customer portal, 8091 private/VPN
+admin, and 8092 Docker-network-only worker registration/lease. The game private
+listener on 8081 is also required for delegation and must not be exposed to the
+public Internet.
+
+`CUSTOMER_SERVICE_SHARED_SECRET` authenticates Customer Service to the game
+private API. Example/default-looking values are rejected by the Customer Service
+process. Customer reward ownership uses a one-shot 10-minute `nhlink_*` proof
+issued only to an already authenticated game identity. The game stores only a
+SHA-256 hash of that proof and consumes it atomically, so Customer Service never
+needs the main P-256 private key.
+
+
+V4.1 uses three separate runtime images. The public game image contains only the
+game binary, the Customer Service image contains only the commercial control
+plane, and managed workers contain only the CLI agent. This reduces accidental
+cross-role exposure compared with the former monolithic runtime image.
+
+`CS_WORKER_IMAGE` is treated as an operator-controlled image reference. If
+`CS_WORKER_AUTO_PULL=true`, Customer Service may ask Docker Engine to pull it.
+For a private registry, use a registry-scoped read-only deploy/robot token in
+`CS_WORKER_REGISTRY_USERNAME/PASSWORD`; those credentials are used only for the
+Docker `X-Registry-Auth` pull request and are never injected into worker
+containers. Pinning production workers to an immutable digest is recommended
+when your registry/deployment workflow supports it.
+
+Managed worker containers never receive the Docker socket. The Customer Service
+process itself does require Docker Engine control; a direct docker.sock mount is
+therefore a high-trust capability and should preferably be replaced with a
+narrowly permissioned socket proxy in production. Global and per-customer worker
+inventory/running limits are enforced even when reverse-proxy rate limits are
+configured separately.
+
+PayPal live mode is deliberately gated, manual credit grants are disabled by
+default and available only from the private Customer Service admin listener,
+and all credit changes are written to an idempotent ledger. These controls are
+operational safeguards, not a legal classification of the commercial product.