Status: done

# 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. This is a checklist subtask for issue 02 and should normally land in the same PR as the unified auth middleware.

Per [ADR-0017 §4](../../docs/adr/0017-tracker-authentication-and-authorization.md): 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](../../docs/adr/0017-tracker-authentication-and-authorization.md) §4

## Related

- `02-a2-unified-auth-boundary_completed.md` — middleware + role checks

## Blocked by

- `02-a2-unified-auth-boundary_completed.md`