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): ****

# Mint a long-lived subkey for pasting into an agent's MCP config:
h4a session create --mcp --tenant default
# eyJhbGciOi... (prints on stdout; TTL = 90 days)

# Or for a throwaway CLI call that runs for seconds:
h4a session create --tenant default
# TTL = 24h (the original default)

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

--mcp vs no flag

• --mcp — TTL = 90 days (2160 hours). Use this when you're pasting the token into an agent's MCP config. MCP bearers have no auto-refresh; a 24h token silently breaks the "paste once" pitch after a day.
• No flag — TTL = 24 hours. Appropriate for throwaway tokens your shell pipes into one command.
• --ttl-hours N — explicit override. Always wins.

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.
• All v0 bearers are full-access within their tenant — scope-narrowing (read-only / deploy-only subkeys) is post-M5 work.