strapi-mcp-server 0.1.1

package/server/src/controllers/oauth/register.ts

@@ -0,0 +1,109 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import type { Context } from 'koa';
+import { getConfig } from '../../config';
+import { ALL_SCOPES, parseScope, type Scope } from '../../services/oauth/scopes';
+import { ensureEmbeddedMode } from './mode-guard';
+
+/**
+ * RFC 7591 Dynamic Client Registration.
+ *
+ * When `oauth.dcr.enabled` is true, any caller can register a client. Safe
+ * because (a) redirect_uris are restricted to loopback HTTP or HTTPS by
+ * `services/oauth/clients.ts.validateRedirectUris`, and (b) the admin still
+ * has to approve the resulting client on the consent screen before any token
+ * is issued. When disabled, this endpoint 403s and clients must be created
+ * manually by an admin via the Clients page.
+ */
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  async register(ctx: Context): Promise<void> {
+    if (!ensureEmbeddedMode(ctx, strapi)) return;
+    const cfg = getConfig(strapi);
+    if (!cfg.oauth.dcr.enabled) {
+      ctx.status = 403;
+      ctx.body = { error: 'dcr_disabled' };
+      return;
+    }
+
+    const ip = ctx.ip ?? ctx.request.ip;
+    const userAgent = ctx.request.header['user-agent'] as string | undefined;
+    const wait = await strapi.plugin('mcp-server').service('rate-limiter').checkDcr(ip);
+    if (wait > 0) {
+      ctx.response.set('Retry-After', String(wait));
+      ctx.status = 429;
+      ctx.body = { error: 'too_many_requests', error_description: 'DCR rate limit exceeded' };
+      strapi.plugin('mcp-server').service('audit').record({
+        ts: new Date(),
+        principalType: 'system',
+        principalId: 'anonymous',
+        tool: 'oauth.dcr.register',
+        params: { rateLimited: true, retryAfterSec: wait },
+        resultStatus: 'error',
+        errorCode: 'too_many_requests',
+        ip,
+        userAgent,
+      });
+      return;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const body = ((ctx.request as any).body ?? {}) as {
+      client_name?: string;
+      redirect_uris?: string[];
+      scope?: string;
+      token_endpoint_auth_method?: string;
+      grant_types?: string[];
+    };
+    if (!body.client_name || !body.redirect_uris) {
+      ctx.status = 400;
+      ctx.body = { error: 'invalid_client_metadata' };
+      return;
+    }
+    const requestedScopes = parseScope(body.scope ?? '');
+    const grantedScopes: Scope[] =
+      requestedScopes.length > 0 ? requestedScopes : [...ALL_SCOPES];
+
+    try {
+      const { client, clientSecret } = await strapi
+        .plugin('mcp-server')
+        .service('clients')
+        .create({
+          clientName: body.client_name,
+          redirectUris: body.redirect_uris,
+          scopes: grantedScopes,
+          isConfidential: body.token_endpoint_auth_method
+            ? body.token_endpoint_auth_method !== 'none'
+            : false,
+        });
+      ctx.status = 201;
+      ctx.body = {
+        client_id: client.clientId,
+        client_name: client.clientName,
+        redirect_uris: client.redirectUris,
+        grant_types: client.grantTypes,
+        scope: client.scopes.join(' '),
+        token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+        ...(clientSecret ? { client_secret: clientSecret } : {}),
+      };
+      strapi.plugin('mcp-server').service('audit').record({
+        ts: new Date(),
+        principalType: 'system',
+        principalId: 'anonymous',
+        clientId: client.clientId,
+        tool: 'oauth.dcr.register',
+        params: {
+          client_name: client.clientName,
+          redirect_uris: client.redirectUris,
+          scopes: client.scopes,
+        },
+        resultStatus: 'ok',
+        ip,
+        userAgent,
+      });
+    } catch (err) {
+      ctx.status = 400;
+      ctx.body = { error: 'invalid_client_metadata', error_description: (err as Error).message };
+    }
+  },
+});

