neuron-tai/docs/adr/0017-tracker-authentication-and-authorization.md

ADR-0017: Tracker authentication and authorization

Status: Accepted

Context

The tracker exposes three overlapping trust domains:

1. Client API access — Bearer API keys for inference and billing (partially gated today).
2. Operator/admin access — session-based accounts in packages/tracker/meshnet_tracker/accounts.py (registration, login, admin listing).
3. Hive replication — gossip endpoints that mutate billing, accounts, and stats without authentication today.

Financial and registry endpoints leak through inconsistent checks: some handlers require only a non-empty Authorization header (header-presence stub), while gossip accepts arbitrary peer events. Alpha requires a single auth boundary before any state mutation or privileged read.

Decisions

1. Account subsystem (accounts.py)

• First registered account is admin; subsequent accounts are user.
• Login identifiers: email or wallet address + PBKDF2-SHA256 password.
• API keys (sk-mesh-…) are scoped to an account; revocation is event-sourced and gossip-replicated.
• Sessions are local (bearer tokens in memory, 7-day TTL) — not replicated across the hive. Each tracker validates its own sessions.
• Account mutations persist to SQLite and replicate via /v1/accounts/gossip events.

2. Client inference auth

• POST /v1/chat/completions requires a valid, non-revoked API key and positive ledger balance (402 if broke).
• Starting credit is 0 for new API keys (ADR-0016 / issue C5). No implicit faucet; clients must deposit mock-USDT via bound wallet (US-032) or admin credit.

3. Gossip auth (alpha blocker)

All hive mutation endpoints require authenticated peer identity:

• /v1/billing/gossip — billing event replication
• /v1/accounts/gossip — account/key replication
• /v1/stats/gossip — rolling RPM merge

Acceptable alpha mechanisms (pick one in implementation):

• Shared hive secret (HMAC over request body + timestamp, configured on all trackers), or
• Mutual TLS between tracker peers (extends ADR-0010 relay TLS pattern).

Followers must reject events from unauthenticated callers. Read-only endpoints (/dashboard, /v1/stats GET) may remain public on LAN alpha deployments.

Out of scope (alpha): POST /v1/gossip — node throughput / peer fan-out gossip (server.py ~1331), distinct from hive mutation endpoints above. Document as unauthenticated alpha limitation; authenticate in a future ADR amendment when node identity binding exists (issue 01 tracks hive endpoints only).

4. Privileged operator endpoints

These require real auth — not header presence alone:

Endpoint	Required role
POST /v1/billing/forfeit	Validator service identity or admin session
POST /v1/benchmark/hop-penalty	Admin session or service token
GET /v1/benchmark/results	Admin session or service token
GET /v1/admin/accounts	Admin session
GET /v1/billing/summary, /v1/billing/settlements, /v1/registry/wallets	Admin session (alpha: restrict financial reads)

The unified auth middleware resolves: API key → account; session token → account + role; service token → validator; hive HMAC → peer.

5. Node registration

Node POST /v1/register is open (ADR-0016) but banned wallets are rejected at registration and excluded from routing. Wallet binding for client deposits (POST /v1/wallet/register) requires a valid API key and cryptographic ownership proof (issue C6).

Consequences

• Gossip authentication (C1) and unified auth boundary (A2) are prerequisites for fraud penalties and billing fixes — an attacker can otherwise forge credits, strikes, or forfeit events.
• Session locality means admin login is per-tracker URL; document in runbooks.
• Multi-tracker auth evolution (client-signed commands) is deferred to ADR-0019.

Related

• ADR-0016 (alpha scope)
• ADR-0015 (billing gate on inference)
• .scratch/alpha-hardening/issues/01-c1-gossip-auth.md, 02-a2-unified-auth-boundary.md