Skip to content

ahstn/oceans-llm / .agents/skills/verify-oceans-admin

verify-oceans-admin

Verified

Verify the Oceans LLM admin control plane and backend gateway against the real local stack, seeded demo data, and bounded live providers when required. Use for user-path checks of sign-in, models, API keys, observability, usage costs, spend controls, batches, agent sessions, request logs, Anthropic Messages thinking and effort compatibility, MCP registry and tool access, OpenRouter routing, guardrails, and Skills storage.

FileKindSize
SKILL.mdskill md29.0 KB
examples/mcp-candidates.jsonconfig3.0 KB
features/README.mdmarkdown10.0 KB
features/account-onboarding.mdmarkdown4.3 KB
features/agent-harnesses.mdmarkdown4.3 KB
features/agent-plugins.mdmarkdown1005 B
features/agent-sessions.mdmarkdown3.9 KB
features/anthropic-messages.mdmarkdown20.7 KB
features/api-keys.mdmarkdown6.5 KB
features/attribution.mdmarkdown13.9 KB
features/audit-log.mdmarkdown4.9 KB
features/backend-gateway.mdmarkdown5.2 KB
features/batch-requests.mdmarkdown4.2 KB
features/design-system.mdmarkdown4.6 KB
features/guardrails.mdmarkdown7.0 KB
features/harness-integration.mdmarkdown7.8 KB
features/identity.mdmarkdown4.2 KB
features/image-generation.mdmarkdown7.3 KB
features/leaderboard.mdmarkdown3.3 KB
features/live-llm-requests.mdmarkdown12.6 KB
features/mcp-client-oauth.mdmarkdown9.9 KB
features/mcp-ownership.mdmarkdown7.4 KB
features/mcp.mdmarkdown19.6 KB
features/models.mdmarkdown8.2 KB
features/password-sign-in.mdmarkdown8.3 KB
features/profile.mdmarkdown2.5 KB
features/rate-limits.mdmarkdown6.0 KB
features/request-logs.mdmarkdown8.6 KB
features/review-agent.mdmarkdown3.7 KB
features/routing.jsonconfig33.6 KB
features/service-tiers.mdmarkdown6.3 KB
features/skills.mdmarkdown9.8 KB
features/spend-controls.mdmarkdown7.3 KB
features/usage-costs.mdmarkdown3.7 KB
features/workspace-connections.mdmarkdown6.1 KB
scripts/check-messages.mjsexecutablescript2.4 KB
scripts/check-messages.test.mjsscript3.0 KB
scripts/control-oceans-adminexecutablescript25.3 KB
scripts/control-oceans-admin.test.mjsscript7.6 KB
scripts/drive-backend-gateway.mjsexecutablescript12.5 KB
scripts/drive-harness-integration.mjsscript6.6 KB
scripts/drive-mcp.mjsscript13.0 KB
scripts/drive-models.mjsscript12.9 KB
scripts/drive-observability.mjsscript16.8 KB
scripts/drive-profile.mjsscript8.2 KB
scripts/drive-service-tiers.mjsexecutablescript20.1 KB
scripts/drive-skills.mjsscript27.2 KB
scripts/mcp-browser.mjsscript26.5 KB
scripts/mcp-canary.mjsscript18.8 KB
scripts/mcp-candidates.mjsscript3.5 KB
scripts/mcp-verification.test.mjsscript10.2 KB
scripts/messages-regressions.mjsscript15.8 KB
scripts/plan-verification.mjsscript5.2 KB
scripts/plan-verification.test.mjsscript6.1 KB
scripts/proof-cli.mjsscript11.1 KB
scripts/proof.mjsscript9.2 KB
scripts/proof.test.mjsscript10.4 KB

features/mcp-client-oauth.md

View on GitHub
# MCP client OAuth

MCP clients without a `gwk_` key can sign in through the gateway. An unauthenticated call to `/mcp` or `/mcp/{server_key}` gets a `401` whose `WWW-Authenticate` header points at the protected-resource metadata. The client then discovers the authorization server, registers or names its Client ID Metadata Document, and sends the user to the `Allow <client> to use Oceans MCP?` consent page in the admin UI. After consent, the gateway issues an `oat_` access token and an `ort_` refresh token bound to that MCP resource. The tokens act as the signed-in user, are refused on non-MCP routes, and stop working when the user signs out or is deactivated.

## Sub-features