package/server/src/controllers/oauth/token.ts

@@ -0,0 +1,206 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import type { Context } from 'koa';
+import { verifyS256 } from '../../services/oauth/pkce';
+import { parseScope, scopeString, isSubsetOf, type Scope } from '../../services/oauth/scopes';
+import { canonicalResourceUrl } from '../../services/oauth/audience';
+import { ensureEmbeddedMode } from './mode-guard';
+
+interface TokenRequestBody {
+  grant_type?: string;
+  code?: string;
+  redirect_uri?: string;
+  client_id?: string;
+  client_secret?: string;
+  code_verifier?: string;
+  refresh_token?: string;
+  resource?: string;
+  scope?: string;
+}
+
+function error(
+  ctx: Context,
+  status: number,
+  code: string,
+  description?: string
+): void {
+  ctx.status = status;
+  ctx.set('Cache-Control', 'no-store');
+  ctx.body = { error: code, ...(description ? { error_description: description } : {}) };
+}
+
+function readClientCreds(ctx: Context, body: TokenRequestBody): {
+  clientId?: string;
+  clientSecret?: string;
+} {
+  const header = ctx.request.header.authorization;
+  if (header?.startsWith('Basic ')) {
+    try {
+      const decoded = Buffer.from(header.slice(6).trim(), 'base64').toString('utf8');
+      const idx = decoded.indexOf(':');
+      if (idx > 0) {
+        return {
+          clientId: decoded.slice(0, idx),
+          clientSecret: decoded.slice(idx + 1),
+        };
+      }
+    } catch {
+      /* fall through */
+    }
+  }
+  return { clientId: body.client_id, clientSecret: body.client_secret };
+}
+
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  async token(ctx: Context): Promise<void> {
+    if (!ensureEmbeddedMode(ctx, strapi)) return;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const body = ((ctx.request as any).body ?? {}) as TokenRequestBody;
+    const grant = body.grant_type;
+
+    if (grant === 'authorization_code') return handleAuthCode(strapi, ctx, body);
+    if (grant === 'refresh_token') return handleRefresh(strapi, ctx, body);
+
+    return error(ctx, 400, 'unsupported_grant_type', `grant_type=${grant ?? ''} not supported`);
+  },
+
+  async revoke(ctx: Context): Promise<void> {
+    if (!ensureEmbeddedMode(ctx, strapi)) return;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const body = ((ctx.request as any).body ?? {}) as { token?: string };
+    if (!body.token) {
+      ctx.status = 400;
+      ctx.body = { error: 'invalid_request' };
+      return;
+    }
+    try {
+      await strapi.plugin('mcp-server').service('tokens').revokeRefresh(body.token);
+    } catch {
+      /* swallow per RFC 7009 */
+    }
+    ctx.status = 200;
+    ctx.body = { ok: true };
+  },
+});
+
+async function handleAuthCode(
+  strapi: Core.Strapi,
+  ctx: Context,
+  body: TokenRequestBody
+): Promise<void> {
+  const creds = readClientCreds(ctx, body);
+  if (!creds.clientId) return error(ctx, 400, 'invalid_request', 'client_id required');
+  if (!body.code) return error(ctx, 400, 'invalid_request', 'code required');
+  if (!body.redirect_uri) return error(ctx, 400, 'invalid_request', 'redirect_uri required');
+  if (!body.code_verifier) return error(ctx, 400, 'invalid_request', 'code_verifier required');
+  if (body.resource !== canonicalResourceUrl(strapi)) {
+    return error(ctx, 400, 'invalid_target', 'resource mismatch');
+  }
+
+  const clientsSvc = strapi.plugin('mcp-server').service('clients');
+  const client = await clientsSvc.findActive(creds.clientId);
+  if (!client) return error(ctx, 401, 'invalid_client');
+  if (!clientsSvc.verifySecret(client, creds.clientSecret)) {
+    return error(ctx, 401, 'invalid_client');
+  }
+  if (!clientsSvc.isAllowedRedirectUri(client, body.redirect_uri)) {
+    return error(ctx, 400, 'invalid_grant', 'redirect_uri mismatch');
+  }
+
+  const tokensSvc = strapi.plugin('mcp-server').service('tokens');
+  const codesSvc = strapi.plugin('mcp-server').service('auth-codes');
+  const consumed = await codesSvc.consume(body.code);
+  if (consumed === 'replayed') {
+    // Don't reveal which family — but log the incident.
+    strapi.log.warn(`[mcp-server] authorization code replay on client=${client.clientId}`);
+    return error(ctx, 400, 'invalid_grant', 'code already used');
+  }
+  if (!consumed) return error(ctx, 400, 'invalid_grant');
+  if (consumed.clientId !== client.clientId) return error(ctx, 400, 'invalid_grant');
+  if (consumed.redirectUri !== body.redirect_uri) {
+    return error(ctx, 400, 'invalid_grant', 'redirect_uri mismatch');
+  }
+  if (consumed.resource !== body.resource) return error(ctx, 400, 'invalid_target');
+  if (!verifyS256(body.code_verifier, consumed.codeChallenge)) {
+    return error(ctx, 400, 'invalid_grant', 'PKCE verification failed');
+  }
+
+  const scopes = parseScope(consumed.scope);
+  const minted = await tokensSvc.mint({
+    adminUserId: consumed.adminUserId,
+    clientId: client.clientId,
+    scope: scopes,
+  });
+  await clientsSvc.touchLastUsed(client.clientId);
+
+  ctx.set('Cache-Control', 'no-store');
+  ctx.body = {
+    access_token: minted.accessToken,
+    token_type: 'Bearer',
+    expires_in: Math.floor(
+      (minted.accessTokenExpiresAt.getTime() - Date.now()) / 1000
+    ),
+    refresh_token: minted.refreshToken,
+    scope: scopeString(scopes),
+  };
+}
+
+async function handleRefresh(
+  strapi: Core.Strapi,
+  ctx: Context,
+  body: TokenRequestBody
+): Promise<void> {
+  const creds = readClientCreds(ctx, body);
+  if (!creds.clientId) return error(ctx, 400, 'invalid_request', 'client_id required');
+  if (!body.refresh_token) return error(ctx, 400, 'invalid_request', 'refresh_token required');
+  if (body.resource && body.resource !== canonicalResourceUrl(strapi)) {
+    return error(ctx, 400, 'invalid_target', 'resource mismatch');
+  }
+
+  const clientsSvc = strapi.plugin('mcp-server').service('clients');
+  const client = await clientsSvc.findActive(creds.clientId);
+  if (!client) return error(ctx, 401, 'invalid_client');
+  if (!clientsSvc.verifySecret(client, creds.clientSecret)) {
+    return error(ctx, 401, 'invalid_client');
+  }
+
+  const tokensSvc = strapi.plugin('mcp-server').service('tokens');
+  const consumed = await tokensSvc.consumeRefresh(body.refresh_token);
+  if (!consumed) return error(ctx, 400, 'invalid_grant');
+  if (consumed.clientId !== client.clientId) {
+    await tokensSvc.revokeFamily(consumed.familyId);
+    return error(ctx, 400, 'invalid_grant');
+  }
+
+  let scopes = parseScope(consumed.scope);
+  if (body.scope) {
+    const requested = parseScope(body.scope);
+    if (!isSubsetOf(requested, scopes as Scope[])) {
+      return error(ctx, 400, 'invalid_scope', 'cannot expand scopes on refresh');
+    }
+    scopes = requested;
+  }
+
+  const minted = await tokensSvc.mint({
+    adminUserId: consumed.adminUserId,
+    clientId: client.clientId,
+    scope: scopes,
+    familyId: consumed.familyId,
+    parentJti: consumed.parentJti ?? undefined,
+  });
+
+  await tokensSvc.markRotated(consumed.id, tokensSvc.hash(minted.refreshToken));
+  await clientsSvc.touchLastUsed(client.clientId);
+
+  ctx.set('Cache-Control', 'no-store');
+  ctx.body = {
+    access_token: minted.accessToken,
+    token_type: 'Bearer',
+    expires_in: Math.floor(
+      (minted.accessTokenExpiresAt.getTime() - Date.now()) / 1000
+    ),
+    refresh_token: minted.refreshToken,
+    scope: scopeString(scopes),
+  };
+}

