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.