Add OAuth2/OIDC per-user Gitea authentication

Introduce a GiteaOAuthValidator for JWT and userinfo validation and
fallbacks, add /oauth/token proxy, and thread per-user tokens through
the
request context and automation paths. Update config and .env.example for
OAuth-first mode, add OpenAPI, extensive unit/integration tests,
GitHub/Gitea CI workflows, docs, and lint/test enforcement (>=80% cov).

.env.example

@@ -1,20 +1,29 @@
-# Runtime Environment
+# Runtime environment
 ENVIRONMENT=production
 
-# Gitea Configuration
-GITEA_URL=https://gitea.example.com
-GITEA_TOKEN=your-bot-user-token-here
+# Gitea OAuth/OIDC resource server
+GITEA_URL=https://git.hiddenden.cafe
 
-# MCP Server Configuration
-# Secure default: bind only localhost unless explicitly overridden.
+# OAuth mode (recommended and required for per-user repository isolation)
+OAUTH_MODE=true
+GITEA_OAUTH_CLIENT_ID=your-gitea-oauth-client-id
+GITEA_OAUTH_CLIENT_SECRET=your-gitea-oauth-client-secret
+# Optional explicit audience override; defaults to GITEA_OAUTH_CLIENT_ID
+OAUTH_EXPECTED_AUDIENCE=
+# OIDC discovery and JWKS cache TTL
+OAUTH_CACHE_TTL_SECONDS=300
+
+# MCP server configuration
 MCP_HOST=127.0.0.1
 MCP_PORT=8080
 ALLOW_INSECURE_BIND=false
 
-# Authentication Configuration (REQUIRED unless AUTH_ENABLED=false)
-AUTH_ENABLED=true
-MCP_API_KEYS=your-generated-api-key-here
-# MCP_API_KEYS=key1,key2,key3
+# Logging / observability
+LOG_LEVEL=INFO
+AUDIT_LOG_PATH=/var/log/aegis-mcp/audit.log
+METRICS_ENABLED=true
+EXPOSE_ERROR_DETAILS=false
+STARTUP_VALIDATE_GITEA=true
 
 # Authentication failure controls
 MAX_AUTH_FAILURES=5
@@ -24,13 +33,6 @@ AUTH_FAILURE_WINDOW=300
 RATE_LIMIT_PER_MINUTE=60
 TOKEN_RATE_LIMIT_PER_MINUTE=120
 
-# Logging / observability
-LOG_LEVEL=INFO
-AUDIT_LOG_PATH=/var/log/aegis-mcp/audit.log
-METRICS_ENABLED=true
-EXPOSE_ERROR_DETAILS=false
-STARTUP_VALIDATE_GITEA=true
-
 # Tool output limits
 MAX_FILE_SIZE_BYTES=1048576
 MAX_TOOL_RESPONSE_ITEMS=200
@@ -50,3 +52,8 @@ WRITE_ALLOW_ALL_TOKEN_REPOS=false
 AUTOMATION_ENABLED=false
 AUTOMATION_SCHEDULER_ENABLED=false
 AUTOMATION_STALE_DAYS=30
+
+# Legacy compatibility (not used for OAuth-protected MCP tool execution)
+# GITEA_TOKEN=
+# MCP_API_KEYS=
+# AUTH_ENABLED=true