77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
# Agent Token Future State
|
|
|
|
Static `ZLH_AGENT_TOKEN` is acceptable as a launch hardening layer, but it should not be treated as the final trust model.
|
|
|
|
## Launch / short term
|
|
|
|
For launch, keep the trust model simple and reliable:
|
|
|
|
- API refuses to start in production without `ZLH_AGENT_TOKEN`.
|
|
- Agent refuses protected requests in production without a configured `ZLH_AGENT_TOKEN`.
|
|
- Portal never sees the Agent token.
|
|
- API injects the token into every Agent request.
|
|
- Protected Agent routes remain behind the token; only intentionally public endpoints such as `/health` and `/version` should be public.
|
|
|
|
This closes the immediate API-to-Agent control-plane gap without adding clock, issuer, audience, or scope drift risk during final launch validation.
|
|
|
|
## Longer-term target
|
|
|
|
The better long-term pattern is short-lived signed API-to-Agent request tokens.
|
|
|
|
In that model:
|
|
|
|
1. API keeps a signing secret or private key.
|
|
2. Agent knows only the verification secret or public key.
|
|
3. API signs a short-lived token per Agent request, usually 30-120 seconds.
|
|
4. Agent verifies issuer, audience, expiry, VMID, and scope before executing the request.
|
|
|
|
Example claims:
|
|
|
|
```json
|
|
{
|
|
"iss": "zpack-api",
|
|
"aud": "zlh-agent",
|
|
"vmid": 5202,
|
|
"scope": "files:read",
|
|
"iat": 1714500000,
|
|
"exp": 1714500060,
|
|
"jti": "request-id"
|
|
}
|
|
```
|
|
|
|
This limits blast radius if a token is exposed. A stolen short-lived `files:read` token for VMID `5202` cannot be reused later to stop another server, restore a backup, or mutate files on a different container.
|
|
|
|
## Roadmap
|
|
|
|
- Phase 1: static `ZLH_AGENT_TOKEN`, fail-closed in production.
|
|
- Phase 2: token rotation and deployment validation so stale or missing tokens are caught before traffic.
|
|
- Phase 3: short-lived API-signed request tokens for API-to-Agent calls.
|
|
- Phase 4: optional mTLS between API and Agent for transport-level service identity.
|
|
|
|
## JWT vs HMAC request signatures
|
|
|
|
JWT is useful when explicit claims and public-key verification are desired.
|
|
|
|
A compact HMAC request-signing scheme may be simpler for the Agent:
|
|
|
|
```text
|
|
X-ZLH-Agent-Timestamp: <unix timestamp>
|
|
X-ZLH-Agent-Vmid: <vmid>
|
|
X-ZLH-Agent-Scope: lifecycle:stop
|
|
X-ZLH-Agent-Signature: HMAC(secret, method + path + timestamp + vmid + scope + bodyHash)
|
|
```
|
|
|
|
Either is better than a forever bearer token once the launch system is stable.
|
|
|
|
## Not a launch blocker
|
|
|
|
Do not jump directly to short-lived signed tokens before launch unless required. They add operational complexity:
|
|
|
|
- clock drift
|
|
- issuer/audience mismatch
|
|
- token scope bugs
|
|
- signing-key/config drift
|
|
- harder provisioning debugging
|
|
|
|
For launch, static token plus fail-closed production behavior is the correct low-risk hardening step. For scale, short-lived signed API-to-Agent tokens are the cleaner end state.
|