package/server/src/controllers/proxy.ts

@@ -0,0 +1,81 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import type { Context } from 'koa';
+import { getConfig } from '../config';
+import { verifySignature } from '../services/proxy-client';
+
+/**
+ * Receives a request forwarded from a peer Strapi instance for a session
+ * this instance owns. The forwarder has already verified the original
+ * bearer token; trust is established via the HMAC on `X-MCP-Proxy-Auth`.
+ *
+ * Note: this endpoint is publicly mountable. Security comes from the HMAC
+ * (signed with `redis.internalSecret`, which is shared only among cluster
+ * peers) and the small attack surface — the only legal action here is to
+ * dispatch into a local session's existing transport.
+ */
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  async receive(ctx: Context): Promise<void> {
+    const cfg = getConfig(strapi);
+    const secret = cfg.redis?.internalSecret;
+    if (!secret) {
+      ctx.status = 503;
+      ctx.body = { error: 'proxy_disabled' };
+      return;
+    }
+
+    const sessionId = decodeURIComponent(ctx.params.sessionId as string);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const body = (ctx.request as any).body;
+    const bodyStr =
+      body === undefined || body === null
+        ? ''
+        : typeof body === 'string'
+          ? body
+          : JSON.stringify(body);
+
+    const ok = verifySignature({
+      header: ctx.request.header['x-mcp-proxy-auth'] as string | undefined,
+      method: ctx.method,
+      sessionId,
+      body: bodyStr,
+      secret,
+    });
+    if (!ok) {
+      strapi.log.warn(`[mcp-server] proxy receive: bad HMAC for session=${sessionId}`);
+      ctx.status = 401;
+      ctx.body = { error: 'invalid_proxy_auth' };
+      return;
+    }
+
+    const sessionStore = strapi.plugin('mcp-server').service('session-store');
+
+    if (ctx.method === 'DELETE') {
+      await sessionStore.close(sessionId);
+      ctx.status = 204;
+      return;
+    }
+
+    const session = sessionStore.getLocal(sessionId);
+    if (!session) {
+      // The directory pointed here but we don't have the session — maybe the
+      // process just restarted or the session was swept. Tell the forwarder.
+      ctx.status = 404;
+      ctx.body = { error: 'session_not_found' };
+      return;
+    }
+
+    ctx.respond = false;
+    ctx.req.socket.setTimeout(0);
+    try {
+      await session.transport.handleRequest(ctx.req, ctx.res, body);
+    } catch (err) {
+      strapi.log.error('[mcp-server] proxy receive dispatch failed', err as Error);
+      if (!ctx.res.headersSent) {
+        ctx.res.statusCode = 500;
+        ctx.res.end(JSON.stringify({ error: 'internal_error' }));
+      }
+    }
+  },
+});

