mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-26 01:24:59 +02:00
e4c95ad9be
* docs(mintlify): cover MCP, OAuth, non-RPC endpoints, and usage Audit against api/ + proto/ revealed 9 OpenAPI specs missing from nav, the scenario/v1 service undocumented, and MCP (32 tools + OAuth 2.1 flow) with no user-facing docs. The stale Docs_To_Review/API_REFERENCE.md still pointed at pre-migration endpoints that no longer exist. - Wire 9 orphaned specs into docs.json: ConsumerPrices, Forecast, Health, Imagery, Radiation, Resilience, Sanctions, Thermal, Webcam - Hand-write ScenarioService.openapi.yaml (3 RPCs) until it's proto-backed (tracked in issue #3207) - New MCP page with tool catalog + client setup (Claude Desktop/web, Cursor) - New MDX for OAuth, Platform, Brief, Commerce, Notifications, Shipping v2, Proxies - New Usage group: quickstart, auth matrix, rate limits, errors - Remove docs/Docs_To_Review/API_REFERENCE.md and EXTERNAL_APIS.md (referenced dead endpoints); add README flagging dir as archival * docs(mintlify): move scenario docs out of generated docs/api/ tree The pre-push hook enforces that docs/api/ is proto-generated only. Replace the hand-written ScenarioService.openapi.yaml with a plain MDX page (docs/api-scenarios.mdx) until the proto migration lands (tracked in issue #3207). * docs(mintlify): fix factual errors flagged in PR review Reviewer caught 5 endpoints where I speculated on shape/method/limits instead of reading the code. All fixes cross-checked against the source: - api-shipping-v2: route-intelligence is GET with query params (fromIso2, toIso2, cargoType, hs2), not POST with a JSON body. Response shape is {primaryRouteId, chokepointExposures[], bypassOptions[], warRiskTier, disruptionScore, ...}. - api-commerce: /api/product-catalog returns {tiers, fetchedAt, cachedUntil, priceSource} with tier groups free|pro|api_starter| enterprise, not the invented {currency, plans}. Document the DELETE purge path too. - api-notifications: Slack/Discord /oauth/start are POST + Clerk JWT + PRO (returning {oauthUrl}), not GET redirects. Callbacks remain GET. - api-platform: /api/version returns the latest GitHub Release ({version, tag, url, prerelease}), not deployed commit/build metadata. - api-oauth + mcp: /api/oauth/register limit is 5/60s/IP (match code), not 10/hour. Also caught while double-checking: /api/register-interest and /api/contact are 5/60min and 3/60min respectively (1-hour window, not 1-minute). Both require Turnstile. Removed the fabricated limits for share-url, notification-channels, create-checkout (they fall back to the default per-IP limit). * docs(mintlify): second-round fixes — verify every claim against source Reviewer caught 7 more cases where I described API behavior I hadn't read. Each fix below cross-checked against the handler. - api-commerce (product-catalog): tiers are flat objects with monthlyPrice/annualPrice/monthlyProductId/annualProductId on paid tiers, price+period for free, price:null for enterprise. There is no nested plans[] array. - api-commerce (referral/me): returns {code, shareUrl}, not counts. Code is a deterministic 8-char HMAC of the Clerk userId; binding into Convex is fire-and-forget via ctx.waitUntil. - api-notifications (notification-channels): actual action set is create-pairing-token, set-channel, set-web-push, delete-channel, set-alert-rules, set-quiet-hours, set-digest-settings. Replaced the made-up list. - api-shipping-v2 (webhooks): alertThreshold is numeric 0-100 (default 50), not a severity string. Subscriber IDs are wh_+24hex; secret is raw 64-char hex (no whsec_ prefix). POST registration returns 201. Added the management routes: GET /{id}, POST /{id}/rotate-secret, POST /{id}/reactivate. - api-platform (cache-purge): auth is Authorization: Bearer RELAY_SHARED_SECRET, not an admin-key header. Body takes keys[] and/or patterns[] (not {key} or {tag}), with explicit per-request caps and prefix-blocklist behavior. - api-platform (download): platform+variant query params, not file=<id>. Response is a 302 to a GitHub release asset; documented the full platform/variant tables. - mcp: server also accepts direct X-WorldMonitor-Key in addition to OAuth bearer. Fixed the curl example which was incorrectly sending a wm_live_ API key as a bearer token. - api-notifications (youtube/live): handler reads channel or videoId, not channelId. - usage-auth: corrected the auth-matrix row for /api/mcp to reflect that OAuth is one of two accepted modes. * docs(mintlify): fix Greptile review findings - mcp.mdx: 'Five' slow tools → 'Six' (list contains 6 tools) - api-scenarios.mdx: replace invalid JSON numeric separator (8_400_000_000) with plain integer (8400000000) Greptile's third finding — /api/oauth/register rate-limit contradiction across api-oauth.mdx / mcp.mdx / usage-rate-limits.mdx — was already resolved in commit4f2600b2a(reviewed commit waseb5654647).
119 lines
3.4 KiB
Plaintext
119 lines
3.4 KiB
Plaintext
---
|
|
title: "OAuth 2.1 Server"
|
|
description: "Dynamic client registration, authorization, and token exchange endpoints that back the WorldMonitor MCP server."
|
|
---
|
|
|
|
WorldMonitor runs a minimal OAuth 2.1 authorization server whose only client-facing purpose today is **granting access to the MCP server** at `/api/mcp`. It implements:
|
|
|
|
- [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) — Dynamic Client Registration
|
|
- [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) — PKCE (required, S256 only)
|
|
- [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) — Authorization Server Metadata
|
|
- [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) — Protected Resource Metadata
|
|
|
|
## Discovery
|
|
|
|
| URL | Purpose |
|
|
|-----|---------|
|
|
| `/.well-known/oauth-authorization-server` | AS metadata (endpoints, supported grants, PKCE methods) |
|
|
| `/.well-known/oauth-protected-resource` | Resource metadata (authorization servers, scopes) |
|
|
|
|
## Endpoints
|
|
|
|
### `POST /api/oauth/register`
|
|
|
|
Dynamic Client Registration. Returns a `client_id` (public clients, no secret).
|
|
|
|
**Request**:
|
|
```json
|
|
{
|
|
"redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
|
|
"client_name": "Claude Desktop",
|
|
"token_endpoint_auth_method": "none"
|
|
}
|
|
```
|
|
|
|
**Response**: `{ "client_id": "c_01HX...", "client_id_issued_at": 1713456789, ... }`
|
|
|
|
**Redirect URI allowlist**: only these prefixes are accepted:
|
|
- `https://claude.ai/api/mcp/auth_callback`
|
|
- `https://claude.com/api/mcp/auth_callback`
|
|
- `http://localhost:<port>` / `http://127.0.0.1:<port>` — any port
|
|
|
|
**Rate limit**: 5 registrations / 60 s / IP.
|
|
|
|
**Client TTL**: 90 days sliding (every successful token exchange refreshes).
|
|
|
|
### `GET /api/oauth/authorize`
|
|
|
|
Starts the OAuth flow. Renders a consent page that redirects to Clerk for sign-in, then issues an authorization code bound to the caller's PRO entitlement.
|
|
|
|
**Required query params**:
|
|
- `response_type=code`
|
|
- `client_id` — from DCR
|
|
- `redirect_uri` — must match the one registered
|
|
- `code_challenge` — PKCE S256
|
|
- `code_challenge_method=S256`
|
|
- `state` — opaque
|
|
- `scope` (optional)
|
|
|
|
**Code TTL**: 10 minutes. Single-use (atomic `GETDEL` on exchange).
|
|
|
|
### `POST /api/oauth/token`
|
|
|
|
Exchanges an authorization code for an access token, or refreshes an existing token.
|
|
|
|
**Grant type: `authorization_code`**:
|
|
```
|
|
grant_type=authorization_code
|
|
code=<from /authorize>
|
|
code_verifier=<PKCE>
|
|
client_id=<from DCR>
|
|
redirect_uri=<same as /authorize>
|
|
```
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"access_token": "wm_oat_...",
|
|
"token_type": "Bearer",
|
|
"expires_in": 3600,
|
|
"refresh_token": "wm_ort_...",
|
|
"scope": "mcp:read"
|
|
}
|
|
```
|
|
|
|
**Grant type: `refresh_token`**:
|
|
```
|
|
grant_type=refresh_token
|
|
refresh_token=<from previous exchange>
|
|
client_id=<from DCR>
|
|
```
|
|
|
|
**Rate limit**: 10 token requests / minute / IP.
|
|
|
|
**Token TTLs**:
|
|
- Access token: 1 hour
|
|
- Refresh token: 7 days
|
|
|
|
All token-endpoint responses include `Cache-Control: no-store, Pragma: no-cache`.
|
|
|
|
## Using tokens
|
|
|
|
Pass the access token on every MCP request:
|
|
|
|
```
|
|
Authorization: Bearer wm_oat_...
|
|
```
|
|
|
|
Tokens are bound to the user's account and re-check entitlement on every call — a downgrade revokes access on the next request.
|
|
|
|
## Error responses
|
|
|
|
Per [RFC 6749 §5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2):
|
|
|
|
```json
|
|
{ "error": "invalid_grant", "error_description": "..." }
|
|
```
|
|
|
|
Common errors: `invalid_request`, `invalid_client`, `invalid_grant`, `unsupported_grant_type`, `invalid_scope`.
|