68e057209c
Lock alpha scope, tracker auth, TOPLOC fraud verification, and deferred multi-tracker money-path work; supersede legacy fraud issues with ADR-0018. Co-authored-by: Cursor <cursoragent@cursor.com>
76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# 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`
|