@kivimedia/kmhub 2.0.0 → 2.9.0

package/remote.mjs

@@ -1,45 +1,18 @@
 #!/usr/bin/env node
 /**
- * kmhub-mcp REMOTE (P5) - a Streamable-HTTP MCP server for KM Hub power users.
+ * Remote Streamable HTTP MCP server for KMHub.
  *
- * ONE process serves MANY orgs. There is no server-wide API key. Instead every
- * request authenticates itself with a KM Hub org API key sent as a Bearer token:
- *
- *     Authorization: Bearer kmh_live_xxxxxxxx
- *
- * That token is bound to a fresh, per-request McpServer whose tools call kmhub-api
- * with exactly that token. The kmhub-api edge function then does the authoritative
- * org scoping + scope check (read vs write), so one caller can never reach another
- * tenant's rows. This is the multi-tenant twin of the local stdio server (index.mjs);
- * both share the SAME tool definitions from tools.mjs.
- *
- * Transport: MCP Streamable HTTP, STATELESS mode (sessionIdGenerator: undefined) -
- * each POST /mcp is a self-contained request/response, so there is no session state
- * to leak across tenants. Deployed on the VPS as pm2 process `kmhub-mcp`; see
- * DEPLOY-VPS.md.
- *
- * Endpoints:
- *   GET  /health  -> { ok: true, ... }        (no auth; for pm2 / nginx / uptime checks)
- *   POST /mcp     -> MCP Streamable HTTP       (Bearer token required)
- *   GET  /mcp     -> 405 (no server-initiated SSE stream in stateless mode)
- *
- * Tool profiles: a caller can load a subset of the tools instead of all of them, which
- * costs the model far fewer tool schemas per turn. Two ways to ask, both per-request so
- * the server stays stateless and two tenants can hold different profiles at the same time:
- *   POST /mcp?profile=money            (query string, wins if both are present)
- *   X-KMHub-Profile: money             (header)
- * Known profiles: core, outreach, money, content, full. Anything else falls back to full
- * rather than erroring, because a typo should never cost someone their tools.
- *
- * Env:
- *   PORT            listen port (default 8830)
- *   HOST            bind address (default 0.0.0.0)
- *   KMHUB_API_BASE  override the kmhub-api base URL (default = the shared one)
- *   MCP_RATE_LIMIT  max POST /mcp requests per token per minute (default 120)
+ * Generic API keys keep their existing behavior. Fully Booked Coach OAuth uses
+ * an opaque access token only at this resource server. The token is introspected
+ * with the dedicated broker, then replaced with a 15-second internal assertion
+ * before any request reaches kmhub-api.
  */
 import http from 'node:http';
