# Auth model

Sherlock is a service-keyed OAuth wallet. There is no `sherlock login` and no
master session: each MCP authenticates for the service it calls.

## Lifecycle

For a service such as `gitea`, `grafana`, `gssh`, or `searxng`, the MCP asks
`internal/authn` for a token on first use:

1. Fresh wallet entry: return it.
2. Stale entry with refresh token: refresh under
   `$XDG_RUNTIME_DIR/sherlock.refresh.lock`, persist, return.
3. Missing or unrecoverable entry: run a PKCE browser flow on `127.0.0.1:6990`,
   serialized by `$XDG_RUNTIME_DIR/sherlock.login.lock`, persist, return.

Long-running MCPs use `TokenSource` and `TokenHolder` so requests always read
the latest bearer. Refresh follows access-token expiry, never opens a browser,
and falls back to a fresh login on the next invocation if refresh can no longer
recover.

## Service identity

The config supplies issuer, client ID/secret, and base URL. Scopes are owned by
each MCP because they follow the tool surface, not the deployment.

Gitea uses Gitea's OAuth2 server. Grafana, Gssh, and SearXNG normally reuse the
shared Authentik `sherlock-cli` provider. Tokens are stored and refreshed per
service and are not reused across unrelated services.

## User controls

`sherlock status` lists stored sessions. `sherlock logout` clears all sessions;
`sherlock logout <service>` clears one.

Sherlock does not use static service-account tokens, share sessions between
operators, or perform RFC 8693 token exchange.