diff --git a/.gitignore b/.gitignore index 35bad4e..13758d6 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,5 @@ target/ *.war *.ear !gradle-wrapper.jar +__pycache__/ +*.pyc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7d28f6..d95b460 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,39 +16,79 @@ You'll need **Java 17+** and **Gradle** (the wrapper is included). ``` src/ + main/resources/ + gitbucket-plugin.properties # the descriptor GitBucket reads + update/mcp-plugin_1.0.xml # Liquibase changelog for the OAuth tables main/scala/ - Plugin.scala # GitBucket plugin entry point + Plugin.scala # GitBucket entry point; declares `versions` com/newsrx/mcpplugin/ - MCPController.scala # HTTP routes, auth, JSON-RPC dispatch + MCPPlugin.scala # registration, routes, anonymous paths + MCPController.scala # HTTP, authentication, JSON-RPC dispatch + PluginDescriptor.scala # reads the packaged descriptor, not a literal mcp/ - JsonRpc.scala # JSON-RPC 2.0 parsing/formatting - ToolDef.scala # Tool interface + registry + schema helpers + JsonRpc.scala # JSON-RPC 2.0 parsing and formatting + ToolDef.scala # tool interface, registry, schema helpers + StrictArgs.scala # argument parsing that refuses coercion + Timestamps.scala # UTC ISO-8601 formatting + oauth/ # the authorization server + OAuthConfig.scala # configuration, and the rules it enforces + OAuthEndpoints.scala # authorize, token, revoke + OAuthStore.scala # grants, codes, rotation, replay detection + Metadata.scala ConsentView.scala # discovery documents, consent screen + ClientMetadata.scala # client ID metadata documents, SSRF policy + PinnedConnection.scala # the fetcher: destination pinning and bounds + Pkce.scala Secrets.scala Scopes.scala ChallengeError.scala + AuthenticatedCaller.scala # the caller, and the scope it holds tools/ - IssueTools.scala # 6 issue management tools - PullRequestTools.scala # 6 pull request tools + IdentityTools.scala # 1 identity tool + IssueTools.scala # 7 issue tools + PullRequestTools.scala # 9 pull request tools RepositoryTools.scala # 2 repository tools - SessionSupport.scala # Database session acquisition - test/scala/com/newsrx/mcpplugin/ - JsonRpcSpec.scala # JSON-RPC protocol tests (15) - ToolDefSpec.scala # Registry and schema tests (23) - ToolArgParseSpec.scala # Argument parsing tests (17) + Authz.scala # the repository read/write guards + SessionSupport.scala # database session acquisition + test/scala/ # the offline suites: `./gradlew test` +itest/ # live-instance gates; see itest/README.md scripts/ - integration_test.py # End-to-end integration test runner + integration_test.py # the original pre-OAuth runner, superseded + # by itest/integration.py ``` +Per-file tool counts are there to orient you, not as an inventory to keep in +step; `ToolRegistrySpec` is what actually pins the registry. + ## Running tests ```bash -./gradlew test # unit tests -python3 scripts/integration_test.py ... # integration tests (needs GitBucket) +./gradlew test # the offline suites +python3 itest/selftest.py # the gates' own guards; no server, no network ``` +Everything else needs a **disposable** GitBucket with the plugin installed — +the gates create accounts and repositories and deliberately attempt refused +writes, so they must never be pointed at an instance holding anything real. +`itest/README.md` has the commands, the system properties each gate needs, and +what each one covers. + ## Adding a new tool -1. Add a class in the appropriate `*Tools.scala` file, extending `ToolDef` and the relevant service trait. -2. Register it in `ToolDef.scala` → `ToolRegistry.all`. -3. Add unit tests in `ToolDefSpec.scala` and/or `ToolArgParseSpec.scala`. -4. Add an integration test case in `scripts/integration_test.py`. +1. Add a class in the appropriate `*Tools.scala` file, extending `ToolDef` and + the relevant service trait. +2. **Declare `requiredScope`.** It is an abstract member of `ToolDef`, so a + tool that omits it does not compile — which is deliberate: the alternative + is a tool that quietly defaults to the weaker requirement. `McpScope.Read` + for a tool that only reads, `McpScope.Write` for anything that changes + state. A `mcp:read` grant cannot call a `Write` tool, and the check happens + before the tool runs; the repository guard in `Authz` still applies inside + it, so the scope is a ceiling and never a substitute for permissions. +3. Register it in `ToolDef.scala` → `ToolRegistry.all`. +4. Add unit tests: schema and registry in `ToolDefSpec.scala` / + `ToolRegistrySpec.scala`, argument parsing in `ToolArgParseSpec.scala` or + `StrictArgsSpec.scala`, and the tool's behaviour through its real `execute` + in `tools/ToolExecutionSpec.scala`. +5. Add a case to `itest/integration.py`, which compares the tool's answer with + GitBucket's own REST API against each repository visibility and each + collaborator role. +6. Add its row to the tool table in `README.md`, including the scope. ## Pull requests @@ -56,6 +96,8 @@ python3 scripts/integration_test.py ... # integration tests (needs GitBucket) - All existing tests must pass (`./gradlew test`). - Match the existing code style (no comments explaining *what*, only *why* when non-obvious). - Update `README.md` if you add or change tool behaviour. +- Use neutral example identities in fixtures (`example-org`, `example.com`, + `example.invalid`). Never a real host, account or deployment address. ## Reporting issues diff --git a/DEPLOY.md b/DEPLOY.md index 0dd09d1..f4166d5 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -1,62 +1,122 @@ -# Deploy to a GitBucket instance — verified runbook +# Installing on a GitBucket instance -Tested 2026-09-03 against a local GitBucket 4.44.0 instance (JDK 21, `~/Downloads/gitbucket.war` -run standalone with Jetty). Full round trip confirmed: build, hot-deploy, MCP handshake, read tool -call, write tool call. +Generic runbook. It names no particular instance: substitute your own host, +account and `GITBUCKET_HOME`. For what the plugin requires, which GitBucket +versions have been tested and what has not been tried, see +[README.md](README.md) and [docs/authentication.md](docs/authentication.md); +this page is only the mechanics of getting the JAR in place. ## 1. Build + ```bash ./gradlew shadowJar ``` + Produces `build/libs/gitbucket-mcp-plugin-.jar`. -## 2. Deploy -Drop the jar into the target GitBucket's plugin directory: +## 2. Install + +Copy the JAR into the target GitBucket's plugin directory: + ```bash -cp build/libs/gitbucket-mcp-plugin-.jar $GITBUCKET_HOME/plugins/ +cp build/libs/gitbucket-mcp-plugin-.jar "$GITBUCKET_HOME/plugins/" ``` -GitBucket runs a `PluginWatchThread` that watches that directory and **hot-reloads on file create** — -no GitBucket restart needed. Confirmed in logs: + +GitBucket runs a `PluginWatchThread` over that directory and reloads on file +creation, so a restart is not always required: + ``` INFO g.core.plugin.PluginWatchThread - ENTRY_CREATE: gitbucket-mcp-plugin-.jar INFO g.core.plugin.PluginWatchThread - Reloading plugins... INFO g.core.plugin.PluginRegistry - Initialize gitbucket-mcp-plugin-.jar INFO g.core.plugin.PluginWatchThread - Reloading finished. ``` -Reload took under 100ms in testing. + +Prefer a restart when **replacing** an installed version: the plugin's +database migration runs from the loaded `Plugin` class's declared versions, +and `itest/upgrade_gate.py` is what exercises install, replacement, migration +and restart as a sequence. + +### Replacing: remove the old JAR, do not rename the new one + +Leave two JARs declaring the same plugin id in that directory and GitBucket +loads **one** of them. Which one is not something to leave to chance, and +neither a restart nor a new filename settles it. From GitBucket's own scan: + +- candidates are ordered by version **descending**, and that version is parsed + from the **file name**, not from the packaged descriptor; +- a file name the version pattern does not match counts as `0.0.0`, so + `gitbucket-mcp-plugin-0.1.0-new.jar` sorts *below* the + `gitbucket-mcp-plugin-0.1.0.jar` it was meant to supersede; +- the first candidate for a given plugin id wins and the rest are skipped, + logged as `Plugin is duplicated. is available.` + +So: **delete the previous JAR** rather than renaming around it, and read that +log line as the signal that one was left behind. Two builds of this plugin can +declare the same version — the version is not an identity — so equal +declared versions make the choice arbitrary rather than newest-wins. + +`$GITBUCKET_HOME/plugins/.installed/` is GitBucket's own copy of what it +loaded. It is rebuilt on each scan, so it is a witness and never the place to +install into. ## 3. Verify + ```bash curl http:///plugin-mcp/health # {"status":"ok","protocol":"MCP","transport":"Streamable HTTP"} ``` -MCP JSON-RPC handshake (Basic auth, GitBucket username + password or PAT): +Then the MCP handshake. HTTP Basic takes a GitBucket account's own +credentials and needs no configuration: + ```bash -curl -u : -H "Content-Type: application/json" \ +curl -u : \ + -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ - -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \ http:///plugin-mcp/ ``` -Returned in testing: -```json -{"jsonrpc":"2.0","result":{"capabilities":{"tools":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"prompts":{"listChanged":false}},"serverInfo":{"name":"gitbucket-mcp-plugin","version":"0.1.0"},"protocolVersion":"2025-03-26"},"id":1} -``` - -`tools/list` returned all 14 documented tools (list/get/create/close/reopen for issues and PRs, plus -repo tools). Round-tripped both a read (`list_repositories`) and a write (`create_issue`) tool call -against a real test repo — both worked and reflected actual GitBucket state. - -## 4. Known gaps / things to check on the target instance -- Auth tested here as HTTP Basic with the GitBucket account's own password (`root:root` on the test - instance). GitBucket's `/api/v3/user/access_tokens` endpoint returned 404 on 4.44.0 — if the prod - instance is on a different version, verify whether PAT creation via API works there, or just use - the account password / an existing PAT the same way `git` already authenticates against it. -- GitBucket version compatibility per this plugin's own README: 4.42.0–4.46.0, Java 17 or 21. The - 4.44.0 test instance is inside that range. -- Not tested: TLS termination in front of GitBucket, concurrent multi-plugin interaction beyond the - bundled gist/emoji/notifications/pages plugins, or behavior under GitBucket's private-repo/LDAP auth - modes. -- This was validated against a disposable local instance, not the shared corporate GitBucket at - `192.168.214.202` — deploying there is a separate, deliberate infra change for whoever owns that - box. + +`tools/list` then enumerates the tools, each with the scope it requires. + +`serverInfo.version` in that reply comes from the descriptor packaged in the +installed JAR rather than from a literal in the source, which is worth having +— but it reports the **declared version only**, and that is not the artifact. +Two builds with different contents and different behaviour can declare the +same version, and this plugin's have: every build in this contribution +declares `0.1.0`. + +**Artifact identity is the file hash.** Compare the hash of the JAR you placed +in the plugins directory with the hash of the build you chose: + +```bash +sha256sum "$GITBUCKET_HOME/plugins/gitbucket-mcp-plugin-.jar" +# must equal the hash recorded for the build you intended to install +``` + +Use the handshake, `serverInfo.version` and `/health` as **smoke checks** — +they tell you something is up and answering — and the hash for *what* is +running. + +For the browser authorization flow, set the external base URL — OAuth stays +off until you do, and nothing else changes: + +``` +-Dgitbucket.mcp.oauth.baseUrl=https:// +``` + +[docs/authentication.md](docs/authentication.md) covers what that value +governs and why it is not taken from a request header. + +## Before deploying anywhere shared + +- Identify the exact artifact by hash, as above, after copying it onto the + target — not by its declared version and not by its file name. +- Run the gates against a **disposable** instance, never a shared one: they + create accounts and repositories and deliberately attempt refused writes. + See [itest/README.md](itest/README.md). +- Untested configurations are listed in [README.md](README.md) — among them + TLS termination by a reverse proxy, GitBucket's LDAP authentication, and + interaction with plugins beyond the bundled ones. Untested is not the same + as known-broken, but it is not evidence either. diff --git a/README.md b/README.md index 0eef2bd..376e0e6 100644 --- a/README.md +++ b/README.md @@ -7,43 +7,78 @@ A [GitBucket](https://github.com/gitbucket/gitbucket) plugin that embeds a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server directly inside GitBucket. AI coding assistants (Claude, Cursor, VS Code Copilot, etc.) can read and manage your GitBucket repositories, issues, and pull requests over MCP — no separate service or proxy required. +Two ways to authenticate: HTTP Basic with a GitBucket account, and OAuth 2.1 with PKCE for clients that expect a browser authorization flow, such as ChatGPT's web connector. Either way the caller is a GitBucket account and every tool is subject to that account's repository permissions. See [docs/authentication.md](docs/authentication.md). + ## Features -14 MCP tools covering the most common developer workflows: +19 MCP tools covering the most common developer workflows. Each one declares +whether it reads or writes, which is what an OAuth grant's scope is checked +against; a Basic-auth caller holds both. + +### Identity + +| Tool | Scope | Description | +|------|-------|-------------| +| `whoami` | `mcp:read` | The GitBucket account this connection is authenticated as | ### Repository tools -| Tool | Description | -|------|-------------| -| `list_repositories` | List repositories accessible to a user or organization | -| `get_repository` | Get repository metadata, branches, and tags | +| Tool | Scope | Description | +|------|-------|-------------| +| `list_repositories` | `mcp:read` | List repositories accessible to a user or organization | +| `get_repository` | `mcp:read` | Get repository metadata, branches, and tags | + +Both tools report the same counters, and they mean what GitBucket means by +them, which is narrower than the names suggest: + +| Field | Meaning | +|-------|---------| +| `issue_count` | **Open** issues, **excluding** pull requests | +| `pr_count` | **Open** pull requests | +| `fork_count` | How many forks exist of this repository's origin. It is **not** a flag that this repository is itself a fork. | +| `is_fork` | Whether this repository is a fork, by GitBucket's own test — it has an origin. | + +Each response repeats those meanings in `issue_count_semantics`, +`pr_count_semantics` and `fork_count_semantics`, so a reader does not have to +assume they are totals. + +`without_forked` on `list_repositories` excludes repositories that are +themselves forks. Counters are read per repository, for the repositories the +caller may read and no others, so a listing costs one repository read per +visible entry. ### Issue tools -| Tool | Description | -|------|-------------| -| `list_issues` | List issues in a repository (open / closed / all) | -| `get_issue` | Get issue details and comment count | -| `create_issue` | Create a new issue | -| `close_issue` | Close an issue with an optional comment | -| `reopen_issue` | Reopen a closed issue | -| `add_issue_comment` | Add a comment to an issue | +| Tool | Scope | Description | +|------|-------|-------------| +| `list_issues` | `mcp:read` | List issues in a repository (open / closed / all) | +| `get_issue` | `mcp:read` | Get issue details and comment count | +| `create_issue` | `mcp:write` | Create a new issue | +| `close_issue` | `mcp:write` | Close an issue with an optional comment | +| `reopen_issue` | `mcp:write` | Reopen a closed issue | +| `add_issue_comment` | `mcp:write` | Add a comment to an issue | +| `update_own_comment` | `mcp:write` | Edit a comment the authenticated account wrote | ### Pull request tools -| Tool | Description | -|------|-------------| -| `list_pull_requests` | List pull requests (open / closed / all) | -| `get_pull_request` | Get pull request details and comment count | -| `add_pr_comment` | Add a comment to a pull request | -| `close_pull_request` | Close a PR without merging, with an optional comment | -| `reopen_pull_request` | Reopen a closed pull request | -| `get_pr_diff` | List changed files and patches for a pull request | +| Tool | Scope | Description | +|------|-------|-------------| +| `list_pull_requests` | `mcp:read` | List pull requests (open / closed / all) | +| `get_pull_request` | `mcp:read` | Get pull request details and comment count | +| `get_pr_diff` | `mcp:read` | List changed files and patches for a pull request | +| `get_thread_comments` | `mcp:read` | Read a pull request's review thread | +| `add_pr_comment` | `mcp:write` | Add a comment to a pull request | +| `close_pull_request` | `mcp:write` | Close a PR without merging, with an optional comment | +| `reopen_pull_request` | `mcp:write` | Reopen a closed pull request | +| `update_pull_request` | `mcp:write` | Change a pull request's title or body | +| `mark_ready_for_review` | `mcp:write` | Take a draft pull request out of draft | ## Requirements -- **GitBucket**: 4.42.0 – 4.46.0 +- **GitBucket**: 4.46.0, 4.47.0 or 4.48.0 (see [compatibility](#gitbucket-version-compatibility)) - **Java**: 17 or 21 (required by GitBucket 4.42+) +- **A database**: H2 (GitBucket's default) or PostgreSQL. The OAuth tables are + created by the plugin's own migration on first start. ## Installation @@ -77,7 +112,30 @@ Once installed, the plugin exposes: | `GET http:///plugin-mcp/health` | Health check | | `GET http:///plugin-mcp/sse` | SSE endpoint event (for SSE-capable clients) | -Authentication uses **HTTP Basic Auth** with your GitBucket credentials. +With OAuth configured, five more: + +| Endpoint | Purpose | +|----------|---------| +| `GET http:///.well-known/oauth-protected-resource` | RFC 9728 resource metadata | +| `GET http:///.well-known/oauth-authorization-server` | RFC 8414 authorization server metadata | +| `GET\|POST http:///plugin-mcp/oauth/authorize` | Consent, on your GitBucket session | +| `POST http:///plugin-mcp/oauth/token` | Code exchange and refresh | +| `POST http:///plugin-mcp/oauth/revoke` | RFC 7009 revocation | + +**HTTP Basic Auth** with your GitBucket credentials works with no configuration +and is unchanged. **OAuth** is off until an operator sets this plugin's external +base URL: + +``` +-Dgitbucket.mcp.oauth.baseUrl=https://git.example.com +``` + +The identifiers the plugin publishes are derived from that one value and never +from a request header, so a `Host` or `X-Forwarded-Host` a client controls +cannot move the issuer. Without it the discovery documents answer 404 and +Bearer tokens are refused; nothing else changes. The full picture — scopes, +token lifetimes, revocation, what the plugin implements itself and what comes +from a library — is in [docs/authentication.md](docs/authentication.md). ## MCP Client Configuration @@ -108,8 +166,38 @@ echo -n "user:password" | base64 Use the HTTP transport URL `http://localhost:8080/plugin-mcp/` with Basic auth headers, matching your client's MCP settings format. +### Clients that authorize in a browser + +A client that speaks MCP authorization — ChatGPT's web connector, for example — +needs only the server URL. It reads +`/.well-known/oauth-protected-resource`, follows it to the authorization server +metadata, registers itself by publishing a client ID metadata document (no +pre-registration with this server, and no client secret), and sends you to +GitBucket's own sign-in and then to a consent screen. + +The **client** chooses which scopes to ask for. The consent screen lists +exactly those and offers one decision — Authorize or Cancel; there is no +per-scope selector, so a client that asks for `mcp:write` is approved or +refused as a whole. A client that asks for nothing is granted the weaker +scope, `mcp:read`. What is granted is the set the server recorded when the +request arrived, not a field posted back with the form. Either way the token +acts as your account and can do nothing your account cannot. + +This requires `gitbucket.mcp.oauth.baseUrl` and a GitBucket the client can +reach over HTTPS. The flow is exercised end to end by +`itest/oauth_controls.py` over real HTTP, and a commercial client — ChatGPT's +connector — has since completed it against a running GitBucket and made +authenticated calls through it. +[docs/authentication.md](docs/authentication.md) says exactly which operations +were observed, against which build, and what that does and does not +establish. + ### Manual testing with curl +`root:root` below is GitBucket's own default administrator on a **fresh local +instance**, which is what these examples assume. Substitute your own account, +and never point these at an instance that holds anything real. + ```bash # List all tools curl -s -u root:root \ @@ -135,14 +223,24 @@ npx @modelcontextprotocol/inspector \ ## GitBucket Version Compatibility -| GitBucket | Status | Notes | -|-----------|--------|-------| -| 4.46.0 | ✅ Supported | Current target | -| 4.45.0 | ✅ Supported | | -| 4.44.0 | ✅ Supported | | -| 4.43.0 | ✅ Supported | H2 1.x → 2.x DB migration (no plugin API change) | -| 4.42.0 | ✅ Supported | Minimum supported version; Java 17 required | -| < 4.42.0 | ❌ Not supported | Plugin API incompatible | +Three versions are tested, by compiling and running the unit suite against +each release's own runtime classpath, including the `oauth2-oidc-sdk` version +that release ships: + +| GitBucket | `oauth2-oidc-sdk` | Status | +|-----------|-------------------|--------| +| 4.48.0 | 11.38.2 | ✅ Tested | +| 4.47.0 | 11.38.2 | ✅ Tested | +| 4.46.0 | 11.33 | ✅ Tested | + +The live, OAuth and upgrade harnesses have been run on 4.48.0, including the +PostgreSQL migration path. For 4.46.0 and 4.47.0 the evidence is the unit +suite against their own runtime classpaths. + +Versions below 4.46.0 are untested rather than known broken: the plugin uses +`anonymousAccessiblePaths`, which earlier releases may not have, and the OAuth +code depends on `oauth2-oidc-sdk` being on the host's classpath. Anything +outside the table above has not been run. ## Development @@ -158,20 +256,78 @@ npx @modelcontextprotocol/inspector \ ./gradlew test ``` -55 tests covering JSON-RPC protocol parsing, tool registry, schema validation, and argument parsing. +Covers JSON-RPC protocol parsing, the tool registry, schema validation, +argument parsing, repository authorization, tool execution through the +production dispatcher, the OAuth grant store against a real database created +by the plugin's own migration, the client metadata fetcher's SSRF policy and +its HTTP framing bounds. The run prints its own total; this page deliberately +does not restate it, because a number written here is wrong the next time a +test is added. ### Integration tests -Requires a running GitBucket instance with the plugin installed: +Requires a **disposable** GitBucket instance with the plugin installed. Both +harnesses build their own fixtures and refuse to run against an instance that +is not blank, but they create accounts and repositories and should never be +pointed at anything you care about. ```bash ./gradlew shadowJar cp build/libs/gitbucket-mcp-plugin-*.jar $GITBUCKET_HOME/plugins/ -# start GitBucket... -python3 scripts/integration_test.py --host localhost --port 8080 --user root --password root +# start GitBucket on 127.0.0.1:8099, with OAuth configured for the second suite: +# -Dgitbucket.mcp.oauth.baseUrl=http://localhost:8099 +# -Dgitbucket.mcp.oauth.allowLoopbackClients=true +# keep a copy of the exact artifact outside the directory GitBucket scans +cp build/libs/gitbucket-mcp-plugin-0.1.0.jar /tmp/candidate.jar +MCP_PLUGIN_JAR=/tmp/candidate.jar \ + python3 itest/integration.py # the tools, against GitBucket's own REST API +python3 itest/oauth_controls.py # the OAuth flow, over HTTP +``` + +`MCP_PLUGIN_JAR` must be **one concrete path**. A glob there does not work: +the shell leaves `*` unexpanded inside an assignment word and the gate exits 2 +before it reaches HTTP. `itest/README.md` has the form to use when the file +name is not known ahead of time. + +`integration.py` needs `MCP_PLUGIN_JAR` to name the exact JAR installed on the +instance, so the version the plugin reports can be compared with the +descriptor actually packaged in the artifact rather than with a literal. + +Installation and upgrade are a third harness, and it starts and stops its own +GitBucket processes rather than using a running one: + +```bash +python3 itest/upgrade_gate.py \ + --war gitbucket.war \ + --previous .jar \ + --candidate build/libs/gitbucket-mcp-plugin-*.jar \ + --home /tmp/gb-upgrade # must not exist, or be empty +``` + +It covers a fresh install, the upgrade through GitBucket's own plugin +mechanism, the migration running, data created under the previous plugin +surviving, and grants and revocations surviving a restart. Add +`--db-url jdbc:postgresql://…` (with `--db-user`, `--db-password`) to run the +same sequence against PostgreSQL instead of the bundled H2; without it the +PostgreSQL path is generated DDL, not an executed migration. + +A fourth harness checks the audience binding, which needs a restart to +observe: it issues a grant while the server is configured as one resource, +restarts the same server as another, and presents the credential again. + +```bash +python3 itest/resource_gate.py \ + --war gitbucket.war \ + --candidate build/libs/gitbucket-mcp-plugin-*.jar \ + --home /tmp/gb-resource # must not exist, or be empty ``` -The script creates test fixtures, exercises all 14 tools, and reports a pass/fail summary. +`integration.py` exercises every tool against each repository visibility and +each collaborator role, comparing the plugin's answer with GitBucket's own. +`oauth_controls.py` drives discovery, consent, code exchange, refresh rotation, +revocation and Bearer-authenticated tool calls through the real endpoints, and +checks what GitBucket stored rather than what the plugin replied. See +[itest/README.md](itest/README.md). ## Contributing diff --git a/build.gradle b/build.gradle index f7eefc8..998759a 100644 --- a/build.gradle +++ b/build.gradle @@ -21,6 +21,19 @@ dependencies { compileOnly 'javax.servlet:javax.servlet-api:4.0.1' compileOnly 'com.fasterxml.jackson.core:jackson-databind:2.15.2' compileOnly 'com.github.takezoe:blocking-slick_2.13:0.0.14' + // Already on GitBucket's runtime classpath (it uses Nimbus for its own + // OpenID Connect sign-in), so this is compileOnly and is not bundled. + // Pinned to the version shipped by the oldest supported GitBucket, 4.46.0, + // so only API present across the tested range is used. + compileOnly 'com.nimbusds:oauth2-oidc-sdk:11.33' + + // Apache HttpClient parses HTTP messages, including the framing a + // hand-written reader got wrong: a body short of its Content-Length and + // an unparseable chunk size both have to be errors, not a short string. + // GitBucket ships both jars (4.5.14 / 4.4.16 in 4.46.0 through 4.48.0), + // so this is compileOnly and nothing is bundled. + compileOnly 'org.apache.httpcomponents:httpclient:4.5.14' + compileOnly 'org.apache.httpcomponents:httpcore:4.4.16' testImplementation 'org.scalatest:scalatest_2.13:3.2.18' testImplementation 'org.scalatestplus:junit-4-13_2.13:3.2.18.0' @@ -28,6 +41,11 @@ dependencies { testImplementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2' testCompileOnly 'io.github.gitbucket:gitbucket_2.13:4.46.0' testCompileOnly 'javax.servlet:javax.servlet-api:4.0.1' + testCompileOnly 'com.nimbusds:oauth2-oidc-sdk:11.33' + testRuntimeOnly 'com.nimbusds:oauth2-oidc-sdk:11.33' + testCompileOnly 'org.apache.httpcomponents:httpclient:4.5.14' + testRuntimeOnly 'org.apache.httpcomponents:httpclient:4.5.14' + testRuntimeOnly 'org.apache.httpcomponents:httpcore:4.4.16' testRuntimeOnly 'io.github.gitbucket:gitbucket_2.13:4.46.0' testRuntimeOnly 'javax.servlet:javax.servlet-api:4.0.1' testRuntimeOnly 'com.github.takezoe:blocking-slick_2.13:0.0.14' diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 0000000..c7ee5af --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,427 @@ +# Authentication + +The MCP endpoint accepts two authentication methods. Both resolve to a real +GitBucket account, and neither grants anything that account does not already +have. + +| Method | For | State | +| --- | --- | --- | +| HTTP Basic | clients that can send a username and password or personal access token, such as Claude Desktop | supported | +| OAuth 2.1 Bearer | clients that require a browser authorization flow, such as ChatGPT | this document | + +## Why the plugin is also the authorization server + +GitBucket is **not** an OAuth authorization server. It ships +`AccessToken`/`AccessTokenService` — personal access tokens, stored as a hash — +and session authenticators, but no authorization endpoint, no token endpoint, +no client registry and no key set. Its OAuth support is as a *client*, for +signing users in from an external provider. Verified against the published +artifacts rather than assumed. + +So an authorization server has to come from somewhere, and there are two +honest options. + +**An external authorization server** (Keycloak, Authentik, a hosted IdP). This +can be done safely: the mapping from the external subject to a GitBucket +account is an explicit, administrator-established binding on +`(issuer, subject)`, stored and verified, and an identity provider that +GitBucket already trusts for sign-in is a reasonable thing to trust for +authorization too. Matching on email is not the only option and is not what +makes this approach hard. + +What makes it hard is operational. It is a second service to deploy, operate, +upgrade and back up; it needs its own availability story, because the MCP +endpoint stops authenticating when it is down; and the binding table has to be +populated and maintained by hand for every user, which is work an +administrator does before anyone can connect. For a plugin whose premise is +"no separate service or proxy required", that cost falls on every deployment +to serve a case most of them do not have. Rejected on those grounds, and +recorded here so the choice is visible rather than implied. A deployment that +already runs an IdP and wants it to own MCP authorization is a reasonable +future option, not a contradiction of this one. + +**The plugin acts as the authorization server**, authenticating the resource +owner with the GitBucket session the user already has. No new identity store, +no account linking, no second service. The resource owner is a GitBucket +account by construction, because the only way to reach the consent screen is +to be signed in to GitBucket. Chosen. + +The cost of that choice is honest too: this plugin then owns authorization +codes, tokens and consent records, and owns their security properties. The +rest of this document is about those properties. + +## What is a dependency and what is ours + +The protocol types come from **`com.nimbusds:oauth2-oidc-sdk`**, Apache-2.0, +which GitBucket already carries on its runtime classpath for its own OpenID +Connect sign-in. It is therefore a `compileOnly` dependency and is **not** +bundled into the plugin JAR: no duplicate classes, no version skew with the +host, no growth in the artifact. Pinned at 11.33, the version shipped by the +oldest supported GitBucket, so only API present across the whole tested range +is used. + +| Supplied by the library | Implemented here | +| --- | --- | +| PKCE: verifier syntax, S256 computation (`CodeVerifier`, `CodeChallenge`) | the policy that S256 is the only accepted method | +| RFC 8414 authorization server metadata: field names, JSON shape | the values in it, and the claim that each one is true | +| Authorization and token request parsing, error objects, token responses, revocation requests | which requests are honoured, and every decision about whether to honour one | +| `ClientID`, `Scope`, `State`, `AuthorizationCode`, `BearerAccessToken` types | the storage, lifetime, binding and rotation of everything they name | +| — | RFC 9728 protected resource metadata, which has no type in the shipped SDK version | +| — | the `WWW-Authenticate` challenge | +| — | consent, CSRF, GitBucket account resolution, scope enforcement, the CIMD fetcher and its SSRF controls, and the schema | + +Randomness and hashing are the JDK's `SecureRandom` and `MessageDigest`. No +cryptography is implemented here, and nothing in the table's right-hand column +is described anywhere in this repository as coming from the library. + +## Boundaries + +| Role | Where it lives | +| --- | --- | +| MCP resource server | the existing `/plugin-mcp/` endpoint, now also accepting `Authorization: Bearer` | +| Authorization server | this plugin, at its own endpoints | +| Resource owner authentication | GitBucket's own session — the plugin never sees a password | +| Account resolution | the signed-in GitBucket account, carried on the grant | +| Repository authorization | unchanged: GitBucket's `hasGuestRole` / `hasDeveloperRole`, per request | +| Persistent state | plugin-owned tables, created by a Solidbase migration | + +Effective access is the **intersection** of the granted scope and the account's +current GitBucket permissions. A token is never sufficient on its own: every +tool still runs the same repository guard it runs under Basic authentication, +so a grant issued yesterday cannot outlive a role removed today. + +## Registration: client ID metadata documents + +ChatGPT supports three registration mechanisms. This plugin implements one. + +- **CIMD** — the client's `client_id` is an HTTPS URL serving its own metadata. + Nothing is registered and nothing is stored. Implemented. +- **Dynamic client registration** (RFC 7591) — requires an open registration + endpoint and a client table. Not implemented: it is a larger attack surface + for a self-hosted server, and CIMD covers the client this work targets. +- **Pre-registration** — an administrator pastes a client ID and secret. + Not implemented. + +Fetching a metadata document means the server makes an outbound request to a +URL a caller supplied, which is a server-side request forgery primitive if it +is done carelessly. The fetcher is therefore bounded: HTTPS only, a response +size and time limit, redirects refused outright rather than followed, and +private, loopback, link-local, unique-local, carrier-grade and multicast +address ranges refused after DNS resolution — every resolved address, not the +first. An IPv4 address written in IPv6 notation is unwrapped and judged as the +address it is. + +**The request goes to the address that was checked.** This is the part that is +easy to get wrong, and this fetcher did: checking an address and then handing a +host *name* to a URL connection checks nothing, because the connection +resolves the name again, independently, and that second answer decides where +the request goes. Verifying afterwards is later still, since a response only +exists once the request has been sent — and sending it is the whole of the +injury. Neither `HttpURLConnection` nor `java.net.http.HttpClient` can be told +which address to use. Apache HttpClient can: its `DnsResolver` is consulted +for the route, so answering with the one address that passed the check is what +pins the destination. + +Pinning the address gives up nothing about authenticating the peer. The socket +factory is the JVM's default HTTPS factory with the default hostname verifier, +so the usual certificate name check happens against the name; SNI carries the +name too. No proxy is consulted, because a proxied request goes wherever the +proxy decides and destination control would be an illusion. + +**A document that arrives incompletely is not a document.** The HTTP message +itself was parsed here once, and the parser was wrong in the two ways a +hand-written one is prone to: a body that stopped short of its +`Content-Length` was returned as though it had finished, and a chunk size that +did not parse was treated as the terminating zero chunk. Both turned a +truncated prefix into a valid client registration, because a JSON document +that parses says nothing about whether the message carrying it completed +(RFC 9112 §6.3, §7.1, §8). Message parsing is now Apache HttpClient's, which +raises on both — and it is already on GitBucket's runtime classpath, so it is +`compileOnly` and nothing is bundled. The size limit refuses an oversized +document rather than returning a prefix of it, for the same reason. + +Two bounds need stating explicitly, because moving to a maintained stack lost +them both and neither loss is visible from a response the server has already +finished sending. A body past the cap **aborts the request** rather than +closing the entity stream: closing a half-read entity makes the client consume +the rest of the framed body first, so a peer that keeps supplying a tail would +hold the fetch open exactly as long as it liked. And the connection manager's +default message constraints are unlimited, so header line length and header +count are set explicitly — 8 KiB and 100, which together bound the whole +header block. + +Redirects are refused rather than re-validated because an allowed host +bouncing to a forbidden one is the usual way such a fence is bypassed, and +there is no legitimate reason for a client's own metadata document to move. + +One escape exists, off by default. `gitbucket.mcp.oauth.allowLoopbackClients` +permits a `client_id` on a loopback address, and opens **loopback only**: the +private, link-local, carrier-grade and multicast ranges stay forbidden with it +on. It exists because a developer running an MCP client on the same machine as +GitBucket otherwise cannot complete an authorization at all. A deployment that +never sets it behaves exactly as if it did not exist. + +## Tokens + +Access tokens are opaque, generated from a cryptographic random source and +stored as a SHA-256 hash, in the same spirit as GitBucket's own personal +access tokens. They are not self-contained. + +That is a deliberate trade. A signed self-contained token needs no storage and +no lookup, but it also cannot be revoked before it expires — revocation +latency becomes the token lifetime. An opaque token costs one indexed lookup +per request and gives **immediate** revocation, which is the property that +matters when a grant is withdrawn or an account is disabled. + +| Credential | Lifetime | Revocation | +| --- | --- | --- | +| authorization code | 60 seconds, single use | consumed atomically | +| access token | 1 hour | immediate | +| refresh token | 30 days, rotated on use | immediate; reuse of a rotated token revokes the whole grant | + +Reuse detection applies to races as well as to theft, because the server +cannot tell them apart. A correctly bound refresh token presented a second +time is treated as reuse and the whole grant is revoked. Nothing about that +decision identifies the legitimate caller — the server has no way to do so, +which is precisely why reuse ends the family rather than being arbitrated. + +The consequence is an interoperability requirement of this policy, and worth +stating plainly: **a client must serialise its refreshes.** If it presents the +same refresh token twice at once, one request rotates it and the other finds a +token that has already been rotated, the grant is revoked, and neither request +leaves the client with a credential it can keep using. That is what OAuth 2.1 +asks for; it is a constraint on the client, not a claim about the server's +ability to tell two callers apart. + +Three things are kept distinct, because they are often conflated: + +- **The database transition.** One refresh credential cannot produce two + independently valid successors, and the chain cannot fork. This holds under + any scheduling and is asserted on stored state. +- **Replay handling.** A correctly bound second presentation revokes the + grant, and that revocation is committed whatever the HTTP endpoint answers. +- **The HTTP result.** A response may already have completed before the + revocation landed. It is not undone. The guarantee is stated where it holds: + every *subsequent* authorization check refuses credentials from the revoked + grant. + +A **binding failure is not a replay.** Presenting a refresh token with the +wrong `client_id` is refused and changes nothing: it does not rotate the +token, does not revoke the grant, and the legitimate client's next refresh +still works. The client id is not a secret — anyone who learned a refresh +token could send it with any client id they liked, and treating that as +evidence of theft would hand an unauthenticated caller a way to destroy a +credential that is in legitimate use. + +The same holds for the authorization code, and for a code that has **already +been spent**. The bindings are checked first, so a wrong client, redirect URI, +resource or PKCE verifier against a used code is refused on its own terms and +the grant it bought survives. Revoking on replay is defensible only for a +presentation that could have come from the legitimate client; whoever captured +a code but not the PKCE verifier must not be able to end the session with it. +A correctly bound replay still revokes. + +Losing a race is treated as a replay, because it is one. When the conditional +claim on a code matches no row, the row is re-read: if something else took it, +the presentation was correctly bound and arrived second, which is the same +situation as an outright replay and gets the same policy. + +Expiry is treated differently on purpose. An expired credential is refused but +does **not** revoke the grant: that is the client being slow, not a credential +being somewhere it should not be. This applies to a superseded refresh token +whose own expiry has passed as well — it is dead of old age, not evidence, and +treating it as a replay would let an old useless token destroy the successor +the legitimate client is using. Cleanup only removes credentials that are +already expired, so the unexpired superseded rows that replay detection needs +are never swept away. + +### The audience is checked where the credential is used + +A grant records the resource it was issued for. That is only a fact in a table +until it is compared with the resource this server actually is, and the +comparison belongs at the point of use: a token outlives the request that +created it, so a reconfigured deployment — or a neighbouring one sharing a +database — presents a perfectly valid, unexpired credential for somewhere +else. Every bearer request checks it before a tool is chosen, and refuses a +mismatch exactly like any other unusable token, so the refusal reveals +nothing. Rotation treats the audience as a binding alongside the client id, +both the resource this server is and the resource the client asked for, so a +mismatch consumes nothing and revokes nothing. + +## Scopes + +| Scope | Grants | +| --- | --- | +| `mcp:read` | the read-only tools | +| `mcp:write` | the mutating tools, in addition to `mcp:read` | + +Every tool declares which one it needs, as an abstract member, so a tool that +forgets to declare does not compile rather than defaulting to the weaker +requirement. A read grant cannot mutate: the scope check happens before the +tool runs, and the repository guard still happens inside it. + +**Who decides which scopes are asked for.** The client does, in its +authorization request. The consent screen lists exactly the scopes that +request named, and offers one decision over the set — Authorize or Cancel. +There is no per-scope selector, so a client asking for `mcp:write` is approved +or refused as a whole; a user who wants a read-only connection refuses and +the client asks for less. A request naming no scope at all is treated as +asking for the weaker one, `mcp:read`. + +What is granted is the set the server recorded when the request arrived, held +in the user's own session, not the value posted back with the consent form. +That record is removed on any decision, allow or deny, so a resubmitted form +cannot mint a second code. + +OIDC scopes (`openid`, `email`, `profile`) and a UserInfo endpoint are **not** +implemented, and the metadata does not advertise them. They are only needed +for workspace domain restrictions, and advertising a capability that is not +implemented is worse than not having it. + +## What the metadata says is what exists + +The discovery documents describe only implemented behaviour. In particular +`code_challenge_methods_supported` lists `S256` and nothing else, because the +plain method is not accepted; `grant_types_supported` lists only +`authorization_code` and `refresh_token`; and no `registration_endpoint` is +published, because dynamic registration is not implemented. + +## Storage + +The four tables — grant, authorization code, refresh token, access token — +are created by the plugin's own schema migration, which GitBucket runs at +startup through Solidbase. Nothing needs to be created by hand, and an +existing installation of an earlier version of this plugin picks the migration +up on the next restart. + +Two notes for anyone changing that migration. Its root element is a bare +``, not a Liquibase ``: Solidbase supplies the +wrapper, the change set id and the author, and a file carrying its own root +parses as a nested changelog and is **skipped silently** — the plugin still +loads and the first request that needs a table fails. And the version list +has to be declared on the root-package class named `Plugin`, which is the one +GitBucket loads by name; it extends `MCPPlugin` so there is a single +declaration. Both failures happened here, and both are now covered by tests +that run the real mechanism rather than a convenient substitute. + +## What has been tested + +Compiled, and the unit suite executed, against the runtime classpaths of +GitBucket **4.46.0**, **4.47.0** and **4.48.0**, each with the +`oauth2-oidc-sdk` version that release ships (11.33 for 4.46.0, 11.38.2 for +the other two). Those three are what has been run; versions between or beyond +them are untested rather than known-good. + +The flow itself is exercised over real HTTP against a disposable GitBucket +with the plugin installed: discovery, consent, approval, denial and CSRF +rejection, code exchange and every binding failure, refresh rotation and +replay, revocation, Bearer authentication, and tool calls through the +production dispatcher — with the effects read back from GitBucket's own REST +API rather than from the plugin's replies. Those controls are +`itest/oauth_controls.py`. + +Installation, upgrade and restart are a separate gate again, because a +migration can be written, committed, tested against a database directly and +still never run: what executes is what the loaded `Plugin` class declares and +what Solidbase finds packaged in the JAR. `itest/upgrade_gate.py` starts real +GitBucket processes and checks the operator's questions — the previous +plugin runs, the candidate replaces it, the migration executes, data created +under the previous plugin survives, a grant issued after the upgrade survives +a restart, and a revocation performed before a restart is still in force +after it. That last one is what distinguishes persistence from a cache. + +That gate has been run on **both** supported backends: the bundled H2, and +PostgreSQL 16, from a blank database through the pre-OAuth plugin to this +one. On PostgreSQL the four tables and the recorded module version were read +back from the database afterwards. The processes run with a non-UTC default +time zone on purpose — a UTC host is the configuration that once hid a +timestamp defect here. + +### A commercial client, and what it does not establish + +A client's behaviour is not the protocol, so the HTTP controls above said +nothing about whether any particular product would accept this server. One has +since connected. ChatGPT's web connector completed the flow against a running +GitBucket with this plugin installed — discovery, client ID metadata +registration, GitBucket sign-in, consent — and was then used for ordinary +work over the resulting connection, by the account that consented, a site +administrator. The operations observed through it: + +- `whoami`, resolving that account and returning the plugin's self-reported + descriptor; +- repository, pull request, issue and review-thread reads; +- issue creation; +- adding an issue comment, reading it back, editing that same comment by + appending to it, and reading it back byte for byte. + +A second MCP client, not ChatGPT's and over a connection whose authentication +path is not recorded here, has read repositories, issues, pull requests and +review threads and added pull request comments, as an account **without** the +administrator flag. + +That is the whole of the claim, and it is narrower than "the connector +works": + +- **Refresh and revocation are not established by it.** Neither was observed + on either connection: no rotation, no replay, no revocation. For the ChatGPT + connection that is a statement about an OAuth grant. For the second client + it is simply that nothing of the kind was seen — its authentication path is + not recorded here, so it is not claimed to hold a grant at all. Rotation, + replay and revocation do have evidence — `itest/oauth_controls.py` over raw + HTTP — but none of it from a commercial client. +- **Neither is the permission matrix.** One administrator and one ordinary + account are two accounts, not the visibility × role × `issuesOption` matrix. + A read that succeeds for an administrator says nothing about a guest. That + matrix is `itest/integration.py`, which drives every tool against every + role, and the refused writes are confined to disposable instances. +- **Nor anything about this source.** The GitBucket these clients reached + carries an **earlier build** of this plugin. Its `list_repositories` + answers still have no `is_fork` field and no `*_semantics` keys, and still + report zero issues and zero pull requests for repositories that have both — + the defect the counter correction fixed. So these are observations about the + authorization flow and the tool surface *on the build that was installed at + the time*. Installing this tree is a separate, deliberate step, and it has + not been taken. + +A separate gate, `itest/resource_gate.py`, covers the audience check the way +only a restart can: one server issues a grant while it calls itself one +resource, the same server restarts as another, and the unexpired credential is +presented again. It then restores the original configuration and checks that +the refused credentials still work, so a refusal is a refusal rather than a +quiet destruction. + +### The guards have been shown to fail + +A suite that passes says nothing until a broken implementation makes it fail. +Nine single-line mutations of production source — the scope gate permitting +everything, a code's `redirect_uri` binding unchecked, a refresh token's +client binding unchecked, the SSRF fence opened, PKCE accepted without +verification, the request resolving the host again instead of using the +checked address, a spent code judged before its bindings, a rotation failure +ignoring expiry, and the audience of a refresh grant unchecked — each turn the +suite red on the controls written for that guard, and the source is restored +byte-for-byte afterwards. The first of those mutations originally left the +suite green, which is how the scope gate turned out to have no offline control +at all; it has one now. + +## Configuration + +The canonical resource URL is configured explicitly. It is **not** derived +from the `Host` header or from `X-Forwarded-*`, because those are attacker- +controlled on a reverse-proxied deployment and a resource identifier that +moves with the request is not an audience binding. A deployment behind a proxy +or in a servlet context path sets the external URL once; everything else — +issuer, endpoints, the `resource` value in tokens — is derived from it. + +| Property | Default | Effect | +| --- | --- | --- | +| `gitbucket.mcp.oauth.baseUrl` | unset | The external base URL. Unset, OAuth is off: discovery answers 404 and Bearer tokens are refused. Basic auth is unaffected. | +| `gitbucket.mcp.oauth.allowLoopbackClients` | `false` | Permits a `client_id` on a loopback address, and nothing else. | + +`GITBUCKET_MCP_OAUTH_BASE_URL` is read if the system property is unset. The +URL must be `https://`, except on `localhost` or `127.0.0.1` where plain HTTP +is allowed so the suites can run, and it must carry no trailing slash, query +or fragment. A value that fails any of these is rejected with a reason rather +than normalised, and OAuth stays off — a bearer token on a cleartext +connection is a bearer token for whoever is on the path, and a base URL that +quietly becomes something else is not an audience binding. diff --git a/itest/README.md b/itest/README.md new file mode 100644 index 0000000..034f0d4 --- /dev/null +++ b/itest/README.md @@ -0,0 +1,240 @@ +# Live-instance integration gate + +The offline suites under `src/test` replace GitBucket's storage and role +predicates, so they establish tool wiring and policy branching but not +GitBucket's own role computation, its SQL or the HTTP transport. This harness +closes that gap: it drives the deployed plugin over `/plugin-mcp/` with real +credentials, on a disposable GitBucket, and cross-checks every answer against +GitBucket's own REST API, its web routes and Git. + +**It must never be pointed at a GitBucket that holds anything real.** It +creates accounts, repositories, issues, comments and merges, and it deliberately +attempts refused writes. `fixtures.py` assumes a blank instance. + +## Running it + +A disposable GitBucket 4.48.0 on `127.0.0.1:8099`, with this plugin installed +and an empty `GITBUCKET_HOME`: + +```sh +java -jar gitbucket.war --port=8099 --host=127.0.0.1 --gitbucket.home=/tmp/gb-itest +# install the artifact you intend to test, keeping a copy outside the +# directory GitBucket scans, and restart +cp build/libs/gitbucket-mcp-plugin-0.1.0.jar /tmp/candidate.jar +cp /tmp/candidate.jar /tmp/gb-itest/plugins/ +MCP_PLUGIN_JAR=/tmp/candidate.jar python3 itest/integration.py +``` + +**Give it one concrete path.** A glob does not work here: the shell does not +expand `*` inside an assignment word, so +`MCP_PLUGIN_JAR=.../gitbucket-mcp-plugin-*.jar` passes the asterisk through +literally and the gate exits 2 with *does not name a readable file* before it +reaches HTTP. If the name is not known ahead of time, resolve it and check +that it resolved to exactly one file: + +```sh +set -- /tmp/gb-itest/plugins/gitbucket-mcp-plugin-*.jar +[ $# -eq 1 ] && [ -f "$1" ] || { echo "expected exactly one JAR, got $#"; exit 2; } +MCP_PLUGIN_JAR=$1 python3 itest/integration.py +``` + +Keeping the copy you point at **outside** `plugins/` avoids the other trap: +GitBucket copies what it loads into `plugins/.installed/` and rebuilds that +directory on each scan, so a path into it is not stable. + +`MCP_PLUGIN_JAR` is required, not optional. The gate compares the version the +plugin reports with the descriptor packaged in that JAR; checking it against a +literal written here would re-introduce exactly the defect the descriptor +lookup exists to prevent, and would quietly encode one fork's version number. +An unset or unreadable path is exit 2, like every other precondition. + +`oauth_controls.py` is a second gate over the same instance, covering the +OAuth flow. It needs two more system properties on the GitBucket command +line, because the plugin publishes its identifiers from a configured base URL +and because a client metadata document served from this machine is on a +loopback address the fetcher refuses by default: + +```sh +java -Dgitbucket.mcp.oauth.baseUrl=http://localhost:8099 \ + -Dgitbucket.mcp.oauth.allowLoopbackClients=true \ + -jar gitbucket.war --port=8099 --host=127.0.0.1 --gitbucket.home=/tmp/gb-itest +python3 itest/oauth_controls.py +``` + +Use `localhost` for the browser part and `127.0.0.1` for the REST control +calls, as the files do: the consent form's action is built from the +configured base URL, so the session cookie has to live on that host name. + +`oauth_gate.py` holds the flow helpers — a local HTTP server that publishes +client metadata documents, PKCE, a non-following HTTP client so redirects are +inspected rather than followed, and the walk through the real consent screen. +`oauth_controls.py` holds the controls themselves. + +## The audience binding + +`resource_gate.py` checks the one property that only a restart can show: a +grant issued while the server calls itself one resource, presented again after +the same server restarts as another. It starts and stops its own processes, +like the upgrade gate. + +```sh +python3 itest/resource_gate.py \ + --war gitbucket.war \ + --candidate build/libs/gitbucket-mcp-plugin-*.jar \ + --home /tmp/gb-resource +``` + +It then restores the original configuration and checks that the refused +credentials work again, so that a refusal is established to be a refusal +rather than a quiet destruction. Each refusal must arrive as the exact +status and error code RFC 6749 §5.2 entitles that scenario to — `(400, +invalid_grant)` at both observation points. A refusal of some other kind is a +refusal of something else, and the gate aborts rather than counting it. + +## Installation and upgrade + +`upgrade_gate.py` is different from the two above: it starts and stops its own +GitBucket processes rather than talking to one you started, because what it +checks is startup, migration and restart. + +```sh +python3 itest/upgrade_gate.py \ + --war gitbucket.war \ + --previous .jar \ + --candidate build/libs/gitbucket-mcp-plugin-*.jar \ + --home /tmp/gb-upgrade +``` + +Add `--db-url jdbc:postgresql://host:port/db --db-user … --db-password …` to +run the whole sequence against PostgreSQL. Without it the bundled H2 is used, +and the PostgreSQL path remains generated DDL rather than an executed +migration. + +It refuses to start if something else is already serving the port: a leftover +server answers health checks and would otherwise be mistaken for the artifact +under test. It stops every process it started, including when it aborts. + +## The repository listing + +`repo_list_gate.py` checks the listing's counters against GitBucket's own REST +API rather than against the plugin's other answers, because the original +defect made two plugin answers disagree and comparing them to each other would +have been the only way to see it. Its fixture holds a repository with real +issues and a pull request, one that is legitimately empty, a private one, and +a real fork, so a correct zero is distinguishable from an unpopulated field. + +```sh +python3 itest/repo_list_gate.py +``` + +Committed effects are observed by asking again rather than by reading the +tables. After a refusal that must change nothing, the lawful operation is +performed next and has to succeed; after a replay that must revoke, a fresh +authorization check has to refuse. That is the property the server actually +has to provide, and it is taken on a connection the first request did not +use. + +It needs only the standard library and `git`. It writes nothing outside a +directory from `tempfile.mkdtemp()`, which it removes on exit. Exit codes: + +| Exit | Meaning | +| --- | --- | +| 0 | every check ran and passed | +| 1 | a check failed | +| 2 | **the gate could not be run** — a precondition failed, a comparison lost its input, or fewer checks executed than that gate's floor. No result may be read from the run. | + +Each gate carries its own floor, declared in its own source rather than here: +`integration.py` 200, `repo_list_gate.py` 35, `upgrade_gate.py` 22, +`resource_gate.py` 15. A run that falls below one is exit 2, not a smaller +pass. + +`BASE` and the account passwords are at the top of `mcp.py`. They are +throwaway credentials for a throwaway instance; do not reuse them anywhere. + +## Nothing here may be skipped + +The two defects this harness was corrected for were both *skips*, not wrong +answers: a precondition that failed quietly, and a comparison whose input went +missing. A green run proved nothing about either, because a skipped check +reports nothing at all. So: + +- every setup step goes through `checks.require_ok`, which raises. `fixtures.py` + verifies that collaborators were actually added, that `issuesOption` and + `isPrivate` read *back* from storage, that the fork's inherited roles were + actually removed, and that every Git command exited zero; +- the web merge route is a fixture, not an inline step, so a creation failure + stops the run instead of skipping the only check of the commit-id recording + path; +- pull request comparisons go through `checks.require_same_set`, which fails on + a partial or empty set rather than comparing the intersection; +- GitBucket's own verdict goes through `checks.native_decision`, which accepts + 200/401/403 and raises on anything else. A 5xx is not a refusal: reading it as + one lets a broken control agree with any answer; +- the stored-state witness for a write goes through `observe.stored_issue_count` + and `observe.observe_issue_write`, which require 200 **and** a JSON list. + There is no sentinel for an unavailable read: it used to answer `-1`, so two + failed reads cancelled into a delta of zero and a refused write was reported + as having stored nothing. A successful empty list stays a lawful zero; +- timestamps go through `checks.require_iso_utc` and `checks.same_instant`, + which compare the moment against GitBucket's own value instead of checking + that a string is non-empty; +- the run aborts if fewer checks executed than the gate's declared floor. + +### Proving the guards fire + +`python3 itest/selftest.py` drives those guards with no server and no network, +and prints its own total — deliberately not repeated here, because a number +written in prose is wrong the next time a control is added. + +Most of its controls are negative: each asserts that a guard **raises** on the +input that used to be tolerated — an empty gateway list, a 500 from +GitBucket's own route, a failed collaborator addition, a `Date.toString` +timestamp, an unreadable stored-issue count, a token-endpoint refusal that is +documented but is not the one the scenario is entitled to. The rest are +lawful twins, which assert the same guard does **not** raise on a legitimate +input. The twins are not padding: a guard that rejects everything passes every +negative control there is, and only a twin notices. + +Two of the bypasses were at the *call site* rather than in the helper, so these +controls drive the real code path with API doubles instead of testing a helper +alone. The stored-count section reproduces a worked counterexample: the +read answers 500 with an error object while the doubled tool refuses to its +caller and writes anyway, in three variants — read failing on the way in, read +failing only on the way out, and both reads working so the unintended insert +shows as a delta of 1. + +End to end, `ITEST_BREAK` injects one of the same faults into a real run: + +| `ITEST_BREAK` | Fault | Required outcome | +| --- | --- | --- | +| `native500` | GitBucket's own issue route answers 500 | abort, exit 2 | +| `webmerge` | the web merge route fails | abort, exit 2 | +| `prlist` | the gateway's pull request list comes back empty | abort, exit 2 | +| `storage` | the stored-issue count cannot be read | abort, exit 2 | + +It is off unless the variable names a fault, and a run with it set announces +itself. + +## What it covers + +| Section | Checks | +| --- | --- | +| transport and identity | `whoami` per account, admin flag, wrong password and unknown account rejected at the transport, registry size over HTTP, descriptor version in `initialize` | +| read authorization | every read tool refused on a private repository without a role, hidden and absent indistinguishable, guest and site-admin access, public readable by any authenticated account, `list_repositories` filtered for the caller | +| issue-creation policy | the `issuesOption` × role × privacy matrix, each case witnessed by the stored issue count **and** compared with GitBucket's own `POST /api/v3/.../issues` verdict | +| issue round-trip | title and body stored byte for byte including Unicode and CRLF, attribution, close/reopen reaching GitBucket's store, a guest refused | +| commit identities | `head_sha` against `git rev-parse`, `merge_base_sha` against `git merge-base`, fork head repository, and the inherited coercion still live on read-only tools | +| `update_pull_request` | omitted-field preservation both ways, explicit clearing, empty title refused, guest and outsider refused, every refusal witnessed as unchanged storage | +| argument strictness | all eight malformed identifier forms against both mutating identifier sites, malformed and null bodies, each with a before/after snapshot of every pull request | +| comments | byte-exact storage, attribution, `total_count` against GitBucket's own count, bounded paging, non-overlap, full coverage, read and write authorization | +| `update_own_comment` | author edits byte-exactly; repository owner, site admin and unrelated account all refused; empty replacement refused; every malformed id refused; a state-change record refused | +| `mark_ready_for_review` | developer role required on the **head** repository of a fork and not the base, stale and malformed preconditions, idempotence, closed and merged refused, nothing but the draft flag changed | +| merged semantics | both of GitBucket's merge routes, `merged` / `merged_at` / `merged_by` / `merged_commit_ids` compared with GitBucket's own fields on every pull request | + +## A note on the fork fixture + +GitBucket copies a repository's collaborators when it is forked. A developer of +the base is therefore usually also a developer of the fork, which makes the +head-repository role check look like a no-op. `fixtures.py` removes the +inherited collaborators from the fork on purpose, so the distinction is +observable. Without that step the check passes for the wrong reason. diff --git a/itest/checks.py b/itest/checks.py new file mode 100644 index 0000000..4381ba8 --- /dev/null +++ b/itest/checks.py @@ -0,0 +1,136 @@ +""" +Assertions the gate cannot skip. + +Every one of these raises instead of returning a verdict, because the two +defects this module exists for were both *skips*: a precondition that failed +quietly and a comparison whose input went missing. A gate that can decline to +run a check is not a gate, so the check either runs or the run stops. + +These functions are pure and need no server, which is what lets +`selftest.py` prove each one fires. +""" + + +class GateError(RuntimeError): + """A precondition failed, or a comparison lost its input. Never caught.""" + + +def require(condition, message): + if not condition: + raise GateError(message) + + +def require_ok(status, body, what, ok=(200, 201, 202, 204)): + """ + A setup step that the rest of the run depends on. + + `fixtures.py` used to ignore these, so a repository created without its + collaborators, or a fork whose inherited roles were not removed, would + still have produced a green run — passing for the wrong reason. + """ + if status not in ok: + raise GateError(f"{what}: expected HTTP {ok}, got {status}: {str(body)[:200]}") + return body + + +def native_decision(status, what): + """ + GitBucket's own allow/deny verdict, used as the control for the gateway's. + + A server error is not a verdict. Reading 500 as "refused" is how a broken + server turns into agreement: the comparison would pass with GitBucket + answering nothing at all. + """ + if status in (200, 201): + return "allowed" + if status in (401, 403): + return "denied" + raise GateError( + f"{what}: GitBucket answered HTTP {status}, which is neither an allow nor a refusal; " + "the comparison has no control and the run is void" + ) + + +def require_same_set(name, got, want): + """ + Full-set equality before any element-wise comparison. + + The previous version compared only the pull requests that appeared in both + answers, so a gateway that dropped every row compared nothing and passed. + """ + got, want = set(got), set(want) + if got != want: + missing, extra = sorted(want - got), sorted(got - want) + raise GateError( + f"{name}: sets differ — missing from the gateway: {missing}; " + f"not in GitBucket's answer: {extra}" + ) + if not got: + raise GateError(f"{name}: both sets are empty, so there is nothing to compare") + return sorted(got) + + +# ── timestamps ────────────────────────────────────────────────────────────── +# The gateway publishes dates as Java `Date.toString()` +# ("Thu Oct 23 11:59:31 UTC 2026"); GitBucket's REST API publishes ISO 8601 +# ("2026-10-23T11:59:31Z"). Comparing a non-empty string against a non-empty +# string proves nothing, so both are reduced to an instant. + +_MONTHS = {m: i + 1 for i, m in enumerate( + "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split())} + + +def java_date_to_epoch(text, what="timestamp"): + import re, calendar + m = re.match( + r"^\w{3} (\w{3}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\S+) (\d{4})$", (text or "").strip()) + if not m: + raise GateError(f"{what}: cannot read {text!r} as a Java Date") + mon, day, hh, mm, ss, zone, year = m.groups() + if zone not in ("UTC", "GMT", "Z"): + raise GateError( + f"{what}: {text!r} is in zone {zone!r}; this comparison assumes the " + "server runs in UTC and will not guess an offset") + return calendar.timegm((int(year), _MONTHS[mon], int(day), int(hh), int(mm), int(ss), 0, 0, 0)) + + +def iso_to_epoch(text, what="timestamp"): + import re, calendar + m = re.match(r"^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})", (text or "").strip()) + if not m: + raise GateError(f"{what}: cannot read {text!r} as an ISO 8601 instant") + y, mo, d, hh, mm, ss = (int(x) for x in m.groups()) + return calendar.timegm((y, mo, d, hh, mm, ss, 0, 0, 0)) + + +def any_date_to_epoch(text, what="timestamp"): + """ + An instant from either format the gateway has published. + + ISO 8601 is what it publishes now. The Java form is still accepted so this + harness can be pointed at an older build, and so the zone guard above + stays exercised. + """ + import re + if re.match(r"^\s*\d{4}-\d{2}-\d{2}", text or ""): + return iso_to_epoch(text, what) + return java_date_to_epoch(text, what) + + +def same_instant(gateway_text, native_text, what, tolerance=1): + """True when the two timestamps name the same moment, to the second.""" + a = any_date_to_epoch(gateway_text, f"{what} (gateway)") + b = iso_to_epoch(native_text, f"{what} (GitBucket)") + return abs(a - b) <= tolerance + + +def require_iso_utc(text, what): + """ + The gateway's own timestamps must be machine-readable, not locale- and + zone-dependent. `Date.toString` passed a truthiness check while being + unusable to a client and incomparable with GitBucket's own answer. + """ + import re + if not re.match(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$", (text or "").strip()): + raise GateError(f"{what}: {text!r} is not an ISO 8601 instant in UTC") + return iso_to_epoch(text, what) diff --git a/itest/fixtures.py b/itest/fixtures.py new file mode 100644 index 0000000..21b1d6a --- /dev/null +++ b/itest/fixtures.py @@ -0,0 +1,187 @@ +""" +Build the whole test estate on a blank GitBucket, from zero. + +Every step is checked. An earlier version ignored the exit status of its Git +commands and of some API calls, which meant a repository created without its +collaborators, or a fork whose inherited roles were never removed, still +produced a green run — passing for the wrong reason. + +Nothing is written outside a temporary directory created by `tempfile`. The +earlier version removed and recreated a hard-coded path under one particular +user's home, which was both unportable and a destructive operation on a path +it did not own. +""" +import os +import shutil +import subprocess +import sys +import tempfile +import time + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from gb import api, Web, BASE +from mcp import ACCOUNTS +from checks import GateError, require, require_ok + +OW = ACCOUNTS["owner1"] +REPOS = [("pub-all", False, "ALL"), ("pub-public", False, "PUBLIC"), ("pub-disable", False, "DISABLE"), + ("priv-all", True, "ALL"), ("priv-private", True, "PRIVATE"), ("priv-disable", True, "DISABLE"), + ("priv-public", True, "PUBLIC")] +R = "priv-private" + +# Set by build(); removed by cleanup(). +WORKDIR = None + + +def git(args, cwd, what): + """Run Git and stop the run if it failed. Returns stdout, stripped.""" + r = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True) + if r.returncode != 0: + raise GateError(f"{what}: git {' '.join(args)} exited {r.returncode}\n" + f" stdout: {r.stdout.strip()[:400]}\n stderr: {r.stderr.strip()[:400]}") + return r.stdout.strip() + + +def _clone(url, dest, what): + require(not os.path.exists(dest), f"{what}: {dest} already exists") + git(["-c", "http.proxy=", "clone", "-q", url, dest], cwd=WORKDIR, what=what) + require(os.path.isdir(os.path.join(dest, ".git")), f"{what}: no .git in {dest}") + + +def _commit_branch(repo_dir, branch, filename, author, what): + git(["checkout", "-q", "main"], cwd=repo_dir, what=f"{what}: checkout main") + with open(os.path.join(repo_dir, filename), "w") as f: + f.write(f"{branch}\n") + git(["checkout", "-q", "-b", branch], cwd=repo_dir, what=f"{what}: branch {branch}") + git(["add", "-A"], cwd=repo_dir, what=f"{what}: add") + git(["-c", f"user.name={author}", "-c", f"user.email={author}@example.invalid", + "commit", "-q", "-m", f"{branch} commit"], cwd=repo_dir, what=f"{what}: commit") + git(["-c", "http.proxy=", "push", "-q", "origin", branch], cwd=repo_dir, what=f"{what}: push {branch}") + sha = git(["rev-parse", branch], cwd=repo_dir, what=f"{what}: rev-parse") + require(len(sha) == 40, f"{what}: {branch} did not resolve to a commit id") + return sha + + +def cleanup(): + global WORKDIR + if WORKDIR and os.path.isdir(WORKDIR): + shutil.rmtree(WORKDIR, ignore_errors=True) + WORKDIR = None + + +def build(): + """Create accounts, repositories, roles, Git history and pull requests.""" + global WORKDIR + WORKDIR = tempfile.mkdtemp(prefix="gitbucket-itest-") + + # The instance must be blank: these fixtures assume nothing already exists. + st, existing = api("GET", "/api/v3/repos/owner1/priv-private") + require(st == 404, + "the target instance is not blank (owner1/priv-private already exists). " + "This harness must only be pointed at a disposable GitBucket.") + + for login, (u, p) in ACCOUNTS.items(): + if login == "root": + continue + st, b = api("POST", "/api/v3/admin/users", + {"login": u, "password": p, "email": f"{u}@example.invalid", "full_name": u}) + require_ok(st, b, f"create account {u}") + + for name, private, _ in REPOS: + st, b = api("POST", "/api/v3/user/repos", + {"name": name, "description": f"test {name}", "private": private, + "auto_init": True}, auth=OW) + require_ok(st, b, f"create repository {name}") + require(b.get("private") is private, f"{name}: privacy was not applied") + for who, perm in (("devuser", "push"), ("guestuser", "pull")): + st, b = api("PUT", f"/api/v3/repos/owner1/{name}/collaborators/{who}", + {"permission": perm}, auth=OW) + require_ok(st, b, f"add collaborator {who} to {name}") + st, cols = api("GET", f"/api/v3/repos/owner1/{name}/collaborators", auth=OW) + require_ok(st, cols, f"read collaborators of {name}") + got = {c["login"] for c in cols} + require({"devuser", "guestuser"} <= got, + f"{name}: collaborators are {sorted(got)}, expected devuser and guestuser") + + web = Web() + st, _, cookies = web.signin("owner1", "Test-pass-1") + require(st == 200 and cookies, "owner1 could not sign in to the web UI") + for name, private, option in REPOS: + st, b = web.post(f"/owner1/{name}/settings/options", + {"description": f"test {name}", "isPrivate": str(private).lower(), + "issuesOption": option, "wikiOption": "PUBLIC", "allowFork": "true", + "mergeOptions": ["merge-commit", "squash", "rebase"], + "defaultMergeOption": "merge-commit", "safeMode": "false"}) + require_ok(st, b, f"set options on {name}") + # Read the stored settings back: the form answers 200 either way. + import re + for name, private, option in REPOS: + st, html = web.get(f"/owner1/{name}/settings/options") + require_ok(st, html, f"read options of {name}") + checked = re.findall(r'name="issuesOption" value="([A-Z]+)"\s*checked', html) + require(checked == [option], + f"{name}: issuesOption reads back as {checked}, expected [{option!r}]") + priv = re.findall(r'name="isPrivate" value="(\w+)"\s*checked', html) + require(priv == [str(private).lower()], + f"{name}: isPrivate reads back as {priv}") + + # --- Git history in the base repository --------------------------------- + base = os.path.join(WORKDIR, "base") + _clone(f"http://owner1:Test-pass-1@127.0.0.1:8099/git/owner1/{R}.git", base, "clone base") + shas = {br: _commit_branch(base, br, fn, "owner1", "base history") + for br, fn in (("feature-a", "a.txt"), ("feature-b", "b.txt"), ("feature-c", "c.txt"))} + + # --- a fork, with the inherited roles removed --------------------------- + st, b = api("POST", f"/api/v3/repos/owner1/{R}/forks", {}, auth=ACCOUNTS["guestuser"]) + require_ok(st, b, "fork priv-private as guestuser") + for _ in range(20): + st, _ = api("GET", f"/api/v3/repos/guestuser/{R}", auth=ACCOUNTS["guestuser"]) + if st == 200: + break + time.sleep(1) + require(st == 200, "the fork did not become available") + + # GitBucket copies the base repository's collaborators into a fork, so a + # developer of the base is normally also a developer of the fork. Without + # removing them the head-repository role check in mark_ready_for_review + # cannot be observed at all, and an earlier run of it passed for exactly + # that wrong reason. + for u in ("devuser", "owner1"): + st, b = api("DELETE", f"/api/v3/repos/guestuser/{R}/collaborators/{u}", + auth=ACCOUNTS["guestuser"]) + require_ok(st, b, f"remove inherited collaborator {u} from the fork") + st, cols = api("GET", f"/api/v3/repos/guestuser/{R}/collaborators", auth=ACCOUNTS["guestuser"]) + require_ok(st, cols, "read the fork's collaborators") + remaining = {c["login"] for c in cols} + require("devuser" not in remaining, + f"devuser is still a collaborator on the fork ({sorted(remaining)}); the " + "head-repository role check would pass for the wrong reason") + + fork = os.path.join(WORKDIR, "fork") + _clone(f"http://guestuser:Test-pass-3@127.0.0.1:8099/git/guestuser/{R}.git", fork, "clone fork") + shas["fork-feature"] = _commit_branch(fork, "fork-feature", "fork.txt", "guestuser", "fork history") + + # --- pull requests ------------------------------------------------------ + prs = {} + for key, payload, auth in ( + ("same_draft", {"title": "same-repo draft", "body": "original body", + "head": "feature-a", "base": "main", "draft": True}, OW), + ("fork_draft", {"title": "fork draft", "body": "fork body", + "head": "guestuser:fork-feature", "base": "main", "draft": True}, + ACCOUNTS["guestuser"]), + ("api_merge", {"title": "to merge by api", "body": "b", + "head": "feature-b", "base": "main"}, OW), + ("web_merge", {"title": "to merge by web", "body": "b", + "head": "feature-c", "base": "main"}, OW), + ): + st, b = api("POST", f"/api/v3/repos/owner1/{R}/pulls", payload, auth=auth) + require_ok(st, b, f"create pull request {key}") + prs[key] = b["number"] + require(prs["same_draft"] != prs["fork_draft"], "pull request numbers collided") + st, d = api("GET", f"/api/v3/repos/owner1/{R}/pulls/{prs['fork_draft']}", auth=OW) + require_ok(st, d, "read the fork pull request") + require(d["head"]["repo"]["full_name"] == f"guestuser/{R}", + f"the fork pull request's head repository is {d['head']['repo']['full_name']}") + require(d["draft"] is True, "the fork pull request is not a draft") + + return prs, base, fork, shas diff --git a/itest/gb.py b/itest/gb.py new file mode 100644 index 0000000..ece963f --- /dev/null +++ b/itest/gb.py @@ -0,0 +1,64 @@ +"""GitBucket's own REST API and web forms, used as the control for the gateway.""" +import base64 +import http.cookiejar +import json +import urllib.error +import urllib.parse +import urllib.request + +BASE = "http://127.0.0.1:8099" + + +def _decode(payload): + try: + return json.loads(payload.decode()) + except Exception: + return payload.decode(errors="replace")[:400] + + +def api(method, path, body=None, auth=("root", "root"), raw=False): + """One call to GitBucket's REST API. Returns (status, parsed-body).""" + data = None if body is None else json.dumps(body).encode() + req = urllib.request.Request(BASE + path, data=data, method=method) + req.add_header("Content-Type", "application/json") + if auth: + token = base64.b64encode(f"{auth[0]}:{auth[1]}".encode()).decode() + req.add_header("Authorization", "Basic " + token) + try: + with urllib.request.urlopen(req) as r: + payload = r.read() + return r.status, (payload if raw else _decode(payload)) + except urllib.error.HTTPError as e: + payload = e.read() + return e.code, (payload if raw else _decode(payload)) + + +class Web: + """A cookie session. Repository settings and the merge route have no API.""" + + def __init__(self): + self.jar = http.cookiejar.CookieJar() + self.opener = urllib.request.build_opener( + urllib.request.HTTPCookieProcessor(self.jar)) + + def signin(self, user, password): + data = urllib.parse.urlencode({"userName": user, "password": password}).encode() + req = urllib.request.Request(BASE + "/signin", data=data, method="POST") + with self.opener.open(req) as r: + return r.status, r.geturl(), sorted(c.name for c in self.jar) + + def get(self, path): + try: + with self.opener.open(BASE + path) as r: + return r.status, r.read().decode(errors="replace") + except urllib.error.HTTPError as e: + return e.code, e.read().decode(errors="replace")[:600] + + def post(self, path, fields): + data = urllib.parse.urlencode(fields, doseq=True).encode() + req = urllib.request.Request(BASE + path, data=data, method="POST") + try: + with self.opener.open(req) as r: + return r.status, r.geturl() + except urllib.error.HTTPError as e: + return e.code, e.read().decode(errors="replace")[:600] diff --git a/itest/harness.py b/itest/harness.py new file mode 100644 index 0000000..8a32c74 --- /dev/null +++ b/itest/harness.py @@ -0,0 +1,28 @@ +import json, sys +RESULTS = [] + +def check(name, got, want, note=""): + ok = got == want + RESULTS.append((ok, name, got, want, note)) + print(("PASS " if ok else "FAIL ") + name + ("" if ok else f"\n got : {got!r}\n want: {want!r}")) + return ok + +def verdict(kind, payload): + """Collapse a tool outcome to a comparable verdict.""" + if kind == "ok": + return "allowed" + msg = payload.get("message", "") if isinstance(payload, dict) else str(payload) + code = payload.get("code") if isinstance(payload, dict) else None + if "not found or not readable" in msg: + return "not-found" + if "may not open an issue" in msg or "does not have write access" in msg or "does not have developer access" in msg or "may edit only their own" in msg: + return "forbidden" + return f"error:{code}:{msg[:70]}" + +def summary(title): + bad = [r for r in RESULTS if not r[0]] + print() + print(f"=== {title}: {len(RESULTS)-len(bad)} passed, {len(bad)} failed ===") + for r in bad: + print(" FAILED:", r[1]) + return len(bad) diff --git a/itest/integration.py b/itest/integration.py new file mode 100644 index 0000000..e3d1b02 --- /dev/null +++ b/itest/integration.py @@ -0,0 +1,476 @@ +""" +The live-instance gate: every check, on a GitBucket built from zero. + +Nothing here may be skipped. Both defects this file was corrected for were +skips rather than wrong answers: a precondition that failed quietly, and a +comparison whose input went missing. So every precondition goes through +`checks.require*`, which raises, and every set comparison goes through +`require_same_set`, which fails on an empty or partial set instead of +comparing whatever happens to be in both answers. + +`selftest.py` proves each of those guards fires, without a server. +""" +import sys, os, json, subprocess +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from mcp import * +from harness import check, summary, verdict, RESULTS +from gb import api, Web +from checks import (GateError, require, require_ok, native_decision, + require_same_set, same_instant, require_iso_utc) +from observe import stored_issue_count, observe_issue_write +import fixtures + +R = "priv-private" +OWNER = ACCOUNTS["owner1"] + +def nat_pr(n): + st, b = api("GET", f"/api/v3/repos/owner1/{R}/pulls/{n}", auth=OWNER) + require_ok(st, b, f"read pull request #{n} from GitBucket", ok=(200,)) + require(isinstance(b, dict), f"pull request #{n}: GitBucket did not answer an object") + return b + +def nat_iss(n): + st, b = api("GET", f"/api/v3/repos/owner1/{R}/issues/{n}", auth=OWNER) + require_ok(st, b, f"read issue #{n} from GitBucket", ok=(200,)) + require(isinstance(b, dict), f"issue #{n}: GitBucket did not answer an object") + return b + +def nat_com(n): + st, b = api("GET", f"/api/v3/repos/owner1/{R}/issues/{n}/comments", auth=OWNER) + require_ok(st, b, f"read the comments of #{n} from GitBucket", ok=(200,)) + require(isinstance(b, list), f"comments of #{n}: GitBucket did not answer a list") + return b + +def nat_pr_list(state="all"): + st, b = api("GET", f"/api/v3/repos/owner1/{R}/pulls?state={state}", auth=OWNER) + require_ok(st, b, f"list {state} pull requests from GitBucket", ok=(200,)) + require(isinstance(b, list) and b, "GitBucket listed no pull requests at all") + return b + +def git(*a, cwd): + return fixtures.git(list(a), cwd, "gate: git " + " ".join(a)) + +# A failed precondition ends the run with its reason and a distinct exit code, +# and never leaves the temporary clone behind. Exit 1 means a check failed; +# exit 2 means the gate could not be run and no result should be read from it. +import atexit +atexit.register(fixtures.cleanup) + +def _on_error(kind, value, tb): + if issubclass(kind, GateError): + print(f"\nGATE ABORTED: {value}", file=sys.stderr) + print("No result may be read from this run.", file=sys.stderr) + sys.exit(2) + sys.__excepthook__(kind, value, tb) + +sys.excepthook = _on_error + +# Fault injection, off unless ITEST_BREAK names a fault. It exists so the +# gate's own guards can be shown to fire end to end, not only in +# `selftest.py`: each named fault reproduces one of the skips this gate was +# corrected for, and the run must abort with exit 2 rather than report success. +# ITEST_BREAK=webmerge the web merge route fails +# ITEST_BREAK=prlist the gateway's pull request list comes back empty +# ITEST_BREAK=native500 GitBucket's own issue route answers 500 +# ITEST_BREAK=storage the stored-issue count cannot be read +_FAULTS = {f for f in os.environ.get("ITEST_BREAK", "").split(",") if f} +if _FAULTS: + print(f"!! fault injection active: {sorted(_FAULTS)} — this run must abort, not pass\n") + +def fault(name): + return name in _FAULTS + + +# The version the plugin reports has to be checked against the artifact under +# test, not against a literal: a literal is exactly the defect this check +# exists to catch, and it also silently encodes one lineage's version number. +# Fail-closed, like every other precondition here — an unreadable descriptor +# is not a passing check, it is a gate that could not be run. +def _packaged_plugin_version(): + import configparser + import zipfile + + jar = os.environ.get("MCP_PLUGIN_JAR", "") + if not jar: + raise GateError( + "MCP_PLUGIN_JAR is not set. It must name the exact plugin JAR installed on the " + "instance under test, so the reported version can be compared with the packaged " + "descriptor instead of a hardcoded string.") + if not os.path.isfile(jar): + raise GateError(f"MCP_PLUGIN_JAR does not name a readable file: {jar}") + try: + with zipfile.ZipFile(jar) as z: + raw = z.read("gitbucket-plugin.properties").decode("utf-8") + except Exception as exc: + raise GateError(f"cannot read gitbucket-plugin.properties from {jar}: {exc}") + parser = configparser.ConfigParser() + parser.read_string("[d]\n" + raw) + version = parser["d"].get("pluginversion", "").strip() + if not version: + raise GateError(f"{jar} packages a descriptor with no pluginVersion") + return version + + +PACKAGED_VERSION = _packaged_plugin_version() +print(f"artifact under test declares pluginVersion={PACKAGED_VERSION}\n") + +prs, BASE_DIR, FORK_DIR, SHAS = fixtures.build() +SAME, FORKPR = prs["same_draft"], prs["fork_draft"] +APIMERGE, WEBMERGE = prs["api_merge"], prs["web_merge"] +print(f"fixtures: same-repo draft #{SAME}, fork draft #{FORKPR}, " + f"api-merge #{APIMERGE}, web-merge #{WEBMERGE}\n") + +# ── 1. transport and identity ─────────────────────────────────────────────── +print("## 1. transport and identity") +for who in ("devuser","guestuser","outsider","root","owner1"): + k,p = call(who,"whoami",{}) + check(f"whoami as {who} resolves to the authenticating account", (k, p.get("login") if k=="ok" else p), ("ok",who)) +k,p = call("devuser","whoami",{}) +check("whoami marks the shipped descriptor as self-reported", p.get("plugin",{}).get("self_reported"), True) +check("whoami reports is_admin truthfully for a plain account", p.get("is_admin"), False) +check("whoami reports is_admin truthfully for a site admin", call("root","whoami",{})[1].get("is_admin"), True) +check("a wrong password is rejected at the transport", rpc("devuser","tools/list",creds=("devuser","WRONG"))[0], 401) +check("an unknown account is rejected at the transport", rpc("devuser","tools/list",creds=("nobody","x"))[0], 401) +st,b = rpc("devuser","tools/list") +check("tools/list publishes the full registry over HTTP", (st, len(b["result"]["tools"])), (200, 19)) +check("initialize reports the version packaged in the artifact under test", + rpc("devuser","initialize",{"protocolVersion":"2024-11-05","capabilities":{}})[1]["result"]["serverInfo"]["version"], + PACKAGED_VERSION) +check("whoami reports the same packaged version, so both read the descriptor", + call("devuser","whoami",{})[1].get("plugin",{}).get("plugin_version"), PACKAGED_VERSION) + +# ── 2. read authorization, against GitBucket's own role lookup ────────────── +print("\n## 2. read authorization") +READ = {"get_repository":{}, "get_pull_request":{"number":1}, "get_issue":{"number":1}, + "get_thread_comments":{"number":1}, "get_pr_diff":{"number":1}, + "list_issues":{}, "list_pull_requests":{}} +for tool, extra in READ.items(): + k,p = call("outsider", tool, {"owner":"owner1","repo":R, **extra}) + check(f"{tool}: an account with no role is refused on a private repository", verdict(k,p), "not-found") + k2,p2 = call("outsider", tool, {"owner":"owner1","repo":"no-such-repo", **extra}) + m1 = p.get("message","").replace(R,"X"); m2 = p2.get("message","").replace("no-such-repo","X") + check(f"{tool}: hidden and absent are indistinguishable", (p.get("code")==p2.get("code"), m1), (True, m2)) +check("the guest role opens a private repository", verdict(*call("guestuser","get_repository",{"owner":"owner1","repo":R})), "allowed") +check("a site admin can read a private repository", verdict(*call("root","get_repository",{"owner":"owner1","repo":R})), "allowed") +check("a public repository is readable by any authenticated account", verdict(*call("outsider","get_repository",{"owner":"owner1","repo":"pub-all"})), "allowed") +ALL7 = {n for n,_,_ in fixtures.REPOS} +PUB3 = {n for n,priv,_ in fixtures.REPOS if not priv} +for who, want in (("outsider",PUB3),("guestuser",ALL7),("devuser",ALL7),("root",ALL7),("owner1",ALL7)): + k,p = call(who,"list_repositories",{"owner":"owner1"}) + got = {r["name"] for r in p.get("repositories",[])} if k=="ok" else {"ERR"} + check(f"list_repositories as {who} is filtered for the caller", (got, p.get("count")), (want, len(want))) + +# ── 3. issue-creation policy, compared with GitBucket's own route ─────────── +print("\n## 3. issue-creation policy, against GitBucket's own verdict") +EXPECT = { + "pub-all": {"outsider":"allowed","guestuser":"allowed","devuser":"allowed","root":"allowed"}, + "pub-public": {"outsider":"forbidden","guestuser":"allowed","devuser":"allowed","root":"allowed"}, + "pub-disable": {"outsider":"forbidden","guestuser":"forbidden","devuser":"forbidden","root":"forbidden"}, + "priv-all": {"outsider":"not-found","guestuser":"forbidden","devuser":"forbidden","root":"forbidden"}, + "priv-private": {"outsider":"not-found","guestuser":"forbidden","devuser":"allowed","root":"allowed"}, + "priv-disable": {"outsider":"not-found","guestuser":"forbidden","devuser":"forbidden","root":"forbidden"}, + "priv-public": {"outsider":"not-found","guestuser":"allowed","devuser":"allowed","root":"allowed"}, +} +# The storage witness goes through `observe.observe_issue_write`, which reads +# the stored count on both sides of the operation and raises if either read is +# unavailable. It used to be a local helper that returned -1 on a failed read, +# so two failed reads cancelled into a delta of zero and a refusal check +# reported "nothing was stored" without the gate having observed storage. +def _count_api(method, path, body=None, auth=None): + st, b = api(method, path, body) if auth is None else api(method, path, body, auth) + if fault("storage") and path.endswith("/issues?state=all"): + return 500, {"message": "injected: the stored-issue read failed"} + return st, b + +for repo in [n for n,_,_ in fixtures.REPOS]: + for who in ("outsider","guestuser","devuser","root"): + want = EXPECT[repo][who] + k, p, wrote = observe_issue_write( + _count_api, + lambda who=who, repo=repo: call(who, "create_issue", + {"owner":"owner1","repo":repo,"title":f"probe {repo}/{who}","body":"probe"}), + "owner1", repo) + v = verdict(k, p) + check(f"create_issue {repo}/{who}: verdict and stored rows", (v, wrote), (want, 1 if want=="allowed" else 0)) + nst, nb = api("POST", f"/api/v3/repos/owner1/{repo}/issues", + {"title":"native","body":"n"}, auth=ACCOUNTS[who]) + # A 5xx is not a refusal. Reading it as one would let a broken server + # agree with anything, so it ends the run instead. + if fault("native500"): + nst = 500 + native = native_decision(nst, f"GitBucket's own create-issue route for {repo}/{who}") + check(f"create_issue {repo}/{who}: agrees with GitBucket's own route", + "allowed" if v=="allowed" else "denied", native) + +# ── 4. issue round-trip ───────────────────────────────────────────────────── +print("\n## 4. issue round-trip and byte exactness") +T, B = "заголовок ✅", "тіло\nдругий\t漢字\r\nкінець" +k,p = call("devuser","create_issue",{"owner":"owner1","repo":R,"title":T,"body":B}) +num = p["number"]; n = nat_iss(num) +check("the issue title is stored byte for byte", n["title"], T) +check("the issue body is stored byte for byte", n["body"], B) +check("the issue is attributed to the authenticating account", n["user"]["login"], "devuser") +check("get_issue reads back the same bytes", tuple(call("devuser","get_issue",{"owner":"owner1","repo":R,"number":num})[1][x] for x in ("title","body")), (T,B)) +call("devuser","close_issue",{"owner":"owner1","repo":R,"number":num}) +check("close_issue reaches GitBucket's own store", nat_iss(num)["state"], "closed") +call("devuser","reopen_issue",{"owner":"owner1","repo":R,"number":num}) +check("reopen_issue reaches GitBucket's own store", nat_iss(num)["state"], "open") +check("a guest cannot close an issue", verdict(*call("guestuser","close_issue",{"owner":"owner1","repo":R,"number":num})), "forbidden") +check("the guest's refused close left the issue open", nat_iss(num)["state"], "open") +call("devuser","add_issue_comment",{"owner":"owner1","repo":R,"number":num,"body":B}) +check("an issue comment is stored byte for byte", nat_com(num)[-1]["body"], B) + +# ── 5. pull request commit identities ─────────────────────────────────────── +print("\n## 5. pull request commit identities, against Git") +git("fetch","-q","origin", cwd=BASE_DIR) +tip = git("rev-parse","origin/feature-a", cwd=BASE_DIR) +mb = git("merge-base","origin/main","origin/feature-a", cwd=BASE_DIR) +require(len(tip)==40 and len(mb)==40, "Git did not resolve the head and merge base") +require(tip == SHAS["feature-a"], "the pushed head no longer matches what the fixture created") +k,p = call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":SAME}) +check("head_sha equals the tip of the head branch as Git reports it", p["head_sha"], tip) +check("merge_base_sha equals git merge-base", p["merge_base_sha"], mb) +check("the stored-snapshot nature of both ids is published", p["commit_ids_are_stored_snapshot"], True) +check("is_draft comes from storage", p["is_draft"], True) +check("a same-repo pull request names its own repository as head", (p["head_user"],p["head_repo"]), ("owner1",R)) +k,pf = call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":FORKPR}) +check("a cross-repo pull request names the fork as head", (pf["head_user"],pf["head_repo"]), ("guestuser",R)) +e1 = call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":1.9})[1] +e2 = call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":1})[1] +check("read-only tools still coerce 1.9 to 1 on this runtime's Jackson", e1.get("message")==e2.get("message"), True) +# Timestamps must be readable by a client regardless of the server's zone. +# `Date.toString` passed a truthiness check while being locale-dependent and +# incomparable with GitBucket's own ISO 8601 answer. +nd_same = nat_pr(SAME) +for field in ("created_at", "updated_at"): + check(f"{field} is published as an ISO 8601 instant in UTC", + bool(require_iso_utc(p.get(field), f"get_pull_request {field}")), True, + note=f"{field}={p.get(field)!r}") +check("created_at names the same instant GitBucket recorded", + same_instant(p["created_at"], nd_same["created_at"], "created_at"), True, + note=f"gateway={p['created_at']!r} gitbucket={nd_same['created_at']!r}") + +# ── 6. update_pull_request ────────────────────────────────────────────────── +print("\n## 6. update_pull_request") +base_pr = nat_pr(SAME) +call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME,"title":"renamed only"}) +a = nat_pr(SAME) +check("a title-only update changes the title", a["title"], "renamed only") +check("a title-only update leaves the body byte-identical", a["body"], base_pr["body"]) +k,p = call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME,"body":B}) +check("the read-back comparison is reported", (p["title_saved_exactly"],p["body_saved_exactly"]), (True,True)) +a = nat_pr(SAME) +check("a body-only update leaves the title untouched", a["title"], "renamed only") +check("a body-only update preserves unicode and CRLF byte for byte", a["body"], B) +call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME,"body":""}) +a = nat_pr(SAME) +check("an explicit empty body clears it", a["body"], "") +check("an explicit empty body leaves the title alone", a["title"], "renamed only") +k,p = call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME,"title":""}) +check("an empty title is refused", (k, "must not be empty" in str(p.get("message",""))), ("error",True)) +check("the refused empty title never reached storage", nat_pr(SAME)["title"], "renamed only") +check("supplying neither field is refused", call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME})[0], "error") +check("a guest cannot update a pull request", verdict(*call("guestuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME,"title":"guest"})), "forbidden") +check("the guest's refused update never reached storage", nat_pr(SAME)["title"], "renamed only") +check("an outsider on a readable public repository is refused as a write", verdict(*call("outsider","update_pull_request",{"owner":"owner1","repo":"pub-all","number":1,"title":"x"})), "forbidden") + +# ── 7. argument strictness on live writes ─────────────────────────────────── +print("\n## 7. argument strictness on live writes") +FORMS = [(1.9,"a fractional number"),(4294967297,"range"),("1","JSON integer"),(True,"JSON integer"), + (None,"JSON integer"),({},"JSON integer"),([],"JSON integer"),(0,"positive")] +snap = {n: nat_pr(n) for n in (SAME, FORKPR, APIMERGE)} +for val,frag in FORMS: + k,p = call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":val,"title":"HIJACKED"}) + check(f"update_pull_request refuses number={json.dumps(val)}", (k, frag in str(p.get("message",""))), ("error",True)) +for val,frag in FORMS: + k,p = call("guestuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":val}) + check(f"mark_ready_for_review refuses number={json.dumps(val)}", (k, frag in str(p.get("message",""))), ("error",True)) +for n,was in snap.items(): + now = nat_pr(n) + check(f"no malformed identifier altered pull request #{n}", (now["title"],now["body"],now["draft"],now["state"]), + (was["title"],was["body"],was["draft"],was["state"])) +k,p = call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME,"body":{}}) +check("a malformed object body is refused instead of erasing the body", (k,"must be a JSON string" in str(p.get("message",""))), ("error",True)) +check("the refused object body left storage untouched", nat_pr(SAME)["body"], "") +check("an explicit null body is refused rather than treated as absent", call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":SAME,"body":None})[0], "error") + +# ── 8. comments ───────────────────────────────────────────────────────────── +print("\n## 8. comments") +UNI = "коментар\nдругий\t— ✅\r\nкінець 漢字 &" +k,p = call("devuser","add_pr_comment",{"owner":"owner1","repo":R,"number":SAME,"body":UNI}) +check("a developer can comment on a pull request", k, "ok") +check("the comment is stored byte for byte", nat_com(SAME)[-1]["body"], UNI) +check("the comment is attributed to the authenticating account", nat_com(SAME)[-1]["user"]["login"], "devuser") +for i in range(6): call("devuser","add_pr_comment",{"owner":"owner1","repo":R,"number":SAME,"body":f"bulk {i}"}) +total = len(nat_com(SAME)) +k,p = call("devuser","get_thread_comments",{"owner":"owner1","repo":R,"number":SAME,"limit":100}) +check("the thread total matches GitBucket's own count", p["total_count"], total) +check("has_more is false on a complete page", p["has_more"], False) +check("ids and authors are published for answering", all("comment_id" in c and "author" in c for c in p["comments"]), True) +k,p1 = call("devuser","get_thread_comments",{"owner":"owner1","repo":R,"number":SAME,"limit":3,"offset":0}) +check("a bounded page returns exactly the limit", len(p1["comments"]), 3) +check("has_more is true when more remain", p1["has_more"], True) +check("next_offset points past the page", p1["next_offset"], 3) +k,p2 = call("devuser","get_thread_comments",{"owner":"owner1","repo":R,"number":SAME,"limit":3,"offset":3}) +check("consecutive pages do not overlap", set(c["comment_id"] for c in p1["comments"]) & set(c["comment_id"] for c in p2["comments"]), set()) +ids = [c["comment_id"] for c in p["comments"]] +check("paging covers the thread exactly once", (len(ids), len(set(ids))), (total,total)) +check("a guest can read a thread they may read", call("guestuser","get_thread_comments",{"owner":"owner1","repo":R,"number":SAME})[0], "ok") +check("an outsider cannot read a private thread", verdict(*call("outsider","get_thread_comments",{"owner":"owner1","repo":R,"number":SAME})), "not-found") +check("a guest cannot comment", verdict(*call("guestuser","add_pr_comment",{"owner":"owner1","repo":R,"number":SAME,"body":"no"})), "forbidden") + +# ── 9. update_own_comment ─────────────────────────────────────────────────── +print("\n## 9. update_own_comment") +cid = [c for c in p["comments"] if c["author"]=="devuser"][0]["comment_id"] +EDIT = "відредаговано\nрядок два\t✅" +k,r = call("devuser","update_own_comment",{"owner":"owner1","repo":R,"comment_id":cid,"body":EDIT}) +check("the author can edit their own comment", k, "ok") +check("the edit is stored byte for byte", {c["id"]:c for c in nat_com(SAME)}[cid]["body"], EDIT) +check("the read-back comparison is reported", r["body_saved_exactly"], True) +check("authorship is unchanged by the edit", {c["id"]:c for c in nat_com(SAME)}[cid]["user"]["login"], "devuser") +for who, label in (("owner1","the repository owner"),("root","a site admin"),("guestuser","an unrelated account")): + k,r = call(who,"update_own_comment",{"owner":"owner1","repo":R,"comment_id":cid,"body":f"{who} takeover"}) + check(f"{label} cannot edit someone else's comment", verdict(k,r), "forbidden" if who!="guestuser" else "forbidden") + check(f"{label}'s refused edit left the text untouched", {c["id"]:c for c in nat_com(SAME)}[cid]["body"], EDIT) +k,r = call("devuser","update_own_comment",{"owner":"owner1","repo":R,"comment_id":cid,"body":""}) +check("an empty replacement is refused rather than blanking the comment", (k,"must not be empty" in str(r.get("message",""))), ("error",True)) +check("the refused blanking left the text untouched", {c["id"]:c for c in nat_com(SAME)}[cid]["body"], EDIT) +for val in (1.9,"1",True,None,{},[],0): + check(f"a malformed comment_id={json.dumps(val)} is refused", call("devuser","update_own_comment",{"owner":"owner1","repo":R,"comment_id":val,"body":"x"})[0], "error") +check("no malformed comment_id altered any comment", {c["id"]:c for c in nat_com(SAME)}[cid]["body"], EDIT) +call("devuser","close_pull_request",{"owner":"owner1","repo":R,"number":SAME}) +call("devuser","reopen_pull_request",{"owner":"owner1","repo":R,"number":SAME}) +k,p = call("devuser","get_thread_comments",{"owner":"owner1","repo":R,"number":SAME,"limit":200}) +acts = [c for c in p["comments"] if c.get("action") not in (None,"comment")] +check("state-change records are surfaced with their action", bool(acts), True) +require(acts, "no close/reopen record appeared, so the non-editable-record check has no subject") +k,r = call("devuser","update_own_comment",{"owner":"owner1","repo":R,"comment_id":acts[0]["comment_id"],"body":"rewrite history"}) +check("a state-change record is refused as non-editable text", (k,"not editable comment text" in str(r.get("message",""))), ("error",True)) + +# ── 10. the Ready transition ──────────────────────────────────────────────── +print("\n## 10. mark_ready_for_review") +head = nat_pr(FORKPR)["head"]["sha"] +check("the fork pull request starts as a draft", nat_pr(FORKPR)["draft"], True) +check("an outsider is refused as not-found on the private base", verdict(*call("outsider","mark_ready_for_review",{"owner":"owner1","repo":R,"number":FORKPR})), "not-found") +check("devuser is a developer on the base repository", verdict(*call("devuser","update_pull_request",{"owner":"owner1","repo":R,"number":FORKPR,"title":"fork draft"})), "allowed") +k,p = call("devuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":FORKPR}) +check("a developer of the base with no role on the head fork is refused", verdict(k,p), "forbidden") +check("that refusal names the head repository", "guestuser/"+R in str(p.get("message","")), True) +check("that refusal left the draft intact", nat_pr(FORKPR)["draft"], True) +k,p = call("root","mark_ready_for_review",{"owner":"owner1","repo":R,"number":FORKPR,"expected_head_sha":"c"*40}) +check("a stale expected_head_sha is refused even for a site admin", (k,"stale expected_head_sha" in str(p.get("message",""))), ("error",True)) +check("the stale precondition left the draft intact", nat_pr(FORKPR)["draft"], True) +check("a malformed precondition is refused, not dropped", call("guestuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":FORKPR,"expected_head_sha":"abc"})[0], "error") +check("the malformed precondition left the draft intact", nat_pr(FORKPR)["draft"], True) +was = nat_pr(FORKPR) +k,p = call("guestuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":FORKPR,"expected_head_sha":head}) +check("the fork owner can mark it ready", (k,p["was_draft"],p["is_draft"],p["changed"]), ("ok",True,False,True)) +check("GitBucket's own API reports it is no longer a draft", nat_pr(FORKPR)["draft"], False) +check("the race guarantee is stated, not overstated", p["race_guarantee"], "checked-then-written; not compare-and-swap") +now = nat_pr(FORKPR) +check("the transition changed nothing but the draft flag", + (now["title"],now["body"],now["head"]["sha"],now["head"]["label"],now["base"]["label"],now["state"]), + (was["title"],was["body"],was["head"]["sha"],was["head"]["label"],was["base"]["label"],was["state"])) +k,p = call("guestuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":FORKPR}) +check("a second call is idempotent and reports changed=false", (k,p["was_draft"],p["is_draft"],p["changed"]), ("ok",False,False,False)) +check("the second call did not re-draft it", nat_pr(FORKPR)["draft"], False) +call("devuser","close_pull_request",{"owner":"owner1","repo":R,"number":SAME}) +check("the same-repo pull request is closed and still a draft", (nat_pr(SAME)["state"],nat_pr(SAME)["draft"]), ("closed",True)) +k,p = call("devuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":SAME}) +check("a closed pull request is refused", (k,"is closed" in str(p.get("message",""))), ("error",True)) +check("the closed pull request stayed a draft", nat_pr(SAME)["draft"], True) +call("devuser","reopen_pull_request",{"owner":"owner1","repo":R,"number":SAME}) +k,p = call("devuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":SAME,"expected_head_sha":nat_pr(SAME)["head"]["sha"]}) +check("once reopened, a developer of the head repository succeeds", (k,p["changed"]), ("ok",True)) +check("GitBucket reports the same-repo pull request is ready", nat_pr(SAME)["draft"], False) + +# ── 11. merged semantics, both merge routes, neither optional ─────────────── +print("\n## 11. merged semantics") +check("an open pull request reports merged=false", + call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":APIMERGE})[1]["merged"], False) + +# --- route A: the REST merge, which records no commit ids ------------------- +st, b = api("PUT", f"/api/v3/repos/owner1/{R}/pulls/{APIMERGE}/merge", + {"commit_message":"api merge"}, auth=OWNER) +require_ok(st, b, f"merge #{APIMERGE} through GitBucket's REST route") +nd = nat_pr(APIMERGE) +require(nd["merged"] is True, f"#{APIMERGE}: GitBucket does not consider it merged after its own merge") +k,p = call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":APIMERGE}) +check("after a REST merge GitBucket reports merged=true", nd["merged"], True) +check("after a REST merge the gateway agrees", p["merged"], nd["merged"]) +check("merged_by matches GitBucket's record", p.get("merged_by"), nd["merged_by"]["login"]) +# Not "is the string non-empty": the same moment, compared with GitBucket's. +check("merged_at is published as an ISO 8601 instant in UTC", + bool(require_iso_utc(p.get("merged_at"), "merged_at")), True, + note=f"merged_at={p.get('merged_at')!r}") +check("merged_at names the same instant GitBucket recorded", + same_instant(p.get("merged_at"), nd.get("merged_at"), "merged_at"), True, + note=f"gateway={p.get('merged_at')!r} gitbucket={nd.get('merged_at')!r}") +check("merged_commit_ids is absent because the REST route records none", "merged_commit_ids" in p, False) +check("a merged pull request is refused by mark_ready_for_review", + call("guestuser","mark_ready_for_review",{"owner":"owner1","repo":R,"number":APIMERGE})[0], "error") + +# --- route B: the web merge, which does record commit ids ------------------- +# Mandatory. The previous version created this pull request inline and skipped +# the whole route if creation failed, so a broken fixture produced a green run +# that had never exercised the recording path at all. The pull request is now +# created in fixtures.py, where failure stops the run. +web = Web() +st, _, cookies = web.signin("owner1", "Test-pass-1") +require(st == 200 and cookies, "owner1 could not sign in for the web merge route") +st, b = web.post(f"/owner1/{R}/pull/{WEBMERGE}/merge", + {"message":"web merge","strategy":"merge-commit","isDraft":"false"}) +if fault("webmerge"): + st, b = 500, "injected: the web merge route failed" +require_ok(st, b, f"merge #{WEBMERGE} through GitBucket's web route") +nd = nat_pr(WEBMERGE) +require(nd["merged"] is True, f"#{WEBMERGE}: the web merge route did not mark it merged") +k,p = call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":WEBMERGE}) +check("after a web merge GitBucket reports merged=true", nd["merged"], True) +check("after a web merge the gateway agrees", p["merged"], True) +check("merged_by matches GitBucket's record on the web route", p.get("merged_by"), nd["merged_by"]["login"]) +check("merged_at names the same instant on the web route", + same_instant(p.get("merged_at"), nd.get("merged_at"), "merged_at"), True, + note=f"gateway={p.get('merged_at')!r} gitbucket={nd.get('merged_at')!r}") +ids = p.get("merged_commit_ids") +check("merged_commit_ids is published when GitBucket recorded them", + isinstance(ids, list) and len(ids) > 0 and all(len(x)==40 for x in ids), True, + note=f"ids={ids!r}") +check("the two merge routes differ only in whether commit ids were recorded", + ("merged_commit_ids" in call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":APIMERGE})[1], + "merged_commit_ids" in p), (False, True)) + +# --- every pull request, as full sets rather than an intersection ----------- +native = {d["number"]: d for d in nat_pr_list("all")} +gateway = {x["number"]: x for x in + call("devuser","list_pull_requests",{"owner":"owner1","repo":R,"state":"all"})[1]["pull_requests"]} +if fault("prlist"): + gateway = {} +# A set comparison first: the previous version iterated GitBucket's list and +# silently dropped any number the gateway had not returned, so a gateway that +# lost every row compared nothing and passed. +numbers = require_same_set("list_pull_requests covers exactly GitBucket's pull requests", + gateway.keys(), native.keys()) +check("the fixture's four pull requests are all present", + sorted(numbers), sorted([SAME, FORKPR, APIMERGE, WEBMERGE])) +for n in numbers: + check(f"list_pull_requests #{n} merged flag equals GitBucket's", gateway[n]["merged"], native[n]["merged"]) + st, one = call("devuser","get_pull_request",{"owner":"owner1","repo":R,"number":n}) + require(st == "ok", f"get_pull_request #{n} failed: {one!r}") + check(f"get_pull_request #{n} merged flag equals GitBucket's", one["merged"], native[n]["merged"]) + check(f"get_pull_request #{n} state equals GitBucket's", one["state"], native[n]["state"]) + check(f"get_pull_request #{n} is_draft equals GitBucket's", one["is_draft"], native[n]["draft"]) +check("at least one pull request is merged and at least one is not", + (any(native[n]["merged"] for n in numbers), any(not native[n]["merged"] for n in numbers)), (True, True)) + +failed = summary("LIVE INTEGRATION GATE") +print(f"total checks: {len(RESULTS)}") +# A run that executed too few checks is not a pass. The count is a floor, not +# an exact figure, so adding checks does not require editing it; it exists so +# that a run which quietly stopped early cannot report success. +MINIMUM_CHECKS = 200 +if len(RESULTS) < MINIMUM_CHECKS: + print(f"GATE ABORTED: only {len(RESULTS)} checks ran, fewer than the " + f"{MINIMUM_CHECKS} this gate must execute", file=sys.stderr) + sys.exit(2) +sys.exit(1 if failed else 0) diff --git a/itest/mcp.py b/itest/mcp.py new file mode 100644 index 0000000..782f257 --- /dev/null +++ b/itest/mcp.py @@ -0,0 +1,47 @@ +import json, urllib.request, urllib.error, base64, itertools + +BASE = "http://127.0.0.1:8099" +_ids = itertools.count(1) + +ACCOUNTS = { + "root": ("root", "root"), + "owner1": ("owner1", "Test-pass-1"), + "devuser": ("devuser", "Test-pass-2"), + "guestuser": ("guestuser", "Test-pass-3"), + "outsider": ("outsider", "Test-pass-4"), +} + +def rpc(who, method, params=None, creds=None): + """One JSON-RPC call to /plugin-mcp/ as `who`. Returns (http_status, body).""" + user, pw = creds if creds else ACCOUNTS[who] + payload = {"jsonrpc": "2.0", "id": next(_ids), "method": method} + if params is not None: + payload["params"] = params + req = urllib.request.Request(BASE + "/plugin-mcp/", data=json.dumps(payload).encode(), method="POST") + req.add_header("Content-Type", "application/json") + req.add_header("Authorization", "Basic " + base64.b64encode(f"{user}:{pw}".encode()).decode()) + try: + with urllib.request.urlopen(req) as r: + return r.status, json.loads(r.read().decode()) + except urllib.error.HTTPError as e: + raw = e.read().decode(errors="replace") + try: + return e.code, json.loads(raw) + except Exception: + return e.code, raw[:400] + +def call(who, tool, args, creds=None): + """tools/call. Returns ('ok', parsed-payload) or ('error', {code,message}).""" + st, body = rpc(who, "tools/call", {"name": tool, "arguments": args}, creds=creds) + if isinstance(body, dict) and "error" in body: + return "error", body["error"] + if isinstance(body, dict) and "result" in body: + res = body["result"] + if isinstance(res, dict) and res.get("content"): + txt = res["content"][0].get("text", "") + try: + return "ok", json.loads(txt) + except Exception: + return "ok", txt + return "ok", res + return "error", {"http": st, "body": body} diff --git a/itest/oauth_controls.py b/itest/oauth_controls.py new file mode 100644 index 0000000..2442f4a --- /dev/null +++ b/itest/oauth_controls.py @@ -0,0 +1,385 @@ +""" +The OAuth controls, run against a disposable GitBucket over HTTP. + + python3 itest/oauth_controls.py + +Nothing here calls the plugin's internals. Each control performs the flow the +way a client would and then reads GitBucket's own API to see what the server +is storing, so a plugin that answered well and did the wrong thing would fail. +""" +import json +import os +import sys +import urllib.parse + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from gb import api, Web +from harness import check, summary, verdict +from checks import GateError, require +import fixtures +import observe +from oauth_gate import (OBASE, RESOURCE, REDIRECT, ClientHost, pkce, http, as_json, + signin, consent_screen, decide, authorize, query_of, + token, redeem, refresh, revoke, tool, outcome) + +ROOT = ("root", "root") +OW = ("owner1", "Test-pass-1") + + +def issues(repo, owner="owner1"): + return observe.stored_issue_count(api, owner, repo) + + +def error_of(payload): + return payload.get("error") if isinstance(payload, dict) else None + + +def rpc_error_message(body): + err = body.get("error") if isinstance(body, dict) else None + return (err or {}).get("message", "") if isinstance(err, dict) else "" + + +def run(): + host = ClientHost() + try: + controls(host) + finally: + host.stop() + return summary("OAuth HTTP controls") + + +def controls(host): + client = host.publish("/client.json", [REDIRECT]) + other = host.publish("/other.json", [REDIRECT], name="Second Client") + + # ── A. discovery, anonymous ────────────────────────────────────────────── + st, _, body = http("GET", f"{OBASE}/.well-known/oauth-protected-resource") + pr = as_json(body) + check("A1 protected-resource metadata is anonymous", st, 200) + check("A1 names this resource", pr.get("resource"), RESOURCE) + check("A1 names its authorization server", pr.get("authorization_servers"), [OBASE]) + + st, _, body = http("GET", f"{OBASE}/.well-known/oauth-authorization-server") + asm = as_json(body) + check("A2 authorization-server metadata is anonymous", st, 200) + check("A2 issuer", asm.get("issuer"), OBASE) + check("A2 S256 only", asm.get("code_challenge_methods_supported"), ["S256"]) + check("A2 scopes", sorted(asm.get("scopes_supported") or []), ["mcp:read", "mcp:write"]) + check("A2 CIMD advertised", asm.get("client_id_metadata_document_supported"), True) + + st, headers, _ = http("POST", f"{OBASE}/plugin-mcp/", + json_body={"jsonrpc": "2.0", "id": 1, "method": "tools/list"}) + check("A3 the MCP endpoint refuses an unauthenticated call", st, 401) + check("A3 and points at its metadata", + "resource_metadata=" in headers.get("WWW-Authenticate", ""), True) + + # ── B. consent ─────────────────────────────────────────────────────────── + verifier, challenge = pkce() + st, hdrs, _ = http( + "GET", f"{OBASE}/plugin-mcp/oauth/authorize?" + urllib.parse.urlencode( + {"response_type": "code", "client_id": client, "redirect_uri": REDIRECT, + "scope": "mcp:read", "code_challenge": challenge, + "code_challenge_method": "S256"})) + location = hdrs.get("Location", "") + check("B1 an unauthenticated authorize goes to GitBucket's own sign-in", + (st, urllib.parse.urlparse(location).path), (302, "/signin")) + + jar = signin(*OW) + st, _, html = consent_screen(jar, client, REDIRECT, "mcp:read mcp:write", challenge) + check("B2 the consent screen renders", st, 200) + check("B2 names the signed-in account", "owner1" in html, True) + check("B2 names the client", "Integration Test Client" in html, True) + check("B2 lists the requested scopes", "mcp:write" in html, True) + + st, location, _ = decide(jar, html, decision="deny") + q = query_of(location) + check("B3 denial redirects with access_denied", + (st, q.get("error"), q.get("iss"), q.get("state")), + (302, ["access_denied"], [OBASE], ["st-1"])) + check("B3 and issues no code", "code" in q, False) + + st, _, html = consent_screen(jar, client, REDIRECT, "mcp:read", challenge) + require(st == 200, "the consent screen did not render for the CSRF control") + st, location, body = decide(jar, html, csrf="not-the-token") + check("B4 a wrong CSRF token is refused", st, 400) + check("B4 with no redirect", location, "") + st, location2, body2 = decide(jar, html) # resubmit, correct token + check("B5 and the pending authorization is gone afterwards", + (st, "no authorization in progress" in body2), (400, True)) + + verifier, challenge = pkce() + st, _, html = consent_screen(jar, client, REDIRECT, "mcp:read mcp:write", challenge) + st, location, _ = decide(jar, html) + q = query_of(location) + check("B6 approval redirects with a code, iss and state", + (st, len(q.get("code", [])), q.get("iss"), q.get("state")), + (302, 1, [OBASE], ["st-1"])) + code = q["code"][0] + + # ── C. code binding, redemption and replay ─────────────────────────────── + st, b = redeem(code, other, REDIRECT, verifier) + check("C1 a wrong client_id is refused", (st, error_of(b)), (400, "invalid_grant")) + st, b = redeem(code, client, "https://client.example.com/elsewhere", verifier) + check("C2 a wrong redirect_uri is refused", (st, error_of(b)), (400, "invalid_grant")) + st, b = redeem(code, client, REDIRECT, verifier, resource="https://example.com/other/") + check("C3 a wrong resource is refused", (st, error_of(b)), (400, "invalid_target")) + st, b = redeem(code, client, REDIRECT, pkce()[0]) + check("C4 a wrong code_verifier is refused", (st, error_of(b)), (400, "invalid_grant")) + + st, granted = redeem(code, client, REDIRECT, verifier) + check("C5 none of those four consumed the code", st, 200) + check("C5 the grant carries the consented scopes", granted.get("scope"), "mcp:read mcp:write") + access, refresh_token = granted.get("access_token"), granted.get("refresh_token") + require(access and refresh_token, "the token response carried no credentials") + + st, _, body = tool(access, "whoami", {}) + kind, payload = outcome(body) + check("C6 the access token acts as the consenting account", + (st, kind, payload.get("login")), (200, "ok", "owner1")) + + # A spent code is not a credential, and possessing one is not evidence. + # Revoking on replay is defensible only for a presentation that could have + # come from the legitimate client; it used to fire for any of these, so + # anyone holding a used code could end a live session. + for label, args, kw, expected in ( + ("client", (code, other, REDIRECT, verifier), {}, "invalid_grant"), + ("redirect", (code, client, "https://client.example.com/elsewhere", verifier), {}, + "invalid_grant"), + ("resource", (code, client, REDIRECT, verifier), + {"resource": "https://elsewhere.example.com/mcp/"}, "invalid_target"), + ("verifier", (code, client, REDIRECT, pkce()[0]), {}, "invalid_grant")): + st, b = redeem(*args, **kw) + check(f"C7 a wrong {label} on a spent code is refused", + (st, error_of(b)), (400, expected)) + st, _, body = tool(access, "whoami", {}) + kind, payload = outcome(body) + check("C7 and none of those four revoked the grant: the token still works", + (st, kind, payload.get("login")), (200, "ok", "owner1")) + + st, b = redeem(code, client, REDIRECT, verifier) + check("C8 a correctly bound replay is refused", (st, error_of(b)), (400, "invalid_grant")) + st, _, body = tool(access, "whoami", {}) + check("C8 and its revocation is committed: the issued token stops working", + (st, "access token" in rpc_error_message(body)), (401, True)) + + # ── D. bearer credentials ──────────────────────────────────────────────── + verifier, challenge = pkce() + code, _ = authorize(jar, client, REDIRECT, "mcp:read mcp:write", challenge) + st, granted = redeem(code, client, REDIRECT, verifier) + require(st == 200, "could not obtain a working grant for the bearer controls") + access, refresh_token = granted["access_token"], granted["refresh_token"] + + st, headers, body = tool("not-a-token", "whoami", {}) + check("D1 an unknown bearer token is refused", st, 401) + check("D1 with an invalid_token challenge", + "error=\"invalid_token\"" in headers.get("WWW-Authenticate", ""), True) + + st, _, body = http("POST", f"{OBASE}/plugin-mcp/", + headers={"Authorization": "Bearer " + access + "x"}, + json_body={"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": "whoami", "arguments": {}}}, + jar=jar) + check("D2 a bad bearer token does not fall back to the browser session", st, 401) + + st, _, body = http( + "POST", f"{OBASE}/plugin-mcp/", + headers={"Authorization": "Bearer " + access, + "X-Forwarded-Authorization": "Basic cm9vdDpyb290"}, + json_body={"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": "whoami", "arguments": {}}}) + kind, payload = outcome(as_json(body)) + check("D3 a bearer caller cannot be re-identified by another header", + payload.get("login") if kind == "ok" else kind, "owner1") + + st, body = revoke(access) + check("D4 revocation answers 200", st, 200) + st, _, body = tool(access, "whoami", {}) + check("D4 and the revoked token stops working at the next check", st, 401) + st, b = refresh(refresh_token, client) + check("D5 revoking the access token revokes its grant", + (st, error_of(b)), (400, "invalid_grant")) + + # ── E. scope enforcement, in the real dispatcher ───────────────────────── + admin = signin(*ROOT) + verifier, challenge = pkce() + code, _ = authorize(admin, client, REDIRECT, "mcp:read", challenge) + st, granted = redeem(code, client, REDIRECT, verifier) + require(st == 200, "the administrator's read-only grant did not issue") + check("E1 a read-only consent issues a read-only grant", granted.get("scope"), "mcp:read") + read_only = granted["access_token"] + + st, _, body = tool(read_only, "whoami", {}) + kind, payload = outcome(body) + check("E2 the caller is the GitBucket administrator", + (kind, payload.get("login"), payload.get("is_admin")), ("ok", "root", True)) + + before = issues("pub-all") + st, _, body = tool(read_only, "create_issue", + {"owner": "owner1", "repo": "pub-all", "title": "read-only must not write"}) + check("E3 read-only consent refuses a write tool to an administrator", st, 403) + check("E3 named as a scope failure", "insufficient_scope" in rpc_error_message(body), True) + check("E3 and nothing was stored", issues("pub-all"), before) + + st, _, body = tool(read_only, "list_issues", {"owner": "owner1", "repo": "pub-all"}) + check("E4 the same grant still reads", outcome(body)[0], "ok") + + # Adequate scope does not override GitBucket's own permission checks. + out = signin("outsider", "Test-pass-4") + verifier, challenge = pkce() + code, _ = authorize(out, client, REDIRECT, "mcp:read mcp:write", challenge) + st, granted = redeem(code, client, REDIRECT, verifier) + require(st == 200, "the outsider's grant did not issue") + outsider = granted["access_token"] + + before = issues("priv-private") + st, _, body = tool(outsider, "create_issue", + {"owner": "owner1", "repo": "priv-private", "title": "no access"}) + kind, payload = outcome(body) + check("E5 write scope does not grant repository access", + verdict(kind, payload), "not-found") + check("E5 and nothing was stored", issues("priv-private"), before) + + before = issues("pub-disable") + st, _, body = tool(outsider, "create_issue", + {"owner": "owner1", "repo": "pub-disable", "title": "issues are off"}) + kind, payload = outcome(body) + check("E6 write scope does not override the repository's issue setting", + verdict(kind, payload), "forbidden") + check("E6 and nothing was stored", issues("pub-disable"), before) + + # A properly scoped, properly permitted write does land. + verifier, challenge = pkce() + code, _ = authorize(jar, client, REDIRECT, "mcp:read mcp:write", challenge) + st, granted = redeem(code, client, REDIRECT, verifier) + require(st == 200, "the owner's write grant did not issue") + writer, writer_refresh = granted["access_token"], granted["refresh_token"] + + before = issues("pub-all") + st, _, body = tool(writer, "create_issue", + {"owner": "owner1", "repo": "pub-all", "title": "an authorized write"}) + kind, payload = outcome(body) + check("E7 an authorized write through an OAuth caller succeeds", kind, "ok") + check("E7 and GitBucket stored it", issues("pub-all"), before + 1) + st, created = api("GET", f"/api/v3/repos/owner1/pub-all/issues/{payload.get('number')}") + check("E7 attributed to the consenting account", + (st, created.get("user", {}).get("login")), (200, "owner1")) + + # ── F. refresh rotation ────────────────────────────────────────────────── + st, b = refresh(writer_refresh, other) + check("F1 a refresh bound to another client is refused", + (st, error_of(b)), (400, "invalid_grant")) + st, rotated = refresh(writer_refresh, client) + check("F2 the binding failure did not consume the refresh token", st, 200) + check("F2 rotation returns a new refresh token", + rotated.get("refresh_token") != writer_refresh, True) + check("F2 and preserves the grant's scopes", rotated.get("scope"), "mcp:read mcp:write") + successor, successor_access = rotated["refresh_token"], rotated["access_token"] + + st, _, body = tool(successor_access, "whoami", {}) + check("F3 the rotated access token works", outcome(body)[0], "ok") + + st, b = refresh(writer_refresh, client) + check("F4 replaying the rotated token is refused", (st, error_of(b)), (400, "invalid_grant")) + st, b = refresh(successor, client) + check("F5 the replay revoked the family: the successor is dead too", + (st, error_of(b)), (400, "invalid_grant")) + st, _, body = tool(successor_access, "whoami", {}) + check("F6 and an access token from the revoked grant is refused at the next check", + st, 401) + + # ── G. account lifecycle and role changes ──────────────────────────────── + dev = signin("devuser", "Test-pass-2") + verifier, challenge = pkce() + code, _ = authorize(dev, client, REDIRECT, "mcp:read mcp:write", challenge) + st, granted = redeem(code, client, REDIRECT, verifier) + require(st == 200, "devuser's grant did not issue") + dev_token = granted["access_token"] + + before = issues("pub-public") + st, _, body = tool(dev_token, "create_issue", + {"owner": "owner1", "repo": "pub-public", "title": "developer write"}) + check("G1 a developer may write", outcome(body)[0], "ok") + check("G1 and it was stored", issues("pub-public"), before + 1) + + st, b = api("DELETE", "/api/v3/repos/owner1/priv-all/collaborators/devuser", auth=OW) + require(st in (200, 204), f"could not remove devuser's role: {st} {b}") + st, b = api("PUT", "/api/v3/repos/owner1/priv-all/collaborators/devuser", + {"permission": "pull"}, auth=OW) + require(st in (200, 201, 204), f"could not demote devuser: {st} {b}") + st, cols = api("GET", "/api/v3/repos/owner1/priv-all/collaborators", auth=OW) + require(any(c["login"] == "devuser" for c in cols), + "devuser is no longer a collaborator, so the control would pass for the wrong reason") + before = issues("priv-all") + st, _, body = tool(dev_token, "create_issue", + {"owner": "owner1", "repo": "priv-all", "title": "after demotion"}) + kind, payload = outcome(body) + check("G2 a role change takes effect for an existing token", + verdict(kind, payload), "forbidden") + check("G2 and nothing was stored", issues("priv-all"), before) + + disable_account("devuser") + st, _, body = tool(dev_token, "whoami", {}) + check("G3 a removed account's outstanding token stops working", st, 401) + + # ── H. the production client-metadata fetch path ───────────────────────── + jar2 = signin(*OW) + _, challenge = pkce() + + st, _, body = consent_screen(jar2, "http://10.0.0.17/client.json", REDIRECT, + "mcp:read", challenge) + check("H1 a plain-http client id on a private address is refused", + (st, "https" in body), (400, True)) + + st, _, body = consent_screen(jar2, "https://10.0.0.17/client.json", REDIRECT, + "mcp:read", challenge) + check("H2 an https client id on a private address is refused", + (st, "non-public address" in body), (400, True)) + + st, _, body = consent_screen(jar2, "https://169.254.169.254/client.json", REDIRECT, + "mcp:read", challenge) + check("H3 the link-local metadata address is refused", + (st, "non-public address" in body), (400, True)) + + moved = host.publish_redirect("/moved.json", host.url("/client.json")) + st, _, body = consent_screen(jar2, moved, REDIRECT, "mcp:read", challenge) + check("H4 the production fetch refuses a redirecting metadata document", + (st, "must not redirect" in body), (400, True)) + + missing = host.url("/absent.json") + st, _, body = consent_screen(jar2, missing, REDIRECT, "mcp:read", challenge) + check("H5 a missing metadata document is unreachable, not a client", + (st, "returned HTTP 404" in body), (400, True)) + + lying = host.publish("/lying.json", [REDIRECT], declared="https://elsewhere.example.com/c") + st, _, body = consent_screen(jar2, lying, REDIRECT, "mcp:read", challenge) + check("H6 a document declaring another client_id is refused", + (st, "declares a different client_id" in body), (400, True)) + + narrow = host.publish("/narrow.json", ["https://client.example.com/only-here"]) + st, _, body = consent_screen(jar2, narrow, REDIRECT, "mcp:read", challenge) + check("H7 an unregistered redirect_uri is refused before any consent", + (st, "not registered" in body), (400, True)) + + +def disable_account(login): + """Mark an account removed through GitBucket's own administration form.""" + web = Web() + st, _, cookies = web.signin("root", "root") + require(st == 200 and cookies, "root could not sign in to disable an account") + st, body = web.post(f"/admin/users/{login}/_edituser", + {"userName": login, "fullName": login, + "mailAddress": f"{login}@example.com", + "description": "", "url": "", "removed": "true"}) + require(st in (200, 302), f"could not disable {login}: {st} {body}") + st, account = api("GET", f"/api/v3/users/{login}") + require(st == 404 or (isinstance(account, dict) and account.get("type") == "removed"), + f"{login} does not read back as removed: {st} {account}") + + +if __name__ == "__main__": + fixtures.build() + try: + failures = run() + finally: + fixtures.cleanup() + sys.exit(1 if failures else 0) diff --git a/itest/oauth_gate.py b/itest/oauth_gate.py new file mode 100644 index 0000000..b92a1ea --- /dev/null +++ b/itest/oauth_gate.py @@ -0,0 +1,251 @@ +""" +The OAuth flow, driven through the production HTTP endpoints. + +Every control here goes over the wire to a running GitBucket with the plugin +installed: discovery, the consent screen, the token endpoint, Bearer +authentication and the real MCP tool dispatcher. Nothing is reimplemented, +and the independent observations go to GitBucket's own REST API rather than +to the plugin's answers. + +Committed effects are observed the way they matter: by asking again. After a +refusal that must change nothing, the lawful operation is performed next and +has to succeed; after a replay that must revoke, a fresh authorization check +has to refuse. That is a stronger reading than inspecting the table, because +it is the property the server actually has to provide, and it is taken on a +connection the first request did not use. + +The instance under test runs with `gitbucket.mcp.oauth.allowLoopbackClients` +on, which is the only way a client metadata document can be served to it from +this machine. The refusal cases below exercise the fence in its default state +as well, through client ids the escape does not cover. + +Note the two host names. The consent screen's form action is built from the +configured base URL, so the browser session must live on that host; the REST +control calls use the address `gb` was configured with. They are the same +server, and keeping them apart is what makes the cookie jar behave. +""" +import base64 +import hashlib +from http import cookiejar as _cookiejar +from http import server as _httpserver +import json +import os +import re +import secrets +import sys +import threading +import urllib.error +import urllib.parse +import urllib.request + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from gb import api, BASE +from mcp import ACCOUNTS +from harness import check, summary, verdict +from checks import GateError, require +import fixtures +import observe + +OBASE = "http://localhost:8099" # must equal the configured base URL +RESOURCE = f"{OBASE}/plugin-mcp/" +REDIRECT = "https://client.example.com/connector/oauth/cb" + + +# ── a client metadata document the server can fetch ───────────────────────── + +class _Handler(_httpserver.BaseHTTPRequestHandler): + documents = {} + + def do_GET(self): + entry = self.documents.get(self.path) + if entry is None: + self.send_response(404) + self.end_headers() + return + if isinstance(entry, str): # a redirect target + self.send_response(302) + self.send_header("Location", entry) + self.end_headers() + return + body = json.dumps(entry).encode() + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def log_message(self, *args): + pass + + +class ClientHost: + def __init__(self): + self.server = _httpserver.HTTPServer(("127.0.0.1", 0), _Handler) + self.port = self.server.server_address[1] + threading.Thread(target=self.server.serve_forever, daemon=True).start() + + def url(self, path): + return f"http://127.0.0.1:{self.port}{path}" + + def publish(self, path, redirect_uris, name="Integration Test Client", declared=None): + url = self.url(path) + _Handler.documents[path] = { + "client_id": declared if declared is not None else url, + "client_name": name, + "redirect_uris": list(redirect_uris)} + return url + + def publish_redirect(self, path, to): + _Handler.documents[path] = to + return self.url(path) + + def stop(self): + self.server.shutdown() + + +def pkce(): + verifier = base64.urlsafe_b64encode(secrets.token_bytes(48)).decode().rstrip("=") + challenge = base64.urlsafe_b64encode( + hashlib.sha256(verifier.encode("ascii")).digest()).decode().rstrip("=") + return verifier, challenge + + +# ── raw HTTP, so responses are inspected rather than followed ─────────────── + +class _NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, *a, **kw): + return None + + +def http(method, url, data=None, headers=None, jar=None, json_body=None): + body = None + hdrs = dict(headers or {}) + if json_body is not None: + body = json.dumps(json_body).encode() + hdrs["Content-Type"] = "application/json" + elif data is not None: + body = urllib.parse.urlencode(data).encode() + hdrs["Content-Type"] = "application/x-www-form-urlencoded" + req = urllib.request.Request(url, data=body, method=method) + for k, v in hdrs.items(): + req.add_header(k, v) + handlers = [_NoRedirect()] + if jar is not None: + handlers.append(urllib.request.HTTPCookieProcessor(jar)) + opener = urllib.request.build_opener(*handlers) + try: + with opener.open(req) as r: + return r.status, dict(r.headers), r.read().decode(errors="replace") + except urllib.error.HTTPError as e: + return e.code, dict(e.headers), e.read().decode(errors="replace") + except urllib.error.URLError as e: + raise GateError(f"{method} {url}: {e}") + + +def as_json(body): + try: + return json.loads(body) + except Exception: + return {"raw": body[:300]} + + +def signin(login, password): + """A real browser session on the configured host.""" + jar = _cookiejar.CookieJar() + status, _, _ = http("POST", f"{OBASE}/signin", + data={"userName": login, "password": password}, jar=jar) + require(status in (200, 302) and len(jar) > 0, f"{login} could not sign in ({status})") + return jar + + +# ── the flow ──────────────────────────────────────────────────────────────── + +def consent_screen(jar, client_id, redirect_uri, scope, challenge, state="st-1", + resource=RESOURCE, method="S256", response_type="code"): + query = {"response_type": response_type, "client_id": client_id, + "redirect_uri": redirect_uri, "scope": scope, + "code_challenge": challenge, "code_challenge_method": method, + "state": state} + if resource: + query["resource"] = resource + status, headers, body = http( + "GET", f"{OBASE}/plugin-mcp/oauth/authorize?" + urllib.parse.urlencode(query), + jar=jar) + return status, headers.get("Location", ""), body + + +def decide(jar, html, decision="allow", csrf=None): + action = re.search(r'
0, True) + check("busy has a nonzero pr count", entries["busy"]["pr_count"] > 0, True) + check("quiet is legitimately zero", (entries["quiet"]["issue_count"], + entries["quiet"]["pr_count"]), (0, 0)) + check("the two repositories do not report the same counts", + entries["busy"]["issue_count"] == entries["quiet"]["issue_count"], False) + + print("\n## 3. closed issues and pull requests are excluded") + status, all_issues = api("GET", "/api/v3/repos/owner1/busy/issues?state=all") + require(status == 200 and isinstance(all_issues, list), "cannot read all issues") + check("GitBucket holds more issues than the open count", + len(all_issues) > entries["busy"]["issue_count"], True) + check("the pull request is not counted as an issue", + entries["busy"]["issue_count"], native_open("owner1", "busy", "issue")) + + print("\n## 4. the listing agrees with the detail of the same repository") + for name in ("busy", "quiet"): + kind, d = detail("owner1", name) + require(kind == "ok", f"get_repository failed for {name}: {d}") + e = entries[name] + check(f"{name}: list and detail agree on issue_count", + e["issue_count"], d["issue_count"]) + check(f"{name}: list and detail agree on pr_count", e["pr_count"], d["pr_count"]) + check(f"{name}: list and detail agree on fork_count", e["fork_count"], d["fork_count"]) + check(f"{name}: list and detail agree on is_fork", e["is_fork"], d["is_fork"]) + + print("\n## 5. the fork filter acts on the fork relationship") + forks, _ = listed("devuser", who="devuser") + fork_names = [n for n, e in forks.items() if e["is_fork"]] + check("the forked repository is visible to its owner and marked a fork", + len(fork_names) >= 1, True) + for n in fork_names: + check(f"{n}: GitBucket agrees it is a fork", native_repo("devuser", n)["fork"], True) + + omitted, _ = listed("devuser", who="devuser") + explicit_false, _ = listed("devuser", who="devuser", without_forked=False) + excluded, _ = listed("devuser", who="devuser", without_forked=True) + check("omitted and false behave the same", sorted(omitted), sorted(explicit_false)) + check("true removes exactly the forks", + sorted(excluded), sorted(n for n in omitted if not omitted[n]["is_fork"])) + check("and leaves the originals", all(not excluded[n]["is_fork"] for n in excluded), True) + + print("\n## 6. the fork filter does not disturb the counters") + busy_excluded, _ = listed("owner1", without_forked=True) + check("busy still reports its real issue count under without_forked", + busy_excluded["busy"]["issue_count"], entries["busy"]["issue_count"]) + check("and no negative placeholder appears as a fork count", + all(e["fork_count"] >= 0 for e in busy_excluded.values()), True) + + print("\n## 7. visibility is unchanged by enrichment") + for who, sees_private in (("outsider", False), ("devuser", False), ("root", True)): + seen, _ = listed("owner1", who=who) + check(f"{who} sees the public repositories", "busy" in seen, True) + check(f"{who} sees the private repository: {sees_private}", + "secret" in seen, sees_private) + owner_view, _ = listed("owner1", who="owner1") + check("the owner sees their own private repository", "secret" in owner_view, True) + kind, _ = detail("owner1", "secret", who="outsider") + check("and an outsider is refused its detail", kind, "error") + + print("\n## 8. the payload says what the counters mean") + check("the listing documents its issue counter", + payload.get("issue_count_semantics"), "open issues, excluding pull requests") + check("the listing documents its pull request counter", + payload.get("pr_count_semantics"), "open pull requests") + check("the listing documents the fork counter", + payload.get("fork_count_semantics"), + "forks of this repository's origin; not a flag that this repository is a fork") + + failed = summary("REPOSITORY LIST GATE") + ran = len(__import__("harness").RESULTS) + if ran < 35: + raise GateError(f"only {ran} checks executed; this gate has no result below 35") + return 1 if failed else 0 + + +if __name__ == "__main__": + try: + sys.exit(run()) + except GateError as exc: + print(f"\nGATE ABORTED: {exc}", file=sys.stderr) + print("No result may be read from this run.", file=sys.stderr) + sys.exit(2) diff --git a/itest/resource_gate.py b/itest/resource_gate.py new file mode 100644 index 0000000..1a176a1 --- /dev/null +++ b/itest/resource_gate.py @@ -0,0 +1,270 @@ +""" +Audience binding, observed across a change of configured resource. + + python3 itest/resource_gate.py --war --candidate --home + +A token says which resource it was issued for, and the store records it. That +is only a fact in a table until something compares it with the resource this +server actually is. The comparison has to happen at the point of use, because +the token outlives the request that created it: a deployment that is +reconfigured, or a token minted for a neighbouring deployment, both arrive +here as a perfectly valid, unexpired credential for somewhere else. + +So this gate does the one thing a single-instance test cannot: it issues a +grant while the server calls itself A, restarts the same server as B, and +presents the credential again. Nothing is revoked in between and no clock +moves; the only thing that changed is which resource the server is. + +The two names are the same machine. That is deliberate — it isolates the +audience check from everything else that might refuse a request. +""" +import argparse +import base64 +import json +import os +import sys +import urllib.error +import urllib.request + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import oauth_gate +import upgrade_gate +from checks import GateError, require +from harness import check, summary + +PORT = 8099 +NAME_A = "localhost" +NAME_B = "127.0.0.1" +ADMIN = ("root", "root") +REPO = "audience" + + +def base_url(name): + return f"http://{name}:{PORT}" + + +def resource_of(name): + return f"{base_url(name)}/plugin-mcp/" + + +def api(method, path, body=None, creds=ADMIN): + data = json.dumps(body).encode() if body is not None else None + req = urllib.request.Request(f"http://127.0.0.1:{PORT}{path}", data=data, method=method) + req.add_header("Content-Type", "application/json") + req.add_header("Authorization", "Basic " + + base64.b64encode(f"{creds[0]}:{creds[1]}".encode()).decode()) + try: + with urllib.request.urlopen(req, timeout=30) as r: + raw = r.read().decode(errors="replace") + return r.status, (json.loads(raw) if raw.strip() else None) + except urllib.error.HTTPError as e: + raw = e.read().decode(errors="replace") + try: + return e.code, json.loads(raw) + except Exception: + return e.code, raw[:300] + + +def issue_count(): + status, body = api("GET", f"/api/v3/repos/root/{REPO}/issues?state=all") + require(status == 200 and isinstance(body, list), + f"cannot read the stored issues ({status}); this gate has no witness") + return len(body) + + +def authorize_under(name, client_id, scope="mcp:read mcp:write"): + """A full consent walk against the server as it is currently configured.""" + oauth_gate.OBASE = base_url(name) + verifier, challenge = oauth_gate.pkce() + jar = oauth_gate.signin(*ADMIN) + code, _ = oauth_gate.authorize(jar, client_id, oauth_gate.REDIRECT, scope, challenge) + status, payload = oauth_gate.redeem(code, client_id, oauth_gate.REDIRECT, verifier, + resource=resource_of(name)) + require(status == 200 and "access_token" in payload, + f"the token endpoint answered {status}: {payload}") + return payload + + +# The documented refusals. RFC 6749 §5.2 gives the token endpoint one shape +# for a rejected grant: HTTP 400 with an `error` code, and 401 when the client +# itself was not accepted. Anything else — a 500, a 404 from a missing route, +# a body that is not the documented object — is the server failing to answer, +# and a failure to answer is not a refusal. Accepting `status >= 400` as proof +# of authorization meant a crashed endpoint read as a correct denial. +TOKEN_REFUSAL_STATUSES = (400, 401) +TOKEN_REFUSAL_ERRORS = { + "invalid_request", "invalid_client", "invalid_grant", + "unauthorized_client", "unsupported_grant_type", "invalid_scope", + "invalid_target", +} + + +# What each refresh scenario is entitled to see. `OAuthEndpoints.refreshFailure` +# answers `400 invalid_grant` for every rotation failure, deliberately, so a +# refusal cannot disclose which binding was wrong. That uniformity is a +# production property and stays; what it means for this gate is that the only +# response proving the resource binding was consulted is that exact pair. +REFRESH_REFUSAL = (400, "invalid_grant") + + +def refused_grant(status, payload, what, expected=REFRESH_REFUSAL): + """ + Assert the refusal this scenario is entitled to, or abort. + + Checking only that the status was >= 400, or only that it was some + documented refusal, is not enough. An `invalid_client` says the client was + not accepted; an `invalid_request` says the request was malformed. Neither + is evidence that the resource binding was examined, and a scenario that + accepts them reports a restriction it never observed. + """ + want_status, want_error = expected + if status not in TOKEN_REFUSAL_STATUSES: + raise GateError( + f"{what}: expected a token-endpoint refusal {TOKEN_REFUSAL_STATUSES}, got " + f"HTTP {status} with {payload!r}. A server failure is not a refusal and " + f"this gate cannot read authorization from it.") + if not isinstance(payload, dict): + raise GateError( + f"{what}: HTTP {status} carried {payload!r}, not an OAuth error object.") + error = payload.get("error") + if error not in TOKEN_REFUSAL_ERRORS: + raise GateError( + f"{what}: HTTP {status} carried error={error!r}, which is not one of the " + f"documented token-endpoint error codes.") + if (status, error) != (want_status, want_error): + raise GateError( + f"{what}: expected {want_status} {want_error!r}, got {status} {error!r}. " + f"That is a refusal, but not the one this scenario establishes, so it is " + f"no evidence that the resource binding was checked.") + return (status, error) + + +def tool_call(name, token, tool, arguments): + oauth_gate.OBASE = base_url(name) + status, headers, payload = oauth_gate.tool(token, tool, arguments) + return status, headers, oauth_gate.outcome(payload) + + +def run(war, candidate, home): + host = oauth_gate.ClientHost() + started = [] + + def boot(name): + gb = upgrade_gate.Instance(war, home) + started.append(gb) + # Instance builds its command from upgrade_gate.OBASE. + upgrade_gate.OBASE = base_url(name) + gb.start() + return gb + + try: + client_id = host.publish("/client.json", [oauth_gate.REDIRECT], name="Audience gate") + + # ── A: the server calls itself localhost ────────────────────────── + print(f"## 1. issued while the resource is {resource_of(NAME_A)}") + gb = upgrade_gate.Instance(war, home) + started.append(gb) + gb.install(candidate, "gitbucket-mcp-plugin-candidate.jar") + upgrade_gate.OBASE = base_url(NAME_A) + gb.start() + + status, _ = api("POST", "/api/v3/user/repos", + {"name": REPO, "description": "audience fixture", + "private": False, "auto_init": True}) + require(status in (200, 201), f"could not create the fixture repository ({status})") + + grant = authorize_under(NAME_A, client_id) + access, refresh = grant["access_token"], grant.get("refresh_token") + require(refresh, "the grant carries no refresh token; the gate needs one") + + st, _, (kind, _) = tool_call(NAME_A, access, "whoami", {}) + check("the token works for the resource it was issued for", (st, kind), (200, "ok")) + before = issue_count() + st, _, (kind, _) = tool_call(NAME_A, access, "create_issue", + {"owner": "root", "repo": REPO, "title": "under A"}) + check("and a write it was consented for succeeds", kind, "ok") + check("which the repository actually stored", issue_count(), before + 1) + gb.stop() + + # ── B: the same server, a different configured resource ─────────── + print(f"\n## 2. the same server restarted as {resource_of(NAME_B)}") + gb = boot(NAME_B) + check("the server is up under the new resource", + api("GET", "/api/v3/repos/root/" + REPO)[0], 200) + check("its metadata now names the new resource", + json.loads(urllib.request.urlopen( + f"http://127.0.0.1:{PORT}/.well-known/oauth-protected-resource", + timeout=10).read().decode()).get("resource"), + resource_of(NAME_B)) + + witness = issue_count() + st, headers, (kind, payload) = tool_call(NAME_B, access, "whoami", {}) + check("a valid, unexpired token for another resource is refused", kind, "error") + check("refused as an authentication failure, not a server error", st, 401) + check("and the challenge names an invalid token", + "invalid_token" in headers.get("WWW-Authenticate", ""), True) + + st, _, (kind, _) = tool_call(NAME_B, access, "create_issue", + {"owner": "root", "repo": REPO, "title": "must not exist"}) + check("a write with that token is refused too", kind, "error") + check("and nothing was stored", issue_count(), witness) + + st, payload = oauth_gate.token(grant_type="refresh_token", refresh_token=refresh, + client_id=client_id) + check("its refresh token is refused under the other resource", + refused_grant(st, payload, "refresh under the other resource"), + REFRESH_REFUSAL) + gb.stop() + + # ── A again: nothing was destroyed by being refused ─────────────── + print(f"\n## 3. restored to {resource_of(NAME_A)}") + gb = boot(NAME_A) + st, _, (kind, _) = tool_call(NAME_A, access, "whoami", {}) + check("the token works again once the resource matches", (st, kind), (200, "ok")) + + oauth_gate.OBASE = base_url(NAME_A) + st, payload = oauth_gate.token(grant_type="refresh_token", refresh_token=refresh, + client_id=client_id, resource="https://elsewhere.example.com/mcp/") + check("a refresh naming the wrong resource is refused", + refused_grant(st, payload, "refresh naming the wrong resource"), + REFRESH_REFUSAL) + st, payload = oauth_gate.token(grant_type="refresh_token", refresh_token=refresh, + client_id=client_id, resource=resource_of(NAME_A)) + check("and the lawful refresh still works, so it was not consumed", + st == 200 and "access_token" in payload, True) + rotated = payload.get("access_token") + st, _, (kind, _) = tool_call(NAME_A, rotated, "whoami", {}) + check("the rotated token works", (st, kind), (200, "ok")) + gb.stop() + finally: + host.stop() + for gb in started: + try: + gb.stop() + except Exception: + pass + + failed = summary("RESOURCE BINDING GATE") + ran = len(__import__("harness").RESULTS) + if ran < 15: + raise GateError(f"only {ran} checks executed; this gate has no result below 15") + return 1 if failed else 0 + + +if __name__ == "__main__": + ap = argparse.ArgumentParser() + ap.add_argument("--war", required=True) + ap.add_argument("--candidate", required=True) + ap.add_argument("--home", required=True) + a = ap.parse_args() + for p in (a.war, a.candidate): + require(os.path.isfile(p), f"not a readable file: {p}") + require(not os.path.exists(a.home) or not os.listdir(a.home), + f"{a.home} is not empty; this gate needs a blank GITBUCKET_HOME") + os.makedirs(a.home, exist_ok=True) + try: + sys.exit(run(a.war, a.candidate, a.home)) + except GateError as exc: + print(f"\nGATE ABORTED: {exc}", file=sys.stderr) + print("No result may be read from this run.", file=sys.stderr) + sys.exit(2) diff --git a/itest/selftest.py b/itest/selftest.py new file mode 100644 index 0000000..1ace092 --- /dev/null +++ b/itest/selftest.py @@ -0,0 +1,335 @@ +""" +Negative controls for the gate's own guards. No server, no network. + +The gate's two P2 defects were skips, not wrong answers: a precondition that +failed quietly and a comparison whose input went missing. A green run proved +nothing about either, because the skipped case never reported anything. These +controls assert the opposite property directly — that each guard *raises* on +the input that used to be tolerated. + +Run with `python3 itest/selftest.py`. Exit 0 means every guard fires. +""" +import os +import sys + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from checks import (GateError, require, require_ok, native_decision, + require_same_set, same_instant, java_date_to_epoch, iso_to_epoch, + require_iso_utc) +from observe import stored_issue_count, observe_issue_write + +RESULTS = [] + + +def fires(name, fn, expect_fragment=None): + """The guard must raise GateError, and say why.""" + try: + fn() + except GateError as e: + ok = expect_fragment is None or expect_fragment in str(e) + RESULTS.append((ok, name, str(e)[:140])) + print(("PASS " if ok else "FAIL ") + name) + if not ok: + print(f" message did not mention {expect_fragment!r}: {e}") + return + RESULTS.append((False, name, "did not raise")) + print("FAIL " + name + "\n the guard did not fire; this is the skip the gate was corrected for") + + +def allows(name, fn, want=None): + """The guard must not raise on a legitimate input.""" + try: + got = fn() + except GateError as e: + RESULTS.append((False, name, str(e)[:140])) + print("FAIL " + name + f"\n raised on a legitimate input: {e}") + return + ok = want is None or got == want + RESULTS.append((ok, name, repr(got)[:140])) + print(("PASS " if ok else "FAIL ") + name) + if not ok: + print(f" got {got!r}, want {want!r}") + + +print("## 1. a failed precondition must stop the run, not be skipped") +# Defect 1: fixtures.py ignored exit statuses, so a repository created without +# its collaborators still produced a green run. +fires("a failed repository creation aborts", + lambda: require_ok(422, {"message": "already exists"}, "create repository pub-all"), + "create repository pub-all") +fires("a failed collaborator addition aborts", + lambda: require_ok(404, {"message": "Not Found"}, "add collaborator devuser to pub-all"), + "got 404") +fires("a failed removal of the fork's inherited roles aborts", + lambda: require_ok(500, "boom", "remove inherited collaborator devuser from the fork"), + "inherited collaborator") +fires("an unmet invariant aborts", + lambda: require(False, "devuser is still a collaborator on the fork"), + "still a collaborator") +allows("a successful creation is allowed through", + lambda: require_ok(200, {"number": 7}, "create pull request"), {"number": 7}) +allows("204 counts as success for a delete", + lambda: require_ok(204, b"", "remove collaborator"), b"") + +print("\n## 2. the web-merge route may not be optional") +# Defect 2a: creating the web-merge pull request inline meant a creation +# failure skipped the whole route. The pull request is now a fixture, and this +# is the guard that made it one. +fires("a web-merge pull request that cannot be created aborts", + lambda: require_ok(500, {"message": "internal"}, "create pull request web_merge"), + "web_merge") +fires("a web merge that does not go through aborts", + lambda: require_ok(400, "not mergeable", "merge #4 through GitBucket's web route"), + "web route") +fires("a web merge GitBucket does not consider merged aborts", + lambda: require(False, "#4: the web merge route did not mark it merged"), + "did not mark it merged") + +print("\n## 3. a set comparison may not fall back to the intersection") +# Defect 2b: the comparison iterated GitBucket's list and dropped any number +# the gateway had not returned. +fires("a gateway list that loses every pull request aborts", + lambda: require_same_set("list_pull_requests", set(), {1, 2, 3, 4}), + "missing from the gateway: [1, 2, 3, 4]") +fires("a gateway list that loses one pull request aborts", + lambda: require_same_set("list_pull_requests", {1, 2, 3}, {1, 2, 3, 4}), + "missing from the gateway: [4]") +fires("a gateway list with an extra pull request aborts", + lambda: require_same_set("list_pull_requests", {1, 2, 3, 4, 9}, {1, 2, 3, 4}), + "not in GitBucket's answer: [9]") +fires("two empty sets abort rather than compare nothing", + lambda: require_same_set("list_pull_requests", set(), set()), + "nothing to compare") +allows("equal sets are allowed through", + lambda: require_same_set("list_pull_requests", {4, 1, 2, 3}, {1, 2, 3, 4}), [1, 2, 3, 4]) + +print("\n## 4. a server error is not an authorization verdict") +# Defect 2c: a 500 from GitBucket's own issue route was read as "refused", so +# a broken control agreed with whatever the gateway said. +for code in (500, 502, 503, 404, 400, 302): + fires(f"HTTP {code} from GitBucket's own route aborts instead of counting as a refusal", + lambda c=code: native_decision(c, "GitBucket's own create-issue route for priv-all/guestuser"), + f"HTTP {code}") +allows("200 is an allow", lambda: native_decision(200, "x"), "allowed") +allows("401 is a refusal", lambda: native_decision(401, "x"), "denied") +allows("403 is a refusal", lambda: native_decision(403, "x"), "denied") + +print("\n## 5. merged_at must be an instant, not a non-empty string") +# The review's item 4: comparing truthiness proved only that something was +# published. +allows("the same moment in both formats compares equal", + lambda: same_instant("Thu Oct 23 11:59:31 UTC 2026", "2026-10-23T11:59:31Z", "merged_at"), True) +allows("a one-second difference is tolerated", + lambda: same_instant("Thu Oct 23 11:59:32 UTC 2026", "2026-10-23T11:59:31Z", "merged_at"), True) +allows("a different moment compares unequal rather than passing", + lambda: same_instant("Thu Oct 23 12:04:31 UTC 2026", "2026-10-23T11:59:31Z", "merged_at"), False) +allows("a day out compares unequal", + lambda: same_instant("Fri Oct 24 11:59:31 UTC 2026", "2026-10-23T11:59:31Z", "merged_at"), False) +fires("an empty gateway timestamp aborts instead of comparing as falsy", + lambda: same_instant("", "2026-10-23T11:59:31Z", "merged_at"), "cannot read") +fires("a missing gateway timestamp aborts", + lambda: same_instant(None, "2026-10-23T11:59:31Z", "merged_at"), "cannot read") +fires("an unparseable gateway timestamp aborts", + lambda: same_instant("yesterday", "2026-10-23T11:59:31Z", "merged_at"), "Java Date") +fires("a timestamp in an unknown zone aborts rather than guessing an offset", + lambda: java_date_to_epoch("Thu Oct 23 11:59:31 PST 2026", "merged_at"), "zone"), +fires("an unparseable GitBucket timestamp aborts", + lambda: iso_to_epoch("n/a", "merged_at"), "ISO 8601") + +print("\n## 6. the gateway's own timestamps must be machine-readable") +allows("an ISO 8601 UTC instant is accepted", + lambda: require_iso_utc("2026-10-23T12:38:41Z", "merged_at"), 1792759121) +fires("a Java Date string is refused as a gateway timestamp", + lambda: require_iso_utc("Fri Oct 23 15:38:41 EEST 2026", "merged_at"), "not an ISO 8601") +fires("an instant with an offset instead of Z is refused", + lambda: require_iso_utc("2026-10-23T15:38:41+03:00", "merged_at"), "not an ISO 8601") +fires("a date without a time is refused", + lambda: require_iso_utc("2026-10-23", "merged_at"), "not an ISO 8601") +fires("an empty timestamp is refused", + lambda: require_iso_utc("", "merged_at"), "not an ISO 8601") +allows("ISO against ISO compares as the same instant", + lambda: same_instant("2026-10-23T12:38:41Z", "2026-10-23T12:38:41Z", "merged_at"), True) +allows("ISO against a different ISO compares unequal", + lambda: same_instant("2026-10-23T12:38:41Z", "2026-10-23T12:40:41Z", "merged_at"), False) + +print("\n## 7. an unavailable storage witness is not a count") +# The defect: the witness was `len(r) if isinstance(r, list) else -1`, so two +# failed reads cancelled into a delta of zero and a refused write was reported +# as having stored nothing while the gate had observed nothing at all. +# These drive the real `observe.stored_issue_count`, not a reimplementation. + +def api_double(status, body): + """GitBucket's REST API, doubled. Records every call it is given.""" + calls = [] + def fn(method, path, payload=None, auth=None): + calls.append((method, path)) + return (status, body) + fn.calls = calls + return fn + +allows("a successful empty list is a lawful count of zero", + lambda: stored_issue_count(api_double(200, []), "owner1", "pub-disable"), 0) +allows("a successful populated list counts its rows", + lambda: stored_issue_count(api_double(200, [{"number": 1}, {"number": 2}]), "owner1", "pub-all"), 2) +for status in (500, 502, 503, 401, 404, 302, 204): + fires(f"HTTP {status} on the stored-issue read aborts instead of becoming a count", + lambda s=status: stored_issue_count(api_double(s, {"message": "x"}), "owner1", "pub-disable"), + "read the stored issues of owner1/pub-disable") +fires("HTTP 200 with an object instead of a list aborts", + lambda: stored_issue_count(api_double(200, {"message": "Not Found"}), "owner1", "pub-disable"), + "not a JSON list") +fires("HTTP 200 with a string body aborts", + lambda: stored_issue_count(api_double(200, "oops"), "owner1", "pub-disable"), + "not a JSON list") +fires("HTTP 200 with a null body aborts", + lambda: stored_issue_count(api_double(200, None), "owner1", "pub-disable"), + "not a JSON list") + +print("\n## 8. the counterexample, through the real call path") +# The case this section exists for: the stored-issue GET answers 500 with an +# error object, GitBucket's own POST answers the expected 401, and the gateway +# records an unintended insert and then returns its policy error. With the old +# witness every one of those cases reported a pass. A test of require_ok in +# isolation could not have caught it, because the bypass was at the call +# site, so these drive the gate's real `observe_issue_write`. + +def inserting_refusal(world): + """A tool that refuses to the caller but writes anyway.""" + def operation(): + world.append("INSERT") + return "error", {"code": -2, + "message": "guestuser may not open an issue in owner1/pub-disable"} + return operation + +def one_policy_case(api_fn, world): + """Exactly what the gate's policy loop does for one case.""" + return observe_issue_write(api_fn, inserting_refusal(world), "owner1", "pub-disable") + +def scripted_api(*answers): + """An API double that answers each read in turn.""" + seq = iter(answers) + return lambda method, path, body=None, auth=None: next(seq) + +# (a) the read fails on the way in: the gate stops before the write is even +# attempted, which is better than detecting it afterwards. +for status, body, label in ((500, {"message": "Internal Server Error"}, "HTTP 500 and an error object"), + (200, {"message": "Not Found"}, "HTTP 200 and a non-list body"), + (404, [], "HTTP 404 and an empty list")): + world = [] + fires(f"an unavailable witness aborts the case before the write, answering {label}", + lambda a=status, b=body, w=world: one_policy_case(api_double(a, b), w), + "stored issues") + ok = world == [] + RESULTS.append((ok, f"...and the operation was never run ({label})", repr(world))) + print(("PASS " if ok else "FAIL ") + f"...and the operation was never run ({label})") + +# (b) the read fails only on the way out, after an unintended insert. This is +# the case the old sentinel turned into a delta of zero. +world = [] +fires("a witness that fails only after the write aborts instead of reporting delta 0", + lambda w=world: one_policy_case(scripted_api((200, []), (500, {"message": "boom"})), w), + "stored issues") +ok = world == ["INSERT"] +RESULTS.append((ok, "...and the unintended insert had in fact happened", repr(world))) +print(("PASS " if ok else "FAIL ") + "...and the unintended insert had in fact happened") + +# (c) with a working witness on both sides the same insert is visible, which is +# what makes the refusal check meaningful at all. +world = [] +kind, payload, delta = one_policy_case(scripted_api((200, []), (200, [{"number": 1}])), world) +ok = (delta == 1 and world == ["INSERT"] and kind == "error") +RESULTS.append((ok, "a working witness reports the unintended insert as delta 1", repr((kind, delta, world)))) +print(("PASS " if ok else "FAIL ") + "a working witness reports the unintended insert as delta 1") +if not ok: + print(f" got kind={kind!r} delta={delta!r} world={world!r}, want ('error', 1, ['INSERT'])") + +print("\n## 9. a lawful refusal is still reported as having written nothing") +world = [] +def refusing_tool_that_writes_nothing(): + return "error", {"code": -2, "message": "may not open an issue"} +allows("a genuine refusal with a working witness gives delta 0", + lambda: observe_issue_write( + (lambda seq=iter([(200, [{"number": 1}]), (200, [{"number": 1}])]): (lambda m, p, b=None, a=None: next(seq)))(), + refusing_tool_that_writes_nothing, "owner1", "priv-private")[2], 0) +allows("a genuine allow with a working witness gives delta 1", + lambda: observe_issue_write( + (lambda seq=iter([(200, []), (200, [{"number": 1}])]): (lambda m, p, b=None, a=None: next(seq)))(), + lambda: ("ok", {"number": 1}), "owner1", "pub-all")[2], 1) +fires("a count that falls across one operation aborts rather than reporting a negative delta", + lambda: observe_issue_write( + (lambda seq=iter([(200, [{"number": 1}, {"number": 2}]), (200, [])]): (lambda m, p, b=None, a=None: next(seq)))(), + refusing_tool_that_writes_nothing, "owner1", "priv-private"), + "fell from 2 to 0") + +# ── 10. a server failure is not an authorization refusal ────────────────── +# +# The resource gate asserted `status >= 400` at its two refresh sites, so an +# HTTP 500 counted as a denial and the gate reported 15/15 and exit 0 while +# two of its negative checks had observed nothing at all. These drive the same +# helper those call sites now use. +print("\n## 10. a server failure is not an authorization refusal") +from resource_gate import refused_grant, TOKEN_REFUSAL_STATUSES, REFRESH_REFUSAL + +for status in (500, 502, 503): + fires(f"HTTP {status} is not a refusal, whatever the body says", + lambda st=status: refused_grant(st, {"error": "invalid_grant"}, "control"), + "is not a refusal") + +fires("a missing token endpoint is not a refusal", + lambda: refused_grant(404, {"error": "invalid_grant"}, "control"), + "is not a refusal") +fires("a 200 is certainly not a refusal", + lambda: refused_grant(200, {"access_token": "t"}, "control"), + "is not a refusal") +fires("a refusal status carrying no object is not a refusal", + lambda: refused_grant(400, "server error", "control"), + "not an OAuth error object") +fires("a refusal status carrying nothing is not a refusal", + lambda: refused_grant(400, None, "control"), + "not an OAuth error object") +fires("a documented status with an undocumented error code is not a refusal", + lambda: refused_grant(400, {"error": "server_error"}, "control"), + "not one of the documented") +fires("a documented status with no error code is not a refusal", + lambda: refused_grant(400, {"error_description": "nope"}, "control"), + "not one of the documented") + +# The positive twins: the guard has to accept what the server really answers, +# or it would merely be strict rather than correct. +allows("a 400 invalid_grant is the documented refusal", + lambda: refused_grant(400, {"error": "invalid_grant"}, "control"), (400, "invalid_grant")) +allows("a 400 invalid_target is the documented refusal on the code path", + lambda: refused_grant(400, {"error": "invalid_target"}, "control", + expected=(400, "invalid_target")), (400, "invalid_target")) +allows("a 401 invalid_client is a refusal of the client itself, where that is expected", + lambda: refused_grant(401, {"error": "invalid_client"}, "control", + expected=(401, "invalid_client")), (401, "invalid_client")) +allows("extra fields alongside a documented error are still a refusal", + lambda: refused_grant(400, {"error": "invalid_grant", "error_description": "x"}, "control"), + (400, "invalid_grant")) + +# A refusal that is not *this* scenario's refusal. Each of these is a lawful, +# documented OAuth error -- and none of them says the resource binding was +# examined, which is the only thing these two scenarios exist to establish. +for wrong_status, wrong_error in [ + (401, "invalid_client"), (400, "invalid_client"), + (400, "invalid_request"), (400, "invalid_target"), + (400, "unauthorized_client"), (400, "invalid_scope"), + (400, "unsupported_grant_type")]: + fires(f"a refresh scenario does not accept {wrong_status} {wrong_error}", + lambda st=wrong_status, er=wrong_error: + refused_grant(st, {"error": er}, "control"), + "not the one this scenario establishes") + +allows("and the pair it is entitled to still passes", + lambda: refused_grant(400, {"error": "invalid_grant"}, "control"), REFRESH_REFUSAL) +allows("a scenario may name a different expected pair explicitly", + lambda: refused_grant(400, {"error": "invalid_target"}, "control", + expected=(400, "invalid_target")), (400, "invalid_target")) + +bad = [r for r in RESULTS if not r[0]] +print() +print(f"=== GATE SELF-TEST: {len(RESULTS)-len(bad)} passed, {len(bad)} failed ===") +for r in bad: + print(" FAILED:", r[1], "|", r[2]) +sys.exit(1 if bad else 0) diff --git a/itest/upgrade_gate.py b/itest/upgrade_gate.py new file mode 100644 index 0000000..fb109df --- /dev/null +++ b/itest/upgrade_gate.py @@ -0,0 +1,384 @@ +""" +Installation, upgrade and restart, through GitBucket's own plugin mechanism. + + python3 itest/upgrade_gate.py --war \ + --previous --candidate + +The direct Liquibase tests under `src/test` establish what the changelog does +to a database. They say nothing about whether GitBucket ever runs it: a +migration can be written, committed, tested and still never execute, because +what runs is what the loaded `Plugin` class declares and what Solidbase finds +packaged in the JAR. + +So this gate never touches the changelog. It starts real GitBucket processes +and asks the questions an operator asks: + +1. the previous plugin runs, and data created under it is real; +2. the candidate replaces it and GitBucket's own machinery migrates; +3. the data created under the previous plugin is still there; +4. an OAuth grant issued after the upgrade survives a restart; +5. a revocation performed before a restart is still in force after it. + +Point 5 is the one that distinguishes persistence from a cache. A revocation +that lived only in memory would come back to life here, and the credential +would start working again. +""" +import argparse +import json +import os +import shutil +import subprocess +import sys +import time +import urllib.error +import urllib.request +import zipfile + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from harness import check, summary +from checks import GateError, require + +PORT = 8099 +OBASE = f"http://localhost:{PORT}" +BASE = f"http://127.0.0.1:{PORT}" + +# oauth_gate reads these at import time, so the addresses have to agree. +import oauth_gate +from oauth_gate import ClientHost, pkce, authorize, redeem, revoke, signin, tool, outcome + +ADMIN = ("root", "root") +TIMEZONE = os.environ.get("ITEST_TZ", "Europe/Kyiv") + + +# ── running GitBucket ─────────────────────────────────────────────────────── + +class Instance: + """One GitBucket process over one GITBUCKET_HOME.""" + + def __init__(self, war, home): + self.war, self.home, self.proc = war, home, None + self.log = os.path.join(home, "server.log") + + def install(self, jar, name): + plugins = os.path.join(self.home, "plugins") + os.makedirs(plugins, exist_ok=True) + shutil.copyfile(jar, os.path.join(plugins, name)) + + def remove_plugin(self, name): + """Take a plugin out of both the scan directory and the staging area.""" + gone = False + for d in (os.path.join(self.home, "plugins"), + os.path.join(self.home, "plugins", ".installed")): + p = os.path.join(d, name) + if os.path.isfile(p): + os.remove(p) + gone = True + return gone + + @staticmethod + def port_is_free(): + import socket + with socket.socket() as s: + s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + try: + s.bind(("127.0.0.1", PORT)) + return True + except OSError: + return False + + def start(self): + require(self.proc is None, "this instance is already running") + # Said plainly here rather than discovered as a readiness timeout two + # minutes later: a leftover server on this port answers health checks + # and would be mistaken for the instance under test. + require(Instance.port_is_free(), + f"127.0.0.1:{PORT} is already in use. Something else is serving this " + f"port; this gate will not attribute its answers to the artifact " + f"under test.") + out = open(self.log, "ab") + self.proc = subprocess.Popen( + ["java", + # A real zone with a DST offset, not UTC: the timestamp handling + # under test renders in the JVM's default zone, and a UTC host is + # exactly the configuration that hid a defect here before. The + # IANA spelling matters too — PostgreSQL 16 rejects the + # deprecated "Europe/Kiev" the JDBC driver would otherwise send. + f"-Duser.timezone={TIMEZONE}", + f"-Dgitbucket.mcp.oauth.baseUrl={OBASE}", + "-Dgitbucket.mcp.oauth.allowLoopbackClients=true", + "-jar", self.war, + f"--port={PORT}", "--host=127.0.0.1", f"--gitbucket.home={self.home}"], + stdout=out, stderr=subprocess.STDOUT) + for _ in range(120): + if self.proc.poll() is not None: + raise GateError(f"GitBucket exited at startup; see {self.log}") + try: + with urllib.request.urlopen(BASE + "/plugin-mcp/health", timeout=3) as r: + if r.status == 200: + return self + except Exception: + time.sleep(1) + raise GateError(f"GitBucket did not become ready; see {self.log}") + + def stop(self): + if self.proc is None: + return + self.proc.terminate() + try: + self.proc.wait(timeout=90) + except subprocess.TimeoutExpired: + self.proc.kill() + self.proc.wait(timeout=30) + self.proc = None + # The plugin watch thread and H2 both need the port and the lock file + # released before the next process claims them. + time.sleep(3) + + def log_text(self): + with open(self.log, encoding="utf-8", errors="replace") as fh: + return fh.read() + + +# ── talking to it without the plugin's help ───────────────────────────────── + +def api(method, path, body=None, creds=ADMIN): + import base64 + data = json.dumps(body).encode() if body is not None else None + req = urllib.request.Request(BASE + path, data=data, method=method) + req.add_header("Content-Type", "application/json") + req.add_header("Authorization", "Basic " + + base64.b64encode(f"{creds[0]}:{creds[1]}".encode()).decode()) + try: + with urllib.request.urlopen(req, timeout=30) as r: + raw = r.read().decode(errors="replace") + return r.status, (json.loads(raw) if raw.strip() else None) + except urllib.error.HTTPError as e: + raw = e.read().decode(errors="replace") + try: + return e.code, json.loads(raw) + except Exception: + return e.code, raw[:300] + + +def rpc_basic(method, params, creds): + import base64 + payload = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params} + req = urllib.request.Request(BASE + "/plugin-mcp/", data=json.dumps(payload).encode(), + method="POST") + req.add_header("Content-Type", "application/json") + req.add_header("Authorization", "Basic " + + base64.b64encode(f"{creds[0]}:{creds[1]}".encode()).decode()) + try: + with urllib.request.urlopen(req, timeout=30) as r: + return r.status, json.loads(r.read().decode()) + except urllib.error.HTTPError as e: + return e.code, e.read().decode(errors="replace")[:300] + + +def packaged_version(jar): + import configparser + with zipfile.ZipFile(jar) as z: + raw = z.read("gitbucket-plugin.properties").decode("utf-8") + p = configparser.ConfigParser() + p.read_string("[d]\n" + raw) + v = p["d"].get("pluginversion", "").strip() + require(bool(v), f"{jar} packages a descriptor with no pluginVersion") + return v + + +def packages_migration(jar): + with zipfile.ZipFile(jar) as z: + return [n for n in z.namelist() if n.startswith("update/") and n.endswith(".xml")] + + +def grant_token(scope="mcp:read mcp:write"): + """A full authorization through the real consent screen. Returns the token.""" + verifier, challenge = pkce() + jar = signin(*ADMIN) + code, _ = authorize(jar, CLIENT_ID, oauth_gate.REDIRECT, scope, challenge) + status, payload = redeem(code, CLIENT_ID, oauth_gate.REDIRECT, verifier) + require(status == 200 and "access_token" in payload, + f"the token endpoint answered {status}: {payload}") + return payload["access_token"] + + +def token_works(access_token): + _, _, payload = tool(access_token, "whoami", {}) + kind, _ = outcome(payload) + return kind == "ok" + + +# ── the gate ──────────────────────────────────────────────────────────────── + +CLIENT_ID = None + + +def run(war, previous, candidate, home): + global CLIENT_ID + prev_name = "gitbucket-mcp-plugin-previous.jar" + cand_name = "gitbucket-mcp-plugin-candidate.jar" + cand_version = packaged_version(candidate) + + check("the previous plugin packages no migration", packages_migration(previous), []) + check("the candidate packages its migration", + packages_migration(candidate), ["update/mcp-plugin_1.0.xml"]) + + host = ClientHost() + started = [] + + def launch(): + gb = Instance(war, home) + started.append(gb) + return gb + + try: + CLIENT_ID = host.publish("/client.json", [oauth_gate.REDIRECT], + name="Upgrade gate client") + + # ── 1. the previous plugin, and real data under it ────────────────── + print("## 1. the previous plugin") + gb = launch() + gb.install(previous, prev_name) + gb.start() + check("the previous plugin initializes", + f"Initialize {prev_name}" in gb.log_text(), True) + st, _ = rpc_basic("tools/list", {}, ADMIN) + check("its MCP endpoint answers over Basic", st, 200) + check("it serves no authorization-server metadata", + api("GET", "/.well-known/oauth-authorization-server")[0], 404) + + st, _ = api("POST", "/api/v3/user/repos", + {"name": "carried", "description": "created under the previous plugin", + "private": False, "auto_init": True}) + require(st in (200, 201), f"could not create the repository ({st})") + st, _ = api("POST", "/api/v3/repos/root/carried/issues", + {"title": "created before the upgrade", "body": "survives?"}) + require(st in (200, 201), f"could not create the issue ({st})") + st, issues = api("GET", "/api/v3/repos/root/carried/issues?state=all") + check("data exists under the previous plugin", (st, len(issues)), (200, 1)) + gb.stop() + + # ── 2. the upgrade, through GitBucket's own mechanism ─────────────── + print("\n## 2. the upgrade") + check("the previous JAR is removed from the scan and the staging area", + gb.remove_plugin(prev_name), True) + gb.install(candidate, cand_name) + gb = launch() + gb.start() + text = gb.log_text() + check("the candidate initializes on the existing home", + f"Initialize {cand_name}" in text, True) + check("nothing failed during startup", + [l for l in text.splitlines() + if ("ERROR" in l or "Exception" in l) and "mcp" in l.lower()], []) + + # ── 3. the migration actually ran ─────────────────────────────────── + print("\n## 3. the migration") + check("the authorization server is now published", + api("GET", "/.well-known/oauth-authorization-server")[0], 200) + check("initialize reports the candidate's packaged version", + rpc_basic("initialize", {"protocolVersion": "2024-11-05", "capabilities": {}}, + ADMIN)[1]["result"]["serverInfo"]["version"], cand_version) + # The tables are not inspected directly. A grant is stored, read back + # on a later request and survives a restart — which is the property, + # and it fails if the migration did not run. + access = grant_token() + check("a grant can be issued against the migrated schema", + token_works(access), True) + + # The Basic connection that existed before the upgrade has to keep + # working, and keep working unscoped: those credentials are the + # account itself, not a delegation of part of it. + st, body = rpc_basic("tools/call", {"name": "whoami", "arguments": {}}, ADMIN) + check("a Basic caller still reaches the dispatcher after the upgrade", st, 200) + check("and is still identified as the authenticating account", + json.loads(body["result"]["content"][0]["text"]).get("login"), ADMIN[0]) + st, body = rpc_basic("tools/call", + {"name": "update_pull_request", + "arguments": {"owner": "root", "repo": "carried", "number": 99}}, + ADMIN) + check("a Basic caller is not refused for scope", + "insufficient_scope" in json.dumps(body), False) + + # ── 4. data created under the previous plugin ─────────────────────── + print("\n## 4. existing data") + st, issues = api("GET", "/api/v3/repos/root/carried/issues?state=all") + check("the repository and its issue survived the upgrade", + (st, len(issues), issues[0]["title"] if issues else None), + (200, 1, "created before the upgrade")) + st, _ = api("GET", "/api/v3/repos/root/carried") + check("the repository itself is intact", st, 200) + + # ── 5. restart: the grant persists ────────────────────────────────── + print("\n## 5. restart with persisted state") + gb.stop() + gb = launch() + gb.start() + check("the token issued before the restart still works", + token_works(access), True) + + # ── 6. restart: the revocation persists ───────────────────────────── + print("\n## 6. restart with persisted revocation") + status, _ = revoke(access) + check("revocation answers 200", status, 200) + check("the token stops working immediately", token_works(access), False) + gb.stop() + gb = launch() + gb.start() + check("the revocation is still in force after a restart", + token_works(access), False) + fresh = grant_token() + check("a new grant still works after all of it", token_works(fresh), True) + gb.stop() + finally: + host.stop() + for gb in started: + try: + gb.stop() + except Exception: + pass + + failed = summary("UPGRADE GATE") + ran = len(__import__("harness").RESULTS) + if ran < 22: + raise GateError(f"only {ran} checks executed; this gate has no result below 22") + return 1 if failed else 0 + + +if __name__ == "__main__": + ap = argparse.ArgumentParser() + ap.add_argument("--war", required=True) + ap.add_argument("--previous", required=True) + ap.add_argument("--candidate", required=True) + ap.add_argument("--home", required=True) + ap.add_argument("--db-url", help=( + "JDBC URL for a blank database. Omitted, GitBucket uses its bundled H2. " + "Supplied, the migration is executed against that backend instead, which " + "is the only way the PostgreSQL path is actually tested rather than " + "generated.")) + ap.add_argument("--db-user", default="") + ap.add_argument("--db-password", default="") + a = ap.parse_args() + for p in (a.war, a.previous, a.candidate): + require(os.path.isfile(p), f"not a readable file: {p}") + require(not os.path.exists(a.home) or not os.listdir(a.home), + f"{a.home} is not empty; this gate needs a blank GITBUCKET_HOME") + os.makedirs(a.home, exist_ok=True) + if a.db_url: + # Written before the first start, so the previous plugin and every + # migration after it run against this backend from the beginning. + with open(os.path.join(a.home, "database.conf"), "w", encoding="utf-8") as fh: + fh.write("db {\n" + f' url = "{a.db_url}"\n' + f' user = "{a.db_user}"\n' + f' password = "{a.db_password}"\n' + "}\n") + print(f"backend: {a.db_url}\n") + else: + print("backend: bundled H2\n") + try: + sys.exit(run(a.war, a.previous, a.candidate, a.home)) + except GateError as exc: + print(f"\nGATE ABORTED: {exc}", file=sys.stderr) + print("No result may be read from this run.", file=sys.stderr) + sys.exit(2) diff --git a/src/main/resources/update/mcp-plugin_1.0.xml b/src/main/resources/update/mcp-plugin_1.0.xml new file mode 100644 index 0000000..b41cfa9 --- /dev/null +++ b/src/main/resources/update/mcp-plugin_1.0.xml @@ -0,0 +1,102 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/main/scala/Plugin.scala b/src/main/scala/Plugin.scala index d60f93f..605f7a2 100644 --- a/src/main/scala/Plugin.scala +++ b/src/main/scala/Plugin.scala @@ -1,18 +1,15 @@ -import gitbucket.core.plugin.{Plugin => GitBucketPlugin, PluginRegistry} -import gitbucket.core.service.SystemSettingsService.SystemSettings -import io.github.gitbucket.solidbase.model.Version -import javax.servlet.ServletContext - -class Plugin extends GitBucketPlugin { - override val pluginId = "mcp-plugin" - override val pluginName = "MCP Plugin" - override val description = "MCP (Model Context Protocol) server for GitBucket" - override val versions = List(new Version("0.1.0")) - - override def controllers( - registry: PluginRegistry, - context: ServletContext, - settings: SystemSettings - ): Seq[(String, com.newsrx.mcpplugin.MCPController)] = - Seq("/*" -> new com.newsrx.mcpplugin.MCPController()) -} +/** + * The class GitBucket loads. + * + * GitBucket finds a plugin by loading the class literally named `Plugin` from + * the root package of the JAR, so this is the only declaration that has any + * effect at runtime: the `versions`, `anonymousAccessiblePaths` and + * `controllers` GitBucket reads are the ones it finds here. + * + * It therefore extends the real definition rather than repeating it. The two + * were separate declarations of the same plugin before, which is a shape that + * fails quietly: a migration added to the other class was never run, the + * plugin still loaded, and the missing table only surfaced as an error on the + * first request that needed it. + */ +class Plugin extends com.newsrx.mcpplugin.MCPPlugin diff --git a/src/main/scala/com/newsrx/mcpplugin/MCPController.scala b/src/main/scala/com/newsrx/mcpplugin/MCPController.scala index 75405e5..cb0b73b 100644 --- a/src/main/scala/com/newsrx/mcpplugin/MCPController.scala +++ b/src/main/scala/com/newsrx/mcpplugin/MCPController.scala @@ -2,7 +2,8 @@ package com.newsrx.mcpplugin import com.fasterxml.jackson.databind.node.ObjectNode import com.newsrx.mcpplugin.mcp.{JsonRpc, ToolRegistry} -import com.newsrx.mcpplugin.tools.SessionSupport +import com.newsrx.mcpplugin.oauth._ +import com.newsrx.mcpplugin.tools.{AuthorizationError, SessionSupport} import gitbucket.core.controller.ControllerBase import gitbucket.core.model.Account import gitbucket.core.service.{AccountService, RepositoryService, SystemSettingsService} @@ -15,27 +16,28 @@ class MCPController with AccountService with RepositoryService with SystemSettingsService - with SessionSupport { + with SessionSupport + with OAuthEndpoints { // ── Routes ──────────────────────────────────────────────────────────────── post("/plugin-mcp/") { contentType = "application/json; charset=UTF-8" - withAuth { account => - handleJsonRpc(account) + withAuth { caller => + handleJsonRpc(caller) } } // Some MCP clients POST without trailing slash post("/plugin-mcp") { contentType = "application/json; charset=UTF-8" - withAuth { account => - handleJsonRpc(account) + withAuth { caller => + handleJsonRpc(caller) } } get("/plugin-mcp/sse") { - withAuth { account => + withAuth { caller => contentType = "text/event-stream; charset=UTF-8" response.setHeader("Cache-Control", "no-cache") response.setHeader("X-Accel-Buffering", "no") @@ -53,7 +55,7 @@ class MCPController // ── JSON-RPC dispatch ───────────────────────────────────────────────────── - private def handleJsonRpc(account: Account): String = { + private def handleJsonRpc(caller: AuthenticatedCaller): String = { val body = request.body if (body.isEmpty) { return JsonRpc.errorResponse(mapper, None, JsonRpc.InvalidRequest, "empty request body") @@ -79,7 +81,7 @@ class MCPController JsonRpc.successResponse(mapper, req.id, ToolRegistry.listResult(mapper)) case "tools/call" => - handleToolCall(account, req) + handleToolCall(caller, req) case "resources/list" => // Resources not implemented — return empty list @@ -102,7 +104,7 @@ class MCPController } } - private def handleToolCall(account: Account, req: JsonRpc.Request): String = { + private def handleToolCall(caller: AuthenticatedCaller, req: JsonRpc.Request): String = { val params = req.params.getOrElse(mapper.createObjectNode()) val toolName = Option(params.get("name")).map(_.asText("")).getOrElse("") if (toolName.isEmpty) { @@ -117,12 +119,29 @@ class MCPController mapper, req.id, JsonRpc.MethodNotFound, s"unknown tool: $toolName" ) + case Some(tool) if !caller.permits(tool.requiredScope) => + // Distinct from an authentication failure, and distinct in the HTTP + // status too: the credential is good, the consent is not wide enough. + // A client that is told "authenticate again" for this will loop. + oauthConfig.foreach { config => + response.setHeader("WWW-Authenticate", + Metadata.challenge(config, Some(ChallengeError.InsufficientScope))) + } + response.setStatus(HttpServletResponse.SC_FORBIDDEN) + JsonRpc.errorResponse(mapper, req.id, JsonRpc.McpError - 3, + s"insufficient_scope: $toolName requires ${tool.requiredScope.name}") + case Some(tool) => val args = Option(params.get("arguments")).getOrElse(mapper.createObjectNode()) try { - val result = tool.execute(args, account, request, mapper) + val result = tool.execute(args, caller.account, request, mapper) JsonRpc.successResponse(mapper, req.id, result) } catch { + // A denial is its own outcome, not an internal failure: reporting it + // as InternalError would tell a caller the server broke when in fact + // the server refused. + case e: AuthorizationError => + JsonRpc.errorResponse(mapper, req.id, JsonRpc.McpError - 2, e.getMessage) case e: NoSuchElementException => JsonRpc.errorResponse(mapper, req.id, JsonRpc.McpError - 1, e.getMessage) case e: IllegalArgumentException => @@ -157,7 +176,9 @@ class MCPController val serverInfo = mapper.createObjectNode() serverInfo.put("name", "gitbucket-mcp-plugin") - serverInfo.put("version", "0.1.0") + // Reported from the descriptor that ships in the JAR instead of a second + // hardcoded literal: the two disagreed in v0.1.1. + serverInfo.put("version", PluginDescriptor.get("pluginVersion")) root.set[ObjectNode]("capabilities", capabilities) root.set[ObjectNode]("serverInfo", serverInfo) @@ -167,35 +188,98 @@ class MCPController // ── Authentication ──────────────────────────────────────────────────────── - private def withAuth(f: Account => String): String = { - authenticate() match { - case None => - response.setHeader("WWW-Authenticate", "Basic realm=\"GitBucket MCP\"") - response.setStatus(HttpServletResponse.SC_UNAUTHORIZED) + private def withAuth(f: AuthenticatedCaller => String): String = { + authenticateCaller() match { + case Right(caller) => f(caller) + case Left(error) => contentType = "application/json; charset=UTF-8" - JsonRpc.errorResponse( - mapper, None, JsonRpc.McpError, "authentication required" - ) - case Some(account) => - f(account) + response.setStatus(error.status) + response.setHeader("WWW-Authenticate", challengeHeader(error)) + JsonRpc.errorResponse(mapper, None, + if (error == ChallengeError.None_) JsonRpc.McpError else JsonRpc.McpError - 4, + if (error == ChallengeError.None_) "authentication required" else error.description) + } + } + + /** + * The challenge offered when authentication fails. + * + * Both schemes are offered when OAuth is configured, so a Basic client is + * not pushed into a browser flow it cannot perform and an OAuth client can + * still discover where to authorize. + */ + private def challengeHeader(error: ChallengeError): String = { + val basic = "Basic realm=\"GitBucket MCP\"" + oauthConfig match { + case Some(config) => + val bearer = Metadata.challenge(config, + if (error == ChallengeError.None_) None else Some(error)) + s"$bearer, $basic" + case None => basic } } - /** Extract and validate Basic auth credentials. */ - private def authenticate(): Option[Account] = - Option(request.getHeader("Authorization")).flatMap { header => - if (!header.startsWith("Basic ")) return None - try { - val decoded = new String(Base64.getDecoder.decode(header.drop(6).trim), "UTF-8") - val colon = decoded.indexOf(':') - if (colon < 0) return None - val username = decoded.substring(0, colon) - val password = decoded.substring(colon + 1) + /** + * Resolve the caller from the Authorization header. + * + * One header, one scheme, one answer. A Bearer token that does not resolve + * is an error and never a reason to look somewhere else: falling back to + * the browser session would mean a stale or stolen token silently acting as + * whoever happens to be signed in, and falling back to Basic would let a + * client downgrade itself out of its own scope restrictions. + */ + private def authenticateCaller(): Either[ChallengeError, AuthenticatedCaller] = + Option(request.getHeader("Authorization")).map(_.trim).filter(_.nonEmpty) match { + case None => Left(ChallengeError.None_) + case Some(header) if header.regionMatches(true, 0, "Bearer ", 0, 7) => + bearerCaller(header.substring(7).trim) + case Some(header) if header.regionMatches(true, 0, "Basic ", 0, 6) => + basicCaller(header.substring(6).trim) + case Some(_) => Left(ChallengeError.InvalidRequest) + } + + private def bearerCaller(token: String): Either[ChallengeError, AuthenticatedCaller] = + oauthConfig match { + case None => Left(ChallengeError.InvalidToken) + case Some(_) if token.isEmpty => Left(ChallengeError.InvalidRequest) + case Some(config) => + OAuthStore.resolveAccessToken(oauthConn, token, now()) match { + case Left(_) => Left(ChallengeError.InvalidToken) + // The grant records which resource it was minted for, and that is + // only a fact in a table until it is compared with the resource this + // server actually is. A token outlives the request that created it: + // a reconfigured deployment, or a neighbouring one, hands over a + // perfectly valid unexpired credential for somewhere else. Refused + // here, before any tool is chosen, and reported exactly like any + // other unusable token so it reveals nothing. + case Right(grant) if grant.resource != config.resource => + Left(ChallengeError.InvalidToken) + case Right(grant) => + implicit val s = Database.getSession(request) + // The account is resolved now, not trusted from the grant row: an + // account removed or disabled since consent must stop working + // here, without waiting for the grant to be revoked. + getAccountByUserName(grant.userName, includeRemoved = false) match { + case Some(account) => Right(AuthenticatedCaller.oauth(account, grant)) + case None => Left(ChallengeError.InvalidToken) + } + } + } + + private def basicCaller(encoded: String): Either[ChallengeError, AuthenticatedCaller] = + try { + val decoded = new String(Base64.getDecoder.decode(encoded), "UTF-8") + val colon = decoded.indexOf(':') + if (colon < 0) Left(ChallengeError.InvalidRequest) + else { implicit val session = Database.getSession(request) val settings = loadSystemSettings() - authenticate(settings, username, password) - } catch { - case _: Exception => None + authenticate(settings, decoded.substring(0, colon), decoded.substring(colon + 1)) match { + case Some(account) => Right(AuthenticatedCaller.basic(account)) + case None => Left(ChallengeError.InvalidToken) + } } + } catch { + case _: Exception => Left(ChallengeError.InvalidRequest) } } diff --git a/src/main/scala/com/newsrx/mcpplugin/MCPPlugin.scala b/src/main/scala/com/newsrx/mcpplugin/MCPPlugin.scala index 7868b40..aa4eb63 100644 --- a/src/main/scala/com/newsrx/mcpplugin/MCPPlugin.scala +++ b/src/main/scala/com/newsrx/mcpplugin/MCPPlugin.scala @@ -2,6 +2,7 @@ package com.newsrx.mcpplugin import gitbucket.core.plugin.{Plugin, PluginRegistry} import gitbucket.core.service.SystemSettingsService.SystemSettings +import io.github.gitbucket.solidbase.migration.LiquibaseMigration import io.github.gitbucket.solidbase.model.Version import javax.servlet.ServletContext @@ -9,7 +10,35 @@ class MCPPlugin extends Plugin { override val pluginId = "mcp-plugin" override val pluginName = "MCP Plugin" override val description = "MCP (Model Context Protocol) server for GitBucket" - override val versions = List(new Version("0.1.0")) + // Schema versions, which are not the plugin version. 1.0 is the first one + // to carry a migration: the OAuth grant, code, refresh and token tables. + // Nothing is added here to change what an admin page displays — a version + // without a real schema change would make Solidbase look for a migration + // that does not exist. + override val versions = List( + new Version("0.1.0"), + new Version("1.0", new LiquibaseMigration("update/mcp-plugin_1.0.xml")) + ) + + /** + * Paths that must work without a GitBucket session. + * + * Discovery is read before a client has any credential at all, and the + * token and revocation endpoints are called by the client rather than by a + * browser. `/plugin-mcp/oauth/authorize` is deliberately absent: it is the + * one endpoint that must know who is signed in. + */ + override def anonymousAccessiblePaths( + registry: PluginRegistry, + context: ServletContext, + settings: SystemSettings + ): Seq[String] = Seq( + "/.well-known/oauth-protected-resource", + "/.well-known/oauth-authorization-server", + "/plugin-mcp/oauth/token", + "/plugin-mcp/oauth/revoke", + "/plugin-mcp/health" + ) override def controllers( registry: PluginRegistry, diff --git a/src/main/scala/com/newsrx/mcpplugin/PluginDescriptor.scala b/src/main/scala/com/newsrx/mcpplugin/PluginDescriptor.scala new file mode 100644 index 0000000..96e4fc7 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/PluginDescriptor.scala @@ -0,0 +1,28 @@ +package com.newsrx.mcpplugin + +import java.util.Properties +import scala.util.Using + +/** + * The plugin descriptor as it ships inside the JAR. + * + * Read from the classpath rather than written into the code a second time, so + * this cannot drift from the descriptor GitBucket itself loads. It remains + * self-reported: it identifies what the running JAR says about itself, not + * what produced its bytes. + * + * Owned by the plugin's root package rather than by `tools`, because both the + * controller and the tool layer read it. Scoped to this package so it stays + * an internal detail of the plugin. + */ +private[mcpplugin] object PluginDescriptor { + private val props: Properties = { + val p = new Properties() + Option(getClass.getClassLoader.getResourceAsStream("gitbucket-plugin.properties")).foreach { in => + Using.resource(in)(p.load) + } + p + } + + def get(key: String): String = Option(props.getProperty(key)).getOrElse("") +} diff --git a/src/main/scala/com/newsrx/mcpplugin/mcp/StrictArgs.scala b/src/main/scala/com/newsrx/mcpplugin/mcp/StrictArgs.scala new file mode 100644 index 0000000..2b673ca --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/mcp/StrictArgs.scala @@ -0,0 +1,118 @@ +package com.newsrx.mcpplugin.mcp + +import com.fasterxml.jackson.databind.JsonNode + +/** + * Argument reading for operations that change stored data. + * + * `MCPController.handleToolCall` hands `arguments` to a tool without checking + * it against the advertised schema, so whatever a client sends is what the + * tool sees. The inherited helpers in [[ToolDef]] go through Jackson's + * `asText("")`, which answers `""` for an object, an array or a null and + * stringifies numbers and booleans. For a read that is merely sloppy. For a + * write it is destructive in two distinct ways: + * + * - `{"body": {}}` becomes an empty string, so a malformed request silently + * erases a description and the read-back then faithfully confirms the + * text the caller never asked for; + * - `{"expected_head_sha": {}}` becomes `""`, which the old `strOpt` then + * discarded as absent, turning a supplied precondition into no + * precondition at all. + * + * These helpers fail closed instead. Absent stays absent; a supplied value + * must be a JSON string, because an empty string is a legitimate edit and + * cannot therefore double as the error signal; everything else is refused + * before any write happens. + */ +object StrictArgs { + + /** + * A supplied JSON string, or `None` when the key is absent. + * + * `""` is returned as `Some("")`: clearing a body is a real edit, and the + * caller's intent to clear it must survive the trip. Any non-string value, + * JSON `null` included, is an error rather than a silent default. + */ + def textOpt(args: JsonNode, key: String): Option[String] = + Option(args.get(key)) match { + case None => None + case Some(node) if node.isTextual => Some(node.asText()) + case Some(node) => + throw new IllegalArgumentException( + s"argument '$key' must be a JSON string, received ${typeName(node)}" + ) + } + + /** A supplied, non-empty JSON string. Absent and empty are both refused. */ + def requiredText(args: JsonNode, key: String): String = + textOpt(args, key) match { + case Some(value) if value.nonEmpty => value + case Some(_) => + throw new IllegalArgumentException(s"argument '$key' must not be empty") + case None => + throw new IllegalArgumentException(s"missing required argument: $key") + } + + /** + * A supplied commit id, validated as 40 hexadecimal characters. + * + * A precondition that cannot be parsed is refused rather than dropped: the + * caller asked for a guarded write, and performing an unguarded one in its + * place would be the opposite of what was requested. Abbreviated ids are + * refused too, because a prefix comparison against a stored full id would + * quietly never match. + */ + def commitIdOpt(args: JsonNode, key: String): Option[String] = + textOpt(args, key).map { value => + if (value.length != 40 || !value.forall(isHexDigit)) { + throw new IllegalArgumentException( + s"argument '$key' must be a full 40-character hexadecimal commit id" + ) + } + value + } + + /** + * A supplied object identifier: a JSON integral number inside Int range and + * strictly positive. + * + * The inherited `ToolDef.int` goes through `asInt(-1)` and admits anything + * that comes back non-negative. Measured on Jackson 2.15.2, `1.9`, + * `4294967297`, `"1"` and `true` all arrive as 1, so a malformed target + * silently became pull request or comment number 1 and the mutation went to + * the wrong object. `isIntegralNumber` rejects the fractional and textual + * and boolean forms, `canConvertToInt` rejects the out-of-range ones, and + * GitBucket's issue, pull request and comment ids start at 1, so zero and + * negatives are outside the domain rather than merely odd. + */ + def identifier(args: JsonNode, key: String): Int = + Option(args.get(key)) match { + case None => + throw new IllegalArgumentException(s"missing required argument: $key") + case Some(node) if !node.isIntegralNumber => + throw new IllegalArgumentException( + s"argument '$key' must be a JSON integer, received ${typeName(node)}" + ) + case Some(node) if !node.canConvertToInt => + throw new IllegalArgumentException( + s"argument '$key' is outside the supported range: ${node.asText()}" + ) + case Some(node) if node.asInt() < 1 => + throw new IllegalArgumentException( + s"argument '$key' must be a positive identifier, received ${node.asInt()}" + ) + case Some(node) => node.asInt() + } + + private def isHexDigit(c: Char): Boolean = + (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F') + + private def typeName(node: JsonNode): String = + if (node.isNull) "null" + else if (node.isObject) "an object" + else if (node.isArray) "an array" + else if (node.isBoolean) "a boolean" + else if (node.isFloatingPointNumber) "a fractional number" + else if (node.isNumber) "a number" + else node.getNodeType.toString.toLowerCase +} diff --git a/src/main/scala/com/newsrx/mcpplugin/mcp/Timestamps.scala b/src/main/scala/com/newsrx/mcpplugin/mcp/Timestamps.scala new file mode 100644 index 0000000..4231fa3 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/mcp/Timestamps.scala @@ -0,0 +1,37 @@ +package com.newsrx.mcpplugin.mcp + +import java.time.ZoneOffset +import java.time.format.DateTimeFormatter +import java.util.Date + +/** + * Timestamps as a client can actually read them. + * + * Every date this gateway published used to go through `java.util.Date. + * toString`, which produces `"Fri Oct 23 15:38:41 EEST 2026"`. Three things + * are wrong with that for a machine-facing payload: + * + * - it is rendered in the server JVM's default time zone, so the same instant + * reads differently on two hosts and the string carries an abbreviation + * (`EEST`) that is ambiguous and not parseable back to an offset; + * - the month and day names are locale-dependent; + * - it cannot be compared with GitBucket's own REST API, which publishes ISO + * 8601 in UTC, so a consumer holding both answers cannot tell whether they + * agree. + * + * Measured, not assumed: the live gate's own `merged_at` comparison refused to + * run against a JVM in `Europe/Kiev` because it could not turn `EEST` into an + * offset. Earlier runs happened to be on a UTC host, which is exactly why this + * stayed invisible. + * + * All timestamps are therefore published as ISO 8601 instants in UTC, to the + * second, matching GitBucket's own API: `2026-10-23T12:38:41Z`. + */ +object Timestamps { + + private val iso = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss'Z'") + + /** An instant in UTC, ISO 8601, second precision. */ + def iso8601(date: Date): String = + iso.format(date.toInstant.atZone(ZoneOffset.UTC)) +} diff --git a/src/main/scala/com/newsrx/mcpplugin/mcp/ToolDef.scala b/src/main/scala/com/newsrx/mcpplugin/mcp/ToolDef.scala index 66ce626..5b31cfc 100644 --- a/src/main/scala/com/newsrx/mcpplugin/mcp/ToolDef.scala +++ b/src/main/scala/com/newsrx/mcpplugin/mcp/ToolDef.scala @@ -2,6 +2,7 @@ package com.newsrx.mcpplugin.mcp import com.fasterxml.jackson.databind.{JsonNode, ObjectMapper} import com.fasterxml.jackson.databind.node.ObjectNode +import com.newsrx.mcpplugin.oauth.McpScope import gitbucket.core.model.Account import javax.servlet.http.HttpServletRequest @@ -10,6 +11,19 @@ trait ToolDef { def name: String def description: String + /** + * The OAuth scope a caller needs to invoke this tool. + * + * Abstract rather than defaulting to [[McpScope.Read]]: a default would be + * the weaker requirement, so a new mutating tool that forgot to declare + * would be callable with a read-only grant and nothing would say so. This + * way it does not compile. + * + * It is one value feeding two places — the advertised policy in + * `tools/list` and the check in the dispatcher — so the two cannot drift. + */ + def requiredScope: McpScope + /** JSON Schema for the `arguments` object. */ def inputSchema(mapper: ObjectMapper): ObjectNode @@ -131,6 +145,9 @@ object ToolRegistry { new ClosePullRequestTool, new ReopenPullRequestTool, new GetPrDiffTool, + new GetThreadCommentsTool, + new UpdatePullRequestTool, + new MarkReadyForReviewTool, // Issue tools new ListIssuesTool, new GetIssueTool, @@ -138,9 +155,12 @@ object ToolRegistry { new CloseIssueTool, new ReopenIssueTool, new AddIssueCommentTool, + new UpdateOwnCommentTool, // Repository tools new ListRepositoriesTool, - new GetRepositoryTool + new GetRepositoryTool, + // Identity + new WhoAmITool ) } diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/AuthenticatedCaller.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/AuthenticatedCaller.scala new file mode 100644 index 0000000..1789ea2 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/AuthenticatedCaller.scala @@ -0,0 +1,39 @@ +package com.newsrx.mcpplugin.oauth + +import gitbucket.core.model.Account + +/** + * Who is calling, and what they were allowed to ask for. + * + * Both authentication methods end here, which is the point: everything + * downstream sees one shape and cannot accidentally treat an OAuth caller as + * unrestricted by forgetting to look at a scope field that only one branch + * populates. + */ +final case class AuthenticatedCaller( + account: Account, + scopes: Set[String], + /** Present only for OAuth callers; a Basic caller holds no grant. */ + grantId: Option[String] +) { + def permits(required: McpScope): Boolean = required.satisfiedBy(scopes) +} + +object AuthenticatedCaller { + + /** + * A caller who presented the account's own password or personal access + * token. + * + * These credentials are the account, not a delegation of part of it, so + * there is no narrower scope to apply and every scope is held. This is what + * keeps the existing Basic connection working exactly as it did: adding + * OAuth must not quietly restrict a client that was never scoped. + */ + def basic(account: Account): AuthenticatedCaller = + AuthenticatedCaller(account, McpScope.all.map(_.name).toSet, None) + + /** A caller presenting an access token, limited to what was consented to. */ + def oauth(account: Account, grant: ResolvedGrant): AuthenticatedCaller = + AuthenticatedCaller(account, grant.scopes, Some(grant.grantId)) +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/ChallengeError.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/ChallengeError.scala new file mode 100644 index 0000000..353f873 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/ChallengeError.scala @@ -0,0 +1,33 @@ +package com.newsrx.mcpplugin.oauth + +/** + * The reasons this resource server refuses a bearer token (RFC 6750 §3.1). + * + * A closed set, with server-authored text. Error descriptions are the one + * place where caller-controlled bytes are most tempting to echo — "token + * `` is malformed" reads helpfully — and the one place where + * echoing them puts attacker text into a response header, a proxy log and + * whatever parses either. + * + * It is also deliberately uninformative about *why* a token failed. A caller + * learns that the token is not usable, not whether it was unknown, expired, + * bound to another resource or revoked; those differences are useful to + * someone probing with tokens they should not have. + */ +sealed abstract class ChallengeError(val code: String, val description: String, val status: Int) + +object ChallengeError { + + /** No credentials at all: not an error, just an invitation to authenticate. */ + case object None_ extends ChallengeError("", "", 401) + + case object InvalidRequest + extends ChallengeError("invalid_request", "malformed authorization header", 400) + + /** Covers unknown, expired, revoked and wrong-audience alike, on purpose. */ + case object InvalidToken + extends ChallengeError("invalid_token", "the access token is not valid", 401) + + case object InsufficientScope + extends ChallengeError("insufficient_scope", "the access token does not grant the required scope", 403) +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/ClientMetadata.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/ClientMetadata.scala new file mode 100644 index 0000000..f6b2674 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/ClientMetadata.scala @@ -0,0 +1,229 @@ +package com.newsrx.mcpplugin.oauth + +import java.net.{InetAddress, URI, URL} +import java.nio.charset.StandardCharsets +import com.fasterxml.jackson.databind.{JsonNode, ObjectMapper} +import scala.jdk.CollectionConverters._ + +/** A client described by its own metadata document (SEP-3149, CIMD). */ +final case class OAuthClient( + clientId: String, + clientName: String, + redirectUris: Set[String] +) { + /** Exact match. A prefix or a host comparison is how redirect validation gets broken. */ + def permits(redirectUri: String): Boolean = redirectUris.contains(redirectUri) +} + +sealed trait ClientMetadataError { def message: String } +object ClientMetadataError { + final case class Rejected(message: String) extends ClientMetadataError + final case class Unreachable(message: String) extends ClientMetadataError + final case class Malformed(message: String) extends ClientMetadataError +} + +/** + * Fetching a client's metadata document. + * + * The client id *is* a URL the caller supplies, and the server then makes a + * request to it. That is a server-side request forgery primitive unless it is + * fenced, and the fence is the interesting part of this file: a GitBucket is + * usually inside a network with things worth reaching. + * + * The rules, each because of a specific way this goes wrong: + * + * - HTTPS only, so the document cannot be substituted on the wire; + * - every resolved address is checked against loopback, link-local, private + * and multicast ranges, so `https://internal.example/` and + * `https://169.254.169.254/` are refused rather than fetched; + * - redirects are not followed at all, so an allowed host cannot bounce the + * request to a refused one — the common bypass of a check done only on the + * first URL; + * - connect and read timeouts, and a hard cap on bytes read, so a slow or + * endless response occupies one request slot briefly instead of a thread + * forever. + * + * Checking the address and then connecting to a *name* closes nothing: the two + * resolutions are independent, and only the second one decides where the + * request goes. Verifying afterwards is worse than useless, because a response + * exists only once the request has been sent. So the address is chosen here + * and the socket is connected to exactly it; see `PinnedConnection`. The host + * name is still what TLS asks for and what the certificate must match, so + * nothing about authenticating the peer is given up. + */ +object ClientMetadata { + + /** + * Permit client metadata documents on loopback addresses. + * + * Off. With it on, part of the fence below is gone: a client id pointing at + * `127.0.0.1` will be fetched, and anything listening there can serve it. + * It exists because a developer running an MCP client on the same machine + * as GitBucket otherwise cannot complete an authorization at all, and + * because the alternative — a test-only branch compiled into the + * production path — is worse. Private, link-local, carrier-grade and + * multicast ranges stay forbidden either way: this opens loopback only. + */ + val AllowLoopbackProperty = "gitbucket.mcp.oauth.allowLoopbackClients" + + def loopbackAllowed(): Boolean = + java.lang.Boolean.parseBoolean(System.getProperty(AllowLoopbackProperty, "false")) + + private val ConnectTimeoutMs = 5000 + private val ReadTimeoutMs = 5000 + private val MaxBytes = 64 * 1024 + + /** Parse and validate a client id without fetching anything. */ + def validateClientId(clientId: String): Either[ClientMetadataError, URI] = + try { + val uri = new URI(clientId) + if (uri.getScheme == null || + (uri.getScheme.toLowerCase != "https" && + !(loopbackAllowed() && uri.getScheme.toLowerCase == "http" && isLoopbackHost(uri.getHost)))) + Left(ClientMetadataError.Rejected("client_id must be an https URL")) + else if (uri.getHost == null || uri.getHost.isEmpty) + Left(ClientMetadataError.Rejected("client_id must name a host")) + else if (uri.getFragment != null) + Left(ClientMetadataError.Rejected("client_id must not carry a fragment")) + else if (uri.getUserInfo != null) + Left(ClientMetadataError.Rejected("client_id must not carry user information")) + else Right(uri) + } catch { + case _: Exception => Left(ClientMetadataError.Rejected("client_id is not a valid URL")) + } + + /** True when this address must never be the target of a server-side fetch. */ + def isForbiddenAddress(addr: InetAddress): Boolean = + isForbiddenAddress(addr, allowLoopback = false) + + def isForbiddenAddress(addr: InetAddress, allowLoopback: Boolean): Boolean = { + val bytes = addr.getAddress + def octet(i: Int): Int = bytes(i) & 0xff + + // An IPv4 address written as an IPv6 one is the same destination, and + // `isSiteLocalAddress` and friends do not look through the wrapper. Both + // the mapped (::ffff:a.b.c.d) and compatible (::a.b.c.d) forms unwrap. + val embeddedIPv4: Option[InetAddress] = + if (bytes.length == 16 && (0 until 10).forall(bytes(_) == 0) && + ((octet(10) == 0xff && octet(11) == 0xff) || (octet(10) == 0 && octet(11) == 0)) && + !(0 until 12).forall(bytes(_) == 0)) + try Some(InetAddress.getByAddress(bytes.slice(12, 16))) catch { case _: Exception => None } + else None + + embeddedIPv4.exists(isForbiddenAddress(_, allowLoopback)) || + (addr.isLoopbackAddress && !allowLoopback) || addr.isLinkLocalAddress || + addr.isSiteLocalAddress || addr.isAnyLocalAddress || addr.isMulticastAddress || + // 100.64.0.0/10, carrier-grade NAT, not covered by isSiteLocalAddress. + (bytes.length == 4 && octet(0) == 100 && octet(1) >= 64 && octet(1) <= 127) || + // fc00::/7, IPv6 unique local. `isSiteLocalAddress` only covers the + // deprecated fec0::/10, so without this a ULA address reads as public. + (bytes.length == 16 && (octet(0) & 0xfe) == 0xfc) + } + + /** How a host name becomes addresses; injectable so the policy is testable. */ + type Resolver = String => Array[InetAddress] + + val systemResolver: Resolver = InetAddress.getAllByName + + /** + * Resolve `host` and return the one address the request may go to. + * + * Returning the address, rather than a verdict about the name, is the point: + * the caller connects to this and to nothing else, so there is no second + * resolution for an attacker to answer differently. + */ + private[oauth] def permittedAddress(host: String, resolve: Resolver, + allowLoopback: Boolean): Either[ClientMetadataError, InetAddress] = + try { + val addresses = resolve(host) + if (addresses == null || addresses.isEmpty) + Left(ClientMetadataError.Unreachable(s"cannot resolve $host")) + // Every address, not the first: a host that resolves to one public and + // one private address must not be reachable by retry. + else if (addresses.exists(isForbiddenAddress(_, allowLoopback))) + Left(ClientMetadataError.Rejected(s"$host resolves to a non-public address")) + else Right(addresses.head) + } catch { + case _: Exception => Left(ClientMetadataError.Unreachable(s"cannot resolve $host")) + } + + /** + * How a validated address becomes a response. + * + * The address is a parameter rather than something the fetcher works out for + * itself, so the destination cannot drift between the check and the request. + * Injectable so a control can see which address the production path dialled. + */ + type Fetcher = (URL, InetAddress) => PinnedResponse + + val pinnedFetcher: Fetcher = (url, address) => + PinnedConnection.fetch(url, address, ConnectTimeoutMs, ReadTimeoutMs, MaxBytes) + + /** + * Fetch and parse a client metadata document. + * + * The address is resolved and checked once, and the connection is pinned to + * it. There is no second resolution and no after-the-fact verification: by + * the time a response exists the request has already been made, which is the + * part that mattered. + */ + def fetch(mapper: ObjectMapper, clientId: String, + open: Fetcher = pinnedFetcher, + resolve: Resolver = systemResolver, + allowLoopback: Boolean = loopbackAllowed()): Either[ClientMetadataError, OAuthClient] = + for { + uri <- validateClientId(clientId) + address <- permittedAddress(uri.getHost, resolve, allowLoopback) + body <- read(uri.toURL, address, open) + client <- parse(mapper, clientId, body) + } yield client + + private def read(url: URL, address: InetAddress, + open: Fetcher): Either[ClientMetadataError, String] = + try { + val response = open(url, address) + if (response.status >= 300 && response.status < 400) + Left(ClientMetadataError.Rejected("client metadata must not redirect")) + else if (response.status != 200) + Left(ClientMetadataError.Unreachable(s"client metadata returned HTTP ${response.status}")) + else Right(response.body) + } catch { + case e: Exception => Left(ClientMetadataError.Unreachable( + s"client metadata could not be fetched: ${e.getClass.getSimpleName}")) + } + + def parse(mapper: ObjectMapper, clientId: String, body: String): Either[ClientMetadataError, OAuthClient] = + try { + val node: JsonNode = mapper.readTree(body) + if (node == null || !node.isObject) + Left(ClientMetadataError.Malformed("client metadata is not a JSON object")) + else { + val declaredId = Option(node.get("client_id")).filter(_.isTextual).map(_.asText()) + // A document that names a different client_id is describing someone + // else, and treating it as this client's is how one client's redirect + // list ends up authorising another's. + if (declaredId.exists(_ != clientId)) + Left(ClientMetadataError.Rejected("client metadata declares a different client_id")) + else { + val uris = Option(node.get("redirect_uris")).filter(_.isArray) + .map(_.elements().asScala.filter(_.isTextual).map(_.asText()).toSet) + .getOrElse(Set.empty[String]) + .filter(u => u.startsWith("https://") || u.startsWith("http://localhost")) + if (uris.isEmpty) + Left(ClientMetadataError.Malformed("client metadata declares no usable redirect_uris")) + else + Right(OAuthClient( + clientId = clientId, + clientName = Option(node.get("client_name")).filter(_.isTextual) + .map(_.asText()).filter(_.nonEmpty).getOrElse(clientId), + redirectUris = uris)) + } + } + } catch { + case _: Exception => Left(ClientMetadataError.Malformed("client metadata is not valid JSON")) + } + + private def isLoopbackHost(host: String): Boolean = + host != null && (host == "localhost" || host == "127.0.0.1" || host == "[::1]" || host == "::1") + +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/ConsentView.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/ConsentView.scala new file mode 100644 index 0000000..86d8088 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/ConsentView.scala @@ -0,0 +1,75 @@ +package com.newsrx.mcpplugin.oauth + +/** + * The consent screen. + * + * Rendered here rather than through a template because every value on it + * comes from somewhere untrusted — the client's own metadata document, and + * query parameters — and the escaping has to be unmissable. A template would + * put the escaping decision one indirection away from the data. + * + * The client name is attacker-controlled: whoever publishes the metadata + * document chooses it. It is escaped, and it is shown next to the client id + * so a name claiming to be something it is not can be seen for what it is. + */ +object ConsentView { + + def escape(raw: String): String = + Option(raw).getOrElse("") + .replace("&", "&") + .replace("<", "<") + .replace(">", ">") + .replace("\"", """) + .replace("'", "'") + + private def scopeLine(scope: String): String = scope match { + case "mcp:read" => "Read your repositories, issues and pull requests" + case "mcp:write" => "Create and change issues, comments and pull requests" + case other => escape(other) + } + + def render(client: OAuthClient, userName: String, scopes: Set[String], + redirectUri: String, state: Option[String], csrfToken: String, + formAction: String): String = { + val items = McpScope.all.map(_.name).filter(scopes.contains).map { s => + s"""
  • ${escape(s)} — ${escape(scopeLine(s))}
  • """ + }.mkString("\n") + + s""" + | + | + | + |Authorize application + | + | + | + |

    Authorize application

    + |
    + |
    ${escape(client.clientName)}
    + |
    ${escape(client.clientId)}
    + |
    + |

    Signed in as ${escape(userName)}. This application is asking to:

    + |
      + |$items + |
    + |

    It will act as you, and only within what your GitBucket account may already do.

    + | + | + | + | + | + | + | + | + | + | + |""".stripMargin + } +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/Metadata.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/Metadata.scala new file mode 100644 index 0000000..1b7c1a4 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/Metadata.scala @@ -0,0 +1,111 @@ +package com.newsrx.mcpplugin.oauth + +import com.fasterxml.jackson.databind.ObjectMapper +import com.fasterxml.jackson.databind.node.ObjectNode +import com.nimbusds.oauth2.sdk.{GrantType, ResponseMode, ResponseType, Scope => NimbusScope} +import com.nimbusds.oauth2.sdk.`as`.AuthorizationServerMetadata +import com.nimbusds.oauth2.sdk.auth.ClientAuthenticationMethod +import com.nimbusds.oauth2.sdk.id.Issuer +import java.net.URI +import scala.jdk.CollectionConverters._ + +/** + * The discovery documents, and the challenge that points at them. + * + * These describe only what is implemented. A metadata document is a promise a + * client acts on without asking again: advertising `plain` PKCE, a + * registration endpoint or an OIDC scope that does not work produces a client + * that fails later, further from the cause, with a worse error. + * + * Ownership, because it differs between the two documents. The authorization + * server document is built and serialized by + * `com.nimbusds.oauth2.sdk.as.AuthorizationServerMetadata`, so RFC 8414 field + * names and shapes are the library's. The protected resource document is + * written here by hand: RFC 9728 has no type in the oauth2-oidc-sdk version + * GitBucket ships, which is a small document and a deliberate exception + * rather than a preference for hand-rolled protocol code. + */ +object Metadata { + + /** + * RFC 9728 protected resource metadata, served at + * `/.well-known/oauth-protected-resource`. + */ + def protectedResource(mapper: ObjectMapper, config: OAuthConfig): ObjectNode = { + val n = mapper.createObjectNode() + n.put("resource", config.resource) + val servers = mapper.createArrayNode() + servers.add(config.issuer) + n.set[ObjectNode]("authorization_servers", servers) + val scopes = mapper.createArrayNode() + McpScope.all.foreach(s => scopes.add(s.name)) + n.set[ObjectNode]("scopes_supported", scopes) + val methods = mapper.createArrayNode() + methods.add("header") + n.set[ObjectNode]("bearer_methods_supported", methods) + n + } + + /** + * RFC 8414 authorization server metadata, served at + * `/.well-known/oauth-authorization-server`. + * + * Built through Nimbus's `AuthorizationServerMetadata`, which owns the field + * names and the JSON shape. + */ + def authorizationServer(mapper: ObjectMapper, config: OAuthConfig): ObjectNode = { + val m = new AuthorizationServerMetadata(new Issuer(config.issuer)) + m.setAuthorizationEndpointURI(URI.create(config.authorizationEndpoint)) + m.setTokenEndpointURI(URI.create(config.tokenEndpoint)) + m.setRevocationEndpointURI(URI.create(config.revocationEndpoint)) + + m.setResponseTypes(List(ResponseType.CODE).asJava) + m.setResponseModes(List(ResponseMode.QUERY).asJava) + m.setGrantTypes(List(GrantType.AUTHORIZATION_CODE, GrantType.REFRESH_TOKEN).asJava) + // S256 only. The absence of "plain" is the point, not an omission. + m.setCodeChallengeMethods(List(Pkce.supportedMethod).asJava) + m.setScopes(new NimbusScope(McpScope.all.map(_.name): _*)) + // Public clients proving possession with PKCE; no client secret exists to + // present, so "none" is the honest value rather than a weaker default. + m.setTokenEndpointAuthMethods(List(ClientAuthenticationMethod.NONE).asJava) + m.setRevocationEndpointAuthMethods(List(ClientAuthenticationMethod.NONE).asJava) + // RFC 9207: the authorization response carries `iss`, so a client can tell + // which server answered and cannot be fed a response from another one. + m.setSupportsAuthorizationResponseIssuerParam(true) + + val node = mapper.readTree(m.toJSONObject.toJSONString).asInstanceOf[ObjectNode] + // SEP-3149. Not modelled by the SDK version GitBucket ships, so it is set + // on the serialized document; the client_id is an HTTPS URL serving the + // client's own metadata, and there is no registration step and therefore + // no registration_endpoint. + node.put("client_id_metadata_document_supported", true) + node + } + + /** + * The `WWW-Authenticate` value for a 401 from the resource server + * (RFC 9728 §5.1), which is how a client discovers where to authenticate + * when it did not look first. + * + * The reason is a [[ChallengeError]] rather than a string, so nothing a + * caller sent can reach a response header. Sanitising caller text would + * also work and is worse: it is a blacklist, it has to stay correct as the + * header grammar grows, and it still copies an attacker's words into a + * response other software may log or parse. + */ + def challenge(config: OAuthConfig, error: Option[ChallengeError] = None): String = { + val metadataUrl = s"${config.baseUrl}/.well-known/oauth-protected-resource" + val parts = Seq( + Some(s"""resource_metadata="$metadataUrl""""), + error.map(e => s"""error="${e.code}""""), + error.map(e => s"""error_description="${e.description}"""") + ).flatten + s"Bearer ${parts.mkString(", ")}" + } + + private def array(mapper: ObjectMapper, parent: ObjectNode, field: String, values: Seq[String]): Unit = { + val arr = mapper.createArrayNode() + values.foreach(arr.add) + parent.set[ObjectNode](field, arr) + } +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthConfig.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthConfig.scala new file mode 100644 index 0000000..9845cc3 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthConfig.scala @@ -0,0 +1,77 @@ +package com.newsrx.mcpplugin.oauth + +/** + * Where this server thinks it is. + * + * Every identifier an OAuth deployment publishes — the issuer, the endpoints, + * the `resource` a token is bound to — is derived from one externally + * configured base URL, and from nothing else. + * + * Specifically not from the request. `Host` and `X-Forwarded-Host` are set by + * whoever is talking to the server, and behind a reverse proxy they are set by + * whoever is talking to the proxy. A resource identifier that follows the + * request header is not an audience binding: a token minted for one `Host` + * would be accepted by the same server asked under another, which is the whole + * property audience binding exists to provide. So the base URL is + * configuration, it is validated once, and a deployment that has not set it + * does not serve OAuth at all rather than guessing. + */ +final case class OAuthConfig( + /** External base URL of this GitBucket, no trailing slash, e.g. `https://git.example.com`. */ + baseUrl: String, + accessTokenLifetimeSeconds: Int = 3600, + refreshTokenLifetimeSeconds: Int = 30 * 24 * 3600, + authorizationCodeLifetimeSeconds: Int = 60 +) { + /** The MCP resource identifier, and the `resource`/audience value in tokens. */ + val resource: String = s"$baseUrl/plugin-mcp/" + + /** This server is its own issuer; RFC 8414 derives the metadata path from it. */ + val issuer: String = baseUrl + + val authorizationEndpoint: String = s"$baseUrl/plugin-mcp/oauth/authorize" + val tokenEndpoint: String = s"$baseUrl/plugin-mcp/oauth/token" + val revocationEndpoint: String = s"$baseUrl/plugin-mcp/oauth/revoke" +} + +object OAuthConfig { + + /** Property and environment names a deployment can set. */ + val BaseUrlProperty = "gitbucket.mcp.oauth.baseUrl" + val BaseUrlEnv = "GITBUCKET_MCP_OAUTH_BASE_URL" + + /** + * Build a configuration from an explicitly supplied base URL. + * + * Returns the reason on the left rather than a boolean, because "OAuth is + * off because the base URL is `http://`" is something an administrator needs + * to be told, and a silently disabled authentication method is how a + * deployment ends up serving an endpoint nobody can authenticate to. + */ + def fromBaseUrl(raw: String): Either[String, OAuthConfig] = { + val trimmed = Option(raw).map(_.trim).getOrElse("") + if (trimmed.isEmpty) + Left(s"not configured: set $BaseUrlProperty or $BaseUrlEnv to this server's external base URL") + else if (!trimmed.startsWith("https://") && !isLoopback(trimmed)) + // Plain HTTP is refused except on loopback, where it is the only way to + // run the test suite. A bearer token on a cleartext connection is a + // bearer token for whoever is on the path. + Left(s"must be an https:// URL (or http://localhost for testing), got: $trimmed") + else if (trimmed.endsWith("/")) + Left(s"must not end with a slash, got: $trimmed") + else if (trimmed.contains("?") || trimmed.contains("#")) + Left(s"must not carry a query or fragment, got: $trimmed") + else + Right(OAuthConfig(trimmed)) + } + + private def isLoopback(url: String): Boolean = + url.startsWith("http://localhost") || url.startsWith("http://127.0.0.1") + + /** Read the configured base URL from the system property, then the environment. */ + def configuredBaseUrl(): Option[String] = + Option(System.getProperty(BaseUrlProperty)) + .orElse(Option(System.getenv(BaseUrlEnv))) + .map(_.trim) + .filter(_.nonEmpty) +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthEndpoints.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthEndpoints.scala new file mode 100644 index 0000000..74f0848 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthEndpoints.scala @@ -0,0 +1,341 @@ +package com.newsrx.mcpplugin.oauth + +import com.fasterxml.jackson.databind.ObjectMapper +import gitbucket.core.controller.ControllerBase +import gitbucket.core.servlet.Database +import java.sql.Connection +import java.time.Instant +import javax.servlet.http.HttpSession + +/** A started authorization, held in the user's session until they decide. */ +private[oauth] final case class PendingAuthorization( + clientId: String, + clientName: String, + redirectUri: String, + scopes: Set[String], + state: Option[String], + codeChallenge: String, + resource: Option[String] +) + +/** + * The authorization server's HTTP surface. + * + * Mixed into the MCP controller so it shares one route table and one database + * session, which is what lets a code be consumed and its token issued inside + * the same transaction. + * + * The pending request lives in the user's HTTP session rather than in hidden + * form fields. A hidden `code_challenge` would be a value the browser could + * be made to change between the consent screen and the decision, and the + * whole point of PKCE is that the challenge is fixed when authorization + * starts. The form carries only an opaque key and a CSRF token. + */ +trait OAuthEndpoints extends ControllerBase { + self: { def mapper: ObjectMapper } => + + private val PendingPrefix = "mcp-oauth-pending:" + private val CsrfAttribute = "mcp-oauth-csrf" + + /** Resolved once per request; absent means OAuth is not configured. */ + protected def oauthConfig: Option[OAuthConfig] = + OAuthConfig.configuredBaseUrl().flatMap(OAuthConfig.fromBaseUrl(_).toOption) + + protected def oauthConn: Connection = Database.getSession(request).conn + + protected def now(): Instant = Instant.now() + + /** Overridable so tests can drive the fetcher without a network. */ + protected def fetchClient(clientId: String): Either[ClientMetadataError, OAuthClient] = + ClientMetadata.fetch(mapper, clientId) + + // ── discovery ───────────────────────────────────────────────────────────── + + get("/.well-known/oauth-protected-resource") { + withConfig { config => + contentType = "application/json; charset=UTF-8" + mapper.writeValueAsString(Metadata.protectedResource(mapper, config)) + } + } + + get("/.well-known/oauth-authorization-server") { + withConfig { config => + contentType = "application/json; charset=UTF-8" + mapper.writeValueAsString(Metadata.authorizationServer(mapper, config)) + } + } + + // ── authorize ───────────────────────────────────────────────────────────── + + get("/plugin-mcp/oauth/authorize") { + withConfig { config => + context.loginAccount match { + // Not signed in: GitBucket's own login, then back here. The plugin + // never sees a password, and the account that consents is whoever + // GitBucket says is signed in. + case None => + redirect(s"/signin?redirect=${urlEncode(request.getRequestURI + queryString)}") + case Some(account) => + startAuthorization(config, account.userName) + } + } + } + + post("/plugin-mcp/oauth/authorize") { + withConfig { config => + context.loginAccount match { + case None => halt(401, "not signed in") + case Some(account) => completeAuthorization(config, account.userName) + } + } + } + + private def startAuthorization(config: OAuthConfig, userName: String): Any = { + val clientId = param("client_id") + val redirectUri = param("redirect_uri") + val responseType = param("response_type") + val challenge = param("code_challenge") + val method = param("code_challenge_method") + val resource = optionalParam("resource") + val state = optionalParam("state") + + // Errors before a validated redirect_uri cannot be sent to the client: + // redirecting to an unvalidated URI is how an authorization server + // becomes an open redirector. + if (clientId.isEmpty || redirectUri.isEmpty) + return badRequest("client_id and redirect_uri are required") + + fetchClient(clientId) match { + case Left(err) => badRequest(s"client_id rejected: ${err.message}") + case Right(client) if !client.permits(redirectUri) => + badRequest("redirect_uri is not registered for this client") + case Right(client) => + // From here the redirect URI is trusted, so protocol errors go back + // to the client as RFC 6749 requires. + if (responseType != "code") + errorRedirect(config, redirectUri, state, "unsupported_response_type") + else if (method != "S256") + errorRedirect(config, redirectUri, state, "invalid_request") + else if (challenge.isEmpty) + errorRedirect(config, redirectUri, state, "invalid_request") + else if (resource.exists(_ != config.resource)) + errorRedirect(config, redirectUri, state, "invalid_target") + else { + val requested = McpScope.parseRequested(param("scope")) + val scopes = if (requested.isEmpty) McpScope.default else requested + val key = Secrets.newCredential() + val pending = PendingAuthorization(client.clientId, client.clientName, redirectUri, + scopes, state, challenge, resource) + httpSession.setAttribute(PendingPrefix + key, pending) + contentType = "text/html; charset=UTF-8" + ConsentView.render(client, userName, scopes, redirectUri, state, + csrfToken(), s"${config.baseUrl}/plugin-mcp/oauth/authorize?k=${urlEncode(key)}") + } + } + } + + private def completeAuthorization(config: OAuthConfig, userName: String): Any = { + val key = param("k") + val attribute = PendingPrefix + key + val pending = Option(httpSession.getAttribute(attribute)).collect { + case p: PendingAuthorization => p + } + + // One use: the pending request is removed whatever the decision, so a + // resubmitted form cannot mint a second code. + httpSession.removeAttribute(attribute) + + pending match { + case None => badRequest("no authorization in progress") + case Some(p) => + if (!Secrets.constantTimeEquals(param("csrf_token"), csrfToken())) + badRequest("invalid CSRF token") + else if (param("decision") != "allow") + errorRedirect(config, p.redirectUri, p.state, "access_denied") + else { + val conn = oauthConn + val issuedAt = now() + val grantId = OAuthStore.createGrant(conn, userName, p.clientId, config.resource, + p.scopes, issuedAt) + val code = OAuthStore.issueCode(conn, grantId, p.codeChallenge, p.redirectUri, + issuedAt.plusSeconds(config.authorizationCodeLifetimeSeconds)) + val params = Seq( + Some("code=" + urlEncode(code)), + // RFC 9207: name the server that answered, so a response cannot be + // taken from one authorization server and replayed to a client + // that expected another. + Some("iss=" + urlEncode(config.issuer)), + p.state.map(s => "state=" + urlEncode(s)) + ).flatten.mkString("&") + redirect(appendQuery(p.redirectUri, params)) + } + } + } + + // ── token ───────────────────────────────────────────────────────────────── + + post("/plugin-mcp/oauth/token") { + withConfig { config => + contentType = "application/json; charset=UTF-8" + response.setHeader("Cache-Control", "no-store") + val conn = oauthConn + param("grant_type") match { + case "authorization_code" => exchangeCode(config, conn) + case "refresh_token" => exchangeRefresh(config, conn) + case "" => tokenError(400, "invalid_request", "grant_type is required") + case other => tokenError(400, "unsupported_grant_type", s"unsupported grant_type") + } + } + } + + private def exchangeCode(config: OAuthConfig, conn: Connection): String = { + val code = param("code") + val clientId = param("client_id") + val redirectUri = param("redirect_uri") + val verifier = param("code_verifier") + val resource = optionalParam("resource") + if (code.isEmpty || clientId.isEmpty || redirectUri.isEmpty || verifier.isEmpty) + return tokenError(400, "invalid_request", "code, client_id, redirect_uri and code_verifier are required") + if (resource.exists(_ != config.resource)) + return tokenError(400, "invalid_target", "resource does not match this server") + + OAuthStore.redeemCode(conn, code, clientId, redirectUri, Some(config.resource), verifier, now()) match { + case Left(failure) => codeFailure(failure) + case Right(grant) => issueTokens(config, conn, grant) + } + } + + private def exchangeRefresh(config: OAuthConfig, conn: Connection): String = { + val refresh = param("refresh_token") + val clientId = param("client_id") + if (refresh.isEmpty || clientId.isEmpty) + return tokenError(400, "invalid_request", "refresh_token and client_id are required") + + val moment = now() + val requested = Option(param("resource")).filter(_.nonEmpty) + OAuthStore.rotateRefreshToken(conn, refresh, clientId, + moment.plusSeconds(config.refreshTokenLifetimeSeconds), moment, + resource = Some(config.resource), requestedResource = requested) match { + case Left(failure) => refreshFailure(failure) + case Right((grant, replacement)) => + val access = OAuthStore.issueAccessToken(conn, grant.grantId, + moment.plusSeconds(config.accessTokenLifetimeSeconds), moment) + tokenResponse(config, access, Some(replacement), grant.scopes) + } + } + + private def issueTokens(config: OAuthConfig, conn: Connection, grant: ResolvedGrant): String = { + val moment = now() + val access = OAuthStore.issueAccessToken(conn, grant.grantId, + moment.plusSeconds(config.accessTokenLifetimeSeconds), moment) + val refresh = OAuthStore.setRefreshToken(conn, grant.grantId, + moment.plusSeconds(config.refreshTokenLifetimeSeconds), moment) + tokenResponse(config, access, Some(refresh), grant.scopes) + } + + private def tokenResponse(config: OAuthConfig, access: String, refresh: Option[String], + scopes: Set[String]): String = { + val n = mapper.createObjectNode() + n.put("access_token", access) + n.put("token_type", "Bearer") + n.put("expires_in", config.accessTokenLifetimeSeconds) + // Returned so a narrowed grant is visible to the client rather than + // discovered later as a refusal. + n.put("scope", McpScope.render(scopes)) + refresh.foreach(n.put("refresh_token", _)) + mapper.writeValueAsString(n) + } + + /** + * A failed code exchange. + * + * `invalid_grant` for everything the caller could have got wrong about the + * code itself, which is what RFC 6749 §5.2 specifies and also avoids + * telling a prober which part they got right. A binding failure is still a + * binding failure in the store — it does not consume the code and does not + * revoke — so the uniform wire error does not become a uniform effect. + */ + private def codeFailure(failure: GrantFailure): String = failure match { + case GrantFailure.ResourceMismatch => tokenError(400, "invalid_target", "resource does not match") + case _ => tokenError(400, "invalid_grant", "the authorization code is not valid") + } + + private def refreshFailure(failure: GrantFailure): String = + tokenError(400, "invalid_grant", "the refresh token is not valid") + + private def tokenError(status: Int, code: String, description: String): String = { + response.setStatus(status) + val n = mapper.createObjectNode() + n.put("error", code) + n.put("error_description", description) + mapper.writeValueAsString(n) + } + + // ── revoke ──────────────────────────────────────────────────────────────── + + post("/plugin-mcp/oauth/revoke") { + withConfig { _ => + contentType = "application/json; charset=UTF-8" + val token = param("token") + if (token.nonEmpty) OAuthStore.revokeByToken(oauthConn, token, now()) + // RFC 7009 §2.2: an unknown token is a successful revocation. Saying + // otherwise turns this endpoint into an oracle for whether a token + // exists. + response.setStatus(200) + "{}" + } + } + + // ── helpers ─────────────────────────────────────────────────────────────── + + private def withConfig(f: OAuthConfig => Any): Any = oauthConfig match { + case Some(config) => f(config) + case None => + response.setStatus(404) + contentType = "application/json; charset=UTF-8" + """{"error":"oauth_not_configured"}""" + } + + protected def httpSession: HttpSession = request.getSession(true) + + /** A per-session CSRF token, created on first use. */ + protected def csrfToken(): String = { + val s = httpSession + Option(s.getAttribute(CsrfAttribute)).map(_.toString).getOrElse { + val token = Secrets.newCredential() + s.setAttribute(CsrfAttribute, token) + token + } + } + + private def param(name: String): String = + Option(request.getParameter(name)).map(_.trim).getOrElse("") + + private def optionalParam(name: String): Option[String] = + Option(request.getParameter(name)).map(_.trim).filter(_.nonEmpty) + + private def queryString: String = + Option(request.getQueryString).filter(_.nonEmpty).map("?" + _).getOrElse("") + + private def badRequest(message: String): Any = { + response.setStatus(400) + contentType = "text/plain; charset=UTF-8" + message + } + + private def errorRedirect(config: OAuthConfig, redirectUri: String, + state: Option[String], error: String): Any = { + val params = Seq( + Some("error=" + urlEncode(error)), + Some("iss=" + urlEncode(config.issuer)), + state.map(s => "state=" + urlEncode(s)) + ).flatten.mkString("&") + redirect(appendQuery(redirectUri, params)) + } + + private def appendQuery(uri: String, query: String): String = + if (uri.contains("?")) s"$uri&$query" else s"$uri?$query" + + private def urlEncode(value: String): String = + java.net.URLEncoder.encode(value, "UTF-8") +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthStore.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthStore.scala new file mode 100644 index 0000000..c4cf314 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/OAuthStore.scala @@ -0,0 +1,459 @@ +package com.newsrx.mcpplugin.oauth + +import java.sql.{Connection, Timestamp} +import java.time.Instant + +/** + * What a token resolves to: a live consent, by a known account, for a known + * client and resource, carrying a scope set. + */ +final case class ResolvedGrant( + grantId: String, + userName: String, + clientId: String, + resource: String, + scopes: Set[String] +) + +/** Why an exchange or a token presentation was refused. */ +sealed trait GrantFailure +object GrantFailure { + case object NotFound extends GrantFailure + case object Expired extends GrantFailure + case object Revoked extends GrantFailure + case object AlreadyUsed extends GrantFailure + case object ClientMismatch extends GrantFailure + case object RedirectMismatch extends GrantFailure + case object ResourceMismatch extends GrantFailure + case object PkceFailed extends GrantFailure +} + +/** + * Persistence for OAuth grants, codes and tokens. + * + * Plain JDBC rather than Slick, deliberately. Every security-relevant + * operation here is a conditional write whose row count is the answer — + * "consume this code if it is still unconsumed and unexpired" — and the + * guarantee depends on that being one statement. Written as SQL it is + * visible; generated, it would be something to re-derive from the query + * builder every time the question comes up. + * + * The SQL is ANSI and uses no vendor features, so the same statements run on + * the H2 and PostgreSQL backends GitBucket supports. + */ +object OAuthStore { + + // ── grants ──────────────────────────────────────────────────────────────── + + /** + * Record a consent decision and return its id. + * + * A fresh grant per authorization rather than one updated in place: two + * concurrent authorizations by the same user for the same client are then + * two independent consents, and revoking one does not silently revoke the + * other. + */ + def createGrant(conn: Connection, userName: String, clientId: String, + resource: String, scopes: Set[String], now: Instant): String = { + val grantId = Secrets.newCredential() + val sql = + """INSERT INTO MCP_OAUTH_GRANT + |(GRANT_ID, USER_NAME, CLIENT_ID, RESOURCE, SCOPES, REVOKED, CREATED_AT, UPDATED_AT) + |VALUES (?, ?, ?, ?, ?, ?, ?, ?)""".stripMargin + using(conn.prepareStatement(sql)) { st => + st.setString(1, grantId) + st.setString(2, userName) + st.setString(3, clientId) + st.setString(4, resource) + st.setString(5, McpScope.render(scopes)) + st.setBoolean(6, false) + st.setTimestamp(7, Timestamp.from(now)) + st.setTimestamp(8, Timestamp.from(now)) + st.executeUpdate() + } + grantId + } + + def findGrant(conn: Connection, grantId: String): Option[ResolvedGrant] = + using(conn.prepareStatement( + "SELECT USER_NAME, CLIENT_ID, RESOURCE, SCOPES FROM MCP_OAUTH_GRANT WHERE GRANT_ID = ? AND REVOKED = ?")) { st => + st.setString(1, grantId) + st.setBoolean(2, false) + using(st.executeQuery()) { rs => + if (rs.next()) + Some(ResolvedGrant(grantId, rs.getString(1), rs.getString(2), rs.getString(3), + McpScope.parseRequested(rs.getString(4)))) + else None + } + } + + /** + * Revoke a grant. + * + * This is the single revocation primitive. Revoking consent, revoking a + * refresh token and detecting a replayed refresh token all end here, + * because they all mean the same thing: this consent is over. Access tokens + * are not deleted — they are checked against their grant on every request, + * so a revoked grant stops them at the next authorization check without a + * second write to race with. + */ + def revokeGrant(conn: Connection, grantId: String, now: Instant): Boolean = + using(conn.prepareStatement( + "UPDATE MCP_OAUTH_GRANT SET REVOKED = ?, UPDATED_AT = ? WHERE GRANT_ID = ? AND REVOKED = ?")) { st => + st.setBoolean(1, true) + st.setTimestamp(2, Timestamp.from(now)) + st.setString(3, grantId) + st.setBoolean(4, false) + st.executeUpdate() == 1 + } + + /** Every live grant for an account, for a consent-management view. */ + def grantsFor(conn: Connection, userName: String): List[ResolvedGrant] = + using(conn.prepareStatement( + "SELECT GRANT_ID, CLIENT_ID, RESOURCE, SCOPES FROM MCP_OAUTH_GRANT WHERE USER_NAME = ? AND REVOKED = ? ORDER BY CREATED_AT")) { st => + st.setString(1, userName) + st.setBoolean(2, false) + using(st.executeQuery()) { rs => + val out = List.newBuilder[ResolvedGrant] + while (rs.next()) + out += ResolvedGrant(rs.getString(1), userName, rs.getString(2), rs.getString(3), + McpScope.parseRequested(rs.getString(4))) + out.result() + } + } + + // ── authorization codes ─────────────────────────────────────────────────── + + def issueCode(conn: Connection, grantId: String, codeChallenge: String, + redirectUri: String, expiresAt: Instant): String = { + val code = Secrets.newCredential() + using(conn.prepareStatement( + """INSERT INTO MCP_OAUTH_CODE (CODE_HASH, GRANT_ID, CODE_CHALLENGE, REDIRECT_URI, EXPIRES_AT, CONSUMED) + |VALUES (?, ?, ?, ?, ?, ?)""".stripMargin)) { st => + st.setString(1, Secrets.hash(code)) + st.setString(2, grantId) + st.setString(3, codeChallenge) + st.setString(4, redirectUri) + st.setTimestamp(5, Timestamp.from(expiresAt)) + st.setBoolean(6, false) + st.executeUpdate() + } + code + } + + /** + * Redeem an authorization code, once. + * + * The consumption is a conditional UPDATE whose row count decides the + * winner, so two simultaneous exchanges of the same code produce exactly + * one token and one `AlreadyUsed`. Checking a flag and then writing it + * would leave a window between the two in which both callers see an unused + * code; there is no such window here, on either backend, because the + * database serialises the update on the row. + * + * Everything the code was bound to is verified: the client that is asking, + * the redirect URI it claims, the resource it wants, and possession of the + * PKCE verifier. A code is not a bearer credential on its own. + */ + def redeemCode(conn: Connection, code: String, clientId: String, redirectUri: String, + resource: Option[String], codeVerifier: String, + now: Instant): Either[GrantFailure, ResolvedGrant] = { + val hash = Secrets.hash(code) + val row = using(conn.prepareStatement( + """SELECT c.GRANT_ID, c.CODE_CHALLENGE, c.REDIRECT_URI, c.EXPIRES_AT, c.CONSUMED, + | g.USER_NAME, g.CLIENT_ID, g.RESOURCE, g.SCOPES, g.REVOKED + | FROM MCP_OAUTH_CODE c JOIN MCP_OAUTH_GRANT g ON g.GRANT_ID = c.GRANT_ID + | WHERE c.CODE_HASH = ?""".stripMargin)) { st => + st.setString(1, hash) + using(st.executeQuery()) { rs => + if (!rs.next()) None + else Some((rs.getString(1), rs.getString(2), rs.getString(3), rs.getTimestamp(4).toInstant, + rs.getBoolean(5), rs.getString(6), rs.getString(7), rs.getString(8), rs.getString(9), + rs.getBoolean(10))) + } + } + + row match { + case None => Left(GrantFailure.NotFound) + case Some((grantId, challenge, storedRedirect, expiresAt, consumed, userName, grantClient, + grantResource, scopes, revoked)) => + // Bindings first, and before anything is written. + // + // Revoking on a replay only makes sense for a presentation that could + // have come from the legitimate client. Checking `consumed` first gave + // that authority to anyone holding the code: a wrong client id, a + // wrong redirect, a wrong resource or a wrong PKCE verifier all + // reached the revocation and destroyed a live grant. Possession of a + // spent code is not evidence, and an unauthenticated caller must not + // be able to end someone's session with it. + if (revoked) Left(GrantFailure.Revoked) + else if (!Secrets.constantTimeEquals(clientId, grantClient)) Left(GrantFailure.ClientMismatch) + else if (!Secrets.constantTimeEquals(redirectUri, storedRedirect)) Left(GrantFailure.RedirectMismatch) + else if (resource.exists(r => !Secrets.constantTimeEquals(r, grantResource))) + Left(GrantFailure.ResourceMismatch) + else if (!Pkce.verify(codeVerifier, challenge)) Left(GrantFailure.PkceFailed) + // Expiry is not a replay. An expired code buys nothing, but it is also + // not evidence that anything was stolen, so it does not revoke. + else if (!expiresAt.isAfter(now)) Left(GrantFailure.Expired) + else if (consumed) replayed(conn, grantId, now) + else if (consumeCode(conn, hash, now)) + Right(ResolvedGrant(grantId, userName, grantClient, grantResource, + McpScope.parseRequested(scopes))) + // The claim was lost. Everything above says this presentation was + // correctly bound, so whatever took the code did so in a race with a + // request that could have been the legitimate one — the same + // situation as an outright replay, and it gets the same policy. The + // row is re-read rather than assumed, so a claim that failed for + // another reason is not reported as a replay. + else classifyLostClaim(conn, hash, grantId, now) + } + } + + /** The documented reuse policy: the family goes, and the caller is told. */ + private def replayed(conn: Connection, grantId: String, + now: Instant): Either[GrantFailure, ResolvedGrant] = { + // RFC 6749 §10.5 and the OAuth 2.1 guidance: a code presented twice may + // have been stolen, so what it bought is withdrawn. + revokeGrant(conn, grantId, now) + Left(GrantFailure.AlreadyUsed) + } + + /** Why did the conditional claim match no row? */ + private def classifyLostClaim(conn: Connection, codeHash: String, grantId: String, + now: Instant): Either[GrantFailure, ResolvedGrant] = + using(conn.prepareStatement( + "SELECT CONSUMED, EXPIRES_AT FROM MCP_OAUTH_CODE WHERE CODE_HASH = ?")) { st => + st.setString(1, codeHash) + using(st.executeQuery()) { rs => + if (!rs.next()) Left(GrantFailure.NotFound) + else if (rs.getBoolean(1)) replayed(conn, grantId, now) + else if (!rs.getTimestamp(2).toInstant.isAfter(now)) Left(GrantFailure.Expired) + else Left(GrantFailure.NotFound) + } + } + + /** The atomic step: true for exactly one caller. */ + private def consumeCode(conn: Connection, codeHash: String, now: Instant): Boolean = + using(conn.prepareStatement( + "UPDATE MCP_OAUTH_CODE SET CONSUMED = ? WHERE CODE_HASH = ? AND CONSUMED = ? AND EXPIRES_AT > ?")) { st => + st.setBoolean(1, true) + st.setString(2, codeHash) + st.setBoolean(3, false) + st.setTimestamp(4, Timestamp.from(now)) + st.executeUpdate() == 1 + } + + // ── access tokens ───────────────────────────────────────────────────────── + + def issueAccessToken(conn: Connection, grantId: String, expiresAt: Instant, now: Instant): String = { + val token = Secrets.newCredential() + using(conn.prepareStatement( + "INSERT INTO MCP_OAUTH_TOKEN (TOKEN_HASH, GRANT_ID, EXPIRES_AT, CREATED_AT) VALUES (?, ?, ?, ?)")) { st => + st.setString(1, Secrets.hash(token)) + st.setString(2, grantId) + st.setTimestamp(3, Timestamp.from(expiresAt)) + st.setTimestamp(4, Timestamp.from(now)) + st.executeUpdate() + } + token + } + + /** + * Resolve a presented access token. + * + * One query, joined to the grant, so revocation takes effect here rather + * than depending on a sweep having run. The guarantee this provides is + * about the *authorization check*: after a grant is revoked, no later check + * passes. It says nothing about an operation already past its check and + * executing — that one finishes. + */ + def resolveAccessToken(conn: Connection, token: String, now: Instant): Either[GrantFailure, ResolvedGrant] = + using(conn.prepareStatement( + """SELECT t.GRANT_ID, t.EXPIRES_AT, g.USER_NAME, g.CLIENT_ID, g.RESOURCE, g.SCOPES, g.REVOKED + | FROM MCP_OAUTH_TOKEN t JOIN MCP_OAUTH_GRANT g ON g.GRANT_ID = t.GRANT_ID + | WHERE t.TOKEN_HASH = ?""".stripMargin)) { st => + st.setString(1, Secrets.hash(token)) + using(st.executeQuery()) { rs => + if (!rs.next()) Left(GrantFailure.NotFound) + else if (rs.getBoolean(7)) Left(GrantFailure.Revoked) + else if (!rs.getTimestamp(2).toInstant.isAfter(now)) Left(GrantFailure.Expired) + else Right(ResolvedGrant(rs.getString(1), rs.getString(3), rs.getString(4), + rs.getString(5), McpScope.parseRequested(rs.getString(6)))) + } + } + + // ── refresh tokens ──────────────────────────────────────────────────────── + + def setRefreshToken(conn: Connection, grantId: String, expiresAt: Instant, now: Instant): String = { + val refresh = Secrets.newCredential() + insertRefresh(conn, Secrets.hash(refresh), grantId, expiresAt, now) + refresh + } + + private def insertRefresh(conn: Connection, hash: String, grantId: String, + expiresAt: Instant, now: Instant): Unit = + using(conn.prepareStatement( + "INSERT INTO MCP_OAUTH_REFRESH (TOKEN_HASH, GRANT_ID, EXPIRES_AT, ROTATED, CREATED_AT) VALUES (?, ?, ?, ?, ?)")) { st => + st.setString(1, hash) + st.setString(2, grantId) + st.setTimestamp(3, Timestamp.from(expiresAt)) + st.setBoolean(4, false) + st.setTimestamp(5, Timestamp.from(now)) + st.executeUpdate() + } + + /** + * Rotate a refresh token: the presented one stops working as the new one + * starts. + * + * Rotation is a conditional UPDATE marking the presented row, so concurrent + * refreshes resolve to exactly one winner. The loser is not merely refused. + * A token that is present but already rotated is either a race or a stolen + * copy being replayed, and from the server's side those are + * indistinguishable, so the grant is revoked — which is what OAuth 2.1 asks + * for, and why a well-behaved client must not refresh twice in parallel. + * + * A binding failure is a different thing from a replay and is handled + * before any of that: the bindings are checked first, and a presentation + * that fails one neither rotates the token nor revokes the grant. + * + * The superseded rows are kept rather than deleted. That is the point: a + * grant that remembered only its current refresh hash could not tell a + * replayed old token from a string that was never issued, and would answer + * "unknown" to the one case that should end the session. An earlier version + * of this code did exactly that, and the concurrency test above is what + * found it. + */ + /** + * Exchange a refresh token for its successor. + * + * `resource` is the audience this server currently is; `requestedResource` + * is what the client asked for, when it asked. Both are bindings, checked + * like the client id and before anything is written: a grant minted for + * another deployment is not a credential here, however valid it is there. + */ + def rotateRefreshToken(conn: Connection, presented: String, clientId: String, + expiresAt: Instant, now: Instant, + resource: Option[String] = None, + requestedResource: Option[String] = None + ): Either[GrantFailure, (ResolvedGrant, String)] = { + val presentedHash = Secrets.hash(presented) + + // The bindings are checked before anything is written. A refresh token + // presented with the wrong client id is a request this server will not + // answer, but it is not evidence about the token: anyone can send a + // wrong client id, and rotating or revoking on that would let an + // unauthenticated caller destroy a credential the legitimate client is + // still using. Only a correctly bound presentation moves the chain. + val binding = refreshRow(conn, presentedHash) match { + case None => Left(GrantFailure.NotFound) + case Some((grantId, _, _)) => + findGrant(conn, grantId) match { + case None => Left(GrantFailure.Revoked) + case Some(grant) if !Secrets.constantTimeEquals(clientId, grant.clientId) => + Left(GrantFailure.ClientMismatch) + case Some(grant) if resource.exists(r => !Secrets.constantTimeEquals(r, grant.resource)) => + // The grant belongs to a different audience than this server is. + Left(GrantFailure.ResourceMismatch) + case Some(grant) if requestedResource.exists(r => !Secrets.constantTimeEquals(r, grant.resource)) => + Left(GrantFailure.ResourceMismatch) + case Some(grant) => Right(grant) + } + } + + binding.flatMap { grant => + // The single atomic claim: at most one caller can take this token's + // rotation, whatever the scheduling. + val rotated = using(conn.prepareStatement( + "UPDATE MCP_OAUTH_REFRESH SET ROTATED = ? WHERE TOKEN_HASH = ? AND ROTATED = ? AND EXPIRES_AT > ?")) { st => + st.setBoolean(1, true) + st.setString(2, presentedHash) + st.setBoolean(3, false) + st.setTimestamp(4, Timestamp.from(now)) + st.executeUpdate() == 1 + } + + if (rotated) { + val replacement = Secrets.newCredential() + insertRefresh(conn, Secrets.hash(replacement), grant.grantId, expiresAt, now) + Right((grant, replacement)) + } else { + // Read after the failed claim, never before: a concurrent winner that + // commits between a read and the claim would otherwise make a replay + // look like an expiry. That gap made the concurrency control + // intermittently disagree with itself, which is how it was found. + refreshRow(conn, presentedHash) match { + // Present but not rotatable: spent, expired, or both. A replay ends + // the grant; an expiry does not, because it is the client being slow + // rather than a credential being somewhere it should not be. + // + // Both at once is the case that was wrong. A superseded token whose + // own expiry has since passed was treated as a replay and revoked + // the family — so an old token, useless to whoever held it, could + // still destroy the successor the legitimate client was using. Its + // expiry is checked first: once a credential is dead of old age, + // presenting it is not evidence of anything. + case Some((id, rotated, expires)) => + if (!expires.isAfter(now)) Left(GrantFailure.Expired) + else if (rotated) { + revokeGrant(conn, id, now) + Left(GrantFailure.AlreadyUsed) + } else Left(GrantFailure.NotFound) + case None => Left(GrantFailure.NotFound) + } + } + } + } + + /** The grant a refresh token belongs to, and whether it has been rotated. */ + /** The grant a refresh row belongs to, whether it is spent, and when it dies. */ + private def refreshRow(conn: Connection, hash: String): Option[(String, Boolean, Instant)] = + using(conn.prepareStatement( + "SELECT GRANT_ID, ROTATED, EXPIRES_AT FROM MCP_OAUTH_REFRESH WHERE TOKEN_HASH = ?")) { st => + st.setString(1, hash) + using(st.executeQuery())(rs => + if (rs.next()) Some((rs.getString(1), rs.getBoolean(2), rs.getTimestamp(3).toInstant)) + else None) + } + + private def refreshGrantId(conn: Connection, hash: String): Option[String] = + refreshRow(conn, hash).map(_._1) + + /** RFC 7009: revoke by either credential type; both end the grant. */ + def revokeByToken(conn: Connection, token: String, now: Instant): Boolean = { + val hash = Secrets.hash(token) + val byAccess = using(conn.prepareStatement( + "SELECT GRANT_ID FROM MCP_OAUTH_TOKEN WHERE TOKEN_HASH = ?")) { st => + st.setString(1, hash) + using(st.executeQuery())(rs => if (rs.next()) Some(rs.getString(1)) else None) + } + byAccess.orElse(refreshGrantId(conn, hash)) + .exists(revokeGrant(conn, _, now)) + } + + // ── housekeeping ────────────────────────────────────────────────────────── + + /** + * Delete expired codes and tokens. + * + * Hygiene, not a security control: nothing here is what makes an expired + * credential stop working, because every read already compares against the + * clock. If this never runs, the tables grow and the system stays correct. + */ + def purgeExpired(conn: Connection, now: Instant): Int = { + val cutoff = Timestamp.from(now) + val codes = using(conn.prepareStatement("DELETE FROM MCP_OAUTH_CODE WHERE EXPIRES_AT < ?")) { st => + st.setTimestamp(1, cutoff); st.executeUpdate() + } + val tokens = using(conn.prepareStatement("DELETE FROM MCP_OAUTH_TOKEN WHERE EXPIRES_AT < ?")) { st => + st.setTimestamp(1, cutoff); st.executeUpdate() + } + val refresh = using(conn.prepareStatement("DELETE FROM MCP_OAUTH_REFRESH WHERE EXPIRES_AT < ?")) { st => + st.setTimestamp(1, cutoff); st.executeUpdate() + } + codes + tokens + refresh + } + + private def using[A <: AutoCloseable, B](resource: A)(body: A => B): B = + try body(resource) finally resource.close() +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/PinnedConnection.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/PinnedConnection.scala new file mode 100644 index 0000000..37370b1 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/PinnedConnection.scala @@ -0,0 +1,177 @@ +package com.newsrx.mcpplugin.oauth + +import java.io.{ByteArrayOutputStream, IOException, InputStream} +import java.net.{InetAddress, URL} +import java.nio.charset.StandardCharsets + +import javax.net.ssl.HttpsURLConnection +import org.apache.http.client.config.RequestConfig +import org.apache.http.client.methods.HttpGet +import org.apache.http.config.{ConnectionConfig, MessageConstraints, RegistryBuilder} +import org.apache.http.conn.DnsResolver +import org.apache.http.conn.socket.{ConnectionSocketFactory, PlainConnectionSocketFactory} +import org.apache.http.conn.ssl.{DefaultHostnameVerifier, SSLConnectionSocketFactory} +import org.apache.http.impl.client.HttpClients +import org.apache.http.impl.conn.BasicHttpClientConnectionManager + +/** What a pinned request came back with. */ +final case class PinnedResponse(status: Int, body: String) + +/** + * One HTTP request to an address that was decided in advance. + * + * Why the address cannot simply be handed to a URL connection. Checking an + * address and then passing a *name* checks nothing: the connection resolves + * the name again, independently, and that second answer decides where the + * request goes. Verifying afterwards is later still, because a response only + * exists once the request has been sent — and for a server-side request + * forgery, sending it is the whole of the damage. + * + * Neither `HttpURLConnection` nor `java.net.http.HttpClient` can be told which + * address to use. Apache HttpClient can: its `DnsResolver` is consulted for + * the route, so answering with the one address that passed the check is what + * pins the destination. The name still travels in the request, in SNI and in + * the certificate check. + * + * Why the message parsing is not written here. It was, and it was wrong in two + * ways that a hand-written parser is exactly prone to: a body that stopped + * short of its `Content-Length` was returned as though it were complete, and a + * chunk size that did not parse was treated as the terminating zero chunk. In + * both cases a truncated prefix of a document became a valid client + * registration. A complete JSON prefix is not evidence that the HTTP message + * finished (RFC 9112 §6.3, §7.1, §8). httpcore raises + * `ConnectionClosedException` and `MalformedChunkCodingException` for these, + * and it is already on GitBucket's runtime classpath, so this is `compileOnly` + * and nothing is bundled. + * + * What is still deliberately not hand-written: certificate verification. The + * socket factory is the JVM's default HTTPS factory with the default hostname + * verifier, so the usual name check happens against the name rather than + * against the pinned address. Pinning decides where the bytes go; it gives up + * nothing about who must be at the other end. + * + * Redirects are not followed and no proxy is consulted — a proxied request + * goes wherever the proxy decides, which would make destination control an + * illusion. + */ +object PinnedConnection { + + /** Header bounds, restored explicitly after the move to a maintained stack. */ + private val MaxHeaderLine = 8 * 1024 + private val MaxHeaderCount = 100 + + def fetch(url: URL, address: InetAddress, connectTimeoutMs: Int, + readTimeoutMs: Int, maxBytes: Int): PinnedResponse = { + val scheme = Option(url.getProtocol).map(_.toLowerCase).getOrElse("") + + if (scheme == "http" && !address.isLoopbackAddress) + throw new IOException("plain http is only reachable on a loopback address") + if (scheme != "http" && scheme != "https") + throw new IOException(s"unsupported scheme: $scheme") + + // The pin. Every lookup on this client's route answers with the address + // that was checked, so the socket cannot be opened anywhere else. + val pinned = new DnsResolver { + def resolve(host: String): Array[InetAddress] = Array(address) + } + + // The JVM's default HTTPS factory, so a deployment's own trust + // configuration applies unchanged, with the default hostname verifier. + val https = new SSLConnectionSocketFactory( + HttpsURLConnection.getDefaultSSLSocketFactory, new DefaultHostnameVerifier) + val registry = RegistryBuilder.create[ConnectionSocketFactory]() + .register("http", PlainConnectionSocketFactory.getSocketFactory) + .register("https", https) + .build() + + val manager = new BasicHttpClientConnectionManager(registry, null, null, pinned) + + // Explicit, finite header bounds. The connection manager's default + // message constraints are unlimited, which quietly dropped the limits the + // previous transport had: a single 1 MiB header was accepted. These two + // are what the maintained stack offers, and together they bound the whole + // header block -- at most MaxHeaderCount lines of at most MaxHeaderLine + // bytes each. + manager.setConnectionConfig(ConnectionConfig.custom() + .setMessageConstraints(MessageConstraints.custom() + .setMaxLineLength(MaxHeaderLine) + .setMaxHeaderCount(MaxHeaderCount) + .build()) + .build()) + + val config = RequestConfig.custom() + .setConnectTimeout(connectTimeoutMs) + .setConnectionRequestTimeout(connectTimeoutMs) + .setSocketTimeout(readTimeoutMs) + .setRedirectsEnabled(false) + .setCircularRedirectsAllowed(false) + .setProxy(null) + .build() + + // Not `useSystemProperties()`: that would pick up a proxy from the + // environment and send the request through it. + val client = HttpClients.custom() + .setConnectionManager(manager) + .setDefaultRequestConfig(config) + .disableRedirectHandling() + .disableAutomaticRetries() + .disableCookieManagement() + .disableAuthCaching() + .build() + + val get = new HttpGet(url.toURI) + try { + val response = client.execute(get) + var finished = false + try { + val status = response.getStatusLine.getStatusCode + val entity = response.getEntity + val body = + if (entity == null) "" + else readBounded(entity.getContent, maxBytes) + finished = true + PinnedResponse(status, body) + } finally { + // Closing an entity stream that has not been read to its end makes + // Apache consume the rest of the framed body first, so a peer that + // keeps supplying a tail holds the fetch open long after the cap was + // exceeded -- which is exactly what the cap exists to prevent. + // Aborting discards the connection instead, with nothing drained. + if (!finished) try get.abort() catch { case _: Exception => () } + try response.close() catch { case _: Exception => () } + } + } catch { + case e: IOException => throw e + case e: Exception => throw new IOException(e.getMessage, e) + } finally { + try client.close() catch { case _: Exception => () } + try manager.close() catch { case _: Exception => () } + } + } + + /** + * Read the whole body, refusing one that is too large. + * + * Refusing rather than truncating: a cap that silently returns a prefix is + * the same defect as accepting a short body, one step removed. The stream is + * read to its end, so httpcore's own framing checks run — a body that stops + * early raises there rather than arriving here as a short string. + * + * The stream is deliberately not closed here. On the lawful path it has + * already reached its end and the response close releases it; on overflow + * the caller aborts the request instead, because closing a half-read entity + * drains the remainder first. + */ + private def readBounded(in: InputStream, maxBytes: Int): String = { + val out = new ByteArrayOutputStream() + val buf = new Array[Byte](8192) + var n = in.read(buf) + while (n >= 0) { + if (out.size() + n > maxBytes) + throw new IOException(s"client metadata is larger than $maxBytes bytes") + out.write(buf, 0, n) + n = in.read(buf) + } + new String(out.toByteArray, StandardCharsets.UTF_8) + } +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/Pkce.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/Pkce.scala new file mode 100644 index 0000000..89d704b --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/Pkce.scala @@ -0,0 +1,54 @@ +package com.newsrx.mcpplugin.oauth + +import com.nimbusds.oauth2.sdk.pkce.{CodeChallenge, CodeChallengeMethod, CodeVerifier} + +/** + * Proof Key for Code Exchange (RFC 7636), S256 only. + * + * The computation and the verifier's syntax rules come from + * `com.nimbusds:oauth2-oidc-sdk`, which GitBucket already carries on its + * runtime classpath for its own OpenID Connect sign-in. This object is a thin + * adapter: it decides the policy — S256 and nothing else — and converts the + * library's exceptions into a boolean the caller can act on. The base64url + * SHA-256 is the library's, not ours. + * + * The `plain` method is not accepted and not advertised. It protects against + * nothing an attacker who can read the authorization response cannot also do, + * and offering it invites a downgrade: a client that can be talked into + * sending `code_challenge_method=plain` has no protection at all. + */ +object Pkce { + + /** The S256 challenge for a verifier, as RFC 7636 §4.2 defines it. */ + def challengeFor(verifier: String): String = + CodeChallenge.compute(CodeChallengeMethod.S256, new CodeVerifier(verifier)).getValue + + /** + * Whether `verifier` is syntactically a code verifier: 43–128 characters + * from the unreserved set. Nimbus enforces this in `CodeVerifier`'s + * constructor. + */ + def isWellFormedVerifier(verifier: String): Boolean = + try { new CodeVerifier(verifier); true } + catch { case _: IllegalArgumentException | _: NullPointerException => false } + + /** Whether `verifier` proves possession of the key behind `challenge`. */ + def verify(verifier: String, challenge: String): Boolean = + try { + if (challenge == null || challenge.isEmpty) false + else { + val computed = CodeChallenge.compute(CodeChallengeMethod.S256, new CodeVerifier(verifier)) + // Nimbus's CodeChallenge equality is a plain String comparison, so the + // constant-time one is ours. A challenge is not secret, which makes + // this belt-and-braces rather than load-bearing; the same routine is + // used below for values that are secret, and one comparison is easier + // to keep right than two. + Secrets.constantTimeEquals(computed.getValue, challenge) + } + } catch { + case _: IllegalArgumentException | _: NullPointerException => false + } + + /** The method this server accepts, for the metadata document. */ + val supportedMethod: CodeChallengeMethod = CodeChallengeMethod.S256 +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/Scopes.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/Scopes.scala new file mode 100644 index 0000000..1bbf9ed --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/Scopes.scala @@ -0,0 +1,62 @@ +package com.newsrx.mcpplugin.oauth + +/** + * The scopes this authorization server issues. + * + * Two, deliberately. A scope list that mirrors the tool list looks precise and + * is unusable: a client has to request twenty of them, a user has to read + * twenty lines of consent, and nobody refuses one. The distinction that + * actually changes what can happen to a repository is read versus write. + */ +sealed abstract class McpScope(val name: String) { + + /** Whether a grant carrying `granted` is sufficient for this requirement. */ + def satisfiedBy(granted: Set[String]): Boolean +} + +object McpScope { + + /** Read-only tools. */ + case object Read extends McpScope("mcp:read") { + def satisfiedBy(granted: Set[String]): Boolean = + granted.contains(Read.name) || granted.contains(Write.name) + } + + /** + * Mutating tools. + * + * `mcp:write` implies `mcp:read`: a client that may change an issue can + * already read it back, and pretending otherwise would only teach clients to + * request both every time. + */ + case object Write extends McpScope("mcp:write") { + def satisfiedBy(granted: Set[String]): Boolean = granted.contains(Write.name) + } + + val all: Seq[McpScope] = Seq(Read, Write) + + private val byName: Map[String, McpScope] = all.map(s => s.name -> s).toMap + + def byScopeName(name: String): Option[McpScope] = byName.get(name) + + /** + * Parse a space-delimited scope string, keeping only scopes this server + * issues. + * + * RFC 6749 allows a server to issue a narrower scope than was requested, and + * that is what happens here: an unknown scope is dropped rather than + * refused, so a client asking for `mcp:read openid` gets `mcp:read` and a + * working connection instead of an error it cannot act on. The granted set + * is returned to the client in the token response, so the narrowing is + * visible rather than silent. + */ + def parseRequested(raw: String): Set[String] = + Option(raw).getOrElse("").split("\\s+").filter(_.nonEmpty).filter(byName.contains).toSet + + /** The default when a client requests no scope at all: the weaker one. */ + val default: Set[String] = Set(Read.name) + + /** Render a granted set in the canonical order, for a token response. */ + def render(granted: Set[String]): String = + all.map(_.name).filter(granted.contains).mkString(" ") +} diff --git a/src/main/scala/com/newsrx/mcpplugin/oauth/Secrets.scala b/src/main/scala/com/newsrx/mcpplugin/oauth/Secrets.scala new file mode 100644 index 0000000..68e7310 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/oauth/Secrets.scala @@ -0,0 +1,52 @@ +package com.newsrx.mcpplugin.oauth + +import java.nio.charset.StandardCharsets +import java.security.{MessageDigest, SecureRandom} +import java.util.Base64 + +/** + * Generating and comparing the credentials this server issues. + * + * Nothing novel: `SecureRandom` for entropy and SHA-256 for storage, both + * from the JDK. The only decisions here are how much entropy and what gets + * persisted, and the answer to the second is never the credential itself. + */ +object Secrets { + + private val random = new SecureRandom() + + /** + * A new credential: 256 bits, base64url without padding. + * + * Authorization codes, access tokens and refresh tokens all use this. They + * have very different lifetimes but the same requirement — unguessable — + * and a shorter code would only save bytes in a URL nobody reads. + */ + def newCredential(): String = { + val bytes = new Array[Byte](32) + random.nextBytes(bytes) + Base64.getUrlEncoder.withoutPadding.encodeToString(bytes) + } + + /** + * What goes in the database. + * + * A credential is stored as its SHA-256, so a reader of the table cannot + * authenticate with what they find there. SHA-256 rather than a password + * hash on purpose: these are 256-bit random values, not passwords, so there + * is no dictionary to slow down, and a per-request bcrypt would be a + * denial-of-service surface on the hot path. + */ + def hash(credential: String): String = { + val digest = MessageDigest.getInstance("SHA-256") + .digest(credential.getBytes(StandardCharsets.UTF_8)) + digest.map("%02x".format(_)).mkString + } + + /** Constant-time comparison, for values where timing could leak a secret. */ + def constantTimeEquals(a: String, b: String): Boolean = + if (a == null || b == null) false + else MessageDigest.isEqual( + a.getBytes(StandardCharsets.UTF_8), + b.getBytes(StandardCharsets.UTF_8)) +} diff --git a/src/main/scala/com/newsrx/mcpplugin/tools/Authz.scala b/src/main/scala/com/newsrx/mcpplugin/tools/Authz.scala new file mode 100644 index 0000000..73bdb86 --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/tools/Authz.scala @@ -0,0 +1,136 @@ +package com.newsrx.mcpplugin.tools + +import gitbucket.core.model.Account +import gitbucket.core.service.RepositoryService +import gitbucket.core.service.RepositoryService.RepositoryInfo +// The Session type GitBucket's services declare, not `slick.jdbc.JdbcBackend.Session`. +// The latter is the Session of the `JdbcBackend` *object*; the services use the +// profile's path-dependent `backend.Session`. An object Session conforms to it +// when passed, which is why production compiled, but a method declared with the +// narrower type overrides nothing — that is what broke the stubs in the tests. +import gitbucket.core.model.Profile.profile.blockingApi.Session + +/** + * Raised when the authenticated caller may not perform the requested + * operation on the named repository. Distinct from `NoSuchElementException` + * so the controller can map it to its own JSON-RPC error code. + */ +class AuthorizationError(message: String) extends RuntimeException(message) + +/** + * Repository authorization for MCP tool execution. + * + * Authentication alone is not authorization. Before this trait existed, every + * tool resolved `owner`/`repo` straight from the request arguments and read or + * wrote it, so any account that could authenticate to the MCP endpoint could + * reach any repository on the instance, private ones included. These guards + * put each tool back under the same rules GitBucket's own controllers apply. + * + * The rules are GitBucket's, not reimplemented here: the role predicates come + * from `gitbucket.core.service.RepositoryService` (4.48.0, + * `hasGuestRole`/`hasDeveloperRole`/`hasOwnerRole`), and the read rule matches + * what GitBucket's `ReferrerAuthenticator` enforces — a public repository is + * readable by any authenticated account, a private one only by an account with + * at least the guest role. + */ +trait RepositoryAuthorization { self: RepositoryService => + + /** + * The repository, if the caller may read it. + * + * A repository that exists but is not readable and one that does not exist + * are reported the same way on purpose: answering "forbidden" for a private + * repository would confirm its existence to a caller who may not see it. + */ + protected def readableRepository(owner: String, repo: String, account: Account)(implicit + s: Session + ): RepositoryInfo = + getRepository(owner, repo) match { + case Some(info) if canRead(info, account) => info + case _ => + throw new NoSuchElementException(s"repository $owner/$repo not found or not readable") + } + + /** The repository, if the caller may write to it (developer role or above). */ + protected def writableRepository(owner: String, repo: String, account: Account)(implicit + s: Session + ): RepositoryInfo = { + val info = readableRepository(owner, repo, account) + if (!hasDeveloperRole(owner, repo, Some(account))) { + throw new AuthorizationError( + s"${account.userName} does not have write access to $owner/$repo" + ) + } + info + } + + /** True when `account` may read `info`. */ + protected def canRead(info: RepositoryInfo, account: Account)(implicit s: Session): Boolean = + !info.repository.isPrivate || + hasGuestRole(info.repository.userName, info.repository.repositoryName, Some(account)) + + /** + * Whether `account` may open an issue in `info`, under the repository's own + * issue policy. + * + * Read access is not the rule GitBucket applies here. `IssueCreationService. + * isIssueEditable` (4.48.0) branches on `options.issuesOption`, and the + * native creation route consults it before writing. Reading alone therefore + * admitted three cases the server itself refuses: a guest of a PRIVATE-issue + * repository, any reader of a DISABLE repository, and an authenticated + * outsider of a PUBLIC-issue repository. + * + * The branch table is reproduced rather than reused because the native + * predicate needs a `Context` the tool layer does not have. The role + * predicates underneath are still GitBucket's. + */ + protected def canCreateIssue(info: RepositoryInfo, account: Account)(implicit s: Session): Boolean = { + val owner = info.repository.userName + val name = info.repository.repositoryName + info.repository.options.issuesOption match { + // ALL: an authenticated caller, but only where the repository is public. + case "ALL" => !info.repository.isPrivate + case "PUBLIC" => hasGuestRole(owner, name, Some(account)) + case "PRIVATE" => hasDeveloperRole(owner, name, Some(account)) + case "DISABLE" => false + // An unknown setting is refused rather than guessed: a future or + // corrupted value must not open the route by default. + case _ => false + } + } + + /** + * The repository, if the caller may open an issue in it. + * + * Readability is checked first and reported as a missing repository, so a + * policy refusal cannot confirm that a private repository exists. + */ + protected def issuableRepository(owner: String, repo: String, account: Account)(implicit + s: Session + ): RepositoryInfo = { + val info = readableRepository(owner, repo, account) + if (!canCreateIssue(info, account)) { + throw new AuthorizationError( + s"${account.userName} may not open an issue in $owner/$repo under its " + + s"issues policy (${info.repository.options.issuesOption})" + ) + } + info + } + + /** + * Developer role on an arbitrary repository, used where the authorized + * repository is not the one named in the arguments. GitBucket's own + * `update_draft` route checks the *head* repository of a pull request, not + * the base one, and this exists so that check can be reproduced exactly + * rather than approximated. + */ + protected def requireDeveloperRole(owner: String, repo: String, account: Account)(implicit + s: Session + ): Unit = + if (!hasDeveloperRole(owner, repo, Some(account))) { + throw new AuthorizationError( + s"${account.userName} does not have developer access to $owner/$repo" + ) + } +} diff --git a/src/main/scala/com/newsrx/mcpplugin/tools/IdentityTools.scala b/src/main/scala/com/newsrx/mcpplugin/tools/IdentityTools.scala new file mode 100644 index 0000000..e5ad18f --- /dev/null +++ b/src/main/scala/com/newsrx/mcpplugin/tools/IdentityTools.scala @@ -0,0 +1,52 @@ +package com.newsrx.mcpplugin.tools + +import com.fasterxml.jackson.databind.{JsonNode, ObjectMapper} +import com.fasterxml.jackson.databind.node.ObjectNode +import com.newsrx.mcpplugin.PluginDescriptor +import com.newsrx.mcpplugin.oauth.McpScope +import com.newsrx.mcpplugin.mcp.ToolDef +import gitbucket.core.model.Account +import javax.servlet.http.HttpServletRequest + +/** + * Who the server validated this call as. + * + * A client cannot otherwise learn the identity its own credentials resolve + * to: a pull request's `author` is whoever opened it, and a separately + * configured REST credential says nothing about the account behind the MCP + * connector's header. Without this tool an agent can only guess, and a guess + * about identity is exactly what must not appear in a review report. + * + * The account here is the one `MCPController.authenticate` already validated + * for this request, so this is a read of server state, not a second check. + */ +class WhoAmITool extends ToolDef { + val name = "whoami" + val requiredScope = McpScope.Read + val description = + "Return the GitBucket account this MCP connection is authenticated as, plus the self-reported plugin descriptor" + + def inputSchema(mapper: ObjectMapper) = objectSchema(mapper, required = Seq()) + + def execute(args: JsonNode, account: Account, request: HttpServletRequest, mapper: ObjectMapper): JsonNode = { + val n = mapper.createObjectNode() + n.put("login", account.userName) + n.put("full_name", account.fullName) + n.put("email", account.mailAddress) + n.put("is_admin", account.isAdmin) + n.put("is_group_account", account.isGroupAccount) + n.put("is_removed", account.isRemoved) + + val plugin = mapper.createObjectNode() + plugin.put("plugin_id", PluginDescriptor.get("pluginId")) + plugin.put("plugin_name", PluginDescriptor.get("pluginName")) + plugin.put("plugin_version", PluginDescriptor.get("pluginVersion")) + plugin.put("plugin_provider", PluginDescriptor.get("pluginProvider")) + // The descriptor is a string inside the JAR. It is not a build attestation + // and must not be used to identify which source revision produced the JAR. + plugin.put("self_reported", true) + n.set[ObjectNode]("plugin", plugin) + + jsonContent(mapper, n) + } +} diff --git a/src/main/scala/com/newsrx/mcpplugin/tools/IssueTools.scala b/src/main/scala/com/newsrx/mcpplugin/tools/IssueTools.scala index 0c19b24..6bf7acf 100644 --- a/src/main/scala/com/newsrx/mcpplugin/tools/IssueTools.scala +++ b/src/main/scala/com/newsrx/mcpplugin/tools/IssueTools.scala @@ -2,7 +2,8 @@ package com.newsrx.mcpplugin.tools import com.fasterxml.jackson.databind.{JsonNode, ObjectMapper} import com.fasterxml.jackson.databind.node.ObjectNode -import com.newsrx.mcpplugin.mcp.ToolDef +import com.newsrx.mcpplugin.oauth.McpScope +import com.newsrx.mcpplugin.mcp.{StrictArgs, Timestamps, ToolDef} import gitbucket.core.model.{Account, Issue} import gitbucket.core.service.{AccountService, IssuesService, LabelsService, MilestonesService, PrioritiesService, RepositoryService} import gitbucket.core.service.IssuesService.IssueSearchCondition @@ -18,6 +19,7 @@ private[tools] trait IssueService with PrioritiesService with MilestonesService with SessionSupport + with RepositoryAuthorization private[tools] object IssueJson { def issueNode(mapper: ObjectMapper, issue: Issue): ObjectNode = { @@ -28,8 +30,8 @@ private[tools] object IssueJson { n.put("state", if (issue.closed) "closed" else "open") n.put("author", issue.openedUserName) n.put("is_pr", issue.isPullRequest) - n.put("created_at", issue.registeredDate.toString) - n.put("updated_at", issue.updatedDate.toString) + n.put("created_at", Timestamps.iso8601(issue.registeredDate)) + n.put("updated_at", Timestamps.iso8601(issue.updatedDate)) n } } @@ -38,6 +40,7 @@ private[tools] object IssueJson { class ListIssuesTool extends ToolDef with IssueService { val name = "list_issues" + val requiredScope = McpScope.Read val description = "List issues in a GitBucket repository (excludes pull requests)" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -56,6 +59,7 @@ class ListIssuesTool extends ToolDef with IssueService { val limit = math.min(intOpt(args, "limit", 30), 100) implicit val session = blockingSession(request) + readableRepository(owner, repo, account) val condition = new IssueSearchCondition( labels = Set.empty, milestone = None, priority = None, @@ -81,6 +85,7 @@ class ListIssuesTool extends ToolDef with IssueService { class GetIssueTool extends ToolDef with IssueService { val name = "get_issue" + val requiredScope = McpScope.Read val description = "Get details of a specific issue" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -97,6 +102,7 @@ class GetIssueTool extends ToolDef with IssueService { val number = int(args, "number") implicit val session = blockingSession(request) + readableRepository(owner, repo, account) getIssue(owner, repo, number.toString) match { case None => @@ -113,6 +119,7 @@ class GetIssueTool extends ToolDef with IssueService { class CreateIssueTool extends ToolDef with IssueService { val name = "create_issue" + val requiredScope = McpScope.Write val description = "Create a new issue in a GitBucket repository" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -131,6 +138,10 @@ class CreateIssueTool extends ToolDef with IssueService { val body = strOpt(args, "body") implicit val session = blockingSession(request) + // Read access is not the rule: GitBucket branches on the repository's + // `issuesOption` before writing, and reading alone admitted cases the + // server itself refuses. + issuableRepository(owner, repo, account) val issueId = insertIssue(owner, repo, loginUser = account.userName, @@ -154,6 +165,7 @@ class CreateIssueTool extends ToolDef with IssueService { class CloseIssueTool extends ToolDef with IssueService { val name = "close_issue" + val requiredScope = McpScope.Write val description = "Close an issue" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -172,6 +184,7 @@ class CloseIssueTool extends ToolDef with IssueService { val reason = strOpt(args, "reason") implicit val session = blockingSession(request) + writableRepository(owner, repo, account) getIssue(owner, repo, number.toString).getOrElse( throw new NoSuchElementException(s"issue #$number not found in $owner/$repo") @@ -188,6 +201,7 @@ class CloseIssueTool extends ToolDef with IssueService { class ReopenIssueTool extends ToolDef with IssueService { val name = "reopen_issue" + val requiredScope = McpScope.Write val description = "Reopen a closed issue" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -204,6 +218,7 @@ class ReopenIssueTool extends ToolDef with IssueService { val number = int(args, "number") implicit val session = blockingSession(request) + writableRepository(owner, repo, account) getIssue(owner, repo, number.toString).getOrElse( throw new NoSuchElementException(s"issue #$number not found in $owner/$repo") @@ -220,6 +235,7 @@ class ReopenIssueTool extends ToolDef with IssueService { class AddIssueCommentTool extends ToolDef with IssueService { val name = "add_issue_comment" + val requiredScope = McpScope.Write val description = "Add a comment to an issue" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -238,6 +254,7 @@ class AddIssueCommentTool extends ToolDef with IssueService { val body = str(args, "body") implicit val session = blockingSession(request) + writableRepository(owner, repo, account) getIssue(owner, repo, number.toString).getOrElse( throw new NoSuchElementException(s"issue #$number not found in $owner/$repo") @@ -253,3 +270,80 @@ class AddIssueCommentTool extends ToolDef with IssueService { jsonContent(mapper, result) } } + +// ── update_own_comment ────────────────────────────────────────────────────── + +/** + * Edit a comment the caller wrote. + * + * Authorship is enforced here rather than assumed: GitBucket lets a + * repository administrator edit anyone's comment, but a gateway that silently + * exercised that power would make an agent's edits indistinguishable from a + * person's. This tool edits the caller's own comments only, and an admin + * calling it on someone else's comment is refused rather than quietly + * elevated. The saved text is read back and compared before success is + * reported. + */ +class UpdateOwnCommentTool extends ToolDef with IssueService { + val name = "update_own_comment" + val requiredScope = McpScope.Write + val description = "Edit a comment written by the authenticated account, with exact read-back of the stored text" + + def inputSchema(mapper: ObjectMapper) = objectSchema( + mapper, + required = Seq("owner", "repo", "comment_id", "body"), + "owner" -> strNode(mapper, "Repository owner"), + "repo" -> strNode(mapper, "Repository name"), + "comment_id" -> intNode(mapper, "Comment id, as returned by get_thread_comments"), + "body" -> strNode(mapper, "Replacement comment text") + ) + + def execute(args: JsonNode, account: Account, request: HttpServletRequest, mapper: ObjectMapper): JsonNode = { + val owner = str(args, "owner") + val repo = str(args, "repo") + val commentId = StrictArgs.identifier(args, "comment_id") + // Strict: a malformed body must not be coerced into empty text and + // overwrite a real comment. An empty replacement is refused outright, + // since blanking a comment is a deletion wearing an edit's clothes. + val body = StrictArgs.requiredText(args, "body") + + implicit val session = blockingSession(request) + readableRepository(owner, repo, account) + + val comment = getComment(owner, repo, commentId.toString).getOrElse( + throw new NoSuchElementException(s"comment $commentId not found in $owner/$repo") + ) + + if (comment.commentedUserName != account.userName) { + throw new AuthorizationError( + s"comment $commentId was written by ${comment.commentedUserName}; " + + s"${account.userName} may edit only their own comments through this gateway" + ) + } + if (comment.action != "comment") { + throw new IllegalArgumentException( + s"comment $commentId is a '${comment.action}' record, not editable comment text" + ) + } + + updateComment(owner, repo, comment.issueId, commentId, body) + + val saved = getComment(owner, repo, commentId.toString).getOrElse( + throw new IllegalStateException(s"comment $commentId disappeared during update") + ) + if (saved.content != body) { + throw new IllegalStateException( + s"comment $commentId was not stored exactly as supplied" + ) + } + + val n = mapper.createObjectNode() + n.put("comment_id", commentId) + n.put("issue_number", comment.issueId) + n.put("author", saved.commentedUserName) + n.put("body", saved.content) + n.put("body_saved_exactly", true) + n.put("updated_at", Timestamps.iso8601(saved.updatedDate)) + jsonContent(mapper, n) + } +} diff --git a/src/main/scala/com/newsrx/mcpplugin/tools/PullRequestTools.scala b/src/main/scala/com/newsrx/mcpplugin/tools/PullRequestTools.scala index 2d9d891..2dcc8f9 100644 --- a/src/main/scala/com/newsrx/mcpplugin/tools/PullRequestTools.scala +++ b/src/main/scala/com/newsrx/mcpplugin/tools/PullRequestTools.scala @@ -2,8 +2,9 @@ package com.newsrx.mcpplugin.tools import com.fasterxml.jackson.databind.{JsonNode, ObjectMapper} import com.fasterxml.jackson.databind.node.ObjectNode -import com.newsrx.mcpplugin.mcp.ToolDef -import gitbucket.core.model.{Account, Issue, PullRequest} +import com.newsrx.mcpplugin.oauth.McpScope +import com.newsrx.mcpplugin.mcp.{StrictArgs, Timestamps, ToolDef} +import gitbucket.core.model.{Account, Issue, IssueComment, PullRequest} import gitbucket.core.service.{AccountService, ActivityService, CommitsService, IssuesService, LabelsService, MergeService, MilestonesService, PrioritiesService, PullRequestService, RepositoryService, RequestCache, SystemSettingsService, WebHookPullRequestReviewCommentService, WebHookPullRequestService, WebHookService} import gitbucket.core.service.IssuesService.IssueSearchCondition import gitbucket.core.util.JGitUtil.DiffInfo @@ -28,21 +29,81 @@ private[tools] trait PrService with RequestCache with SystemSettingsService with SessionSupport + with RepositoryAuthorization private[tools] object PrJson { - def prNode(mapper: ObjectMapper, issue: Issue, pr: PullRequest): ObjectNode = { + + /** + * A pull request as this gateway reports it. + * + * Commit identities carry GitBucket's stored meaning, verified against + * 4.48.0 rather than guessed from the column names: + * + * - `PullRequest.commitIdTo` is the head commit, resolved by + * `JGitUtil.updatePullRequest` from `refs/pull//head`; + * - `PullRequest.commitIdFrom` is the *merge base* between the base branch + * and the head branch, not the current tip of the base branch. + * + * Calling `commitIdFrom` a "base SHA" would therefore be wrong, so it is + * published as `merge_base_sha`. Both are values stored when the pull + * request was last updated; neither is a live read of a branch tip now, and + * `commit_ids_are_stored_snapshot` says so in the payload rather than only + * in this comment. + * + * `mergedComment` is what GitBucket itself treats as the merge record: the + * issue comment whose action is `merge`, fetched with + * `IssuesService.getMergedComment`. It is passed in rather than read here + * because this object holds no session. + */ + def prNode( + mapper: ObjectMapper, + issue: Issue, + pr: PullRequest, + mergedComment: Option[(IssueComment, Account)] + ): ObjectNode = { val n = mapper.createObjectNode() n.put("number", issue.issueId) n.put("title", issue.title) n.put("body", issue.content.getOrElse("")) n.put("state", if (issue.closed) "closed" else "open") n.put("author", issue.openedUserName) + n.put("base_owner", pr.userName) + n.put("base_repo", pr.repositoryName) n.put("base_branch", pr.branch) - n.put("head_branch", pr.requestBranch) n.put("head_user", pr.requestUserName) + n.put("head_repo", pr.requestRepositoryName) + n.put("head_branch", pr.requestBranch) + n.put("head_sha", pr.commitIdTo) + n.put("merge_base_sha", pr.commitIdFrom) + n.put("commit_ids_are_stored_snapshot", true) n.put("is_draft", pr.isDraft) - n.put("created_at", issue.registeredDate.toString) - n.put("updated_at", issue.updatedDate.toString) + // Merged state comes from the merge *comment*, which is the record + // GitBucket's own API reads (`ApiPullRequest.apply` takes + // `mergedComment` and sets `merged = mergedComment.isDefined`). + // + // This used to be derived from `PullRequest.mergedCommitIds`, and that was + // wrong. Measured on a live 4.48.0 instance: after a merge through + // `PUT /api/v3/.../pulls/:id/merge`, GitBucket answered `merged: true` + // with a `merged_at`, while the column was still empty and this gateway + // answered `merged: false`. Only the web merge route writes that column + // (`PullRequestsController` line 367, for the revert feature); the API + // route does not. A closed pull request that was never merged still + // reports merged=false, which `state` alone cannot say. + n.put("merged", mergedComment.isDefined) + mergedComment.foreach { case (comment, account) => + n.put("merged_at", Timestamps.iso8601(comment.registeredDate)) + n.put("merged_by", account.userName) + } + // The commit ids of the merge, when GitBucket recorded them. Absent on a + // merge performed through the API, so a consumer must not read their + // absence as "not merged" — `merged` is the field that answers that. + pr.mergedCommitIds.map(_.trim).filter(_.nonEmpty).foreach { ids => + val arr = mapper.createArrayNode() + ids.split(",").map(_.trim).filter(_.nonEmpty).foreach(arr.add) + n.set[ObjectNode]("merged_commit_ids", arr) + } + n.put("created_at", Timestamps.iso8601(issue.registeredDate)) + n.put("updated_at", Timestamps.iso8601(issue.updatedDate)) n } } @@ -51,6 +112,7 @@ private[tools] object PrJson { class ListPullRequestsTool extends ToolDef with PrService { val name = "list_pull_requests" + val requiredScope = McpScope.Read val description = "List pull requests in a GitBucket repository" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -77,10 +139,12 @@ class ListPullRequestsTool extends ToolDef with PrService { visibility = None, groups = Set.empty, others = Nil ) + readableRepository(owner, repo, account) + val prs = searchPullRequestByApi(condition, 0, limit, (owner, repo)) val arr = mapper.createArrayNode() prs.foreach { t => - arr.add(PrJson.prNode(mapper, t._1, t._4)) + arr.add(PrJson.prNode(mapper, t._1, t._4, getMergedComment(owner, repo, t._1.issueId))) } val root = mapper.createObjectNode() @@ -94,6 +158,7 @@ class ListPullRequestsTool extends ToolDef with PrService { class GetPullRequestTool extends ToolDef with PrService { val name = "get_pull_request" + val requiredScope = McpScope.Read val description = "Get details of a specific pull request" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -110,12 +175,13 @@ class GetPullRequestTool extends ToolDef with PrService { val number = int(args, "number") implicit val session = blockingSession(request) + readableRepository(owner, repo, account) getPullRequest(owner, repo, number) match { case None => throw new NoSuchElementException(s"pull request #$number not found in $owner/$repo") case Some((issue, pr)) => - val node = PrJson.prNode(mapper, issue, pr) + val node = PrJson.prNode(mapper, issue, pr, getMergedComment(owner, repo, number)) node.put("comment_count", getComments(owner, repo, number).size) jsonContent(mapper, node) } @@ -126,6 +192,7 @@ class GetPullRequestTool extends ToolDef with PrService { class AddPrCommentTool extends ToolDef with PrService { val name = "add_pr_comment" + val requiredScope = McpScope.Write val description = "Add a comment to a pull request" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -144,6 +211,7 @@ class AddPrCommentTool extends ToolDef with PrService { val body = str(args, "body") implicit val session = blockingSession(request) + writableRepository(owner, repo, account) getPullRequest(owner, repo, number).getOrElse( throw new NoSuchElementException(s"pull request #$number not found in $owner/$repo") @@ -164,6 +232,7 @@ class AddPrCommentTool extends ToolDef with PrService { class ClosePullRequestTool extends ToolDef with PrService { val name = "close_pull_request" + val requiredScope = McpScope.Write val description = "Close a pull request without merging" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -182,6 +251,7 @@ class ClosePullRequestTool extends ToolDef with PrService { val reason = strOpt(args, "reason") implicit val session = blockingSession(request) + writableRepository(owner, repo, account) getPullRequest(owner, repo, number).getOrElse( throw new NoSuchElementException(s"pull request #$number not found in $owner/$repo") @@ -198,6 +268,7 @@ class ClosePullRequestTool extends ToolDef with PrService { class ReopenPullRequestTool extends ToolDef with PrService { val name = "reopen_pull_request" + val requiredScope = McpScope.Write val description = "Reopen a closed pull request" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -214,6 +285,7 @@ class ReopenPullRequestTool extends ToolDef with PrService { val number = int(args, "number") implicit val session = blockingSession(request) + writableRepository(owner, repo, account) getPullRequest(owner, repo, number).getOrElse( throw new NoSuchElementException(s"pull request #$number not found in $owner/$repo") @@ -230,6 +302,7 @@ class ReopenPullRequestTool extends ToolDef with PrService { class GetPrDiffTool extends ToolDef with PrService { val name = "get_pr_diff" + val requiredScope = McpScope.Read val description = "Get the list of files changed in a pull request" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -246,6 +319,7 @@ class GetPrDiffTool extends ToolDef with PrService { val number = int(args, "number") implicit val session = blockingSession(request) + readableRepository(owner, repo, account) val (_, pr) = getPullRequest(owner, repo, number).getOrElse( throw new NoSuchElementException(s"pull request #$number not found in $owner/$repo") @@ -275,3 +349,264 @@ class GetPrDiffTool extends ToolDef with PrService { jsonContent(mapper, root) } } + +// ── get_thread_comments ───────────────────────────────────────────────────── + +/** + * The comment bodies of one issue or pull request thread. + * + * `get_pull_request` and `get_issue` report only a `comment_count`, which is + * not a read: an agent asked to act on review remarks cannot see them. This + * returns the text, with the ids and authors needed to answer in the right + * place, and a bounded page so a long thread cannot be pulled in one call. + */ +class GetThreadCommentsTool extends ToolDef with PrService { + val name = "get_thread_comments" + val requiredScope = McpScope.Read + val description = "Read the comments of an issue or pull request thread, with ids, authors and bounded pagination" + + val MaxLimit = 50 + + def inputSchema(mapper: ObjectMapper) = objectSchema( + mapper, + required = Seq("owner", "repo", "number"), + "owner" -> strNode(mapper, "Repository owner"), + "repo" -> strNode(mapper, "Repository name"), + "number" -> intNode(mapper, "Issue or pull request number"), + "offset" -> intNode(mapper, "Comments to skip, oldest first (default: 0)"), + "limit" -> intNode(mapper, s"Maximum comments to return (default: 30, max: $MaxLimit)") + ) + + def execute(args: JsonNode, account: Account, request: HttpServletRequest, mapper: ObjectMapper): JsonNode = { + val owner = str(args, "owner") + val repo = str(args, "repo") + val number = int(args, "number") + val offset = math.max(intOpt(args, "offset", 0), 0) + val limit = math.min(math.max(intOpt(args, "limit", 30), 1), MaxLimit) + + implicit val session = blockingSession(request) + readableRepository(owner, repo, account) + + if (getIssue(owner, repo, number.toString).isEmpty) { + throw new NoSuchElementException(s"issue or pull request #$number not found in $owner/$repo") + } + + // GitBucket records state changes ("close", "reopen", "merge", …) as + // comments too. Those carry no author text, so they are reported with + // their action rather than silently dropped: a thread with the deletions + // hidden would misrepresent what happened. + val all = getComments(owner, repo, number) + val page = all.slice(offset, offset + limit) + + val arr = mapper.createArrayNode() + page.foreach { c => + val n = mapper.createObjectNode() + n.put("comment_id", c.commentId) + n.put("author", c.commentedUserName) + n.put("action", c.action) + n.put("body", c.content) + n.put("created_at", Timestamps.iso8601(c.registeredDate)) + n.put("updated_at", Timestamps.iso8601(c.updatedDate)) + arr.add(n) + } + + val root = mapper.createObjectNode() + root.put("number", number) + root.put("total_count", all.size) + root.put("offset", offset) + root.put("returned", page.size) + root.put("has_more", offset + page.size < all.size) + root.put("next_offset", offset + page.size) + root.set[ObjectNode]("comments", arr) + jsonContent(mapper, root) + } +} + +// ── update_pull_request ───────────────────────────────────────────────────── + +/** + * Change a pull request's title or body, and nothing else. + * + * GitBucket's `updateIssue` takes both title and content and writes both, so + * an omitted argument would blank the other field. The current value is read + * first and passed through unchanged, and the saved row is read back and + * compared, because this installation has already answered 200 to a REST + * PATCH whose field it then ignored. Branches are never touched. + */ +class UpdatePullRequestTool extends ToolDef with PrService { + val name = "update_pull_request" + val requiredScope = McpScope.Write + val description = "Update the title and/or body of a pull request, preserving the field that is not supplied" + + def inputSchema(mapper: ObjectMapper) = objectSchema( + mapper, + required = Seq("owner", "repo", "number"), + "owner" -> strNode(mapper, "Repository owner"), + "repo" -> strNode(mapper, "Repository name"), + "number" -> intNode(mapper, "Pull request number"), + "title" -> strNode(mapper, "New title; omit to keep the current one"), + "body" -> strNode(mapper, "New body; omit to keep the current one") + ) + + def execute(args: JsonNode, account: Account, request: HttpServletRequest, mapper: ObjectMapper): JsonNode = { + val owner = str(args, "owner") + val repo = str(args, "repo") + // Strict identifier: the inherited `int` coerces 1.9, 4294967297, "1" and + // true all to 1, which would send the edit to pull request 1. + val number = StrictArgs.identifier(args, "number") + // Read through the strict helpers, not the coercing ones: a malformed + // `body` must not become an empty string and erase the description. + // An omitted field and a supplied empty string are different requests, + // so only a JSON string counts as supplied. + val newTitle = StrictArgs.textOpt(args, "title") + val newBody = StrictArgs.textOpt(args, "body") + + if (newTitle.isEmpty && newBody.isEmpty) { + throw new IllegalArgumentException("supply at least one of: title, body") + } + // Empty-title policy: a pull request must keep a title, so an empty one is + // refused. An empty body is accepted, because clearing a description is a + // normal edit and there is no equivalent reason to forbid it. + if (newTitle.contains("")) { + throw new IllegalArgumentException("argument 'title' must not be empty") + } + + implicit val session = blockingSession(request) + writableRepository(owner, repo, account) + + val (issue, _) = getPullRequest(owner, repo, number).getOrElse( + throw new NoSuchElementException(s"pull request #$number not found in $owner/$repo") + ) + + val title = newTitle.getOrElse(issue.title) + val content = newBody.orElse(issue.content) + + updateIssue(owner, repo, number, title, content) + + // Read back and compare the stored bytes. A write that reports success + // without this proves nothing about what was saved. + val (saved, savedPr) = getPullRequest(owner, repo, number).getOrElse( + throw new IllegalStateException(s"pull request #$number disappeared during update") + ) + val titleOk = saved.title == title + val bodyOk = saved.content.getOrElse("") == content.getOrElse("") + + val root = PrJson.prNode(mapper, saved, savedPr, getMergedComment(owner, repo, number)) + root.put("title_saved_exactly", titleOk) + root.put("body_saved_exactly", bodyOk) + if (!titleOk || !bodyOk) { + throw new IllegalStateException( + s"update of pull request #$number was not stored exactly: " + + s"title_saved_exactly=$titleOk body_saved_exactly=$bodyOk" + ) + } + jsonContent(mapper, root) + } +} + +// ── mark_ready_for_review ─────────────────────────────────────────────────── + +/** + * Take a draft pull request out of draft, using GitBucket's own operation. + * + * `PullRequestService.updateDraftToPullRequest` (4.48.0) writes `isDraft = + * false` and nothing else. It is one-way: it never sets a pull request back to + * draft, so repeating this call preserves the ready state rather than toggling + * it. GitBucket's `update_draft` route fires no hook or event, and this does + * not add one. + * + * Authorization reproduces that route exactly, including the part that is easy + * to get wrong: read access to the *base* repository plus the developer role + * on the pull request's *head* repository, which for a fork is a different + * repository from the one named in the arguments. + * + * Race guarantee, stated precisely: `expected_head_sha` is compared against + * the stored head before the transition and the stored head is returned after + * it, both inside the request's transaction, but this is a check followed by a + * write and not an atomic compare-and-swap. A push that lands between them is + * not prevented. Do not describe it as compare-and-swap. + */ +class MarkReadyForReviewTool extends ToolDef with PrService { + val name = "mark_ready_for_review" + val requiredScope = McpScope.Write + val description = "Take an open, unmerged draft pull request out of draft using GitBucket's native operation" + + def inputSchema(mapper: ObjectMapper) = objectSchema( + mapper, + required = Seq("owner", "repo", "number"), + "owner" -> strNode(mapper, "Repository owner of the base repository"), + "repo" -> strNode(mapper, "Base repository name"), + "number" -> intNode(mapper, "Pull request number"), + "expected_head_sha" -> strNode( + mapper, + "Full 40-character commit id. If given, refuse when the stored head differs. " + + "Checked before the write, not atomically with it." + ) + ) + + def execute(args: JsonNode, account: Account, request: HttpServletRequest, mapper: ObjectMapper): JsonNode = { + val owner = str(args, "owner") + val repo = str(args, "repo") + val number = StrictArgs.identifier(args, "number") + // A supplied precondition is validated, never discarded: silently + // dropping a malformed one would perform the unguarded write the caller + // explicitly asked to avoid. + val expected = StrictArgs.commitIdOpt(args, "expected_head_sha") + + implicit val session = blockingSession(request) + + // Base repository must be readable by the caller; the write permission + // that matters lives on the head repository, checked below. + readableRepository(owner, repo, account) + + val (issue, pr) = getPullRequest(owner, repo, number).getOrElse( + throw new NoSuchElementException(s"pull request #$number not found in $owner/$repo") + ) + + requireDeveloperRole(pr.requestUserName, pr.requestRepositoryName, account) + + if (issue.closed) { + throw new IllegalArgumentException( + s"pull request #$number is closed; only an open pull request can be marked ready" + ) + } + // Merged is read from the merge comment, the same record GitBucket's own + // API reads. `mergedCommitIds` is not written by the API merge route, so + // testing it here would have let a merged pull request through whenever it + // had somehow been reopened. + if (getMergedComment(owner, repo, number).isDefined) { + throw new IllegalArgumentException( + s"pull request #$number is merged; only an unmerged pull request can be marked ready" + ) + } + expected.foreach { want => + if (!want.equalsIgnoreCase(pr.commitIdTo)) { + throw new IllegalArgumentException( + s"stale expected_head_sha: pull request #$number records head ${pr.commitIdTo}, caller expected $want" + ) + } + } + + val wasDraft = pr.isDraft + // Already-ready is not an error: the requested end state is the same, and + // the native operation is one-way, so calling it again changes nothing. + if (wasDraft) { + updateDraftToPullRequest(owner, repo, number) + } + + val (afterIssue, afterPr) = getPullRequest(owner, repo, number).getOrElse( + throw new IllegalStateException(s"pull request #$number disappeared during the transition") + ) + + val root = PrJson.prNode(mapper, afterIssue, afterPr, getMergedComment(owner, repo, number)) + root.put("was_draft", wasDraft) + root.put("changed", wasDraft && !afterPr.isDraft) + root.put("race_guarantee", "checked-then-written; not compare-and-swap") + if (afterPr.isDraft) { + throw new IllegalStateException( + s"pull request #$number is still a draft after the native transition" + ) + } + jsonContent(mapper, root) + } +} diff --git a/src/main/scala/com/newsrx/mcpplugin/tools/RepositoryTools.scala b/src/main/scala/com/newsrx/mcpplugin/tools/RepositoryTools.scala index f2af37b..039f06a 100644 --- a/src/main/scala/com/newsrx/mcpplugin/tools/RepositoryTools.scala +++ b/src/main/scala/com/newsrx/mcpplugin/tools/RepositoryTools.scala @@ -2,6 +2,7 @@ package com.newsrx.mcpplugin.tools import com.fasterxml.jackson.databind.{JsonNode, ObjectMapper} import com.fasterxml.jackson.databind.node.ObjectNode +import com.newsrx.mcpplugin.oauth.McpScope import com.newsrx.mcpplugin.mcp.ToolDef import gitbucket.core.model.Account import gitbucket.core.service.{AccountService, RepositoryService} @@ -11,45 +12,104 @@ private[tools] trait RepoService extends RepositoryService with AccountService with SessionSupport + with RepositoryAuthorization // ── list_repositories ─────────────────────────────────────────────────────── class ListRepositoriesTool extends ToolDef with RepoService { val name = "list_repositories" + val requiredScope = McpScope.Read val description = "List repositories accessible to a GitBucket user" def inputSchema(mapper: ObjectMapper) = objectSchema( mapper, required = Seq("owner"), "owner" -> strNode(mapper, "User or organization name"), - "without_forked" -> boolNode(mapper, "Exclude forked repositories (default: false)") + "without_forked" -> boolNode(mapper, "Exclude repositories that are themselves forks (default: false)") ) def execute(args: JsonNode, account: Account, request: HttpServletRequest, mapper: ObjectMapper): JsonNode = { - val owner = str(args, "owner") + val owner = str(args, "owner") val withoutForked = bool(args, "without_forked", default = false) implicit val session = blockingSession(request) - val repos = getUserRepositories(owner, withoutForked) - val arr = mapper.createArrayNode() - repos.foreach { info => - val r = info.repository - val n = mapper.createObjectNode() - n.put("name", r.repositoryName) - n.put("owner", r.userName) - n.put("description", r.description.getOrElse("")) - n.put("is_private", r.isPrivate) - n.put("default_branch", r.defaultBranch) - n.put("issue_count", info.issueCount) - n.put("pr_count", info.pullCount) - n.put("fork_count", info.forkedCount) - arr.add(n) + // Enumerate without physical information. That second argument is + // `withoutPhysicalInfo`, not a fork filter: passing the caller's + // `without_forked` into it skipped the Git reads and published + // GitBucket's -1 placeholder as a fork count. Here it is deliberately + // true, because this pass only decides *which* repositories the caller + // may see; nothing from it is published. + val candidates = getUserRepositories(owner, withoutPhysicalInfo = true) + + // `getUserRepositories` answers for `owner`, not for the caller: without + // this filter the listing hands every private repository of any account to + // anyone who can authenticate. Each entry is kept only if the caller may + // read it under GitBucket's own rule. + val visible = candidates.filter(canRead(_, account)) + + // GitBucket's own fork test, the one its REST API uses: + // `fork = repository.originUserName.isDefined`. A fork *count* says how + // many forks exist of this lineage and is no indication that this + // repository is itself a fork. + val selected = + if (withoutForked) visible.filterNot(_.repository.originUserName.isDefined) else visible + + // Counts come from GitBucket's own detail read, for the repositories the + // caller may read and no others. `createRepositoryInfo`, which the + // enumeration above uses, builds a RepositoryInfo through the constructor + // GitBucket documents as "without issue, pull request, and milestone + // count" -- those fields are 0 because nothing counted them, not because + // the repository is empty. Publishing them as measurements reported every + // repository as having no issues and no pull requests. + // + // The cost: one native detail read per *readable* repository, in place of + // the physical read the enumeration used to perform for every repository + // including the ones the caller cannot see. + val arr = mapper.createArrayNode() + var published = 0 + selected.foreach { candidate => + val r = candidate.repository + // The record that gets published is authorized, not the one that was + // enumerated. Those are two separate reads, and between them a + // repository can become private: the enumeration snapshot said public, + // the detail read returns the new private description and counts, and + // publishing that under the earlier decision discloses it. The early + // filter above still has its own job -- it keeps repositories the caller + // never had access to from being read at all -- but it cannot speak for + // a record it has not seen. + // + // A repository that stops being readable in between is omitted, and the + // count is of what was published, so the two stay consistent. This + // claims no atomicity: a decision taken before a change cannot be + // withdrawn afterwards. It only refuses to attach an old decision to + // newly read data. + getRepository(r.userName, r.repositoryName).filter(canRead(_, account)).foreach { info => + val n = mapper.createObjectNode() + n.put("name", info.repository.repositoryName) + n.put("owner", info.repository.userName) + n.put("description", info.repository.description.getOrElse("")) + n.put("is_private", info.repository.isPrivate) + n.put("default_branch", info.repository.defaultBranch) + n.put("issue_count", info.issueCount) + n.put("pr_count", info.pullCount) + n.put("fork_count", info.forkedCount) + n.put("is_fork", info.repository.originUserName.isDefined) + arr.add(n) + published += 1 + } } val root = mapper.createObjectNode() - root.put("count", repos.size) + root.put("count", published) root.set[ObjectNode]("repositories", arr) + // The counters mean what GitBucket means by them, which is narrower than + // the names suggest, so the payload says so rather than leaving a reader + // to assume totals. + root.put("issue_count_semantics", "open issues, excluding pull requests") + root.put("pr_count_semantics", "open pull requests") + root.put("fork_count_semantics", + "forks of this repository's origin; not a flag that this repository is a fork") jsonContent(mapper, root) } } @@ -58,6 +118,7 @@ class ListRepositoriesTool extends ToolDef with RepoService { class GetRepositoryTool extends ToolDef with RepoService { val name = "get_repository" + val requiredScope = McpScope.Read val description = "Get details of a specific GitBucket repository" def inputSchema(mapper: ObjectMapper) = objectSchema( @@ -73,10 +134,8 @@ class GetRepositoryTool extends ToolDef with RepoService { implicit val session = blockingSession(request) - getRepository(owner, repo) match { - case None => - throw new NoSuchElementException(s"repository $owner/$repo not found") - case Some(info) => + readableRepository(owner, repo, account) match { + case info => val r = info.repository val n = mapper.createObjectNode() n.put("name", r.repositoryName) @@ -87,6 +146,11 @@ class GetRepositoryTool extends ToolDef with RepoService { n.put("issue_count", info.issueCount) n.put("pr_count", info.pullCount) n.put("fork_count", info.forkedCount) + n.put("is_fork", r.originUserName.isDefined) + n.put("issue_count_semantics", "open issues, excluding pull requests") + n.put("pr_count_semantics", "open pull requests") + n.put("fork_count_semantics", + "forks of this repository's origin; not a flag that this repository is a fork") val branches = mapper.createArrayNode() info.branchList.foreach(branches.add) diff --git a/src/test/resources/cimd-test-server.p12 b/src/test/resources/cimd-test-server.p12 new file mode 100644 index 0000000..604bb6a Binary files /dev/null and b/src/test/resources/cimd-test-server.p12 differ diff --git a/src/test/scala/com/newsrx/mcpplugin/PluginEntryPointSpec.scala b/src/test/scala/com/newsrx/mcpplugin/PluginEntryPointSpec.scala new file mode 100644 index 0000000..d5de8c6 --- /dev/null +++ b/src/test/scala/com/newsrx/mcpplugin/PluginEntryPointSpec.scala @@ -0,0 +1,49 @@ +package com.newsrx.mcpplugin + +import org.junit.runner.RunWith +import org.scalatestplus.junit.JUnitRunner +import org.scalatest.funsuite.AnyFunSuite +import org.scalatest.matchers.should.Matchers + +/** + * What GitBucket actually loads. + * + * GitBucket loads the root-package class named `Plugin` by name. Everything + * the plugin declares — its schema versions, the paths that work without a + * session, its controllers — is read from that object and from nowhere else. + * + * These cases are deliberately about the entry point rather than about + * `MCPPlugin`: a second plugin class that looks authoritative but is never + * loaded is exactly how a migration can be declared, committed, tested and + * still never run. + */ +@RunWith(classOf[JUnitRunner]) +class PluginEntryPointSpec extends AnyFunSuite with Matchers { + + private val loaded = Class.forName("Plugin").getDeclaredConstructor().newInstance() + .asInstanceOf[gitbucket.core.plugin.Plugin] + + test("the class GitBucket loads is this plugin") { + loaded.pluginId shouldBe "mcp-plugin" + } + + test("the loaded class declares the OAuth schema migration") { + // Solidbase migrates up to the last declared version and GitBucket then + // requires the recorded version to equal it, so the migration has to be + // declared on this class to run at all. + loaded.versions.map(_.getVersion) should contain("1.0") + loaded.versions.last.getVersion shouldBe "1.0" + loaded.versions.last.getMigrations should not be empty + } + + test("the loaded class opens the paths a client needs before it has a token") { + val paths = loaded.anonymousAccessiblePaths(null, null, null) + paths should contain allOf ( + "/.well-known/oauth-protected-resource", + "/.well-known/oauth-authorization-server", + "/plugin-mcp/oauth/token", + "/plugin-mcp/oauth/revoke") + // The consent screen is the one endpoint that must know who is signed in. + paths should not contain "/plugin-mcp/oauth/authorize" + } +} diff --git a/src/test/scala/com/newsrx/mcpplugin/RepositoryAuthorizationSpec.scala b/src/test/scala/com/newsrx/mcpplugin/RepositoryAuthorizationSpec.scala new file mode 100644 index 0000000..6187c4e --- /dev/null +++ b/src/test/scala/com/newsrx/mcpplugin/RepositoryAuthorizationSpec.scala @@ -0,0 +1,259 @@ +package com.newsrx.mcpplugin + +import com.newsrx.mcpplugin.tools.{AuthorizationError, RepositoryAuthorization} +import gitbucket.core.model.{Account, Repository, RepositoryOptions} +import gitbucket.core.service.{AccountService, RepositoryService} +import gitbucket.core.service.RepositoryService.RepositoryInfo +import org.junit.runner.RunWith +import org.scalatestplus.junit.JUnitRunner +import org.scalatest.funsuite.AnyFunSuite +import org.scalatest.matchers.should.Matchers +import gitbucket.core.model.Profile.profile.blockingApi.Session + +/** + * Fixtures for exercising authorization without a database. + * + * The role predicates are GitBucket's and are stubbed here, so these controls + * verify that the guard consults them and obeys their verdict, and that the + * refusal shape is right. They do not re-verify GitBucket's own role + * computation; that needs a live instance and is listed in the runbook. + */ +object AuthzFixtures { + private val epoch = new java.util.Date(0L) + + private val options = RepositoryOptions( + issuesOption = "PUBLIC", + externalIssuesUrl = None, + wikiOption = "PUBLIC", + externalWikiUrl = None, + allowFork = true, + mergeOptions = "merge-commit", + defaultMergeOption = "merge-commit", + safeMode = false + ) + + def repository(owner: String, name: String, isPrivate: Boolean): Repository = + Repository( + userName = owner, + repositoryName = name, + isPrivate = isPrivate, + description = None, + defaultBranch = "main", + registeredDate = epoch, + updatedDate = epoch, + lastActivityDate = epoch, + originUserName = None, + originRepositoryName = None, + parentUserName = None, + parentRepositoryName = None, + options = options + ) + + /** + * Named `repoInfo`, not `info`: a ScalaTest suite already inherits an + * `info: Informer`, and wildcard-importing a fixture helper of the same + * name loses to the inherited member, so the call resolved to `Informer` + * and reported "unknown parameter name isPrivate". + */ + def repoInfo(owner: String, name: String, isPrivate: Boolean): RepositoryInfo = + RepositoryInfo( + owner = owner, + name = name, + repository = repository(owner, name, isPrivate), + issueCount = 0, + pullCount = 0, + forkedCount = 0, + milestoneCount = 0, + branchList = Seq("main"), + tags = Nil, + managers = Nil + ) + + def account(name: String, admin: Boolean = false): Account = + Account( + userName = name, + fullName = name, + mailAddress = s"$name@example.com", + password = "", + isAdmin = admin, + url = None, + registeredDate = epoch, + updatedDate = epoch, + lastLoginDate = None, + image = None, + isGroupAccount = false, + isRemoved = false, + description = None + ) +} + +/** + * A world of repositories and roles, with GitBucket's data access replaced. + * + * `guests` and `developers` name the accounts holding each role, so a test can + * state a permission matrix directly. The session is never dereferenced: every + * method that would touch it is overridden. + */ +class StubAuthz( + repositories: Map[(String, String), RepositoryInfo], + guests: Set[(String, String, String)] = Set.empty, + developers: Set[(String, String, String)] = Set.empty +) extends RepositoryService + // `RepositoryService` has a self-type of `AccountService`, so it must be + // mixed in even though none of its queries run here. + with AccountService + with RepositoryAuthorization { + + override def getRepository(userName: String, repositoryName: String)(implicit + s: Session + ): Option[RepositoryInfo] = + repositories.get((userName, repositoryName)) + + override def hasGuestRole(owner: String, repository: String, loginAccount: Option[Account])(implicit + s: Session + ): Boolean = + loginAccount.exists { a => + a.isAdmin || guests.contains((owner, repository, a.userName)) || + developers.contains((owner, repository, a.userName)) + } + + override def hasDeveloperRole(owner: String, repository: String, loginAccount: Option[Account])(implicit + s: Session + ): Boolean = + loginAccount.exists(a => a.isAdmin || developers.contains((owner, repository, a.userName))) + + // Exposed so the controls can call the protected guards directly. + def readable(owner: String, repo: String, account: Account)(implicit s: Session): RepositoryInfo = + readableRepository(owner, repo, account) + + def writable(owner: String, repo: String, account: Account)(implicit s: Session): RepositoryInfo = + writableRepository(owner, repo, account) + + def visible(info: RepositoryInfo, account: Account)(implicit s: Session): Boolean = + canRead(info, account) + + def requireDeveloper(owner: String, repo: String, account: Account)(implicit s: Session): Unit = + requireDeveloperRole(owner, repo, account) +} + +@RunWith(classOf[JUnitRunner]) +class RepositoryAuthorizationSpec extends AnyFunSuite with Matchers { + + import AuthzFixtures._ + + private implicit val session: Session = null + + private val publicRepo = repoInfo("example-org", "public-repo", isPrivate = false) + private val privateRepo = repoInfo("example-org", "private-repo", isPrivate = true) + private val repos = Map( + ("example-org", "public-repo") -> publicRepo, + ("example-org", "private-repo") -> privateRepo + ) + + private val outsider = account("outsider") + private val guest = account("guest") + private val developer = account("developer") + private val admin = account("admin", admin = true) + + private def world = new StubAuthz( + repos, + guests = Set(("example-org", "private-repo", "guest")), + developers = Set(("example-org", "private-repo", "developer"), ("example-org", "public-repo", "developer")) + ) + + // ── read ────────────────────────────────────────────────────────────────── + + test("a public repository is readable by any authenticated account") { + world.readable("example-org", "public-repo", outsider).name shouldBe "public-repo" + } + + test("a private repository is not readable without a role") { + a[NoSuchElementException] should be thrownBy world.readable("example-org", "private-repo", outsider) + } + + test("a private repository is readable with the guest role") { + world.readable("example-org", "private-repo", guest).name shouldBe "private-repo" + } + + test("an admin can read a private repository") { + world.readable("example-org", "private-repo", admin).name shouldBe "private-repo" + } + + test("an inaccessible private repository is indistinguishable from a missing one") { + // The point of the control: a caller who may not see the repository must + // not be able to infer that it exists from a different error. + val denied = the[NoSuchElementException] thrownBy world.readable("example-org", "private-repo", outsider) + val missing = the[NoSuchElementException] thrownBy world.readable("example-org", "no-such-repo", outsider) + denied.getClass shouldBe missing.getClass + denied.getMessage.replace("private-repo", "X") shouldBe + missing.getMessage.replace("no-such-repo", "X") + } + + test("a denial does not leak the private flag or any repository detail") { + val denied = the[NoSuchElementException] thrownBy world.readable("example-org", "private-repo", outsider) + denied.getMessage.toLowerCase should not include "private=true" + denied.getMessage.toLowerCase should not include "forbidden" + } + + // ── write ───────────────────────────────────────────────────────────────── + + test("a guest cannot write to a repository they can read") { + // Read access and write access are separate verdicts; conflating them is + // how a reader would gain the ability to comment or close. + world.readable("example-org", "private-repo", guest).name shouldBe "private-repo" + an[AuthorizationError] should be thrownBy world.writable("example-org", "private-repo", guest) + } + + test("a developer can write") { + world.writable("example-org", "private-repo", developer).name shouldBe "private-repo" + } + + test("an outsider writing to a public repository is refused as a write, not as a read") { + // The repository is readable, so the failure must be the write verdict. + world.readable("example-org", "public-repo", outsider).name shouldBe "public-repo" + an[AuthorizationError] should be thrownBy world.writable("example-org", "public-repo", outsider) + } + + test("a write to an unreadable repository is refused before the write verdict") { + // Order matters: answering AuthorizationError here would confirm that the + // private repository exists. + a[NoSuchElementException] should be thrownBy world.writable("example-org", "private-repo", outsider) + } + + // ── listing filter ──────────────────────────────────────────────────────── + + test("canRead filters a listing to what the caller may see") { + val w = world + val all = Seq(publicRepo, privateRepo) + all.filter(w.visible(_, outsider)).map(_.name) shouldBe Seq("public-repo") + all.filter(w.visible(_, guest)).map(_.name) should contain theSameElementsAs Seq( + "public-repo", + "private-repo" + ) + all.filter(w.visible(_, admin)).map(_.name) should have size 2 + } + + // ── explicit developer check on a named repository ──────────────────────── + + test("requireDeveloperRole applies to the repository it is given, not the one being read") { + // The readiness transition needs the developer role on the *head* + // repository of a fork, which is a different repository from the base. + val w = world + noException should be thrownBy w.requireDeveloper("example-org", "private-repo", developer) + an[AuthorizationError] should be thrownBy w.requireDeveloper("example-org", "private-repo", guest) + } + + // ── sensitivity ─────────────────────────────────────────────────────────── + + // An earlier version of this file ended with a "sensitivity" case that built + // a variant whose read rule ignored privacy and then asserted that the + // outsider got in. It was removed: a passing test whose assertion is that + // unauthorized access succeeds reads as a sanctioned behaviour, and it + // demonstrated nothing about the tools, only about a subclass written for + // the occasion. + // + // What it was reaching for is now done against the real code, by mutating + // the production source rather than a test double: see + // `ToolExecutionSpec`, which drives the tools' own `execute`, and the + // mutation record in `docs/validation-runbook.md`. +} diff --git a/src/test/scala/com/newsrx/mcpplugin/StrictArgsSpec.scala b/src/test/scala/com/newsrx/mcpplugin/StrictArgsSpec.scala new file mode 100644 index 0000000..7038436 --- /dev/null +++ b/src/test/scala/com/newsrx/mcpplugin/StrictArgsSpec.scala @@ -0,0 +1,144 @@ +package com.newsrx.mcpplugin + +import com.fasterxml.jackson.databind.ObjectMapper +import com.newsrx.mcpplugin.mcp.StrictArgs +import org.junit.runner.RunWith +import org.scalatestplus.junit.JUnitRunner +import org.scalatest.funsuite.AnyFunSuite +import org.scalatest.matchers.should.Matchers + +/** + * Controls for the argument contract of the mutating tools. + * + * These run offline with no GitBucket instance: the code under test is pure + * Jackson handling, and it is the same code the tools call. Each case below + * corresponds to a way the previous coercing helpers would have destroyed or + * weakened a write. + */ +@RunWith(classOf[JUnitRunner]) +class StrictArgsSpec extends AnyFunSuite with Matchers { + + private val mapper = new ObjectMapper() + + private def args(json: String) = mapper.readTree(json) + + // ── omitted vs intentionally empty ──────────────────────────────────────── + + test("an omitted key is absent, not empty") { + StrictArgs.textOpt(args("""{"title":"t"}"""), "body") shouldBe None + } + + test("an explicitly empty string is supplied, not absent") { + // The distinction that matters: clearing a body must reach the tool as a + // request to clear it, while omitting it must leave the stored text alone. + StrictArgs.textOpt(args("""{"body":""}"""), "body") shouldBe Some("") + } + + test("a normal string round-trips unchanged") { + StrictArgs.textOpt(args("""{"body":"hello"}"""), "body") shouldBe Some("hello") + } + + // ── wrong JSON types are refused before any write ───────────────────────── + + test("an object body is refused instead of becoming empty text") { + // The regression this whole helper exists for: `asText("")` turned `{}` + // into "" and the tool then erased a real description. + val thrown = the[IllegalArgumentException] thrownBy + StrictArgs.textOpt(args("""{"body":{}}"""), "body") + thrown.getMessage should include("must be a JSON string") + thrown.getMessage should include("an object") + } + + test("an array body is refused") { + an[IllegalArgumentException] should be thrownBy + StrictArgs.textOpt(args("""{"body":[1,2]}"""), "body") + } + + test("a numeric body is refused rather than stringified") { + an[IllegalArgumentException] should be thrownBy + StrictArgs.textOpt(args("""{"body":42}"""), "body") + } + + test("a boolean body is refused rather than stringified") { + an[IllegalArgumentException] should be thrownBy + StrictArgs.textOpt(args("""{"body":true}"""), "body") + } + + test("an explicit null body is refused, not treated as absent") { + // Treating null as absent would silently turn "clear this" or a client + // bug into "change nothing", which is a different operation either way. + an[IllegalArgumentException] should be thrownBy + StrictArgs.textOpt(args("""{"body":null}"""), "body") + } + + // ── Unicode and newlines survive ────────────────────────────────────────── + + test("unicode and newlines are preserved byte for byte") { + val text = "перший рядок\nдругий\t— ok ✅\r\nкінець" + val node = mapper.createObjectNode() + node.put("body", text) + StrictArgs.textOpt(node, "body") shouldBe Some(text) + } + + // ── requiredText ────────────────────────────────────────────────────────── + + test("requiredText refuses an absent key") { + // The exception is bound to a value first: chaining `getMessage` into the + // infix `thrownBy` expression does not parse. + val thrown = the[IllegalArgumentException] thrownBy + StrictArgs.requiredText(args("""{}"""), "body") + thrown.getMessage should include("missing required argument") + } + + test("requiredText refuses an empty string") { + // Blanking a comment is a deletion wearing an edit's clothes. + val thrown = the[IllegalArgumentException] thrownBy + StrictArgs.requiredText(args("""{"body":""}"""), "body") + thrown.getMessage should include("must not be empty") + } + + test("requiredText refuses a wrong type") { + an[IllegalArgumentException] should be thrownBy + StrictArgs.requiredText(args("""{"body":{}}"""), "body") + } + + test("requiredText accepts real text") { + StrictArgs.requiredText(args("""{"body":"text"}"""), "body") shouldBe "text" + } + + // ── commit id precondition ──────────────────────────────────────────────── + + test("an absent precondition stays absent") { + StrictArgs.commitIdOpt(args("""{}"""), "expected_head_sha") shouldBe None + } + + test("a full 40-character hexadecimal id is accepted") { + val sha = "0123456789abcdef0123456789abcdef01234567" + sha.length shouldBe 40 + StrictArgs.commitIdOpt(args(s"""{"expected_head_sha":"$sha"}"""), "expected_head_sha") shouldBe Some(sha) + } + + test("an abbreviated id is refused rather than compared as a prefix") { + // A prefix never equals a stored full id, so accepting one would make the + // precondition always fail — or, worse, be quietly dropped. + an[IllegalArgumentException] should be thrownBy + StrictArgs.commitIdOpt(args("""{"expected_head_sha":"1f822ae"}"""), "expected_head_sha") + } + + test("a non-hexadecimal id of the right length is refused") { + val forty = "z" * 40 + an[IllegalArgumentException] should be thrownBy + StrictArgs.commitIdOpt(args(s"""{"expected_head_sha":"$forty"}"""), "expected_head_sha") + } + + test("an empty precondition is refused, not discarded") { + // The old `strOpt` dropped "" and performed an unguarded write. + an[IllegalArgumentException] should be thrownBy + StrictArgs.commitIdOpt(args("""{"expected_head_sha":""}"""), "expected_head_sha") + } + + test("an object precondition is refused, not discarded") { + an[IllegalArgumentException] should be thrownBy + StrictArgs.commitIdOpt(args("""{"expected_head_sha":{}}"""), "expected_head_sha") + } +} diff --git a/src/test/scala/com/newsrx/mcpplugin/TimestampsSpec.scala b/src/test/scala/com/newsrx/mcpplugin/TimestampsSpec.scala new file mode 100644 index 0000000..b22f34a --- /dev/null +++ b/src/test/scala/com/newsrx/mcpplugin/TimestampsSpec.scala @@ -0,0 +1,74 @@ +package com.newsrx.mcpplugin + +import com.newsrx.mcpplugin.mcp.Timestamps +import java.util.{Date, TimeZone} +import org.junit.runner.RunWith +import org.scalatestplus.junit.JUnitRunner +import org.scalatest.funsuite.AnyFunSuite +import org.scalatest.matchers.should.Matchers + +/** + * Controls for the published timestamp format. + * + * The regression these exist for: every date went through + * `java.util.Date.toString`, which renders in the JVM's default zone with + * locale-dependent names ("Fri Oct 23 15:38:41 EEST 2026"). It read as a + * plausible timestamp, so a non-empty-string assertion passed, while being + * unparseable for a client and incomparable with GitBucket's own ISO 8601 + * output. The live gate refused to compare it once it ran on a host in + * Europe/Kiev. + * + * The default zone is changed inside these cases on purpose: a formatter that + * depends on it must fail here. + */ +@RunWith(classOf[JUnitRunner]) +class TimestampsSpec extends AnyFunSuite with Matchers { + + private def withZone[A](id: String)(body: => A): A = { + val previous = TimeZone.getDefault + try { + TimeZone.setDefault(TimeZone.getTimeZone(id)) + body + } finally TimeZone.setDefault(previous) + } + + private val epoch = new Date(0L) + private val instant = new Date(1792759121000L) // 2026-10-23T12:38:41Z + + test("the epoch formats as an ISO 8601 instant in UTC") { + Timestamps.iso8601(epoch) shouldBe "1970-01-01T00:00:00Z" + } + + test("a known instant formats to the second, with a Z suffix") { + Timestamps.iso8601(instant) shouldBe "2026-10-23T12:38:41Z" + } + + test("the output does not depend on the JVM's default time zone") { + // The whole point: Date.toString would answer differently in each of + // these, which is what made the field unusable. + val renderings = Seq("UTC", "Europe/Kiev", "America/Los_Angeles", "Asia/Kolkata", "Pacific/Chatham") + .map(z => withZone(z)(Timestamps.iso8601(instant))) + renderings.distinct shouldBe Seq("2026-10-23T12:38:41Z") + } + + test("the output does not depend on the JVM's default locale") { + val previous = java.util.Locale.getDefault + try { + java.util.Locale.setDefault(java.util.Locale.forLanguageTag("uk-UA")) + Timestamps.iso8601(instant) shouldBe "2026-10-23T12:38:41Z" + java.util.Locale.setDefault(java.util.Locale.forLanguageTag("ja-JP")) + Timestamps.iso8601(instant) shouldBe "2026-10-23T12:38:41Z" + } finally java.util.Locale.setDefault(previous) + } + + test("every output matches the shape GitBucket's own API publishes") { + val pattern = """^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$""".r + Seq(epoch, instant, new Date(), new Date(253402300799000L)).foreach { d => + withClue(s"$d: ") { pattern.findFirstIn(Timestamps.iso8601(d)) should not be empty } + } + } + + test("a date before the epoch still formats as an instant") { + Timestamps.iso8601(new Date(-1000L)) shouldBe "1969-12-31T23:59:59Z" + } +} diff --git a/src/test/scala/com/newsrx/mcpplugin/ToolDefSpec.scala b/src/test/scala/com/newsrx/mcpplugin/ToolDefSpec.scala index 4612ab0..8f502d3 100644 --- a/src/test/scala/com/newsrx/mcpplugin/ToolDefSpec.scala +++ b/src/test/scala/com/newsrx/mcpplugin/ToolDefSpec.scala @@ -132,6 +132,9 @@ class ToolDefSpec extends AnyFunSuite with Matchers { private object TestTool extends ToolDef { val name = "test_tool" val description = "tool for testing helpers" + // Every tool must declare the scope it needs; the member is abstract so + // that a new one cannot silently inherit the weaker requirement. + val requiredScope = com.newsrx.mcpplugin.oauth.McpScope.Read def inputSchema(mapper: ObjectMapper) = objectSchema(mapper, Seq("x"), "x" -> strNode(mapper, "required string")) diff --git a/src/test/scala/com/newsrx/mcpplugin/ToolRegistrySpec.scala b/src/test/scala/com/newsrx/mcpplugin/ToolRegistrySpec.scala new file mode 100644 index 0000000..947a83a --- /dev/null +++ b/src/test/scala/com/newsrx/mcpplugin/ToolRegistrySpec.scala @@ -0,0 +1,156 @@ +package com.newsrx.mcpplugin + +import com.fasterxml.jackson.databind.ObjectMapper +import com.newsrx.mcpplugin.oauth.McpScope +import com.newsrx.mcpplugin.mcp.ToolRegistry +import org.junit.runner.RunWith +import org.scalatestplus.junit.JUnitRunner +import org.scalatest.funsuite.AnyFunSuite +import org.scalatest.matchers.should.Matchers +import scala.jdk.CollectionConverters._ + +/** + * Offline controls for what the registry publishes. These run without a + * GitBucket instance or a database, so they check the surface a client + * discovers, not the behaviour of a tool against real data. Behavioural + * controls for authorization, read-back and the ready transition need a live + * instance and are listed in README.md under "Checks not executed here". + */ +@RunWith(classOf[JUnitRunner]) +class ToolRegistrySpec extends AnyFunSuite with Matchers { + + private val mapper = new ObjectMapper() + + test("every registered tool has a unique name and a non-empty description") { + val tools = ToolRegistry.all(mapper) + val names = tools.map(_.name) + names.distinct.size shouldBe names.size + tools.foreach { t => + withClue(s"tool ${t.name}: ") { + t.name.trim should not be empty + t.description.trim should not be empty + } + } + } + + test("the operations this increment adds are discoverable") { + val names = ToolRegistry.all(mapper).map(_.name).toSet + // Named individually rather than by count, so adding an unrelated tool + // cannot make this pass while one of these is missing. + names should contain allOf ( + "whoami", + "get_thread_comments", + "update_pull_request", + "update_own_comment", + "mark_ready_for_review" + ) + } + + test("the pre-existing tools are still published") { + val names = ToolRegistry.all(mapper).map(_.name).toSet + names should contain allOf ( + "list_pull_requests", "get_pull_request", "add_pr_comment", + "close_pull_request", "reopen_pull_request", "get_pr_diff", + "list_issues", "get_issue", "create_issue", + "close_issue", "reopen_issue", "add_issue_comment", + "list_repositories", "get_repository" + ) + } + + test("every input schema is an object schema with a required array") { + ToolRegistry.all(mapper).foreach { t => + val schema = t.inputSchema(mapper) + withClue(s"tool ${t.name}: ") { + schema.get("type").asText() shouldBe "object" + schema.has("properties") shouldBe true + schema.get("required").isArray shouldBe true + } + } + } + + test("every declared required argument exists among the schema properties") { + ToolRegistry.all(mapper).foreach { t => + val schema = t.inputSchema(mapper) + val props = schema.get("properties").fieldNames().asScala.toSet + val required = schema.get("required").elements().asScala.map(_.asText()).toSet + withClue(s"tool ${t.name}: ") { + (required diff props) shouldBe empty + } + } + } + + test("whoami takes no required arguments") { + val tool = ToolRegistry.find("whoami", mapper).getOrElse(fail("whoami is not registered")) + tool.inputSchema(mapper).get("required").size() shouldBe 0 + } + + test("mark_ready_for_review offers expected_head_sha but does not demand it") { + val tool = ToolRegistry + .find("mark_ready_for_review", mapper) + .getOrElse(fail("mark_ready_for_review is not registered")) + val schema = tool.inputSchema(mapper) + schema.get("properties").has("expected_head_sha") shouldBe true + val required = schema.get("required").elements().asScala.map(_.asText()).toSet + required should not contain "expected_head_sha" + } + + test("update_pull_request requires neither title nor body in its schema") { + // Either one alone is a valid edit, so the schema cannot demand both; the + // "at least one" rule is enforced in execute and is not expressible here. + val tool = ToolRegistry + .find("update_pull_request", mapper) + .getOrElse(fail("update_pull_request is not registered")) + val required = tool.inputSchema(mapper).get("required").elements().asScala.map(_.asText()).toSet + required shouldBe Set("owner", "repo", "number") + } + + test("the shipped descriptor carries the version the server reports") { + // v0.1.1 shipped with a descriptor saying 0.1.0 and a separate hardcoded + // literal in the controller. The version now has one source; this fails if + // the descriptor is missing from the test classpath or left empty. + PluginDescriptor.get("pluginVersion").trim should not be empty + PluginDescriptor.get("pluginId") shouldBe "mcp-plugin" + } + + // ── scope policy ────────────────────────────────────────────────────────── + + test("every registered tool declares the scope it requires") { + // The member is abstract, so this cannot fail at runtime — it is here to + // state the invariant the compiler is enforcing, and to fail loudly if a + // default is ever introduced. + ToolRegistry.all(mapper).foreach { t => + withClue(s"${t.name}: ")(Seq(McpScope.Read, McpScope.Write) should contain(t.requiredScope)) + } + } + + test("the read and write split is exactly the published one") { + val byScope = ToolRegistry.all(mapper).groupBy(_.requiredScope).map { + case (k, v) => k -> v.map(_.name).toSet + } + byScope(McpScope.Read) shouldBe Set("whoami", "list_repositories", "get_repository", + "list_issues", "get_issue", "list_pull_requests", "get_pull_request", "get_pr_diff", + "get_thread_comments") + byScope(McpScope.Write) shouldBe Set("create_issue", "close_issue", "reopen_issue", + "add_issue_comment", "update_own_comment", "add_pr_comment", "close_pull_request", + "reopen_pull_request", "update_pull_request", "mark_ready_for_review") + } + + test("no tool whose name reads as a mutation is classified read-only") { + // A cheap independent check on the table above: if someone adds + // `delete_issue` and marks it Read, this notices without the list being + // updated. + val mutating = Seq("create", "close", "reopen", "update", "add", "delete", "merge", "mark") + ToolRegistry.all(mapper) + .filter(t => mutating.exists(t.name.startsWith)) + .foreach(t => withClue(s"${t.name}: ")(t.requiredScope shouldBe McpScope.Write)) + } + + test("a write grant satisfies every tool; a read grant satisfies only the read tools") { + val read = Set("mcp:read") + val write = Set("mcp:write") + val all = ToolRegistry.all(mapper) + all.count(_.requiredScope.satisfiedBy(write)) shouldBe all.size + all.count(_.requiredScope.satisfiedBy(read)) shouldBe 9 + all.count(_.requiredScope.satisfiedBy(Set.empty[String])) shouldBe 0 + } +} diff --git a/src/test/scala/com/newsrx/mcpplugin/oauth/ClientMetadataSpec.scala b/src/test/scala/com/newsrx/mcpplugin/oauth/ClientMetadataSpec.scala new file mode 100644 index 0000000..735d52a --- /dev/null +++ b/src/test/scala/com/newsrx/mcpplugin/oauth/ClientMetadataSpec.scala @@ -0,0 +1,251 @@ +package com.newsrx.mcpplugin.oauth + +import com.fasterxml.jackson.databind.ObjectMapper +import java.net.{InetAddress, URL} +import org.junit.runner.RunWith +import org.scalatestplus.junit.JUnitRunner +import org.scalatest.funsuite.AnyFunSuite +import org.scalatest.matchers.should.Matchers + +/** + * The client metadata fetcher, and the fence around it. + * + * The client id is a URL the caller supplies and the server then requests, so + * these are the controls that keep it from becoming a way to reach things + * inside the network a GitBucket usually sits in. + */ +@RunWith(classOf[JUnitRunner]) +class ClientMetadataSpec extends AnyFunSuite with Matchers { + + private val mapper = new ObjectMapper() + private val clientId = "https://client.example.com/.well-known/mcp-client" + + private def doc(body: String) = ClientMetadata.parse(mapper, clientId, body) + + /** A resolver, so the policy is tested rather than this sandbox's DNS. */ + private def resolvesTo(ip: String): ClientMetadata.Resolver = + (_: String) => Array(InetAddress.getByName(ip)) + + private val publicHost = resolvesTo("93.184.216.34") + + // ── what counts as a client id ──────────────────────────────────────────── + + test("an https client id with a host is accepted") { + ClientMetadata.validateClientId(clientId).isRight shouldBe true + } + + test("a non-https client id is refused") { + Seq("http://client.example.com/m", "file:///etc/passwd", "gopher://x/1", + "ftp://client.example.com/m").foreach { id => + withClue(s"$id: ")(ClientMetadata.validateClientId(id).isLeft shouldBe true) + } + } + + test("a client id carrying credentials or a fragment is refused") { + // user:pass@ can make a URL read as one host and resolve as another. + ClientMetadata.validateClientId("https://user:pw@client.example.com/m").isLeft shouldBe true + ClientMetadata.validateClientId("https://client.example.com/m#x").isLeft shouldBe true + } + + test("a malformed client id is refused rather than thrown") { + Seq("", "not a url", "https://", "https:// space").foreach { id => + withClue(s"[$id]: ")(ClientMetadata.validateClientId(id).isLeft shouldBe true) + } + } + + // ── the SSRF fence ──────────────────────────────────────────────────────── + + test("loopback, link-local, private and carrier-grade addresses are forbidden targets") { + Seq("127.0.0.1", "127.0.0.53", "::1", + "169.254.169.254", // cloud instance metadata + "10.0.0.1", "172.16.0.1", "192.168.1.1", + "100.64.0.1", "100.127.255.254", + "0.0.0.0", "224.0.0.1").foreach { ip => + withClue(s"$ip: ")( + ClientMetadata.isForbiddenAddress(InetAddress.getByName(ip)) shouldBe true) + } + } + + test("ordinary public addresses are permitted targets") { + Seq("93.184.216.34", "8.8.8.8", "2606:2800:220:1:248:1893:25c8:1946").foreach { ip => + withClue(s"$ip: ")( + ClientMetadata.isForbiddenAddress(InetAddress.getByName(ip)) shouldBe false) + } + } + + test("a host resolving to any forbidden address is refused, not just the first") { + // A split-horizon name that answers with one public and one private + // address must not be reachable by retrying. + var opened = false + val mixed: ClientMetadata.Resolver = (_: String) => + Array(InetAddress.getByName("93.184.216.34"), InetAddress.getByName("10.0.0.5")) + ClientMetadata.fetch(mapper, clientId, (_: URL, _: InetAddress) => { opened = true; null }, mixed).isLeft shouldBe true + opened shouldBe false + } + + test("a fetch succeeds through the real path when every rule is satisfied") { + val body = s"""{"client_id":"$clientId","client_name":"Example","redirect_uris":["https://a.example.com/cb"]}""" + ClientMetadata.fetch(mapper, clientId, (_: URL, _: InetAddress) => stub(200, body), publicHost) + .map(_.clientName) shouldBe Right("Example") + } + + test("a client id resolving to a forbidden address is refused before any request") { + var opened = false + val result = ClientMetadata.fetch(mapper, clientId, + (_: URL, _: InetAddress) => { opened = true; null }, resolvesTo("127.0.0.1")) + result shouldBe Left(ClientMetadataError.Rejected( + "client.example.com resolves to a non-public address")) + withClue("the fetcher must refuse before opening a connection: ")(opened shouldBe false) + } + + test("a redirect is refused rather than followed") { + // The classic bypass: an allowed host answers 302 to a forbidden one. + Seq(301, 302, 303, 307, 308).foreach { status => + val result = ClientMetadata.fetch(mapper, clientId, (_: URL, _: InetAddress) => stub(status, ""), publicHost) + withClue(s"$status: ") { + result shouldBe Left(ClientMetadataError.Rejected("client metadata must not redirect")) + } + } + } + + test("a non-200 response is reported as unreachable, not parsed") { + ClientMetadata.fetch(mapper, clientId, (_: URL, _: InetAddress) => stub(404, "{}"), publicHost).isLeft shouldBe true + ClientMetadata.fetch(mapper, clientId, (_: URL, _: InetAddress) => stub(500, "{}"), publicHost).isLeft shouldBe true + } + + test("the response body is capped, so an endless document cannot be read forever") { + val huge = """{"client_id":"""" + clientId + """","redirect_uris":["https://a.example.com/cb"],"pad":"""" + + ("x" * (300 * 1024)) + """"}""" + // Truncated at the cap, so it no longer parses: refused, not consumed. + val result = ClientMetadata.fetch(mapper, clientId, (_: URL, _: InetAddress) => stub(200, huge), publicHost) + result.isLeft shouldBe true + } + + test("loopback stays forbidden unless the escape is explicitly set") { + val loopback = InetAddress.getByName("127.0.0.1") + ClientMetadata.isForbiddenAddress(loopback) shouldBe true + ClientMetadata.isForbiddenAddress(loopback, allowLoopback = false) shouldBe true + ClientMetadata.isForbiddenAddress(loopback, allowLoopback = true) shouldBe false + } + + test("the loopback escape opens loopback and nothing else") { + // The reason it is narrow: a flag that quietly also admitted 10.0.0.0/8 + // or 169.254.169.254 would be an SSRF switch rather than a development + // convenience. + Seq("10.0.0.1", "172.16.0.1", "192.168.1.1", "169.254.169.254", + "100.64.0.1", "224.0.0.1").foreach { ip => + withClue(s"$ip with the escape on: ")( + ClientMetadata.isForbiddenAddress(InetAddress.getByName(ip), allowLoopback = true) shouldBe true) + } + } + + test("the escape is off unless the property says otherwise") { + val previous = System.getProperty(ClientMetadata.AllowLoopbackProperty) + try { + System.clearProperty(ClientMetadata.AllowLoopbackProperty) + ClientMetadata.loopbackAllowed() shouldBe false + System.setProperty(ClientMetadata.AllowLoopbackProperty, "false") + ClientMetadata.loopbackAllowed() shouldBe false + System.setProperty(ClientMetadata.AllowLoopbackProperty, "yes") + ClientMetadata.loopbackAllowed() shouldBe false // only "true" counts + System.setProperty(ClientMetadata.AllowLoopbackProperty, "true") + ClientMetadata.loopbackAllowed() shouldBe true + } finally { + if (previous == null) System.clearProperty(ClientMetadata.AllowLoopbackProperty) + else System.setProperty(ClientMetadata.AllowLoopbackProperty, previous) + } + } + + test("an http client id is only accepted on loopback, and only with the escape") { + val previous = System.getProperty(ClientMetadata.AllowLoopbackProperty) + try { + System.setProperty(ClientMetadata.AllowLoopbackProperty, "true") + ClientMetadata.validateClientId("http://localhost:9000/m").isRight shouldBe true + ClientMetadata.validateClientId("http://127.0.0.1:9000/m").isRight shouldBe true + // Still not any other http host, even with the escape on. + ClientMetadata.validateClientId("http://evil.example.com/m").isLeft shouldBe true + System.setProperty(ClientMetadata.AllowLoopbackProperty, "false") + ClientMetadata.validateClientId("http://localhost:9000/m").isLeft shouldBe true + } finally { + if (previous == null) System.clearProperty(ClientMetadata.AllowLoopbackProperty) + else System.setProperty(ClientMetadata.AllowLoopbackProperty, previous) + } + } + + // ── what a document has to say ──────────────────────────────────────────── + + test("a well-formed document yields the client's name and redirect URIs") { + val result = doc(s"""{"client_id":"$clientId","client_name":"Example Client", + |"redirect_uris":["https://chatgpt.com/connector_platform_oauth_redirect"]}""".stripMargin) + result.map(_.clientName) shouldBe Right("Example Client") + result.map(_.redirectUris) shouldBe Right(Set("https://chatgpt.com/connector_platform_oauth_redirect")) + } + + test("a document declaring a different client_id is refused") { + // Otherwise one client's redirect list could authorise another's. + doc(s"""{"client_id":"https://evil.example.com/m","redirect_uris":["https://a.example.com/cb"]}""") shouldBe + Left(ClientMetadataError.Rejected("client metadata declares a different client_id")) + } + + test("a document with no usable redirect URI is refused") { + doc(s"""{"client_id":"$clientId"}""").isLeft shouldBe true + doc(s"""{"client_id":"$clientId","redirect_uris":[]}""").isLeft shouldBe true + // Non-https redirects are dropped, which leaves none. + doc(s"""{"client_id":"$clientId","redirect_uris":["http://evil.example.com/cb"]}""").isLeft shouldBe true + } + + test("a document that is not JSON, or not an object, is refused") { + Seq("", "not json", "[1,2,3]", "\"a string\"", "null").foreach { body => + withClue(s"[$body]: ")(doc(body).isLeft shouldBe true) + } + } + + test("the client name falls back to the client id rather than being empty") { + doc(s"""{"client_id":"$clientId","client_name":"","redirect_uris":["https://a.example.com/cb"]}""") + .map(_.clientName) shouldBe Right(clientId) + } + + // ── redirect matching ───────────────────────────────────────────────────── + + test("a redirect URI must match exactly") { + val client = OAuthClient(clientId, "C", Set("https://chatgpt.com/connector/oauth/abc")) + client.permits("https://chatgpt.com/connector/oauth/abc") shouldBe true + // Every one of these is a near-miss a prefix or host check would admit. + client.permits("https://chatgpt.com/connector/oauth/abc/..") shouldBe false + client.permits("https://chatgpt.com/connector/oauth/abcd") shouldBe false + client.permits("https://chatgpt.com/connector/oauth/abc?x=1") shouldBe false + client.permits("https://chatgpt.com/connector/oauth/abc#x") shouldBe false + client.permits("https://evil.example.com/connector/oauth/abc") shouldBe false + client.permits("https://chatgpt.com.evil.example.com/connector/oauth/abc") shouldBe false + } + + // ── consent rendering of untrusted values ───────────────────────────────── + + test("a client name cannot inject markup into the consent screen") { + val hostile = """""" + val client = OAuthClient("https://evil.example.com/m\" onload=\"x", hostile, + Set("https://evil.example.com/cb")) + val html = ConsentView.render(client, "alice", Set("mcp:read"), + "https://evil.example.com/cb", Some("s\">"), "csrf", "/plugin-mcp/oauth/authorize?k=1") + html should not include "