update security

docs/client-api.md

@@ -12,6 +12,7 @@ credentials.
   "code": "TAPM-ABCDE-FGHIJ",
   "host_fingerprint": "sha256-of-the-host-machine-id",
   "hostname": "pve01",
+  "installation_id": "123e4567-e89b-42d3-a456-426614174000",
   "requested_action": "install-rmm",
   "requested_package": ""
 }
@@ -50,6 +51,9 @@ authorization code.
 When `requested_action` or `requested_package` is present, the broker validates
 that entitlement before enrolling the host. Older clients may omit both fields,
 but current clients should always identify what they intend to use.
+Current V2 clients also send their random `installation_id`. A successful
+code exchange marks the matching fleet record as verified; it does not expose
+or replace the host's fleet credential.
 
 An installer must proceed only when its required package slug or action slug is
 present in this response. The current action slugs are:
@@ -83,3 +87,55 @@ The server also returns the expected value in `X-TAPM-SHA256`.
 
 Codes and sessions expire at the same authorization deadline. Revoking an
 authorization immediately invalidates all of its sessions.
+
+## Fleet registration
+
+V2 clients register a locally generated installation identity:
+
+`POST https://tapm.example.com/api/v1/hosts/register`
+
+```json
+{
+  "schema_version": 1,
+  "installation_id": "123e4567-e89b-42d3-a456-426614174000",
+  "credential": "64-lowercase-hexadecimal-characters",
+  "proxmenu_version": "2026.7.26-7",
+  "git_commit": "40-lowercase-hexadecimal-characters",
+  "pve_version": "pve-manager/9.0.3/abc~1",
+  "os_version": "Debian GNU/Linux 13 (trixie)",
+  "kernel_version": "6.14.11-2-pve",
+  "architecture": "amd64",
+  "clustered": false
+}
+```
+
+The first request returns `201`; subsequent authenticated registrations return
+`200`. The broker stores a SHA-256 digest of the 256-bit random credential, not
+the credential itself. New registrations are limited per privacy-preserving
+HMAC of the source address to reduce anonymous registry abuse.
+
+## Fleet lifecycle events
+
+`POST https://tapm.example.com/api/v1/hosts/events`
+
+The request uses `Authorization: Bearer HOST_CREDENTIAL`. Its body has the same
+schema and platform metadata as registration, omits `credential`, and adds:
+
+```json
+{
+  "event": "run_completed",
+  "result": "success",
+  "error_code": "",
+  "duration_seconds": 19
+}
+```
+
+Accepted events are `run_started`, `run_completed`, `run_failed`, and
+`upgraded`. Events are best-effort and are sent only while TA-ProxMenu is
+running; there is no resident monitoring service.
+
+The fleet API deliberately does not accept or store hostnames, machine IDs,
+MAC addresses, usernames, customer names, VM/container inventory, deployment
+tokens, or command output. The portal shows random installation IDs, first and
+last activity, verification status, software/platform versions, cluster mode,
+and the latest structured result.

docs/deployment.md

@@ -20,14 +20,27 @@ into the Gitea container, preventing them from overriding its internal listener.
 ## 1. VM and network
 
 Install Docker Engine with Compose v2. Permit the selected HTTP and HTTPS ports
-and forward public TCP 80 and 443 from the datacenter edge to them. The
-Create public DNS A/AAAA records for both application names before requesting
-the certificate.
+and forward public TCP 80 and 443 from the datacenter edge to them. Create
+public DNS A/AAAA records for both application names before requesting the
+certificate.
 
 Public port 80 must reach the container's port 80 for HTTP-01 certificate
 renewal. For example, if `HTTP_PORT=8080`, the edge must forward public port 80
 to VM port 8080. If IPv6 is published, it must reach this same VM.
 
+The company firewall should provide volumetric DDoS protection and permit only
+the required forwarded ports. Nginx supplies the application-edge controls:
+unknown HTTP hostnames are dropped, unknown TLS SNI names are rejected,
+TLS is restricted to 1.2/1.3, session tickets and version disclosure are
+disabled, broker requests and per-address connections are limited, slow-client
+timeouts are bounded, Gitea login bursts are throttled, and HSTS plus browser
+security headers are returned. Container PID ceilings and Docker log rotation
+reduce the impact of local resource exhaustion.
+Nginx also runs with a read-only container filesystem and narrowly scoped
+temporary filesystems. The broker trusts proxy headers because Nginx is its
+only production ingress; Nginx replaces rather than appends client-supplied
+forwarding headers.
+
 ## 2. Install the repository
 
 ```sh