package/server/src/destroy.ts

@@ -0,0 +1,28 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+
+export async function destroy({ strapi }: { strapi: Core.Strapi }): Promise<void> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const rt = (strapi as any).__mcpServerRuntime;
+  if (rt?.sweepTimer) clearInterval(rt.sweepTimer);
+  if (rt?.auditTimer) clearInterval(rt.auditTimer);
+
+  try {
+    strapi.plugin('mcp-server').service('heartbeat').stop();
+  } catch (err) {
+    strapi.log.warn(`[mcp-server] heartbeat stop: ${(err as Error).message}`);
+  }
+
+  try {
+    await strapi.plugin('mcp-server').service('session-store').closeAll();
+  } catch (err) {
+    strapi.log.error('[mcp-server] failed to close sessions on destroy', err as Error);
+  }
+
+  try {
+    await strapi.plugin('mcp-server').service('redis').disconnect();
+  } catch (err) {
+    strapi.log.warn(`[mcp-server] redis disconnect: ${(err as Error).message}`);
+  }
+}

package/server/src/index.ts

@@ -0,0 +1,23 @@
+'use strict';
+
+import { register } from './register';
+import { bootstrap } from './bootstrap';
+import { destroy } from './destroy';
+import config from './config';
+import contentTypes from './content-types';
+import routes from './routes';
+import controllers from './controllers';
+import services from './services';
+import policies from './policies';
+
+export default {
+  register,
+  bootstrap,
+  destroy,
+  config,
+  contentTypes,
+  routes,
+  controllers,
+  services,
+  policies,
+};

package/server/src/policies/authenticate.ts

@@ -0,0 +1,81 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { errors } from '@strapi/utils';
+import { bearerChallenge } from '../services/oauth/errors';
+
+export interface PolicyCtx {
+  request: { header: Record<string, string | undefined> };
+  response: { set: (h: string, v: string) => void };
+  state: Record<string, unknown>;
+}
+
+/**
+ * Validate the Authorization header, attach { user, permissions, scopes, clientId, jti }
+ * to ctx.state.mcpAuth. Failure → 401 with WWW-Authenticate per RFC 6750.
+ *
+ * Never log the Authorization header — only its presence/absence.
+ */
+export default async (
+  ctx: PolicyCtx,
+  _cfg: unknown,
+  { strapi }: { strapi: Core.Strapi }
+): Promise<boolean> => {
+  const header = ctx.request.header.authorization;
+  if (!header || !header.startsWith('Bearer ')) {
+    ctx.response.set(
+      'WWW-Authenticate',
+      bearerChallenge(strapi, { error: 'invalid_token', error_description: 'missing bearer token' })
+    );
+    throw new errors.UnauthorizedError('missing bearer token');
+  }
+  const token = header.slice(7).trim();
+  if (!token) {
+    ctx.response.set('WWW-Authenticate', bearerChallenge(strapi, { error: 'invalid_token' }));
+    throw new errors.UnauthorizedError('empty bearer token');
+  }
+
+  const tokens = strapi.plugin('mcp-server').service('tokens');
+  let claims;
+  try {
+    claims = await tokens.verifyAccessToken(token);
+  } catch (err) {
+    const message = (err as Error).message;
+    ctx.response.set(
+      'WWW-Authenticate',
+      bearerChallenge(strapi, {
+        error: 'invalid_token',
+        error_description: message === 'expired' ? 'token expired' : 'invalid token',
+      })
+    );
+    throw new errors.UnauthorizedError(message);
+  }
+
+  const principal = await strapi
+    .plugin('mcp-server')
+    .service('permissions')
+    .loadPrincipal(claims.sub);
+  if (!principal) {
+    try {
+      await tokens.revokeAllForUser(claims.sub);
+      await strapi
+        .plugin('mcp-server')
+        .service('session-store')
+        .closeForPrincipal(claims.sub);
+    } catch {
+      /* non-fatal */
+    }
+    ctx.response.set('WWW-Authenticate', bearerChallenge(strapi, { error: 'invalid_token' }));
+    throw new errors.UnauthorizedError('principal unavailable');
+  }
+
+  ctx.state.mcpAuth = {
+    principal,
+    scopes: claims.scope,
+    clientId: claims.clientId,
+    jti: claims.jti,
+    adminUserId: claims.sub,
+    exp: claims.exp,
+  };
+  return true;
+};

package/server/src/policies/index.ts

@@ -0,0 +1,13 @@
+'use strict';
+
+import origin from './origin';
+import authenticate from './authenticate';
+import rateLimit from './rateLimit';
+import scope from './scope';
+
+export default {
+  origin,
+  authenticate,
+  rateLimit,
+  scope,
+};