- `oauth-challenge` returns `401` with `WWW-Authenticate: Bearer resource_metadata="…", scope="mcp:aggregate"` on `/mcp`, and the per-server metadata URL with `scope="mcp:proxy"` on `/mcp/{server_key}`.
- `oauth-discovery` serves `/.well-known/oauth-protected-resource/mcp`, `/.well-known/oauth-protected-resource/mcp/{server_key}`, and `/.well-known/oauth-authorization-server`.
- `oauth-registration` accepts RFC 7591 registration at `/oauth/register` and returns a `client_id`.
- `oauth-metadata-document` accepts an https `client_id` that names a Client ID Metadata Document, advertises `client_id_metadata_document_supported: true`, refuses documents on private, loopback, link-local, or metadata addresses, and shows `Published by <host>` with an `Unverified` badge on the consent page.
- `oauth-cors` answers CORS preflights from any origin, without credentials, on the metadata, token, registration, and revocation endpoints and on `/mcp` and `/mcp/{server_key}` (exposing `WWW-Authenticate` and `Mcp-Session-Id`), and not on `/oauth/authorize` or the consent API.
- `oauth-consent` shows `/admin/oauth/consent?request_id=<id>` after sign-in, with the client name, the `Returns to` host, the `Access`, and `Allow` and `Deny`.
- `oauth-token` exchanges the code with PKCE at `/oauth/token` and returns `oat_` and `ort_` tokens.
- `oauth-mcp-call` accepts the `oat_` token on `/mcp` and records the invocation with auth method `oauth`.
- `oauth-refresh` rotates the refresh token; a reused refresh token revokes the grant.
- `oauth-revocation` ends access through `/oauth/revoke`, through `Disconnect` in the `Authorized MCP clients` card, and through sign-out of the approving session.
- `oauth-route-boundary` rejects `oat_` tokens on non-MCP routes such as `/v1/models`.

## How to get to it (user POV)

- An MCP client opens `/oauth/authorize?…` in the browser. The gateway redirects to `/admin/oauth/consent?request_id=<id>`, which sends a signed-out user to `/admin/login` first and back afterwards.
- The consent page has no sidebar link and needs no page permission. Any active signed-in user can open it.

## Driving it with control-oceans-admin

Preconditions:

- `control-oceans-admin doctor` passes, and you are signed in as `admin@local`.
- `gateway.yaml` enables `mcp.client_oauth`. Its issuer comes from `OCEANS_LOCAL_PUBLIC_BASE_URL`, which the `gateway-local` mise task template sets to `http://127.0.0.1:$GATEWAY_PORT`. Check that `/.well-known/oauth-authorization-server` reports the run's gateway origin as `issuer`, then run the protocol steps with `curl` or `fetch` against that origin.
- Generate a PKCE pair for the run: a 43-character verifier and its S256 challenge. Do not reuse a pair between runs.

