initial upload

2026-07-25 13:11:37 -05:00
commit 943ddb064f
25 changed files with 2586 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Proxmox client API
+
+The ProxMenu client uses two HTTPS requests. It never receives Gitea
+credentials.
+
+## Exchange a deployment code
+
+`POST https://tapm.scity.us/api/v1/exchange`
+
+```json
+{
+  "code": "TAPM-ABCDE-FGHIJ",
+  "host_fingerprint": "sha256-of-the-host-machine-id",
+  "hostname": "pve01"
+}
+```
+
+Successful response:
+
+```json
+{
+  "session_token": "opaque-session-token",
+  "expires_at": "2026-07-25T23:30:00Z",
+  "packages": [
+    {
+      "slug": "sentinelone-linux",
+      "display_name": "SentinelOne Linux Agent",
+      "version": "26.1.1.31",
+      "sha256": "64-lowercase-hexadecimal-characters",
+      "download_url": "https://tapm.scity.us/api/v1/packages/sentinelone-linux"
+    }
+  ]
+}
+```
+
+The first exchange enrolls that host against the authorization. Reusing the
+same code and host fingerprint does not consume another host slot. A different
+fingerprint consumes one slot until the configured limit is reached.
+
+## Download a package
+
+Send the session from the exchange:
+
+```sh
+curl --fail --location \
+  --header "Authorization: Bearer SESSION_TOKEN" \
+  --output /tmp/package.deb \
+  'https://tapm.scity.us/api/v1/packages/sentinelone-linux'
+```
+
+The client must calculate SHA-256 after download and compare it to the value
+returned by the exchange. It must delete the file and stop if the values differ.
+The server also returns the expected value in `X-TAPM-SHA256`.
+
+## Status behavior
+
+- `400`: malformed request
+- `403`: invalid, expired, revoked, or exhausted authorization
+- `429`: too many failed exchanges from the source address; retry after the
+  `Retry-After` interval
+- `502`: private package registry unavailable
+
+Codes and sessions expire at the same authorization deadline. Revoking an
+authorization immediately invalidates all of its sessions.