neuron-tai/.scratch/alpha-hardening/issues/20-validator-service-token.md

Status: ready-for-agent

20 — Validator service token for /v1/billing/forfeit

What to build

Define and implement a validator service token distinct from client API keys and admin sessions. The validator process must authenticate when calling POST /v1/billing/forfeit; arbitrary Bearer strings and client API keys must be rejected.

Per ADR-0017 §4: forfeit accepts validator service identity or admin session only.

Configuration

Item	Alpha default
Env var	MESHNET_VALIDATOR_SERVICE_TOKEN (tracker + validator)
Config flag	--validator-service-token / tracker config file equivalent
Header format	Authorization: Bearer <service-token> with a dedicated prefix or separate header scheme documented in runbooks (e.g. Authorization: Service <token> — pick one and test consistently)
Rotation	Manual: set new token on tracker + validator, restart both; document zero-downtime rotation as post-alpha

Rejection rules

• Client API keys (sk-mesh-…) → 403 on forfeit (even if valid for inference)
• Non-empty garbage Bearer → 401/403
• Missing auth → 401
• Valid validator service token → 200 (existing forfeit semantics)
• Admin session → 200 (operator override)

Test-first

1. Red: validator (or test client) posts forfeit with a valid API key — must fail after fix.
2. Red: Authorization: Bearer garbage — must fail (covered by issue 02; this issue defines the accepted token).
3. Green: configured service token succeeds; wrong token fails.

Acceptance criteria

• Service token configurable via env/flag on tracker and validator
• Unified auth middleware resolves service token → validator role (issue 02)
• API keys explicitly rejected on forfeit path
• Integration test: validator client with service token forfeit succeeds; API key forfeit fails
• Runbook stub: rotation procedure (manual alpha)

ADR links

• ADR-0017 §4

Related

• 02-a2-unified-auth-boundary.md — middleware + role checks

Blocked by

• 02-a2-unified-auth-boundary.md