sherlock/docs/auth-model.md

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, or gssh, 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 never opens a browser; if refresh can no longer recover, the next invocation performs a fresh login.

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 and Gssh 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.