@kadoa/mcp 0.6.3 → 0.6.5-rc.1

package/README.md

@@ -2,6 +2,88 @@
 
 Use [Kadoa](https://kadoa.com) from ChatGPT, Claude.ai, Claude Code, Cursor, and other MCP clients.
 
+## Authentication
+
+Public API is the only OAuth authority. This server is an MCP resource server:
+it publishes protected-resource metadata, verifies RS256 resource tokens against
+Public API JWKS, enforces the exact issuer and resource audience, and exchanges
+each resource token for a request-local Public API token using a dedicated service secret.
+It does not mount authorization, registration, token, refresh, or revocation
+routes and does not store end-user credentials.
+
+This runtime targets the separate `mcp-server-beta` deployment. Production MCP
+at `https://mcp.kadoa.com/mcp` remains on legacy authentication until a separate
+approved migration.
+
+```sh
+MCP_AUTH_ISSUER=https://api.kadoa.com/v5/auth
+MCP_AUTH_JWKS_URL=https://api.kadoa.com/v5/auth/.well-known/jwks.json
+MCP_AUTH_AUDIENCE=https://beta.mcp.kadoa.com/mcp
+MCP_DOWNSTREAM_TOKEN_ENDPOINT=https://api.kadoa.com/v5/auth/mcp/downstream-token
+# Inject MCP_DOWNSTREAM_EXCHANGE_SECRET from a dedicated secret store.
+MCP_ALLOWED_ORIGIN_HOSTNAMES=beta.mcp.kadoa.com
+MCP_LEGACY_TRANSPORT_ENABLED=true
+```
+
+`MCP_LEGACY_TRANSPORT_ENABLED` controls protocol-version compatibility only.
+When `true`, supported 2025 protocol requests use the same central verifier and
+downstream exchange as modern requests. It never selects another authentication
+implementation. Missing central configuration fails startup.
+
+The exchange secret must contain at least 32 characters without whitespace.
+Generate at least 32 random bytes, encode as hex, and inject the same value into
+Public API as `KADOA_MCP_DOWNSTREAM_EXCHANGE_SECRET`. Never reuse the worker or
+legacy registry credentials. Secret rotation requires restarting both consumers.
+The service secret does not replace the user token or its authorization checks.
+No Google service account or metadata-server access is required.
+
+### Historical local central-mode fixture
+
+This fixture depends on the earlier backend local-issuer configuration, which
+is absent from the narrowed beta rollout candidate. The commands below are not
+a validated proof for that candidate. Do not restore browser OAuth or local-issuer
+support to run this rollout.
+
+The normal `dev` entrypoint authenticates downstream exchange with
+`MCP_DOWNSTREAM_EXCHANGE_SECRET`. The test-only launcher imports the backend
+exchange owner and uses a local-only fixture secret. It requires
+`KADOA_ENVIRONMENT=local`, binds to `127.0.0.1:3002`, and is not included in the
+published package build.
+
+Start the backend services without the regular MCP child. The shared environment
+pins the backend issuer, Assistant MCP URL, resource audience, and downstream
+Public API audience to literal loopback addresses. If the backend root `.env`
+defines `KADOA_MCP_TOKEN_ALLOWED_RESOURCES`, set it to
+`http://127.0.0.1:3002/mcp` as well. Backend package processes load that file and
+a conflicting value makes the Assistant exchange fail with `invalid_target`.
+The backend `turbo.json` dev task must propagate every variable exported by
+`local-central-env.sh`; the launcher checks this before it starts.
+
+```sh
+cd /home/gabrielziegler/kadoa/kadoa-backend
+direnv exec . bash -lc '
+  source /home/gabrielziegler/kadoa/kadoa-mcp/tests/integration/local-central-env.sh
+  ./start-kadoa.sh --quick --services=dashboard,api,shelly,events-gateway,operations
+'
+```
+
+In a second terminal, start the local central resource server with the backend's
+local environment:
+
+```sh
+direnv exec /home/gabrielziegler/kadoa/kadoa-backend bash -lc '
+  source /home/gabrielziegler/kadoa/kadoa-mcp/tests/integration/local-central-env.sh
+  cd /home/gabrielziegler/kadoa/kadoa-mcp
+  KADOA_BACKEND_ROOT=/home/gabrielziegler/kadoa/kadoa-backend bun run dev:central-local
+'
+```
+
+Open a new Dashboard Assistant session and request a workflow list. The proof
+covers the central resource server, backend-owned token exchange, live team
+membership checks, downstream Public API credentials, and real tool calls. It
+does not prove the current beta candidate, browser OAuth consent, or a deployed
+network boundary.
+
 ## Remote Server (no install needed)
 
 A hosted MCP server is available at `https://mcp.kadoa.com/mcp`. Connect from any MCP client — no local install needed. You sign in with your Kadoa account via OAuth.
@@ -301,7 +383,7 @@ Use this when you want to validate a change end-to-end against real clients (Cla
 There are two ways to consume an RC:
 
 - **Local stdio**: `npx @kadoa/mcp@rc` — installs from the `rc` dist-tag on npm. Good for quick sanity checks where the bug doesn't depend on the hosted OAuth flow.
-- **Hosted `mcp-server-test`**: a separate k8s deployment alongside prod in the same GKE cluster. Required when you need to validate the OAuth callback, Redis token store, multi-tenant session behavior, etc.
+- **Hosted `mcp-server-test`**: a separate k8s deployment alongside prod in the same GKE cluster. Use it to validate protected-resource discovery, OAuth callbacks owned by Public API, and multi-tenant behavior.
 
 #### Publish an RC to npm
 
@@ -380,13 +462,18 @@ The server starts in HTTP mode. You authenticate via OAuth the same way as with
 
 ### HTTP server environment variables
 
-Opaque OAuth bearer tokens are routed to the existing OAuth verifier. RS256 Kadoa access tokens (Public API tokens, including delegated Kadoa Assistant tokens) additionally require:
+| Variable | Description |
+|---|---|
+| `MCP_AUTH_ISSUER` | Exact Public API OAuth issuer, such as `https://api.kadoa.com/v5/auth` |
+| `MCP_AUTH_JWKS_URL` | JWKS URL for the issuer |
+| `MCP_AUTH_AUDIENCE` | Exact MCP resource URL served by this deployment; its path must be `/mcp` |
+| `MCP_DOWNSTREAM_TOKEN_ENDPOINT` | Public API service-authenticated downstream exchange endpoint |
+| `MCP_DOWNSTREAM_EXCHANGE_SECRET` | Dedicated service credential shared only with the downstream exchange |
+| `MCP_ALLOWED_ORIGIN_HOSTNAMES` | Comma-separated hostnames admitted when an HTTP Origin header is present; required outside loopback |
+| `MCP_LEGACY_TRANSPORT_ENABLED` | `true` serves supported 2025 protocol versions through central auth; `false` rejects them |
 
-| Variable | Description | If unset |
-|---|---|---|
-| `MCP_AUTH_ISSUER` | Issuer of Public API RS256 access tokens, `https://api.kadoa.com/v5/auth` | RS256 bearers rejected |
-| `MCP_AUTH_JWKS_URL` | JWKS of that issuer, `https://api.kadoa.com/v5/auth/.well-known/jwks.json` | RS256 bearers rejected |
-| `MCP_AUTH_AUDIENCE` | This pod's exact resource URL, e.g. `https://beta.mcp.kadoa.com/mcp` — must match the pod actually serving the request; a value copied from another pod's config cross-accepts that pod's tokens | RS256 bearers rejected |
+All authentication and downstream-exchange settings are required. Old opaque
+MCP bearer credentials are rejected.
 
 ## Contributing
 
@@ -447,10 +534,10 @@ CLI and MCP both call **identical** SDK domain methods. A new feature added to t
 ### Where to find things in this repo
 
 - `src/tools.ts` — every MCP tool. Single file by design; search for the tool name.
-- `src/auth.ts` — OAuth flow, JWT verification, team selection.
-- `src/client.ts` — wires `@kadoa/node-sdk` per request, injects bearer token.
-- `src/http.ts` — Express server, transport adapter, session handling.
-- `src/redis-store.ts` — token store for the hosted server.
+- `src/kadoa-access-token.ts` — verifies Public API resource tokens.
+- `src/downstream-token.ts` — exchanges resource tokens for request-local Public API credentials.
+- `src/client.ts` — wires `@kadoa/node-sdk` per request.
+- `src/http.ts` — Express resource server and transport adapter.
 - `tests/unit/` — bun tests; run with `bun run test`.
 
 ## License