feat(auth): support RS256 + OIDC discovery (JWKS auto-fetch)

Add Jwt__Algorithm config to choose between HS256 (shared symmetric key,
existing behavior, default) and RS256 (Authority-based OIDC discovery,
public-key auto-fetch with periodic refresh).

RS256 mode makes the server compatible with any standard OAuth 2.1 / OIDC
provider (Logto, ZITADEL, Keycloak, Auth0) without requiring a shared
secret. HS256 mode remains the default for minimal self-built AS setups.

README.md

@@ -8,6 +8,13 @@ The MCP server holds a single read-only Gitea Personal Access Token (PAT)
 internally and never exposes it to the MCP client. Clients authenticate to
 this server with an OAuth-issued JWT instead.
 
+Two JWT signing modes are supported:
+
+- **HS256** (default) — shared symmetric key between AS and this server. Use for self-built minimal AS.
+- **RS256** — fetches JWKS automatically via OIDC discovery from `<Issuer>/.well-known/openid-configuration`. Use with any standard provider: [Logto](https://logto.io), [ZITADEL](https://zitadel.com), [Keycloak](https://www.keycloak.org), [Auth0](https://auth0.com), etc.
+
+See [Choosing an AS](#choosing-an-as) below for setup guidance.
+
 ## Architecture
 
 ```
@@ -60,10 +67,11 @@ All tools require a valid JWT with `scope=read:gitea`.
 | `Gitea__RepoBlacklist` | *(empty)* | no | Comma-separated `owner/repo` pairs to hide |
 | `Gitea__DefaultLimit` | `50` | no | Default page size for list operations |
 | `Gitea__MaxFileBytes` | `1048576` | no | Max file/log read size in bytes (1MB) |
+| `Jwt__Algorithm` | `HS256` | no | `HS256` or `RS256` |
 | `Jwt__Issuer` | — | **yes** | Expected `iss` claim — your AS's issuer URL |
 | `Jwt__Audience` | `gitea` | no | Expected `aud` claim |
-| `Jwt__SigningKey__Current` | — | **yes** | HS256 signing key, shared with your AS |
-| `Jwt__SigningKey__Previous` | — | no | Previous key for rotation window |
+| `Jwt__SigningKey__Current` | — | HS256 only | HS256 signing key, shared with your AS |
+| `Jwt__SigningKey__Previous` | — | no | Previous HS256 key for rotation window |
 | `Mcp__OAuthDiscovery__Issuer` | — | **yes** | `/.well-known` `issuer` field |
 | `Mcp__OAuthDiscovery__AuthorizationEndpoint` | — | **yes** | Your AS's `/authorize` URL |
 | `Mcp__OAuthDiscovery__TokenEndpoint` | — | **yes** | Your AS's `/token` URL |
@@ -146,6 +154,35 @@ on every push to `main`. It expects these repository Variables / Secrets:
 - `vars.IMAGE_OWNER` — registry owner/namespace
 - `secrets.PACKAGES_TOKEN` — registry push token
 
+## Choosing an AS
+
+Claude.ai chat enforces the full OAuth Authorization Code + PKCE flow against
+your MCP server's `/.well-known/oauth-authorization-server` endpoint — there
+is no bearer-token shortcut. Pick one of these paths:
+
+**Hosted (fastest start, recommended for new setups)** — RS256 mode:
+
+| Provider | Free tier | Notes |
+|---|---|---|
+| [Logto Cloud](https://logto.io) | 5000 MAU | Lightest, ~30 min setup |
+| [ZITADEL Cloud](https://zitadel.com) | 25k auths/month | More featureful, slightly heavier docs |
+
+Set `Jwt__Algorithm=RS256` and `Jwt__Issuer=<your-tenant-issuer-URL>`.
+Public keys are fetched automatically from `<Issuer>/.well-known/openid-configuration`.
+
+**Self-hosted, full-featured** — RS256 mode:
+[Keycloak](https://www.keycloak.org), [ZITADEL](https://github.com/zitadel/zitadel), [Logto](https://github.com/logto-io/logto), [Authentik](https://goauthentik.io).
+
+**Self-hosted, minimal** — HS256 mode:
+Write your own ~500 LoC AS that issues HS256 JWTs with the right claims. The
+MCP server's `Jwt__SigningKey__Current` and the AS's signing key must match.
+
+**Required AS features regardless of choice:**
+- OAuth 2.1 + PKCE (RFC 7636)
+- Dynamic Client Registration (RFC 7591) — so Claude.ai can self-register
+- `resource` parameter support (RFC 8707) — for audience-bound tokens
+- Custom scope support (`read:gitea`)
+
 ## License
 
 MIT