package/server/src/policies/origin.ts

@@ -0,0 +1,50 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { errors } from '@strapi/utils';
+import { getConfig } from '../config';
+
+/**
+ * Origin + Host validation. Required for DNS rebinding mitigation.
+ * Empty allowlist → reject all (default-deny).
+ *
+ * Strapi's PolicyContext is built via Object.assign({}, ctx) which only copies
+ * own properties — `ctx.set`/`ctx.throw` (on the Koa prototype) get stripped.
+ * Use `ctx.response.*` for header/status work and throw Strapi error classes
+ * to surface proper HTTP statuses through the framework's error middleware.
+ */
+export default (
+  ctx: {
+    request: { header: Record<string, string | undefined>; url?: string; method?: string };
+    response: { set: (h: string, v: string) => void };
+  },
+  _cfg: unknown,
+  { strapi }: { strapi: Core.Strapi }
+): boolean => {
+  const cfg = getConfig(strapi);
+  const origin = ctx.request.header.origin;
+  const host = ctx.request.header.host;
+
+  if (cfg.allowedOrigins.length === 0) {
+    throw new errors.ForbiddenError('origin not allowed');
+  }
+
+  if (cfg.allowedOrigins.includes('*')) return true;
+
+  if (origin) {
+    if (!cfg.allowedOrigins.includes(origin)) {
+      throw new errors.ForbiddenError('origin not allowed');
+    }
+  } else {
+    try {
+      const resourceHost = new URL(cfg.resourceUrl).host;
+      if (!host || host !== resourceHost) {
+        throw new errors.ForbiddenError('host not allowed');
+      }
+    } catch (err) {
+      if (err instanceof errors.ForbiddenError) throw err;
+      throw new errors.ForbiddenError('host validation failed');
+    }
+  }
+  return true;
+};

package/server/src/policies/rateLimit.ts

@@ -0,0 +1,27 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { errors } from '@strapi/utils';
+
+export interface PolicyCtx {
+  state: Record<string, unknown>;
+  ip?: string;
+  request: { ip?: string };
+  response: { set: (h: string, v: string) => void };
+}
+
+export default async (
+  ctx: PolicyCtx,
+  _cfg: unknown,
+  { strapi }: { strapi: Core.Strapi }
+): Promise<boolean> => {
+  const mcpAuth = ctx.state.mcpAuth as { adminUserId?: string } | undefined;
+  const principalId = mcpAuth?.adminUserId;
+  const ip = ctx.ip ?? ctx.request.ip;
+  const wait = await strapi.plugin('mcp-server').service('rate-limiter').check(principalId, ip);
+  if (wait > 0) {
+    ctx.response.set('Retry-After', String(wait));
+    throw new errors.RateLimitError('rate limit exceeded');
+  }
+  return true;
+};

package/server/src/policies/scope.ts

@@ -0,0 +1,32 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { errors } from '@strapi/utils';
+import { bearerChallenge } from '../services/oauth/errors';
+import type { Scope } from '../services/oauth/scopes';
+
+export interface PolicyCtx {
+  state: { mcpAuth?: { scopes?: Scope[] } };
+  response: { set: (h: string, v: string) => void };
+}
+
+/**
+ * Higher-order policy for admin/audit routes. Returns a policy function whose
+ * `config` is the required scope name. Currently unused for /mcp itself
+ * (per-tool checks happen inside the tool callback).
+ */
+export default (
+  ctx: PolicyCtx,
+  config: { scope: Scope },
+  { strapi }: { strapi: Core.Strapi }
+): boolean => {
+  const granted = ctx.state.mcpAuth?.scopes ?? [];
+  if (!granted.includes(config.scope)) {
+    ctx.response.set(
+      'WWW-Authenticate',
+      bearerChallenge(strapi, { error: 'insufficient_scope', scope: config.scope })
+    );
+    throw new errors.ForbiddenError('insufficient_scope');
+  }
+  return true;
+};