@kivimedia/kmhub 2.9.0 → 2.10.0

package/remote.mjs

@@ -1,929 +1,929 @@
-#!/usr/bin/env node
-/**
- * Remote Streamable HTTP MCP server for KMHub.
- *
- * 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,
-  FAMILY_NAMES,
-  PROFILE_NAMES,
-  SERVER_NAME,
-  SERVER_VERSION,
-  TOOL_NAMES,
-  makeCaller,
-  registerTools,
-  resolveProfile,
-  toolNamesFor,
-} from './tools.mjs';
-
-const PORT = Number(process.env.PORT || 8830);
-const HOST = process.env.HOST || '0.0.0.0';
-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);
-}
-
-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 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 bucket = rateMap.get(key);
-  if (!bucket || now >= bucket.resetAt) {
-    evictExpiredAndBound(rateMap, now);
-    bucket = { count: 0, resetAt: now + WINDOW_MS };
-    rateMap.set(key, bucket);
-  }
-  bucket.count += 1;
-  if (bucket.count > limit) {
-    return Math.max(1, Math.ceil((bucket.resetAt - now) / 1000));
-  }
-  return 0;
-}
-
-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();
-  evictExpiredAndBound(buckets, now);
-  evictExpiredAndBound(oauthBuckets, now);
-  evictExpiredAndBound(introspectTokenBuckets, now);
-}, WINDOW_MS).unref();
-
-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);
-}
-
-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 = {}) {
-  sendJson(res, status, {
-    jsonrpc: '2.0',
-    error: { code, message },
-    id: null,
-  }, extraHeaders);
-}
-
-function bearerToken(req) {
-  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 };
-  };
-}
-
-function requestProfile(req, url) {
-  const fromQuery = url.searchParams.get('profile');
-  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() : ''),
-  );
-}
-
-async function handleMcpPost(req, res, caller, profile) {
-  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
-  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,
-  });
-
-  res.on('close', () => {
-    transport.close().catch(() => {});
-    server.close().catch(() => {});
-  });
-
-  try {
-    await server.connect(transport);
-    await transport.handleRequest(req, res);
-  } catch {
-    console.error('kmhub-mcp remote: MCP request failed');
-    if (!res.headersSent) {
-      sendRpcError(res, 500, -32603, 'Internal server error');
-    }
-  }
-}
-
-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(/\/+$/, '') || '/';
-
-  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,
-      server: SERVER_NAME,
-      version: SERVER_VERSION,
-      transport: 'streamable-http',
-      tools: TOOL_NAMES.length,
-      families: FAMILY_NAMES,
-      default_profile: DEFAULT_PROFILE,
-      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') {
-    if (req.method === 'GET' || req.method === 'DELETE') {
-      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',
-      });
-    }
-
-    const token = bearerToken(req);
-    if (!token) {
-      return sendRpcError(
-        res,
-        401,
-        -32001,
-        '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 handleMcpPost(req, res, caller, profile);
-  }
-
-  return sendRpcError(res, 404, -32601, `Not found: ${req.method} ${path}`);
-});
-
-httpServer.listen(PORT, HOST, () => {
-  console.error(
-    `kmhub-mcp remote ${SERVER_VERSION}: listening on http://${HOST}:${PORT}. `
-      + `Families: ${FAMILY_NAMES.join(', ')}. Profiles: ${PROFILE_NAMES.join(', ')}. `
-      + `Tools: ${TOOL_NAMES.length}.`,
-  );
-});
-
-for (const signal of ['SIGINT', 'SIGTERM']) {
-  process.on(signal, () => {
-    httpServer.close(() => process.exit(0));
-    setTimeout(() => process.exit(0), 3000).unref();
-  });
-}
+#!/usr/bin/env node
+/**
+ * Remote Streamable HTTP MCP server for KMHub.
+ *
+ * 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,
+  FAMILY_NAMES,
+  PROFILE_NAMES,
+  SERVER_NAME,
+  SERVER_VERSION,
+  TOOL_NAMES,
+  makeCaller,
+  registerTools,
+  resolveProfile,
+  toolNamesFor,
+} from './tools.mjs';
+
+const PORT = Number(process.env.PORT || 8830);
+const HOST = process.env.HOST || '0.0.0.0';
+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);
+}
+
+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 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 bucket = rateMap.get(key);
+  if (!bucket || now >= bucket.resetAt) {
+    evictExpiredAndBound(rateMap, now);
+    bucket = { count: 0, resetAt: now + WINDOW_MS };
+    rateMap.set(key, bucket);
+  }
+  bucket.count += 1;
+  if (bucket.count > limit) {
+    return Math.max(1, Math.ceil((bucket.resetAt - now) / 1000));
+  }
+  return 0;
+}
+
+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();
+  evictExpiredAndBound(buckets, now);
+  evictExpiredAndBound(oauthBuckets, now);
+  evictExpiredAndBound(introspectTokenBuckets, now);
+}, WINDOW_MS).unref();
+
+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);
+}
+
+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 = {}) {
+  sendJson(res, status, {
+    jsonrpc: '2.0',
+    error: { code, message },
+    id: null,
+  }, extraHeaders);
+}
+
+function bearerToken(req) {
+  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 };
+  };
+}
+
+function requestProfile(req, url) {
+  const fromQuery = url.searchParams.get('profile');
+  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() : ''),
+  );
+}
+
+async function handleMcpPost(req, res, caller, profile) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  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,
+  });
+
+  res.on('close', () => {
+    transport.close().catch(() => {});
+    server.close().catch(() => {});
+  });
+
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(req, res);
+  } catch {
+    console.error('kmhub-mcp remote: MCP request failed');
+    if (!res.headersSent) {
+      sendRpcError(res, 500, -32603, 'Internal server error');
+    }
+  }
+}
+
+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(/\/+$/, '') || '/';
+
+  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,
+      server: SERVER_NAME,
+      version: SERVER_VERSION,
+      transport: 'streamable-http',
+      tools: TOOL_NAMES.length,
+      families: FAMILY_NAMES,
+      default_profile: DEFAULT_PROFILE,
+      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') {
+    if (req.method === 'GET' || req.method === 'DELETE') {
+      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',
+      });
+    }
+
+    const token = bearerToken(req);
+    if (!token) {
+      return sendRpcError(
+        res,
+        401,
+        -32001,
+        '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 handleMcpPost(req, res, caller, profile);
+  }
+
+  return sendRpcError(res, 404, -32601, `Not found: ${req.method} ${path}`);
+});
+
+httpServer.listen(PORT, HOST, () => {
+  console.error(
+    `kmhub-mcp remote ${SERVER_VERSION}: listening on http://${HOST}:${PORT}. `
+      + `Families: ${FAMILY_NAMES.join(', ')}. Profiles: ${PROFILE_NAMES.join(', ')}. `
+      + `Tools: ${TOOL_NAMES.length}.`,
+  );
+});
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    httpServer.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 3000).unref();
+  });
+}