- **Challenge.** `POST /mcp` with a `tools/list` JSON-RPC body and no `Authorization`. Expect `401` and `WWW-Authenticate` naming `/.well-known/oauth-protected-resource/mcp` and `scope="mcp:aggregate"`.
- **Discovery.** `GET` the metadata URL from the header. `resource` is `<issuer>/mcp` and `authorization_servers` is `[<issuer>]`. `GET /.well-known/oauth-authorization-server`. `issuer` matches, `code_challenge_methods_supported` is `["S256"]`, `registration_endpoint` is present, and `client_id_metadata_document_supported` is `true`.
- **CORS.** Send `OPTIONS /oauth/token` with `Origin: https://app.example.net`, `Access-Control-Request-Method: POST`, and `Access-Control-Request-Headers: content-type`. Expect `200`, `Access-Control-Allow-Origin: *`, and no `Access-Control-Allow-Credentials`. Repeat for `/oauth/register`, `/oauth/revoke`, and both `.well-known` documents. `GET /oauth/authorize?…` with the same `Origin` has no `Access-Control-Allow-Origin`.
- **Metadata document refused on internal addresses.** Open `/oauth/authorize` with `client_id=https://127.0.0.1:<gateway port>/client.json`, then with `client_id=https://localhost/client.json`, and the other parameters as in **Consent**. Each shows the `Authorization failed` page with `invalid_client` and `resolves to an address that is not allowed`. The second one proves the check happens at DNS resolution, since `localhost` is a name. Open it with `client_id=https://editor.example.com` and expect `must include a path`.
- **Metadata document sign-in.** Needs a document on a public HTTPS host you control, since Oceans never fetches from loopback. Publish `{"client_id":"<url>","client_name":"Verify document client","redirect_uris":["http://127.0.0.1:9/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"none"}` at `<url>`, then run **Consent** with `client_id=<url>`. The consent page shows `Published by <host>` with an `Unverified` badge and the `Oceans has not verified this client` note. Continue with **Allow** and **Token**, using `<url>` as the `client_id`. Without such a host, record this step as not verified; `metadata_document_tests` covers it with a fixture.
- **Registration.** `POST /oauth/register` with `{"client_name":"Verify client","redirect_uris":["http://127.0.0.1:9/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"none"}`. Expect `201` with a `client_id`.
- **Grant a tool (for the MCP call).** Through the admin API, register a temporary `auth_mode: none` MCP server that points at a local stub upstream, refresh its discovery, and grant one tool to the signed-in user. Disable the server and revoke the grant during cleanup.
- **Consent.** In the browser, open `/oauth/authorize?response_type=code&client_id=<id>&redirect_uri=http://127.0.0.1:9/callback&state=verify&code_challenge=<challenge>&code_challenge_method=S256&resource=<issuer>/mcp`. The URL becomes `/admin/oauth/consent?request_id=<id>`. The heading `Allow Verify client to use Oceans MCP?`, the `Returns to` host `127.0.0.1:9` with a `This device` badge, `All MCP servers you have access to`, and the loopback warning are visible. Capture an ARIA snapshot and a screenshot.
- **Allow.** Press `Allow`. The browser navigates to `http://127.0.0.1:9/callback?code=…&state=verify&iss=<issuer>`. Nothing listens there, so read the code from the failed navigation URL.
- **Token.** `POST /oauth/token` as a form with `grant_type=authorization_code`, the `client_id`, the code, the `redirect_uri`, the `code_verifier`, and `resource=<issuer>/mcp`. Expect `200`, `Cache-Control: no-store`, an `oat_` access token, an `ort_` refresh token, and `scope` `mcp:aggregate`. Redeeming the same code again returns `invalid_grant`.
- **MCP call.** `POST /mcp` with `Authorization: Bearer <oat_…>` and an `initialize` body. Expect `200` and an `mcp-session-id`. Send `notifications/initialized`, then `tools/list` with that session, and expect the three aggregate tools. Authorize again with `resource=<issuer>/mcp/<server_key>` for the temporary server and call its tool with `tools/call`. Expect `200`, and the invocation detail metadata shows `auth_method` `oauth` and the `oauth_client_id`. The same per-server token on `/mcp` returns `401` `invalid_token`.
- **API keys still work.** Create a temporary user API key for `alice@platform.local` (the bootstrap admin cannot own keys), send `initialize` to `/mcp` with it, expect `200`, then revoke the key.
- **Route boundary.** `GET /v1/models` with the same token. Expect `401`.
- **Refresh.** `POST /oauth/token` with `grant_type=refresh_token`, the `client_id`, and the refresh token. Expect a new `ort_` token. Send the old refresh token again. Expect `invalid_grant`, and the newest access token now fails on `/mcp` with `401`.
- **Revocation.** Repeat consent and token exchange, then `POST /oauth/revoke` with `token=<oat_…>` and the `client_id`. Expect `200`, after which `/mcp` returns `401`.
- **Disconnect from the account page.** Repeat consent and token exchange, then open `/admin/account/connections`. The `Authorized MCP clients` card lists `Verify client`. Choose `Disconnect Verify client`, and the access token then gets `401` on `/mcp`. As platform admin, `GET /api/v1/admin/mcp/authorized-clients?user_id=<id>` agrees with the card before and after.
- **Deny.** Start another authorization and press `Deny`. The browser returns to the callback with `error=access_denied` and `iss`.
- **Proof.** Record each check with `control-oceans-admin record`, with the consent screenshot and ARIA snapshot as artifacts.

## Gotchas

- Never record codes, verifiers, access tokens, or refresh tokens in evidence. Record only their prefixes and lengths.
- The consent page and `/oauth/authorize` must use the gateway origin that matches the issuer. Opening the UI port directly breaks the flow.
- The authorization code expires 60 seconds after `Allow`, so exchange it promptly.
- Signing out of the admin UI revokes every client that session approved. Sign out only at the end of the run.
- Consent is asked every time; the gateway never remembers it.
- A metadata document is cached for its `Cache-Control` lifetime, up to 24 hours. After editing a published document, wait out that lifetime or publish it with `Cache-Control: no-store` while testing.
- `http::mcp_client_oauth::{flow_tests, registration_tests, lifecycle_tests, mcp_route_tests, authorized_clients_tests, metadata_document_tests}` prove the full protocol against the real router, including MCP tool calls through a local upstream, without a browser. This recipe adds the browser consent path and the admin UI.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall