strapi-mcp-server 0.1.1

package/server/src/services/proxy-client.ts

@@ -0,0 +1,167 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { createHmac, timingSafeEqual } from 'crypto';
+import { request as httpRequest } from 'http';
+import { request as httpsRequest } from 'https';
+import type { Context } from 'koa';
+import { URL } from 'url';
+import { getConfig } from '../config';
+
+const HEADER = 'x-mcp-proxy-auth';
+const SKEW_MS = 30_000;
+
+interface SignArgs {
+  method: string;
+  sessionId: string;
+  body: string;
+  secret: string;
+  ts?: number;
+}
+
+function sign({ method, sessionId, body, secret, ts = Date.now() }: SignArgs): {
+  header: string;
+  ts: number;
+} {
+  const bodyHash = body
+    ? createHmac('sha256', secret).update(body).digest('hex')
+    : '';
+  const payload = `${method.toUpperCase()}|${sessionId}|${ts}|${bodyHash}`;
+  const mac = createHmac('sha256', secret).update(payload).digest('hex');
+  return { header: `t=${ts};s=${mac}`, ts };
+}
+
+/**
+ * Verify a `X-MCP-Proxy-Auth` header. Returns true on success; the receiver
+ * MUST refuse the request on false.
+ *
+ * Defense-in-depth note: timing-safe compare of MACs, ±30s window on the
+ * timestamp to bound replay. The HMAC includes the method, session id, and a
+ * hash of the body so a stolen header can't be reused on a different request.
+ */
+export function verifySignature(args: {
+  header: string | undefined;
+  method: string;
+  sessionId: string;
+  body: string;
+  secret: string;
+}): boolean {
+  if (!args.header) return false;
+  const parts = Object.fromEntries(
+    args.header.split(';').map((p) => {
+      const i = p.indexOf('=');
+      return i < 0 ? [p, ''] : [p.slice(0, i), p.slice(i + 1)];
+    })
+  );
+  const ts = Number(parts.t);
+  const provided = parts.s;
+  if (!Number.isFinite(ts) || !provided) return false;
+  if (Math.abs(Date.now() - ts) > SKEW_MS) return false;
+  const { header } = sign({
+    method: args.method,
+    sessionId: args.sessionId,
+    body: args.body,
+    secret: args.secret,
+    ts,
+  });
+  const expected = header.split(';')[1].slice(2);
+  const a = Buffer.from(expected, 'hex');
+  const b = Buffer.from(provided, 'hex');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  /**
+   * Forward the current request to `address` (e.g. `http://10.0.0.5:1337`).
+   * Streams the response (including SSE) back to the original client.
+   *
+   * Throws on transport-level failure (peer unreachable, TLS error). Callers
+   * should catch and either respond 502 or invalidate the directory entry.
+   */
+  async forward(ctx: Context, address: string, sessionId: string): Promise<void> {
+    const cfg = getConfig(strapi);
+    const secret = cfg.redis?.internalSecret;
+    if (!secret) {
+      throw new Error('redis.internalSecret is required for cross-instance proxying');
+    }
+
+    const peer = new URL(address);
+    peer.pathname = `/__mcp/proxy/${encodeURIComponent(sessionId)}`;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const parsed = (ctx.request as any).body;
+    const bodyStr = parsed === undefined || parsed === null ? '' : JSON.stringify(parsed);
+    const { header: authHeader } = sign({
+      method: ctx.method,
+      sessionId,
+      body: bodyStr,
+      secret,
+    });
+
+    const headers: Record<string, string> = {
+      [HEADER]: authHeader,
+      // Pass through what the SDK needs.
+      accept: (ctx.request.header.accept as string) ?? 'application/json, text/event-stream',
+      'mcp-session-id': sessionId,
+    };
+    if (bodyStr) {
+      headers['content-type'] = (ctx.request.header['content-type'] as string) ?? 'application/json';
+      headers['content-length'] = String(Buffer.byteLength(bodyStr));
+    }
+    // Forward the original Authorization header so audit / debugging can
+    // trace it on the owner instance, though the owner trusts the HMAC and
+    // does not re-verify the JWT.
+    if (ctx.request.header.authorization) {
+      headers.authorization = ctx.request.header.authorization as string;
+    }
+
+    const isHttps = peer.protocol === 'https:';
+    const reqFn = isHttps ? httpsRequest : httpRequest;
+
+    return new Promise<void>((resolve, reject) => {
+      const upstream = reqFn(
+        {
+          protocol: peer.protocol,
+          hostname: peer.hostname,
+          port: peer.port || (isHttps ? 443 : 80),
+          method: ctx.method,
+          path: peer.pathname,
+          headers,
+          // SSE: never timeout
+          timeout: 0,
+        },
+        (res) => {
+          ctx.respond = false;
+          ctx.res.statusCode = res.statusCode ?? 502;
+          for (const [k, v] of Object.entries(res.headers)) {
+            if (v !== undefined) ctx.res.setHeader(k, v as string | string[]);
+          }
+          res.on('error', (err) => {
+            strapi.log.warn(`[mcp-server] proxy upstream error: ${err.message}`);
+            try {
+              ctx.res.end();
+            } catch {
+              /* socket already closed */
+            }
+          });
+          res.pipe(ctx.res);
+          res.on('end', () => resolve());
+          ctx.req.on('close', () => {
+            // Client disconnected — tear down the upstream connection so we
+            // don't leak open sockets on the owner instance.
+            upstream.destroy();
+          });
+        }
+      );
+
+      upstream.on('error', (err) => reject(err));
+
+      if (bodyStr) upstream.write(bodyStr);
+      upstream.end();
+    });
+  },
+
+  /** Re-export verify helper so the receiver controller can use it. */
+  verify: verifySignature,
+});

package/server/src/services/rate-limiter.ts

@@ -0,0 +1,180 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { getConfig, type RateBucketConfig } from '../config';
+import type { RedisLike } from './redis';
+
+interface Bucket {
+  tokens: number;
+  lastRefill: number;
+}
+
+const principalBuckets = new Map<string, Bucket>();
+const ipBuckets = new Map<string, Bucket>();
+const dcrBuckets = new Map<string, Bucket>();
+let lastReap = Date.now();
+
+// Token-bucket take, in Lua so refill + decrement are atomic. Returns 0 when
+// the request is allowed, otherwise the integer seconds the caller should
+// wait before retrying (ceil((1 - tokens) / refill)). Bucket state lives in
+// a small hash and is allowed to expire when idle.
+const TAKE_LUA = `
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local refill = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local idle_ttl = tonumber(ARGV[4])
+
+local b = redis.call('HMGET', key, 'tokens', 'lastRefill')
+local tokens = tonumber(b[1])
+local last = tonumber(b[2])
+if tokens == nil then
+  tokens = capacity
+  last = now
+end
+
+local elapsed = (now - last) / 1000.0
+if elapsed < 0 then elapsed = 0 end
+tokens = math.min(capacity, tokens + elapsed * refill)
+
+local wait = 0
+if tokens < 1 then
+  wait = math.ceil((1 - tokens) / refill)
+  if wait < 1 then wait = 1 end
+else
+  tokens = tokens - 1
+end
+
+redis.call('HMSET', key, 'tokens', tokens, 'lastRefill', now)
+redis.call('PEXPIRE', key, idle_ttl)
+return wait
+`;
+
+function takeLocal(map: Map<string, Bucket>, key: string, cfg: RateBucketConfig): number {
+  const now = Date.now();
+  let b = map.get(key);
+  if (!b) {
+    b = { tokens: cfg.capacity, lastRefill: now };
+    map.set(key, b);
+  }
+  const elapsed = (now - b.lastRefill) / 1000;
+  b.tokens = Math.min(cfg.capacity, b.tokens + elapsed * cfg.refillPerSec);
+  b.lastRefill = now;
+  if (b.tokens < 1) {
+    const wait = (1 - b.tokens) / cfg.refillPerSec;
+    return Math.max(1, Math.ceil(wait));
+  }
+  b.tokens -= 1;
+  return 0;
+}
+
+async function takeRedis(
+  redis: RedisLike,
+  key: string,
+  cfg: RateBucketConfig
+): Promise<number> {
+  // Idle TTL = 10 minutes — same as the in-memory reaper. Lets idle keys
+  // expire on their own rather than holding state forever.
+  const idleTtlMs = 10 * 60 * 1000;
+  try {
+    const result = await redis.eval(
+      TAKE_LUA,
+      1,
+      key,
+      cfg.capacity,
+      cfg.refillPerSec,
+      Date.now(),
+      idleTtlMs
+    );
+    return typeof result === 'number' ? result : Number(result) || 0;
+  } catch {
+    // Redis hiccup: fail-open for rate limiting (a brief gap is better than
+    // a hard outage). The next request will re-try the script.
+    return 0;
+  }
+}
+
+function reapLocal(): void {
+  const now = Date.now();
+  if (now - lastReap < 5 * 60 * 1000) return;
+  lastReap = now;
+  for (const map of [principalBuckets, ipBuckets, dcrBuckets]) {
+    for (const [k, b] of map.entries()) {
+      if (now - b.lastRefill > 10 * 60 * 1000) map.delete(k);
+    }
+  }
+}
+
+export default ({ strapi }: { strapi: Core.Strapi }) => {
+  async function redisClient(): Promise<RedisLike | null> {
+    const cfg = getConfig(strapi);
+    if (!cfg.redis?.enabled) return null;
+    return strapi.plugin('mcp-server').service('redis').get();
+  }
+
+  function redisKey(...parts: string[]): string {
+    return strapi.plugin('mcp-server').service('redis').key('rl', ...parts);
+  }
+
+  return {
+    /**
+     * Check both buckets (principal and IP). Returns 0 when allowed; otherwise
+     * the number of seconds the client should wait before retrying (`Retry-After`).
+     *
+     * When `redis.enabled === true` the buckets are cluster-wide; otherwise
+     * each Node process has its own.
+     */
+    async check(principalId: string | undefined, ip: string | undefined): Promise<number> {
+      const cfg = getConfig(strapi);
+      const redis = await redisClient();
+      if (!redis) {
+        reapLocal();
+        if (principalId) {
+          const wait = takeLocal(principalBuckets, principalId, cfg.rateLimit.perPrincipal);
+          if (wait > 0) return wait;
+        }
+        if (ip) {
+          const wait = takeLocal(ipBuckets, ip, cfg.rateLimit.perIp);
+          if (wait > 0) return wait;
+        }
+        return 0;
+      }
+
+      if (principalId) {
+        const wait = await takeRedis(redis, redisKey('p', principalId), cfg.rateLimit.perPrincipal);
+        if (wait > 0) return wait;
+      }
+      if (ip) {
+        const wait = await takeRedis(redis, redisKey('ip', ip), cfg.rateLimit.perIp);
+        if (wait > 0) return wait;
+      }
+      return 0;
+    },
+
+    /**
+     * Per-IP rate limit for `POST /oauth/register`. Separate bucket from the
+     * normal per-IP limit because DCR has no principal at request time and
+     * we want a different (typically tighter) ceiling on registrations than
+     * on tool calls. Driven by `oauth.dcr.ratelimitPerHour`.
+     */
+    async checkDcr(ip: string | undefined): Promise<number> {
+      if (!ip) return 0;
+      const cfg = getConfig(strapi);
+      const capacity = Math.max(1, cfg.oauth.dcr.ratelimitPerHour);
+      const refillPerSec = capacity / 3600;
+      const bucketCfg: RateBucketConfig = { capacity, refillPerSec };
+      const redis = await redisClient();
+      if (!redis) {
+        reapLocal();
+        return takeLocal(dcrBuckets, ip, bucketCfg);
+      }
+      return takeRedis(redis, redisKey('dcr', ip), bucketCfg);
+    },
+
+    reset(): void {
+      principalBuckets.clear();
+      ipBuckets.clear();
+      dcrBuckets.clear();
+    },
+  };
+};

package/server/src/services/redis.ts

@@ -0,0 +1,139 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { getConfig } from '../config';
+
+// Loose Redis interface — narrow surface we actually use. Avoids forcing a
+// hard typed dep on ioredis when Redis is disabled.
+export interface RedisLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+  del(...keys: string[]): Promise<number>;
+  eval(script: string, numKeys: number, ...keysAndArgs: (string | number)[]): Promise<unknown>;
+  sadd(key: string, ...members: string[]): Promise<number>;
+  srem(key: string, ...members: string[]): Promise<number>;
+  smembers(key: string): Promise<string[]>;
+  scard(key: string): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  hset(key: string, field: string, value: string): Promise<number>;
+  hgetall(key: string): Promise<Record<string, string>>;
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(...channels: string[]): Promise<unknown>;
+  on(event: string, listener: (...args: unknown[]) => void): unknown;
+  quit(): Promise<unknown>;
+  status?: string;
+}
+
+let client: RedisLike | null = null;
+let initializing: Promise<RedisLike | null> | null = null;
+let subscriber: RedisLike | null = null;
+let initializingSub: Promise<RedisLike | null> | null = null;
+
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  /**
+   * Return the shared Redis client. Returns null when Redis is disabled in
+   * config — callers must handle that case and fall back to local state.
+   * Multiple concurrent callers during boot share the same connect promise.
+   */
+  async get(): Promise<RedisLike | null> {
+    const cfg = getConfig(strapi);
+    if (!cfg.redis?.enabled) return null;
+    if (client) return client;
+    if (initializing) return initializing;
+    initializing = (async () => {
+      try {
+        // Dynamic require so single-instance deployments don't need ioredis
+        // installed at all. If they enable Redis but skipped install, fail
+        // loudly with a useful message.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const IORedis = require('ioredis');
+        const Ctor = IORedis.default ?? IORedis;
+        const instance: RedisLike = new Ctor(cfg.redis!.url, {
+          lazyConnect: false,
+          maxRetriesPerRequest: 3,
+          enableReadyCheck: true,
+        });
+        instance.on('error', (err: unknown) => {
+          strapi.log.warn(`[mcp-server] redis error: ${(err as Error).message}`);
+        });
+        instance.on('connect', () => {
+          strapi.log.info('[mcp-server] redis connected');
+        });
+        client = instance;
+        return instance;
+      } catch (err) {
+        const msg = (err as Error).message;
+        strapi.log.error(
+          `[mcp-server] redis init failed (${msg}). Install ioredis or set redis.enabled=false.`
+        );
+        client = null;
+        return null;
+      } finally {
+        initializing = null;
+      }
+    })();
+    return initializing;
+  },
+
+  /**
+   * Build a namespaced key. All Redis keys flow through here so that
+   * deployments with shared Redis can prefix per-tenant.
+   */
+  key(...parts: string[]): string {
+    const cfg = getConfig(strapi);
+    const prefix = cfg.redis?.keyPrefix ?? 'mcp:';
+    return prefix + parts.join(':');
+  },
+
+  /**
+   * Return a dedicated subscriber connection. ioredis (and any RESP client)
+   * cannot issue normal commands once a connection has called SUBSCRIBE — so
+   * pub/sub work uses a second client. Lazy-instantiated like the main one.
+   */
+  async getSubscriber(): Promise<RedisLike | null> {
+    const cfg = getConfig(strapi);
+    if (!cfg.redis?.enabled) return null;
+    if (subscriber) return subscriber;
+    if (initializingSub) return initializingSub;
+    initializingSub = (async () => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const IORedis = require('ioredis');
+        const Ctor = IORedis.default ?? IORedis;
+        const instance: RedisLike = new Ctor(cfg.redis!.url, {
+          lazyConnect: false,
+          maxRetriesPerRequest: null,
+          enableReadyCheck: true,
+        });
+        instance.on('error', (err: unknown) => {
+          strapi.log.warn(`[mcp-server] redis subscriber error: ${(err as Error).message}`);
+        });
+        subscriber = instance;
+        return instance;
+      } catch (err) {
+        strapi.log.error(
+          `[mcp-server] redis subscriber init failed: ${(err as Error).message}`
+        );
+        subscriber = null;
+        return null;
+      } finally {
+        initializingSub = null;
+      }
+    })();
+    return initializingSub;
+  },
+
+  /** Close the shared client + subscriber. Called from destroy(). */
+  async disconnect(): Promise<void> {
+    for (const c of [client, subscriber]) {
+      if (!c) continue;
+      try {
+        await c.quit();
+      } catch {
+        // best-effort
+      }
+    }
+    client = null;
+    subscriber = null;
+  },
+});

