# ADR-0003: Per-agent bearer tokens for identity and authorization

**Status:** Accepted (2026-08-08)

## Context

The design doc proposed identifying the connecting agent via "MCP handshake client info". The
`clientInfo` object in the MCP `initialize` request is **self-reported by the client** and trivially
forged. Hanging the permissions model off it — including `secrets: {read: false}` — would make that
model decorative rather than enforcing. This matters more once WireGuard or Pangolin place the
endpoint on a network beyond the operator's full control.

Alternatives considered: mTLS client certificates (stronger binding, but meaningful setup friction
per agent and per machine) and full OAuth 2.1 per the MCP authorization spec (standards-correct and
the right answer for public exposure, but an entire authorization server to build and operate for a
single-user homelab).

## Decision

Each agent identity is issued a **Bridle bearer token**. Identity and permissions derive from the
token presented on the connection. `clientInfo` is retained as a **display hint only** — surfaced in
the audit log and Web Panel, never consulted for an authorization decision.

Tokens are issued, rotated, and revoked through the admin API and Web Panel.

## Consequences

- Simple, revocable, and sufficient behind WireGuard.
- Forging `clientInfo` gains an attacker nothing.
- Token issuance/rotation/revocation is phase-1 scope.
- If Bridle is ever exposed to clients the operator does not control, revisit in favor of OAuth 2.1
  per the MCP authorization spec.