Control Plane Auth

How QTG authenticates and authorizes service-to-service callers using HMAC signatures, role-scoped keys, and nonce replay protection.

Control Plane Auth

What is this auth for?

QTG v3’s inbound auth is not a user login system — it is control plane access control.

The questions it answers are:

1. Did this request really come from a registered system?
2. Does this key have permission to perform this action?
3. Was the request body tampered with in transit?
4. Is this request a replay of a previous one?

In other words, this is not multi-tenancy — it’s a service-to-service command protection layer.

Human-auth login exists only as an opt-in local profile: qtg core-local plus qtg human login / qtg human inspect / qtg human logout (browser/WebAuthn, loopback callback, /v3/auth/human/*), with qtg bootstrap-human-owner as the one-off owner bootstrap. No hosted/public login surface exists — the human routes 404 unless the local human origin is explicitly enabled (human_local_origin). Do not treat the internal persistence/service code as a generally available user-login surface.

Who are the callers?

Examples of systems that act as callers:

• signal-bot — creates movements (operator or agent)
• dashboard — approves/rejects (operator)
• ops-cli — retries/resumes/cancels (operator)
• admin-cli — signer rotation + registry status control (admin)
• read-monitor — status queries (operator)

These systems don’t see different data — they share the same control plane but differ only in what actions they are allowed to take. The exception is the agent role, which is additionally tenant-isolated to a single namespace (see The agent role and namespace isolation).

Authentication method

Required headers:

• X-QTG-Key-Id
• X-QTG-Timestamp
• X-QTG-Nonce
• X-QTG-Signature

Canonical string:

METHOD
PATH
QUERY
SHA256(raw_body_bytes)
TIMESTAMP
NONCE

• PATH is the routed, percent-decoded path the server dispatches on — no origin, no query string.
• QUERY is the query exactly as sent: no leading ?, no sorting, empty string if absent. Sorting before signing transmits bytes you did not sign, and every such request 401s.

The caller computes HMAC-SHA256 over this canonical string and sends it as X-QTG-Signature.

QTG verifies in this order:

1. timestamp freshness check
2. key_id lookup
3. HMAC comparison
4. nonce uniqueness check
5. role check
6. (agent keys only) namespace match check

The signature is verified before the role check on purpose. The other way round, an unauthenticated caller could probe any key_id against any route and read that key’s role off the 401-vs-403 split.

Why is a nonce needed?

With only a timestamp, it’s possible to “resend the same request within the 5-minute window.”

For example:

• approve movement X
• An attacker captures the same request and resends it 30 seconds later

To prevent this, a nonce ledger is required.

QTG records (key_id, nonce) in the DB, and if the same combination arrives again it is rejected with 401 replay detected.

Role model

Authorization is a 3-role axis. Every API client key carries exactly one role, constrained at the DB level to one of:

• admin — full control (template/signer/executor mutation, registry, rotation)
• operator — approve/reject, retry/resume/cancel, reads, and (when installed and enabled) Pro capital transfers
• agent — propose movements within a single tenant namespace, read its own status

This replaced the older 6-”purpose” model (read/write/approval/operate/admin/all). The purpose column survives as a label only; the live authorization axis is roles, and the seed CLI accepts only --role.

Authority is a fixed route catalog, keyed by (method, path) → allowed roles:

Route	Allowed roles
POST /v3/movements, GET /v3/movements, GET /v3/movements/{id} · /timeline	admin, operator, agent
GET /v3/balances, GET /v3/route-catalog, POST /v3/routes/recommend, GET /v3/whoami	admin, operator, agent
POST /v3/movements/{id}/approve · /reject · /actions/retry · /resume · /cancel	admin, operator
GET /v3/signers, GET /v3/executors, GET /v3/audit/events, GET /v3/registry/audit	admin, operator
/v3/capital-transfers (all verbs)	admin, operator
POST / PATCH /v3/plan-templates, PATCH /v3/executors/{key}, PATCH /v3/signers/{key}	admin
POST /v3/template-proposals/{id}/promote, /v3/agent-wallet-funding/envelopes writes	admin
POST /v3/agent-authorities/{key}/template-proposals · /bridge-attempt	agent only

Reads are not automatically the loosest tier — GET /v3/signers is admin+operator while GET /v3/movements is open to agents. The table prevents, for example, an agent key from approving its own proposal, or an operator key from mutating a signer registry entry.

The catalog is extended at boot. Pro registers its own routes (capital transfers, CCIP/Stargate administration, and auto-approve policies) through the same (method, path) → roles mechanism, so an OSS deployment simply has fewer entries — never looser ones. Capital-transfer creation remains disabled until its separate Pro mutation flag is explicitly enabled.

The agent role and namespace isolation

The agent role is the only one with tenant isolation. An agent key is bound 1:1 to a network-scoped authority. The control plane enforces that the authority / namespace in the request path matches the authority the key is bound to — a mismatch is rejected with 403 agent_namespace_mismatch before the handler runs. So even a leaked agent key can only act within its own namespace, and only to propose: agent-originated movements are never auto-approved, whatever auto-approve policy is in scope, and a human operator must approve them.

Storage structure

Keys and replay-protection state are backed by a DB-based registry:

• a record per registered client system
• a record per issued key, looked up directly by key_id
• a nonce ledger that records seen (key_id, nonce) pairs for replay defense

Authentication channels

QTG has two primary authentication channels plus an opt-in human-session bearer plane:

Channel	Path	Auth method	Purpose
HMAC API	/v3/*	HMAC-SHA256 signature (4 headers) + role check	Programmatic API access
Dashboard HMAC	/dashboard/*	Per-operator HMAC v3 (nonce + timestamp); browser holds a non-extractable CryptoKey	Dashboard UI write protection
Human session	/v3/auth/human/*, /v3/auth/human-sessions/*	Bearer qtgs1. session token + WebAuthn-backed capability check (validate_session)	Opt-in local human login profile (JEP-877)

A Pro-registered OIDC bearer seam also exists for browser movement routes (register_oidc_routes), inactive unless registered.

These channels are separate and do not cross. Dashboard UI uses /dashboard/* routes; programmatic callers like Hummingbot and signal-bot use /v3/* routes. Dashboard write keys are issued as role=operator (admin keys are also accepted; the dashboard_writer label survives only for log clarity). The old MG_DASHBOARD_WRITE_TOKEN / VITE_DASHBOARD_WRITE_TOKEN bearer-token model has been removed — the server hard-fails at startup if MG_DASHBOARD_WRITE_TOKEN is set. See the dashboard auth migration runbook.

---

Caller Inventory & Naming Matrix

Naming Convention

Key ID pattern: {client-name}-{environment}

Element	Rule	Example
client-name	lowercase hyphenated, matches the system name	strategy-engine, ops-cli
environment	staging or prod	staging, prod
suffix (optional)	only when the same client needs multiple keys	dashboard-staging-v2

Client Name: stays identical across environments. Must match the --client-name argument of the seed CLI.

HMAC Caller Matrix

Client Name	Key ID (staging)	Role	Actual system	Usage
strategy-engine	strategy-engine-staging	operator (or agent for namespace-scoped bots)	Hummingbot controller / signal bot	Create movements (signal)
dashboard	dashboard-staging	operator	Dashboard (HMAC path)	Approve/reject movements
ops-cli	ops-cli-staging	operator	Operations CLI scripts	Retry/resume/cancel
admin-cli	admin-cli-staging	admin	Admin CLI scripts	Signer rotation, registry management, auto-approve policy
read-monitor	read-monitor-staging	operator	Monitoring/alerting system	Status queries, polling (reads need the operator role)

There is no read-only role: GET routes are reachable by operator (and many by agent). Use operator for read/monitor callers.

---

Seed procedure

# Staging seed example
uv run python -m qtg.interfaces.tools.seed_auth_client \
  --client-name strategy-engine \
  --key-id strategy-engine-staging \
  --role operator \
  --database-url "$MG_DATABASE_URL"

# Prod seed example (change DB URL)
uv run python -m qtg.interfaces.tools.seed_auth_client \
  --client-name strategy-engine \
  --key-id strategy-engine-prod \
  --role operator \
  --database-url "$MG_PROD_DATABASE_URL"

The hmac_secret printed to stdout is only visible at this moment. Store it in a secure location immediately.

Key lifecycle management CLI:

# List all registered keys
uv run python -m qtg.interfaces.tools.list_auth_keys \
  --database-url "$MG_DATABASE_URL"

# Revoke is governed; the legacy revoke_auth_key command is deliberately retired.
# QTG_KEY_ID/QTG_HMAC_SECRET must identify an active HMAC admin.
qtg auth revoke-credential --credential-type hmac --credential-id "$OLD_KEY_ID" \
  --reason "planned key rotation"
# Never use a key ID plus DB URL as authority. Explicit self-revoke is supported
# for emergencies; preserve a recovery admin credential when continuity is needed.

---

Secret Storage Policy

Principles

1. Complete isolation between environments: staging and prod use separate secrets. Never share them.
2. Least privilege: each caller is issued a key with the narrowest role it needs (agent < operator < admin). Reserve admin for the admin CLI only.
3. Store immediately on creation: the secret printed by the seed CLI is one-time only. Store it in a secure location immediately.
4. No git commits: never commit .env files, seed artifacts, or any file containing a secret.

Storage guide by environment

Environment	Storage method	Access control	Backup
local dev	.env file (gitignored)	Developer only	Not required
staging	.env.staging on host, chmod 600	Operator access only	Optional
prod	.env.prod on host, chmod 600	Operator access only	Encrypted separate backup required

Management by secret type

Secret type	How generated	Where stored	Rotation impact
HMAC caller secret	seed_auth_client CLI (auto 64-char hex)	Caller’s .env + DB (api_client_keys)	Zero-downtime possible
Dashboard writer HMAC key	seed_auth_client --role operator (per operator)	DB (api_client_keys); browser holds a non-extractable CryptoKey	Zero-downtime (per-operator key revoke)
Callback HMAC secret	openssl rand -hex 32	.env (sender) + receiver config	Both sender and receiver must rotate
Exchange API keys	Exchange console	.env	Container restart required

Rotation policy

• Scheduled rotation: once per quarter, or immediately upon suspected secret exposure
• HMAC key rotation (zero-downtime):
  1. Check current keys with list_auth_keys
  2. Seed a new key for the same client (seed_auth_client --key-id {client}-{env}-v{N+1})
  3. Deploy the new secret to the caller (update .env + restart)
  4. Smoke test with the new key
  5. Run qtg auth revoke-credential --credential-type hmac --credential-id "$OLD_KEY_ID" \ --reason "planned key rotation" with an authenticated HMAC-admin actor. The legacy revoke_auth_key command fails closed; explicit self-revoke remains available for emergencies.
• Dashboard writer rotation: re-seed the operator’s HMAC key and revoke the old one — no frontend rebuild (the key is no longer baked into the bundle)
• Emergency rotation: execute immediately, accepting service interruption

---

One-line summary

QTG v3 auth is a layer that enforces “who can send what kind of command to this control plane” via HMAC + role + nonce (+ namespace isolation for agent keys).