Hiddenden/AegisGitea-MCP
5
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

ci: raise the coverage gate to 90 percent; docs: reconcile OAuth docs with the implementation

Browse Source
This commit is contained in:
Latte committed 2026-10-14 17:53:58 +02:00
1 parent 0f5f5cdd95
commit d7cac91175
7 files changed
+66 -21
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/configuration.md
+18 -4
View File
@@ -56,22 +56,36 @@ when OAuth is on.
| Variable | Default | Rules |
|---|---|---|
| `OAUTH_ENABLED` | `false` | When true, the four settings below are required, or the server refuses to start (exit code 2, with the list of what is missing). |
| `OAUTH_ENABLED` | `false` | When true, `GITEA_OAUTH_CLIENT_ID`, `GITEA_OAUTH_CLIENT_SECRET`, `TOKEN_ENCRYPTION_KEY` and `PUBLIC_BASE_URL` are required, or the server refuses to start (exit code 2, with the list of what is missing). |
| `GITEA_OAUTH_CLIENT_ID` | unset | Client id of the Gitea OAuth application (created by `setup`). |
| `GITEA_OAUTH_CLIENT_SECRET` | unset | Its client secret. |
| `TOKEN_ENCRYPTION_KEY` | unset | At least 32 characters. Encrypts stored user tokens. Losing it invalidates every stored login. |
| `TOKEN_ENCRYPTION_KEY` | unset | At least 32 characters. Encrypts the token store. The key cannot be rotated in place: a store written with another key stops startup (exit code 2) instead of being wiped, until you restore the original key or move `DATA_DIR/oauth-store.json` away, which signs every user out. |
| `OAUTH_SCOPES` | all `write:<category>` scopes | Granular Gitea scopes only (`read:` or `write:` plus activitypub, admin, issue, misc, notification, organization, package, repository, user). Anything else is rejected, because Gitea grants full access for unknown scope strings. Must not be empty. |
| `OAUTH_REDIRECT_ALLOWLIST` | empty | Comma list of redirect URIs MCP clients may register: exact URIs (`https://client.example/cb`) or prefixes ending in `/` that allow a whole host (`https://claude.ai/`). A bare origin without a path is refused. Empty accepts any https URI (and http on `localhost`, `127.0.0.1`, `[::1]`). With a list, https URIs must match it; loopback URIs stay allowed for native clients. Checked at registration and again at `/authorize`. |
`PUBLIC_BASE_URL` is also required for OAuth. The Gitea OAuth application's redirect URI is
`<PUBLIC_BASE_URL>/oauth/callback`.
OAuth-only deployments are supported: with `OAUTH_ENABLED=true` and neither `MCP_BEARER_TOKEN`
nor `GITEA_TOKEN`, every user brings their own Gitea token and admin-token mode is simply not
available (nothing falls back to it). `GITEA_TOKEN` stays required whenever admin-token mode is
reachable: with a static bearer, without any HTTP authentication, and on stdio.
Sign-in flow and limits: `/authorize` sends the browser to the consent page `/oauth/consent`,
which names the client and the redirect URI and needs an explicit approval (CSRF token, cookie
and an `Origin` that matches `PUBLIC_BASE_URL`) before the browser goes to Gitea; the callback
`/oauth/callback` completes only in that same browser. Issued `agm_` access tokens live 1 hour
and refresh tokens 30 days (rotated on use, reuse revokes the grant); authorization codes live 5
minutes and pending sign-ins 10 minutes. Bounds: 500 registered clients (10 redirect URIs and 8
KiB of metadata each), 1024 pending sign-ins and codes, 50 sessions per Gitea login, and per
client address 20 pending sign-ins and 20 registrations per hour. The consent form body is
limited to 16 KiB and must be `application/x-www-form-urlencoded`.
## State
| Variable | Default | Rules |
|---|---|---|
| `DATA_DIR` | `~/.local/state/aegis-gitea-mcp` (`/var/lib/aegis-mcp` in the image) | `~` is expanded. Holds the token store (`oauth-tokens.json`, mode 0600) and the audit log. |
| `DATA_DIR` | `~/.local/state/aegis-gitea-mcp` (`/var/lib/aegis-mcp` in the image) | `~` is expanded. Holds the encrypted token store (`oauth-store.json`, mode 0600) and the audit log. A new directory is created with mode 0700; an existing one must belong to the running user and is tightened to 0700, otherwise OAuth startup fails. |
| `AUDIT_LOG_PATH` | `DATA_DIR/audit.log` | Path of the hash-chained audit log. See [audit-logging.md](audit-logging.md). The server opens it for append at startup and exits with code 2 and a message on stderr when it cannot. |
## Tool exposure