+import { createHash, createHmac, randomUUID } from 'node:crypto';
+import { isIP } from 'node:net';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { registerPrompts } from './prompts.mjs';
 import {
   DEFAULT_BASE,
   DEFAULT_PROFILE,
@@ -56,75 +29,534 @@ import {
 
 const PORT = Number(process.env.PORT || 8830);
 const HOST = process.env.HOST || '0.0.0.0';
-const BASE = DEFAULT_BASE;
-const RATE_LIMIT = Number(process.env.MCP_RATE_LIMIT || 120); // requests / token / minute
+const EXPECTED_API_BASE = 'https://jpwbosrmkibsdgckowsm.supabase.co/functions/v1/kmhub-api';
+const EXPECTED_BROKER_BASE = 'https://jpwbosrmkibsdgckowsm.supabase.co/functions/v1/coach-oauth-broker';
+const EXPECTED_CONSENT_URL = 'https://hub.kivimedia.co/oauth/consent';
+const BASE = process.env.KMHUB_API_BASE || DEFAULT_BASE;
+const EXPECTED_PUBLIC_ORIGIN = 'https://mcp.kivimedia.co';
+const PUBLIC_ORIGIN = (
+  process.env.MCP_PUBLIC_ORIGIN || EXPECTED_PUBLIC_ORIGIN
+).replace(/\/+$/, '');
+const RESOURCE_URL = `${PUBLIC_ORIGIN}/mcp`;
+const RESOURCE_METADATA_URL = `${PUBLIC_ORIGIN}/.well-known/oauth-protected-resource/mcp`;
+const CONSENT_URL = process.env.KMHUB_COACH_CONSENT_URL || EXPECTED_CONSENT_URL;
+const BROKER_BASE = (
+  process.env.COACH_OAUTH_BROKER_URL
+  || EXPECTED_BROKER_BASE
+).replace(/\/+$/, '');
+const BROKER_SECRET = process.env.COACH_OAUTH_BROKER_SECRET || '';
+const INTERNAL_SECRET = process.env.COACH_MCP_INTERNAL_SECRET || '';
+const COACH_SCOPE = 'coach:operate';
+const WORKSPACE_SCOPE = 'workspace:operate';
+
+/*
+ * The scope-to-profile pairing. 🚨 The fourth copy of something the database owns
+ * (kmhub_oauth_profile_for_scope, migration 667), mirrored by the broker and by
+ * kmhub-api. All four must agree: this end decides what to ask for, the far end decides
+ * what to accept, and a disagreement means a connector that authorizes cleanly and then
+ * cannot call anything.
+ */
+const PROFILE_BY_SCOPE = new Map([
+  [COACH_SCOPE, 'coach'],
+  [WORKSPACE_SCOPE, 'workspace'],
+]);
+const profileForScope = (scope) => PROFILE_BY_SCOPE.get(scope) || null;
+
+/*
+ * The internal assertion's audience names the profile, so kmhub-api can refuse a coach
+ * assertion presented as a workspace one. Both ends build this string the same way.
+ */
+const internalAudienceFor = (profile) => `${BASE.replace(/\/+$/, '')}/${profile}`;
+
+/*
+ * What a fresh connection asks for when the client does not name a scope. Workspace,
+ * because that is what 56 of the 58 workspaces need; a coach client names its own scope
+ * and is unaffected. Safe to change because no OAuth connection has ever been completed.
+ */
+const DEFAULT_SCOPE = WORKSPACE_SCOPE;
+
+const COACH_ASSERTION_PREFIX = 'kmh_coach_int_';
+const ACCESS_TOKEN_PATTERN = /^kmh_(?:coach|ws)_at_[0-9a-f]{64}$/;
+const API_KEY_PATTERN = /^kmh_live_[a-f0-9]+$/i;
+// Two OAuth client families since migration 763: Claude and ChatGPT (developer-mode
+// connectors). The redirect is the security anchor - a code can only ever go back to a
+// claude.ai / claude.com / chatgpt.com callback. Mirrors kmhub_oauth_redirect_family in the
+// database and oauthRedirectFamily in supabase/functions/_shared/coach-oauth.ts.
+const CLIENT_ID_PATTERN = /^kmh_(?:claude|chatgpt)_[0-9a-f]{36}$/;
+const OFFICIAL_REDIRECTS = new Set([
+  'https://claude.ai/api/mcp/auth_callback',
+  'https://claude.com/api/mcp/auth_callback',
+  // ChatGPT's one stable callback. Its per-connector form is refused (migration 764).
+  'https://chatgpt.com/connector_platform_oauth_redirect',
+]);
+
+function isApprovedRedirect(uri) {
+  return typeof uri === 'string' && OFFICIAL_REDIRECTS.has(uri);
+}
+
+/**
+ * One known scope out of whatever the client asked for. Claude asks for exactly one;
+ * ChatGPT may ask for every scope the metadata lists ("workspace:operate coach:operate"),
+ * or add OIDC ones. Workspace wins when present (it is what 56 of 58 workspaces need),
+ * then coach, and an empty or unknown-only request falls back to the default. The broker
+ * and the database still check the result against the client's own scope list.
+ */
+function normalizeRequestedScope(raw) {
+  const asked = typeof raw === 'string' ? raw.split(/\s+/).filter(Boolean) : [];
+  if (asked.includes(WORKSPACE_SCOPE)) return WORKSPACE_SCOPE;
+  if (asked.includes(COACH_SCOPE)) return COACH_SCOPE;
+  return DEFAULT_SCOPE;
+}
+
+/** The resource indicator, tolerating one trailing slash on the URL a person typed. */
+function canonicalResource(raw) {
+  if (raw === RESOURCE_URL || raw === RESOURCE_URL + '/') return RESOURCE_URL;
+  return raw;
+}
+const RATE_LIMIT = Number(process.env.MCP_RATE_LIMIT || 120);
 const WINDOW_MS = 60_000;
+const MAX_OAUTH_BODY_BYTES = 32 * 1024;
+const REQUESTED_MAX_RATE_BUCKETS = Number(process.env.MCP_MAX_RATE_BUCKETS || 5000);
+const RATE_BUCKET_CAP_VALID = (
+  Number.isInteger(REQUESTED_MAX_RATE_BUCKETS)
+  && REQUESTED_MAX_RATE_BUCKETS >= 100
+  && REQUESTED_MAX_RATE_BUCKETS <= 100000
+);
+const MAX_RATE_BUCKETS = RATE_BUCKET_CAP_VALID ? REQUESTED_MAX_RATE_BUCKETS : 5000;
+const TRUSTED_PROXY_SOURCES = new Set(
+  (process.env.MCP_TRUSTED_PROXY_SOURCES || '127.0.0.1,::1')
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean),
+);
+const TRUSTED_PROXY_HEADER = (
+  process.env.MCP_TRUSTED_PROXY_HEADER || 'x-forwarded-for'
+).toLowerCase();
+const OAUTH_ROUTE_LIMITS = {
+  register: 10,
+  authorize: 60,
+  token: 60,
+  revoke: 60,
+  introspect: 240,
+};
+// All ChatGPT users reach this server from OpenAI's egress addresses, so a per-source cap on
+// token checks would make every ChatGPT workspace share one small bucket. The per-TOKEN cap
+// stays at OAUTH_ROUTE_LIMITS.introspect; the per-source ceiling for this route is wider.
+//
+// 🚨 Wider, not unbounded. 6000 sat above MAX_RATE_BUCKETS, and the per-token buckets lived
+// in the shared map, so one address sending fresh junk tokens evicted its own source bucket
+// (it never reached the cap) and every other route's buckets with it: 20000 of 20000 junk
+// checks reached the broker in a replay (review of 5cf8b4ad). The ceiling now stays well
+// under the cap, and per-token buckets live in their own map where churn evicts only them.
+const OAUTH_SOURCE_LIMITS = {
+  introspect: 1200,
+};
+const TRUSTED_PROXY_CONFIG_VALID = (
+  TRUSTED_PROXY_SOURCES.size > 0
+  && Array.from(TRUSTED_PROXY_SOURCES).every((value) => isIP(value) !== 0)
+  && /^[a-z0-9-]{1,64}$/.test(TRUSTED_PROXY_HEADER)
+);
+const OAUTH_CONFIGURED = (
+  PUBLIC_ORIGIN === EXPECTED_PUBLIC_ORIGIN
+  && CONSENT_URL === EXPECTED_CONSENT_URL
+  && BROKER_BASE === EXPECTED_BROKER_BASE
+  && BASE === EXPECTED_API_BASE
+  && BROKER_SECRET.length >= 32
+  && INTERNAL_SECRET.length >= 32
+  && BROKER_SECRET !== INTERNAL_SECRET
+  && RATE_BUCKET_CAP_VALID
+  && TRUSTED_PROXY_CONFIG_VALID
+);
+const REQUIRE_PRODUCTION_OAUTH = (
+  process.env.NODE_ENV === 'production'
+  || process.env.MCP_REQUIRE_OAUTH_CONFIG === 'true'
+);
+if (REQUIRE_PRODUCTION_OAUTH && !OAUTH_CONFIGURED) {
+  console.error(
+    'kmhub-mcp remote: production OAuth configuration is invalid or incomplete',
+  );
+  process.exit(1);
+}
 
-// ---- light in-memory per-token rate limiter -------------------------------
-// First line of defense at the MCP layer. kmhub-api still enforces the
-// authoritative per-key limit (60 reads / 20 writes per minute) downstream.
-const buckets = new Map(); // token -> { count, resetAt }
+const buckets = new Map();
+const oauthBuckets = new Map();
+// Per-token introspect buckets only. Kept apart from oauthBuckets so a flood of fresh tokens
+// can evict nothing but its own kind (see OAUTH_SOURCE_LIMITS).
+const introspectTokenBuckets = new Map();
 
-function rateLimited(token) {
+function tokenFingerprint(token) {
+  return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+
+function normalizeIp(value) {
+  const trimmed = String(value || '').trim();
+  if (trimmed.startsWith('::ffff:') && isIP(trimmed.slice(7)) === 4) {
+    return trimmed.slice(7);
+  }
+  return trimmed;
+}
+
+function requestSourceIp(req) {
+  const socketIp = normalizeIp(req.socket.remoteAddress);
+  if (!TRUSTED_PROXY_SOURCES.has(socketIp)) return socketIp || 'unknown';
+  const headerValue = req.headers[TRUSTED_PROXY_HEADER];
+  const forwarded = (Array.isArray(headerValue) ? headerValue.join(',') : headerValue || '')
+    .split(',')
+    .map((value) => normalizeIp(value));
+  for (let index = forwarded.length - 1; index >= 0; index -= 1) {
+    if (isIP(forwarded[index])) return forwarded[index];
+  }
+  return socketIp || 'unknown';
+}
+
+function evictExpiredAndBound(rateMap, now) {
+  for (const [key, bucket] of rateMap) {
+    if (now >= bucket.resetAt) rateMap.delete(key);
+  }
+  while (rateMap.size >= MAX_RATE_BUCKETS) {
+    const oldest = rateMap.keys().next().value;
+    if (oldest === undefined) break;
+    rateMap.delete(oldest);
+  }
+}
+
+function hitWindow(rateMap, key, limit) {
   const now = Date.now();
-  let b = buckets.get(token);
-  if (!b || now >= b.resetAt) {
-    b = { count: 0, resetAt: now + WINDOW_MS };
-    buckets.set(token, b);
+  let bucket = rateMap.get(key);
+  if (!bucket || now >= bucket.resetAt) {
+    evictExpiredAndBound(rateMap, now);
+    bucket = { count: 0, resetAt: now + WINDOW_MS };
+    rateMap.set(key, bucket);
   }
-  b.count += 1;
-  if (b.count > RATE_LIMIT) {
-    return Math.max(1, Math.ceil((b.resetAt - now) / 1000)); // retry-after seconds
+  bucket.count += 1;
+  if (bucket.count > limit) {
+    return Math.max(1, Math.ceil((bucket.resetAt - now) / 1000));
   }
   return 0;
 }
 
-// Periodically evict stale buckets so memory does not grow unbounded.
+function rateLimited(token) {
+  return hitWindow(buckets, tokenFingerprint(token), RATE_LIMIT);
+}
+
+function oauthAbuseLimited(req, route, clientFingerprint = 'anonymous') {
+  const source = requestSourceIp(req);
+  const limit = OAUTH_ROUTE_LIMITS[route] || OAUTH_ROUTE_LIMITS.token;
+  const sourceLimit = OAUTH_SOURCE_LIMITS[route] || limit;
+  const sourceKey = tokenFingerprint(route + '\n' + source);
+  const sourceRetryAfter = hitWindow(oauthBuckets, sourceKey, sourceLimit);
+  if (sourceRetryAfter) return sourceRetryAfter;
+
+  const fingerprintKey = tokenFingerprint(
+    route + '\n' + source + '\n' + clientFingerprint,
+  );
+  const fingerprintMap = route === 'introspect' ? introspectTokenBuckets : oauthBuckets;
+  return hitWindow(fingerprintMap, fingerprintKey, limit);
+}
+
 setInterval(() => {
   const now = Date.now();
-  for (const [token, b] of buckets) if (now >= b.resetAt) buckets.delete(token);
+  evictExpiredAndBound(buckets, now);
+  evictExpiredAndBound(oauthBuckets, now);
+  evictExpiredAndBound(introspectTokenBuckets, now);
 }, WINDOW_MS).unref();
 
-// ---- helpers --------------------------------------------------------------
-function sendJson(res, status, obj) {
-  const body = JSON.stringify(obj);
-  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) });
+function sendJson(res, status, value, extraHeaders = {}) {
+  const body = JSON.stringify(value);
+  res.writeHead(status, {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(body),
+    'x-content-type-options': 'nosniff',
+    ...extraHeaders,
+  });
   res.end(body);
 }
 
-// A well-formed JSON-RPC error response (id null: the request never reached a handler).
+function sendOAuthJson(res, status, value, extraHeaders = {}) {
+  sendJson(res, status, value, {
+    'cache-control': 'no-store',
+    pragma: 'no-cache',
+    ...extraHeaders,
+  });
+}
+
+function sendOAuthRateLimit(res, retryAfter) {
+  return sendOAuthJson(
+    res,
+    429,
+    {
+      error: 'temporarily_unavailable',
+      error_description: 'Too many OAuth requests. Retry shortly.',
+    },
+    { 'retry-after': String(retryAfter) },
+  );
+}
+
+function redirectAuthorizationError(
+  res,
+  redirectUri,
+  state,
+  error,
+  description,
+) {
+  const location = new URL(redirectUri);
+  location.searchParams.set('error', error);
+  if (description) location.searchParams.set('error_description', description);
+  location.searchParams.set('state', state);
+  location.searchParams.set('iss', PUBLIC_ORIGIN);
+  res.writeHead(302, {
+    location: location.toString(),
+    'cache-control': 'no-store',
+    pragma: 'no-cache',
+  });
+  res.end();
+}
+
 function sendRpcError(res, status, code, message, extraHeaders = {}) {
-  const body = JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null });
-  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), ...extraHeaders });
-  res.end(body);
+  sendJson(res, status, {
+    jsonrpc: '2.0',
+    error: { code, message },
+    id: null,
+  }, extraHeaders);
 }
 
 function bearerToken(req) {
-  const h = req.headers['authorization'] || req.headers['Authorization'];
-  if (!h || typeof h !== 'string') return null;
-  const m = h.match(/^Bearer\s+(.+)$/i);
-  return m ? m[1].trim() : null;
+  const header = req.headers.authorization;
+  if (!header || typeof header !== 'string') return null;
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : null;
+}
+
+function oauthChallenge(error = '') {
+  const detail = error ? `, error="${error}"` : '';
+  return `Bearer realm="kmhub-mcp", resource_metadata="${RESOURCE_METADATA_URL}", scope="${DEFAULT_SCOPE}"${detail}`;
+}
+
+function authorizationServerMetadata() {
+  return {
+    issuer: PUBLIC_ORIGIN,
+    authorization_endpoint: `${PUBLIC_ORIGIN}/authorize`,
+    token_endpoint: `${PUBLIC_ORIGIN}/token`,
+    registration_endpoint: `${PUBLIC_ORIGIN}/register`,
+    revocation_endpoint: `${PUBLIC_ORIGIN}/revoke`,
+    response_types_supported: ['code'],
+    grant_types_supported: ['authorization_code', 'refresh_token'],
+    token_endpoint_auth_methods_supported: ['none'],
+    code_challenge_methods_supported: ['S256'],
+    scopes_supported: [WORKSPACE_SCOPE, COACH_SCOPE],
+    authorization_response_iss_parameter_supported: true,
+  };
+}
+
+function protectedResourceMetadata() {
+  return {
+    resource: RESOURCE_URL,
+    authorization_servers: [PUBLIC_ORIGIN],
+    scopes_supported: [WORKSPACE_SCOPE, COACH_SCOPE],
+    bearer_methods_supported: ['header'],
+    // This is the name Claude shows in its Add Connector dialog. It is the whole
+    // workspace now, not one product inside it.
+    resource_name: 'KM Hub by Kivi Media',
+  };
+}
+
+async function readRequestBody(req, maxBytes = MAX_OAUTH_BODY_BYTES) {
+  const declaredLength = Number(req.headers['content-length'] || 0);
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    const error = new Error('request_too_large');
+    error.status = 413;
+    throw error;
+  }
+
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > maxBytes) {
+      const error = new Error('request_too_large');
+      error.status = 413;
+      throw error;
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function brokerRequest(action, body) {
+  if (BROKER_SECRET.length < 32) {
+    return { ok: false, status: 503, data: { error: 'broker_unavailable' } };
+  }
+  try {
+    const response = await fetch(`${BROKER_BASE}/${action}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json',
+        'x-kmhub-broker-secret': BROKER_SECRET,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(8000),
+    });
+    const text = await response.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      data = { error: 'broker_invalid_response' };
+    }
+    return { ok: response.ok, status: response.status, data };
+  } catch {
+    return { ok: false, status: 503, data: { error: 'broker_unavailable' } };
+  }
+}
+
+function validUuid(value) {
+  return typeof value === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+async function introspectCoachToken(accessToken) {
+  const result = await brokerRequest('introspect', {
+    access_token: accessToken,
+    resource: RESOURCE_URL,
+  });
+  if (!result.ok) return { verdict: 'unavailable' };
+  const binding = result.data;
+  if (!binding || binding.active !== true) return { verdict: 'denied' };
+  if (
+    !validUuid(binding.grant_id)
+    || !validUuid(binding.connection_id)
+    || !validUuid(binding.user_id)
+    || !validUuid(binding.org_id)
+    || typeof binding.client_id !== 'string'
+    || !CLIENT_ID_PATTERN.test(binding.client_id)
+    || profileForScope(binding.scope) === null
+    || binding.profile !== profileForScope(binding.scope)
+    || binding.resource !== RESOURCE_URL
+    || typeof binding.expires_at !== 'string'
+    || Date.parse(binding.expires_at) <= Date.now()
+  ) {
+    return { verdict: 'denied' };
+  }
+  return { verdict: 'allowed', binding };
+}
+
+function base64urlJson(value) {
+  return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+}
+
+function canonicalInternalTarget(path) {
+  if (
+    typeof path !== 'string'
+    || !path.startsWith('/')
+    || path.startsWith('//')
+    || path.includes('#')
+    || path.includes('://')
+  ) {
+    return null;
+  }
+  try {
+    const parsed = new URL(path, 'https://kmhub-internal.invalid');
+    if (parsed.origin !== 'https://kmhub-internal.invalid') return null;
+    return parsed.pathname + parsed.search;
+  } catch {
+    return null;
+  }
+}
+
+function signInternalAssertion(binding, method, target, rawBody) {
+  if (INTERNAL_SECRET.length < 32) return null;
+  const issuedAt = Math.floor(Date.now() / 1000);
+  const header = base64urlJson({
+    alg: 'HS256',
+    typ: 'JWT',
+    kid: 'coach-mcp-v1',
+  });
+  const payload = base64urlJson({
+    iss: PUBLIC_ORIGIN,
+    aud: internalAudienceFor(binding.profile),
+    sub: binding.user_id,
+    org_id: binding.org_id,
+    grant_id: binding.grant_id,
+    connection_id: binding.connection_id,
+    client_id: binding.client_id,
+    resource: RESOURCE_URL,
+    scope: binding.scope,
+    profile: binding.profile,
+    method: method.toUpperCase(),
+    path: target,
+    body_sha256: createHash('sha256').update(rawBody, 'utf8').digest('hex'),
+    iat: issuedAt,
+    exp: issuedAt + 15,
+    jti: randomUUID(),
+  });
+  const signingInput = header + '.' + payload;
+  const signature = createHmac('sha256', INTERNAL_SECRET)
+    .update(signingInput, 'utf8')
+    .digest('base64url');
+  return COACH_ASSERTION_PREFIX + signingInput + '.' + signature;
+}
+
+function makeInternalCaller(binding) {
+  return async function call(method, path, body) {
+    const target = canonicalInternalTarget(path);
+    if (!target) {
+      return {
+        ok: false,
+        status: 400,
+        data: { error: 'invalid_internal_route' },
+      };
+    }
+    const hasBody = body !== undefined && body !== null;
+    const rawBody = hasBody ? JSON.stringify(body) : '';
+    const assertion = signInternalAssertion(binding, method, target, rawBody);
+    if (!assertion) {
+      return {
+        ok: false,
+        status: 503,
+        data: { error: 'coach_authorization_unavailable' },
+      };
+    }
+    const response = await fetch(BASE.replace(/\/+$/, '') + target, {
+      method,
+      headers: {
+        Authorization: 'Bearer ' + assertion,
+        'content-type': 'application/json',
+      },
+      body: hasBody ? rawBody : undefined,
+    });
+    const text = await response.text();
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+    return { ok: response.ok, status: response.status, data };
+  };
 }
 
-// Which tool profile this ONE request asked for. Query string beats header; an
-// unknown or missing value resolves to `full`, never an error. Derived per request
-// and passed down by argument - nothing about the profile is ever stored, so the
-// server stays stateless and two tenants can hold two different profiles at once.
 function requestProfile(req, url) {
   const fromQuery = url.searchParams.get('profile');
-  const raw = req.headers['x-kmhub-profile'];
-  const fromHeader = Array.isArray(raw) ? raw[0] : raw;
-  return resolveProfile((fromQuery && fromQuery.trim()) || (typeof fromHeader === 'string' ? fromHeader.trim() : ''));
+  const rawHeader = req.headers['x-kmhub-profile'];
+  const fromHeader = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+  return resolveProfile(
+    (fromQuery && fromQuery.trim())
+    || (typeof fromHeader === 'string' ? fromHeader.trim() : ''),
+  );
 }
 
-// ---- one MCP request, scoped to one org's token ---------------------------
-async function handleMcpPost(req, res, token, profile) {
+async function handleMcpPost(req, res, caller, profile) {
   const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
-  registerTools(server, makeCaller(BASE, token), { profile });
-
-  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  registerTools(server, caller, { profile });
+  // The commands ship WITH the connector, not beside it. A file on disk cannot tell
+  // anyone whether the connector landed; a prompt listed by this server can only be
+  // there because it did. See prompts.mjs for the install this rule was written from.
+  registerPrompts(server);
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
 
-  // Tear the per-request server + transport down when the response closes.
   res.on('close', () => {
     transport.close().catch(() => {});
     server.close().catch(() => {});
@@ -132,22 +564,223 @@ async function handleMcpPost(req, res, token, profile) {
 
   try {
     await server.connect(transport);
-    // Let the transport read + parse the request body and write the response.
     await transport.handleRequest(req, res);
-  } catch (err) {
-    console.error('kmhub-mcp remote: request error', err);
+  } catch {
+    console.error('kmhub-mcp remote: MCP request failed');
     if (!res.headersSent) {
       sendRpcError(res, 500, -32603, 'Internal server error');
     }
   }
 }
 
-// ---- router ---------------------------------------------------------------
+async function handleRegister(req, res) {
+  let metadata;
+  try {
+    const raw = await readRequestBody(req);
+    metadata = JSON.parse(raw);
+  } catch (error) {
+    const status = error?.status === 413 ? 413 : 400;
+    return sendOAuthJson(res, status, { error: 'invalid_client_metadata' });
+  }
+  const registerFingerprint = [
+    typeof metadata?.client_name === 'string' ? metadata.client_name : 'unknown',
+    Array.isArray(metadata?.redirect_uris)
+      ? metadata.redirect_uris.filter((value) => typeof value === 'string').sort().join(',')
+      : 'none',
+    String(req.headers['user-agent'] || ''),
+  ].join('|');
+  const retryAfter = oauthAbuseLimited(req, 'register', registerFingerprint);
+  if (retryAfter) return sendOAuthRateLimit(res, retryAfter);
+
+  const result = await brokerRequest('register', metadata);
+  return sendOAuthJson(res, result.status, result.data);
+}
+
+async function handleAuthorize(req, url, res) {
+  const parameters = url.searchParams;
+  const redirectUri = parameters.get('redirect_uri');
+  const state = parameters.get('state');
+  const clientId = parameters.get('client_id') || 'missing-client';
+  const retryAfter = oauthAbuseLimited(req, 'authorize', clientId);
+  if (retryAfter) return sendOAuthRateLimit(res, retryAfter);
+
+  if (!redirectUri || !isApprovedRedirect(redirectUri) || !state) {
+    return sendOAuthJson(res, 400, {
+      error: 'invalid_request',
+      error_description: 'The authorization request has no approved redirect or state.',
+    });
+  }
+
+  const resource = canonicalResource(parameters.get('resource'));
+  const scope = normalizeRequestedScope(parameters.get('scope'));
+  if (
+    parameters.get('response_type') !== 'code'
+    || !parameters.get('client_id')
+    || resource !== RESOURCE_URL
+    || profileForScope(scope) === null
+    || !parameters.get('code_challenge')
+    || parameters.get('code_challenge_method') !== 'S256'
+  ) {
+    return redirectAuthorizationError(
+      res,
+      redirectUri,
+      state,
+      'invalid_request',
+      'The authorization request is incomplete or unsupported.',
+    );
+  }
+
+  const result = await brokerRequest('authorize', {
+    client_id: parameters.get('client_id'),
+    redirect_uri: redirectUri,
+    state,
+    resource,
+    scope,
+    code_challenge: parameters.get('code_challenge'),
+    code_challenge_method: parameters.get('code_challenge_method'),
+    request_partition_hash: tokenFingerprint(
+      'authorize-partition\n' + requestSourceIp(req),
+    ),
+  });
+  if (!result.ok || typeof result.data?.request_token !== 'string') {
+    const error = result.data?.error === 'invalid_client'
+      ? 'unauthorized_client'
+      : 'server_error';
+    return redirectAuthorizationError(
+      res,
+      redirectUri,
+      state,
+      error,
+      'KMHub could not start this authorization request.',
+    );
+  }
+
+  const location = new URL(CONSENT_URL);
+  location.searchParams.set('request_token', result.data.request_token);
+  res.writeHead(302, {
+    location: location.toString(),
+    'cache-control': 'no-store',
+    pragma: 'no-cache',
+  });
+  res.end();
+}
+
+async function parseForm(req) {
+  const raw = await readRequestBody(req);
+  return new URLSearchParams(raw);
+}
+
+async function handleToken(req, res) {
+  let form;
+  try {
+    form = await parseForm(req);
+  } catch (error) {
+    const status = error?.status === 413 ? 413 : 400;
+    return sendOAuthJson(res, status, { error: 'invalid_request' });
+  }
+
+  const grantType = form.get('grant_type');
+  const payload = {
+    grant_type: grantType,
+    client_id: form.get('client_id'),
+    resource: canonicalResource(form.get('resource')),
+  };
+  if (grantType === 'authorization_code') {
+    Object.assign(payload, {
+      code: form.get('code'),
+      redirect_uri: form.get('redirect_uri'),
+      code_verifier: form.get('code_verifier'),
+    });
+  } else if (grantType === 'refresh_token') {
+    // The scope is NOT forwarded on a refresh: the broker reads it off the refresh token,
+    // which is the grant the database actually stands behind. A client re-sending every
+    // scope it saw in the metadata (ChatGPT may) would otherwise be refused.
+    Object.assign(payload, {
+      refresh_token: form.get('refresh_token'),
+    });
+  }
+
+  const retryAfter = oauthAbuseLimited(
+    req,
+    'token',
+    typeof payload.client_id === 'string' ? payload.client_id : 'missing-client',
+  );
+  if (retryAfter) return sendOAuthRateLimit(res, retryAfter);
+
+  const result = await brokerRequest('token', payload);
+  return sendOAuthJson(res, result.status, result.data);
+}
+
+async function handleRevoke(req, res) {
+  let form;
+  try {
+    form = await parseForm(req);
+  } catch (error) {
+    const status = error?.status === 413 ? 413 : 400;
+    return sendOAuthJson(res, status, { error: 'invalid_request' });
+  }
+  const clientId = form.get('client_id') || 'missing-client';
+  const retryAfter = oauthAbuseLimited(req, 'revoke', clientId);
+  if (retryAfter) return sendOAuthRateLimit(res, retryAfter);
+
+  const result = await brokerRequest('revoke', {
+    client_id: form.get('client_id'),
+    token: form.get('token'),
+    token_type_hint: form.get('token_type_hint'),
+  });
+  if (result.status === 200) {
+    res.writeHead(200, {
+      'cache-control': 'no-store',
+      pragma: 'no-cache',
+    });
+    return res.end();
+  }
+  return sendOAuthJson(res, result.status, result.data);
+}
+
 const httpServer = http.createServer(async (req, res) => {
   const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
   const path = url.pathname.replace(/\/+$/, '') || '/';
 
-  // Health: no auth, cheap, used by pm2 / nginx / uptime monitors.
+  if (
+    req.method === 'GET'
+    && (
+      path === '/.well-known/oauth-protected-resource'
+      || path === '/.well-known/oauth-protected-resource/mcp'
+    )
+  ) {
+    return sendJson(res, 200, protectedResourceMetadata(), {
+      'access-control-allow-origin': '*',
+      'cache-control': 'public, max-age=300',
+    });
+  }
+
+  if (
+    req.method === 'GET'
+    && (
+      path === '/.well-known/oauth-authorization-server'
+      || path === '/.well-known/openid-configuration'
+    )
+  ) {
+    return sendJson(res, 200, authorizationServerMetadata(), {
+      'access-control-allow-origin': '*',
+      'cache-control': 'public, max-age=300',
+    });
+  }
+
+  if (req.method === 'POST' && path === '/register') {
+    return handleRegister(req, res);
+  }
+  if (req.method === 'GET' && path === '/authorize') {
+    return handleAuthorize(req, url, res);
+  }
+  if (req.method === 'POST' && path === '/token') {
+    return handleToken(req, res);
+  }
+  if (req.method === 'POST' && path === '/revoke') {
+    return handleRevoke(req, res);
+  }
+
   if (req.method === 'GET' && (path === '/health' || path === '/healthz')) {
     return sendJson(res, 200, {
       ok: true,
@@ -157,19 +790,33 @@ const httpServer = http.createServer(async (req, res) => {
       tools: TOOL_NAMES.length,
       families: FAMILY_NAMES,
       default_profile: DEFAULT_PROFILE,
-      profiles: Object.fromEntries(PROFILE_NAMES.map((p) => [p, toolNamesFor(p).length])),
+      profiles: Object.fromEntries(
+        PROFILE_NAMES.map((profile) => [profile, toolNamesFor(profile).length]),
+      ),
+      oauth: {
+        enabled: OAUTH_CONFIGURED,
+        authorization_server: OAUTH_CONFIGURED ? PUBLIC_ORIGIN : null,
+        resource: OAUTH_CONFIGURED ? RESOURCE_URL : null,
+        resource_metadata: OAUTH_CONFIGURED ? RESOURCE_METADATA_URL : null,
+        token_passthrough: false,
+      },
     });
   }
 
   if (path === '/mcp') {
-    // Streamable HTTP stateless: only POST carries JSON-RPC. GET (server SSE) is unused.
     if (req.method === 'GET' || req.method === 'DELETE') {
-      return sendRpcError(res, 405, -32000, 'Method not allowed: this server is stateless (POST /mcp only).', {
-        allow: 'POST',
-      });
+      return sendRpcError(
+        res,
+        405,
+        -32000,
+        'Method not allowed: this server is stateless (POST /mcp only).',
+        { allow: 'POST' },
+      );
     }
     if (req.method !== 'POST') {
-      return sendRpcError(res, 405, -32000, 'Method not allowed.', { allow: 'POST' });
+      return sendRpcError(res, 405, -32000, 'Method not allowed.', {
+        allow: 'POST',
+      });
     }
 
     const token = bearerToken(req);
@@ -178,19 +825,89 @@ const httpServer = http.createServer(async (req, res) => {
         res,
         401,
         -32001,
-        'Missing KM Hub API key. Send it as: Authorization: Bearer kmh_live_...',
-        { 'www-authenticate': 'Bearer realm="kmhub-mcp"' },
+        'Sign in to KMHub to connect this MCP server.',
+        { 'www-authenticate': oauthChallenge() },
+      );
+    }
+
+    let profile;
+    let caller;
+    if (API_KEY_PATTERN.test(token)) {
+      profile = requestProfile(req, url);
+      caller = makeCaller(BASE, token);
+    } else if (ACCESS_TOKEN_PATTERN.test(token)) {
+      // Set from the introspected binding once it is known, a few lines below. Left
+      // undefined here on purpose: the old code pinned it to 'coach' before anyone had
+      // said which product this token was for.
+      profile = null;
+      const introRetryAfter = oauthAbuseLimited(
+        req,
+        'introspect',
+        tokenFingerprint('introspect-token\n' + token),
+      );
+      if (introRetryAfter) {
+        return sendRpcError(
+          res,
+          429,
+          -32002,
+          'Too many coach authorization checks. Retry shortly.',
+          { 'retry-after': String(introRetryAfter) },
+        );
+      }
+      const introspection = await introspectCoachToken(token);
+      if (introspection.verdict === 'denied') {
+        return sendRpcError(
+          res,
+          401,
+          -32001,
+          'The Fully Booked Coach connection is invalid or expired.',
+          { 'www-authenticate': oauthChallenge('invalid_token') },
+        );
+      }
+      if (introspection.verdict !== 'allowed') {
+        return sendRpcError(
+          res,
+          503,
+          -32004,
+          'KMHub could not verify the coach connection. Retry shortly.',
+        );
+      }
+      if (INTERNAL_SECRET.length < 32) {
+        return sendRpcError(
+          res,
+          503,
+          -32004,
+          'KMHub coach authorization is not configured.',
+        );
+      }
+      // The tool surface follows the grant. A workspace connection gets the full set,
+      // the same as an API key for the same workspace; coach keeps its own bounded
+      // profile. introspectCoachToken has already refused any binding whose profile and
+      // scope disagree, so this value is the one the database stood behind.
+      profile = introspection.binding.profile === 'coach' ? 'coach' : DEFAULT_PROFILE;
+      caller = makeInternalCaller(introspection.binding);
+    } else {
+      return sendRpcError(
+        res,
+        401,
+        -32001,
+        'The KMHub credential is not recognized.',
+        { 'www-authenticate': oauthChallenge('invalid_token') },
       );
     }
 
     const retryAfter = rateLimited(token);
     if (retryAfter) {
-      return sendRpcError(res, 429, -32002, `Rate limit exceeded. Retry after ${retryAfter}s.`, {
-        'retry-after': String(retryAfter),
-      });
+      return sendRpcError(
+        res,
+        429,
+        -32002,
+        `Rate limit exceeded. Retry after ${retryAfter}s.`,
+        { 'retry-after': String(retryAfter) },
+      );
     }
 
-    return handleMcpPost(req, res, token, requestProfile(req, url));
+    return handleMcpPost(req, res, caller, profile);
   }
 
   return sendRpcError(res, 404, -32601, `Not found: ${req.method} ${path}`);
@@ -198,15 +915,14 @@ const httpServer = http.createServer(async (req, res) => {
 
 httpServer.listen(PORT, HOST, () => {
   console.error(
-    `kmhub-mcp remote ${SERVER_VERSION}: listening on http://${HOST}:${PORT}  (POST /mcp, GET /health). ` +
-      `Families: ${FAMILY_NAMES.join(', ')}. Profiles: ${PROFILE_NAMES.join(', ')} (default ${DEFAULT_PROFILE}). ` +
-      `Tools: ${TOOL_NAMES.join(', ')}.`,
+    `kmhub-mcp remote ${SERVER_VERSION}: listening on http://${HOST}:${PORT}. `
+      + `Families: ${FAMILY_NAMES.join(', ')}. Profiles: ${PROFILE_NAMES.join(', ')}. `
+      + `Tools: ${TOOL_NAMES.length}.`,
   );
 });
 
-// Graceful shutdown for pm2 restarts.
-for (const sig of ['SIGINT', 'SIGTERM']) {
-  process.on(sig, () => {
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
     httpServer.close(() => process.exit(0));
     setTimeout(() => process.exit(0), 3000).unref();
   });