# 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`