Authentication

Status: v0 (M1). Single-operator model. Multi-tenant auth lands in M5.

Two keys, two roles

• Master key — 32 random bytes. Generated by the control plane on first run; stored at /var/lib/h4a/master.key, mode 0600. Also stored on your laptop at ~/.config/h4a/credentials after h4a login, because the CLI needs it to mint subkeys. Treat it like a root password.

• Subkey — a short-lived JWT (HS256, signed with the master key) with a tenant claim and exp. This is what you paste into an agent's MCP config.

Flow

# On the control-plane host, once:
cat /var/lib/h4a/master.key         # copy

# On your laptop, once:
h4a login https://h4a.site
#   Master key (input hidden): ****

# Every time you want a fresh subkey for an agent:
h4a session create --tenant default --ttl-hours 24
# eyJhbGciOi... (prints on stdout)

Paste the JWT into your agent's MCP config as the bearer token. The MCP URL is https://h4a.site/mcp.

Error responses

All 401 responses carry this docs_url and a human-readable message. Common cases:

• missing Bearer header — add Authorization: Bearer <subkey> on every request.
• token expired — mint a new subkey with h4a session create.
• master key mismatch — the key on your laptop doesn't match the control plane's; re-run h4a login.
• unexpected signing method — the token wasn't minted by this control plane.

Rotation

v0 has no automatic rotation. If the master key leaks:

1. ssh to the control-plane VM.
2. rm /var/lib/h4a/master.key && systemctl restart h4a-controlplane.
3. h4a login https://h4a.site again on every operator machine.
4. All existing subkeys are now invalid; agents must session create again.

Threat model

• Single operator, single tenant. The master key protects against casual theft; it does not protect against a compromised control-plane host.
• Subkeys are stateless (no revocation list). To invalidate a subkey before exp, rotate the master key.
• Bearer tokens only travel over TLS — never over plaintext HTTP.