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).

docs/api-reference.md

@@ -1,49 +1,69 @@
 # API Reference
 
-## Endpoints
+## Core Endpoints
 
 - `GET /`: server metadata.
 - `GET /health`: health probe.
 - `GET /metrics`: Prometheus metrics (when enabled).
-- `POST /automation/webhook`: ingest policy-controlled webhook events.
-- `POST /automation/jobs/run`: run policy-controlled automation jobs.
+
+## OAuth Discovery and Token Exchange
+
+- `GET /.well-known/oauth-protected-resource`
+  - Returns OAuth protected resource metadata used by MCP clients.
+- `GET /.well-known/oauth-authorization-server`
+  - Returns OAuth authorization server metadata.
+- `POST /oauth/token`
+  - Proxies OAuth authorization-code token exchange to Gitea.
+
+## MCP Endpoints
+
 - `GET /mcp/tools`: list tool definitions.
-- `POST /mcp/tool/call`: execute a tool (`Authorization: Bearer <api-key>` required except in explicitly disabled auth mode).
+- `POST /mcp/tool/call`: execute a tool.
 - `GET /mcp/sse` and `POST /mcp/sse`: MCP SSE transport.
 
-## Automation Jobs
+Authentication requirements:
 
-`POST /automation/jobs/run` supports:
-- `dependency_hygiene_scan` (read-only scaffold).
-- `stale_issue_detection` (read-only issue age analysis).
-- `auto_issue_creation` (write-mode + whitelist + policy required).
+- MCP tool execution requires `Authorization: Bearer <token>`.
+- Missing or invalid tokens return `401` with:
+  - `WWW-Authenticate: Bearer resource_metadata="<absolute metadata url>", scope="read:repository"`
+
+Scope requirements:
+
+- Read tools require `read:repository`.
+- Write tools require `write:repository`.
+- Insufficient scope returns `403`.
+
+## Automation Endpoints
+
+- `POST /automation/webhook`: ingest policy-controlled webhook events.
+- `POST /automation/jobs/run`: run policy-controlled automation jobs.
 
 ## Read Tools
 
-- `list_repositories`.
-- `get_repository_info` (`owner`, `repo`).
-- `get_file_tree` (`owner`, `repo`, optional `ref`, `recursive`).
-- `get_file_contents` (`owner`, `repo`, `filepath`, optional `ref`).
-- `search_code` (`owner`, `repo`, `query`, optional `ref`, `page`, `limit`).
-- `list_commits` (`owner`, `repo`, optional `ref`, `page`, `limit`).
-- `get_commit_diff` (`owner`, `repo`, `sha`).
-- `compare_refs` (`owner`, `repo`, `base`, `head`).
-- `list_issues` (`owner`, `repo`, optional `state`, `page`, `limit`, `labels`).
-- `get_issue` (`owner`, `repo`, `issue_number`).
-- `list_pull_requests` (`owner`, `repo`, optional `state`, `page`, `limit`).
-- `get_pull_request` (`owner`, `repo`, `pull_number`).
-- `list_labels` (`owner`, `repo`, optional `page`, `limit`).
-- `list_tags` (`owner`, `repo`, optional `page`, `limit`).
-- `list_releases` (`owner`, `repo`, optional `page`, `limit`).
+- `list_repositories`
+- `get_repository_info` (`owner`, `repo`)
+- `get_file_tree` (`owner`, `repo`, optional `ref`, `recursive`)
+- `get_file_contents` (`owner`, `repo`, `filepath`, optional `ref`)
+- `search_code` (`owner`, `repo`, `query`, optional `ref`, `page`, `limit`)
+- `list_commits` (`owner`, `repo`, optional `ref`, `page`, `limit`)
+- `get_commit_diff` (`owner`, `repo`, `sha`)
+- `compare_refs` (`owner`, `repo`, `base`, `head`)
+- `list_issues` (`owner`, `repo`, optional `state`, `page`, `limit`, `labels`)
+- `get_issue` (`owner`, `repo`, `issue_number`)
+- `list_pull_requests` (`owner`, `repo`, optional `state`, `page`, `limit`)
+- `get_pull_request` (`owner`, `repo`, `pull_number`)
+- `list_labels` (`owner`, `repo`, optional `page`, `limit`)
+- `list_tags` (`owner`, `repo`, optional `page`, `limit`)
+- `list_releases` (`owner`, `repo`, optional `page`, `limit`)
 
 ## Write Tools (Write Mode Required)
 
-- `create_issue` (`owner`, `repo`, `title`, optional `body`, `labels`, `assignees`).
-- `update_issue` (`owner`, `repo`, `issue_number`, one or more of `title`, `body`, `state`).
-- `create_issue_comment` (`owner`, `repo`, `issue_number`, `body`).
-- `create_pr_comment` (`owner`, `repo`, `pull_number`, `body`).
-- `add_labels` (`owner`, `repo`, `issue_number`, `labels`).
-- `assign_issue` (`owner`, `repo`, `issue_number`, `assignees`).
+- `create_issue` (`owner`, `repo`, `title`, optional `body`, `labels`, `assignees`)
+- `update_issue` (`owner`, `repo`, `issue_number`, one or more of `title`, `body`, `state`)
+- `create_issue_comment` (`owner`, `repo`, `issue_number`, `body`)
+- `create_pr_comment` (`owner`, `repo`, `pull_number`, `body`)
+- `add_labels` (`owner`, `repo`, `issue_number`, `labels`)
+- `assign_issue` (`owner`, `repo`, `issue_number`, `assignees`)
 
 ## Validation and Limits
 
@@ -54,8 +74,8 @@
 
 ## Error Model
 
-- Policy denial: HTTP `403`.
-- Validation error: HTTP `400`.
 - Auth error: HTTP `401`.
+- Policy/scope denial: HTTP `403`.
+- Validation error: HTTP `400`.
 - Rate limit: HTTP `429`.
-- Internal errors: HTTP `500` without stack traces in production.
+- Internal errors: HTTP `500` (no stack traces in production).