package/server/src/services/session-directory.ts

@@ -0,0 +1,121 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { getConfig } from '../config';
+import type { SessionPrincipal } from './session-store';
+
+export interface DirectoryEntry {
+  instance: string;
+  /** Internal-facing URL of the owning instance (e.g. http://10.0.0.5:1337). */
+  address: string;
+  adminUserId: string;
+  clientId: string;
+  createdAt: number;
+  expiresAt: number;
+}
+
+/**
+ * Redis-backed mapping from session id to its owning instance. No-op (returns
+ * null / 0) when Redis is disabled OR when `redis.internalAddress` is not
+ * configured — in that case sessions stay process-local and the cluster must
+ * use sticky load balancing.
+ */
+export default ({ strapi }: { strapi: Core.Strapi }) => {
+  async function client() {
+    const cfg = getConfig(strapi);
+    if (!cfg.redis?.enabled || !cfg.redis.internalAddress) return null;
+    return strapi.plugin('mcp-server').service('redis').get();
+  }
+
+  function key(...parts: string[]): string {
+    return strapi.plugin('mcp-server').service('redis').key('sess', ...parts);
+  }
+
+  function principalKey(adminUserId: string, clientId: string): string {
+    return `${adminUserId}:${clientId}`;
+  }
+
+  return {
+    /**
+     * Returns true when this slice's session-routing features are enabled.
+     * Callers use this to decide whether to consult Redis or stay local-only.
+     */
+    async isActive(): Promise<boolean> {
+      const r = await client();
+      return r !== null;
+    },
+
+    async register(entry: DirectoryEntry & { id: string }): Promise<void> {
+      const r = await client();
+      if (!r) return;
+      const ttlSec = Math.max(1, Math.ceil((entry.expiresAt - Date.now()) / 1000));
+      const pkey = principalKey(entry.adminUserId, entry.clientId);
+      // Multi-step write — Redis client doesn't expose pipelining in our
+      // narrow interface so we do small sequential calls. Worth tightening
+      // if this shows up in load testing.
+      await r.hset(key(entry.id), 'instance', entry.instance);
+      await r.hset(key(entry.id), 'address', entry.address);
+      await r.hset(key(entry.id), 'adminUserId', entry.adminUserId);
+      await r.hset(key(entry.id), 'clientId', entry.clientId);
+      await r.hset(key(entry.id), 'createdAt', String(entry.createdAt));
+      await r.hset(key(entry.id), 'expiresAt', String(entry.expiresAt));
+      await r.expire(key(entry.id), ttlSec);
+      await r.sadd(key('idx', pkey), entry.id);
+      await r.expire(key('idx', pkey), ttlSec);
+    },
+
+    async lookup(id: string): Promise<DirectoryEntry | null> {
+      const r = await client();
+      if (!r) return null;
+      const h = await r.hgetall(key(id));
+      if (!h || !h.instance) return null;
+      // Heartbeat check: if the owning instance is no longer publishing
+      // heartbeats, the entry is orphaned. Drop it and report not-found so
+      // the client gets a clean 404 → re-init instead of a 502 from a
+      // failed proxy attempt.
+      const alive = await strapi
+        .plugin('mcp-server')
+        .service('heartbeat')
+        .isAlive(h.instance);
+      if (!alive) {
+        await this.unregister(id, {
+          adminUserId: h.adminUserId,
+          clientId: h.clientId,
+          jti: '',
+        });
+        return null;
+      }
+      return {
+        instance: h.instance,
+        address: h.address,
+        adminUserId: h.adminUserId,
+        clientId: h.clientId,
+        createdAt: Number(h.createdAt) || 0,
+        expiresAt: Number(h.expiresAt) || 0,
+      };
+    },
+
+    async unregister(id: string, principal?: SessionPrincipal): Promise<void> {
+      const r = await client();
+      if (!r) return;
+      await r.del(key(id));
+      if (principal) {
+        await r.srem(key('idx', principalKey(principal.adminUserId, principal.clientId)), id);
+      }
+    },
+
+    /** Count current sessions for a principal across the cluster. */
+    async countForPrincipal(adminUserId: string, clientId: string): Promise<number> {
+      const r = await client();
+      if (!r) return 0;
+      return r.scard(key('idx', principalKey(adminUserId, clientId)));
+    },
+
+    /** Session ids belonging to a principal across the cluster. */
+    async sessionsForPrincipal(adminUserId: string, clientId: string): Promise<string[]> {
+      const r = await client();
+      if (!r) return [];
+      return r.smembers(key('idx', principalKey(adminUserId, clientId)));
+    },
+  };
+};