oauth: redefine gating mode as pure OAuth resource server (#109)

[BorisTyshkevich]

Closes #109. Alternative path to #106 (#106 is the v2 stateful approach; #109 is the v1 stateless approach using Auth0's native DCR + reuse-detection).

Note on PR base: stacked on top of #105 (which is stacked on #104). Until both predecessors merge, the diff shown is against feature/oauth-require-email-verified. Once #104 + #105 land, GitHub auto-rebases this onto main and the diff narrows to the #109 commits alone.

Why

Today oauth.mode: gating means MCP is the OAuth Authorization Server — DCR endpoint, /authorize, /token, JWE-wrapped refresh tokens, custom HKDF rotation, and (under #106) KeeperMap-backed refresh-token reuse detection. Auth0 Enterprise / Authentik / Keycloak / Okta all do these natively.

Under #109 oauth.mode: gating is redefined to mean MCP is a pure OAuth resource server: it validates AS-issued JWTs (signature + RFC 8707 audience byte-equality + expiry), enforces per-tool scopes, and impersonates the user to ClickHouse via cluster_secret + Auth.Username. The upstream IdP owns DCR, /authorize, /token, refresh rotation, and reuse detection.

Forward mode (oauth.mode: forward) is unchanged — kept for IdPs without DCR (Google direct, basic-tier Auth0).

Trade-offs (accepted up front)

• Role-picker (oauth: DCR consent and bind tokens to roles #107): Auth0's stock consent UI shows scopes, not a CH-discovered role list. Deferred to v2.
• Revocation latency: Auth0 grant revocations take effect after natural access-token expiry. Mitigated by access_token_lifetime: 600 on the per-cluster Auth0 API.
• Refresh-token reuse detection: now Auth0's job. The MCP-side state in oauth: H-2 — refresh-token reuse detection (gating mode) #106 (pkg/oauth_state, KeeperMap) is no longer needed — oauth: H-2 — refresh-token reuse detection (gating mode) #106 stays open as a v2 follow-up if/when the role-picker forces MCP back into the AS business.

What changes

Commit	Effect
5cd4e87	Delete gating-mode AS handlers + state machinery (route registration gated by mode; forward path preserved)
124335b	Refuse gating + AS-side fields at startup (client_id, client_secret, token_url, auth_url, userinfo_url, public_auth_server_url, refresh_revokes_tracking); require Issuer + Audience non-empty under gating
845149d	Drop gating-AS test groups; add Audience to TestValidateOAuthRuntimeConfig fixtures
93008c7	Rewrite docs/oauth_authorization.md mode taxonomy + Auth0 setup checklist + migration note
3ab6738	Accept namespaced */email custom claim for CH impersonation (Auth0 enhanced-security third-party DCR strips the standard email claim — operators add it back via a post-login Action under a URL-prefixed key)

Net diff: ~580 production lines removed, ~580 test lines removed (gating-AS surface), ~210 docs lines added.

Live validation

Rolled out to two clusters (helm values live in the operator-side acm/mcp repo, not this PR):

• otel-mcp (gating, post-oauth: gating mode simplification  #109 redefined): claude.ai DCR'd connector → Auth0 → MCP → CH currentUser() returns btyshkevich@gmail.com. RFC 9728 advertises Auth0 as the AS; /.well-known/oauth-authorization-server returns 404 under gating. End-to-end smoke pass.
• antalya-mcp (forward, unchanged path): regression-free; CH returns rows via the existing <token_processor> flow. Confirms forward mode is preserved.

Operator runbook for replicating this on the next gating cluster (github, billing, customer deployments) is in the ops wiki at mcp-oauth-debugging.md § #109.

Test plan

• go build ./... clean on the branch
• go test ./pkg/{config,jwe_auth,clickhouse,server}/... ./cmd/altinity-mcp/... — pass (skipping embedded-CH harness tests, which are blocked by an environmental CH-26.3 bug unrelated to this PR — confirmed pre-existing on the base branch)
• Live e2e on otel + antalya per the description above
• CI green on the full stacked diff

🤖 Generated with Claude Code