@imenam/mcp-http-gateway 2.0.16 → 2.0.19

package/README.md

@@ -53,6 +53,7 @@ GATEWAY_CONFIG_DIR=./config
 | `GATEWAY_PORT` | `3500` | Port HTTP du gateway |
 | `GATEWAY_CONFIG_DIR` | `./config` (relatif au cwd) | Dossier contenant `mcp-servers.json` |
 | `GATEWAY_ADMIN_TOKEN` | — | Active `POST /admin/reload` et en est le jeton. Absent, la route n'existe pas. Voir [Rechargement à chaud](#rechargement-à-chaud). |
+| `GATEWAY_SCOPE_SECRET` | — | Impose un périmètre d'accès signé sur chaque requête. Absent, toute requête voit tous les MCP et tous les outils. Voir [Périmètre d'accès](#périmètre-daccès). |
 | `GATEWAY_BODY_LIMIT` | `32mb` | Taille maximale du corps d'une requête. Le défaut d'express (100 ko) ne suffit pas dès qu'un appel d'outil porte le contenu d'un fichier en base64 ; au-delà de cette limite, la réponse est un `413`. Ne s'applique pas aux routes de [relais HTTP](#relais-http-mcp_http_relay_port). |
 
 ### `mcp-servers.json`
@@ -147,6 +148,40 @@ Le jeton passe par l'en-tête `X-Gateway-Admin-Token`, indépendamment de l'auth
 
 Chaque réponse du gateway porte l'en-tête `X-Gateway-Revision`. Sa valeur change à chaque démarrage du gateway et à chaque rechargement qui modifie quelque chose. Le [mode MCP](#mode-mcp) s'en sert pour mettre à jour les outils de l'agent.
 
+Sous [périmètre d'accès](#périmètre-daccès), la révision est suffixée de l'empreinte du périmètre (`5ecfab70.3~03d09cc8`) : un changement de droits change la révision, et le relais relit les outils de l'agent comme après un rechargement.
+
+## Périmètre d'accès
+
+Le gateway ne sait pas qui l'appelle. Quand il est placé derrière un frontal qui authentifie ses utilisateurs (le hub `mcp-gateway-manager`, par exemple), c'est ce frontal qui décide de ce que chaque requête peut atteindre, et le gateway qui l'applique.
+
+Avec `GATEWAY_SCOPE_SECRET` défini, **toute requête** doit porter l'en-tête `X-Gateway-Scope`, signé avec ce secret. Une requête sans en-tête, ou dont la signature est fausse, est refusée en `403`. Seules `POST /admin/reload` (qui a son propre jeton) et `/.well-known/*` y échappent.
+
+L'en-tête vaut `<charge>.<signature>` :
+
+- `charge` : un objet JSON, encodé en base64url ;
+- `signature` : le HMAC-SHA256 de la charge encodée, avec `GATEWAY_SCOPE_SECRET` pour clé, en base64url.
+
+```jsonc
+{ "v": 1, "all": true }                       // tout le gateway
+{ "v": 1, "mcps": {
+    "documentor": "*",                         // tous les outils de ce MCP, y compris ceux ajoutés plus tard
+    "github": ["get_info", "pull_request"]     // ces outils seulement
+} }
+```
+
+Les MCP sont désignés par leur nom (la clé de `mcpServers`). Le périmètre s'applique partout :
+
+| Point d'accès | MCP hors périmètre | Outil hors périmètre |
+|---|---|---|
+| `GET /mcps`, `GET /mcp-definitions`, `list_mcps` | absent | absent de `tools` |
+| `GET /{route}/tools`, `list_tools` | `404` / « No MCP found » | absent |
+| `POST /{route}/tools/:toolName`, `call_tool` | `404` / « No MCP found » | `403` / « Tool not allowed » |
+| `/{route}/http/*` | `404` | — (le relais suit le MCP) |
+| `GET /startup-exposition`, `tools/list` de `/mcp` | outils absents | outil absent |
+| `GET /tools/search` | résultats absents | résultat absent |
+
+Le module `scope.js` exporte `encodeScope(charge, secret)`, qui fabrique l'en-tête.
+
 ## Routes
 
 ### `GET /mcps`

package/mcp-endpoint.js

@@ -6,6 +6,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { getProtectedResourceMetadata } from './auth.js';
 import { toolDefinition } from './startup-exposition.js';
+import { allowsMcp, allowsTool, filterTools } from './scope.js';
 
 const tools = [
   {
@@ -39,17 +40,27 @@ const tools = [
   },
 ];
 
-function buildMcpServer(registry) {
+/**
+ * Serveur MCP d'une requête, restreint à son périmètre (voir scope.js) : un MCP hors
+ * périmètre est introuvable, un outil hors périmètre n'est ni listé ni appelable.
+ */
+function buildMcpServer(registry, scope) {
   const server = new Server(
     { name: 'mcp-http-gateway-remote', version: '1.0.0' },
     { capabilities: { tools: {} } }
   );
 
   // Outils des MCP pré-exposés en ALL : publiés tels quels, appelables sans call_tool.
-  const { proxyTools } = registry;
+  const proxyTools = registry.proxyTools.filter(t => allowsTool(scope, t.mcpName, t.toolName));
   const proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
   const allTools = [...tools, ...proxyTools.map(toolDefinition)];
 
+  /** Le MCP servi sur cette route, s'il est dans le périmètre. */
+  const visibleEntry = (route) => {
+    const entry = registry.byRoute(route);
+    return entry && allowsMcp(scope, entry.name) ? entry : null;
+  };
+
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -58,7 +69,7 @@ function buildMcpServer(registry) {
     try {
       const proxy = proxyIndex.get(name);
       if (proxy) {
-        const entry = registry.byRoute(proxy.route);
+        const entry = visibleEntry(proxy.route);
         if (!entry) {
           return { content: [{ type: 'text', text: `No MCP found for route: ${proxy.route}` }], isError: true };
         }
@@ -67,25 +78,29 @@ function buildMcpServer(registry) {
 
       if (name === 'list_mcps') {
         const text = registry.entries
+          .filter(m => allowsMcp(scope, m.name))
           .map(m => `- ${m.name} (route: ${m.route})${m.description ? ` — ${m.description}` : ''}`)
           .join('\n');
         return { content: [{ type: 'text', text }] };
       }
 
       if (name === 'list_tools') {
-        const entry = registry.byRoute(args.route);
+        const entry = visibleEntry(args.route);
         if (!entry) {
           return { content: [{ type: 'text', text: `No MCP found for route: ${args.route}` }], isError: true };
         }
-        const text = JSON.stringify(entry.tools);
+        const text = JSON.stringify(filterTools(scope, entry.name, entry.tools));
         return { content: [{ type: 'text', text }] };
       }
 
       if (name === 'call_tool') {
-        const entry = registry.byRoute(args.route);
+        const entry = visibleEntry(args.route);
         if (!entry) {
           return { content: [{ type: 'text', text: `No MCP found for route: ${args.route}` }], isError: true };
         }
+        if (!allowsTool(scope, entry.name, args.tool_name)) {
+          return { content: [{ type: 'text', text: `Tool not allowed: ${args.tool_name}` }], isError: true };
+        }
         const result = await entry.client.callTool({
           name: args.tool_name,
           arguments: args.arguments ?? {},
@@ -139,7 +154,7 @@ export function registerMcpEndpoint(app, registry) {
   // Conséquence : plus de 404 "session inconnue" après une période d'inactivité ou un redémarrage,
   // et l'endpoint supporte le scale-out multi-instances.
   app.post('/mcp', async (req, res) => {
-    const server = buildMcpServer(registry);
+    const server = buildMcpServer(registry, req.scope);
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: undefined,
       enableJsonResponse: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-http-gateway",
-  "version": "2.0.16",
+  "version": "2.0.19",
   "type": "module",
   "description": "HTTP gateway that exposes MCP servers as REST routes — bridge between MCP and any HTTP-capable agent",
   "main": "server.js",
@@ -18,7 +18,8 @@
     "http-relay.js",
     "gateway-exec.js",
     "gateway-watch.js",
-    "mcp-registry.js"
+    "mcp-registry.js",
+    "scope.js"
   ],
   "scripts": {
     "start": "node server.js",

package/scope.js

@@ -0,0 +1,123 @@
+import crypto from 'crypto';
+
+// --- Périmètre d'accès d'une requête ---
+//
+// Le périmètre dit quels MCP, et quels outils de chaque MCP, une requête peut atteindre.
+// Il n'est pas calculé ici : c'est le frontal qui a authentifié l'appelant (le hub
+// mcp-gateway-manager) qui le fixe, puis le transmet dans l'en-tête `X-Gateway-Scope`,
+// signé avec le secret partagé `GATEWAY_SCOPE_SECRET`.
+//
+// Sans `GATEWAY_SCOPE_SECRET`, le gateway ne connaît pas de périmètre : toute requête voit
+// tous les MCP et tous les outils. Avec, toute requête doit porter un périmètre valide,
+// sinon elle est refusée en 403.
+//
+// Format de l'en-tête : `<charge>.<signature>`
+//   - charge     : JSON encodé en base64url ;
+//   - signature  : HMAC-SHA256 de la charge (telle qu'encodée), en base64url.
+//
+// Charge, version 1 :
+//   { "v": 1, "all": true }                                  → tout le gateway
+//   { "v": 1, "mcps": { "documentor": "*",                   → tous les outils du MCP
+//                       "github": ["get_info", "clone"] } }  → ces outils seulement
+// Un MCP absent de `mcps` est invisible : il n'apparaît dans aucune liste et ses routes
+// répondent comme une route inconnue.
+
+export const SCOPE_HEADER = 'X-Gateway-Scope';
+
+const SCOPE_VERSION = 1;
+
+/** Périmètre d'une requête qui voit tout le gateway. */
+export const FULL_SCOPE = Object.freeze({ all: true, mcps: null, digest: null });
+
+function sign(encoded, secret) {
+  return crypto.createHmac('sha256', secret).update(encoded).digest('base64url');
+}
+
+/** Construit la valeur de l'en-tête pour une charge donnée. */
+export function encodeScope(payload, secret) {
+  const encoded = Buffer.from(JSON.stringify({ v: SCOPE_VERSION, ...payload }), 'utf8').toString('base64url');
+  return `${encoded}.${sign(encoded, secret)}`;
+}
+
+function signatureMatches(encoded, presented, secret) {
+  const expected = Buffer.from(sign(encoded, secret));
+  const actual = Buffer.from(presented);
+  return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
+}
+
+function parseMcps(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const mcps = new Map();
+  for (const [name, tools] of Object.entries(raw)) {
+    if (tools === '*') {
+      mcps.set(name, '*');
+    } else if (Array.isArray(tools) && tools.every((tool) => typeof tool === 'string')) {
+      mcps.set(name, new Set(tools));
+    } else {
+      return null;
+    }
+  }
+  return mcps;
+}
+
+/**
+ * Lit et vérifie l'en-tête de périmètre.
+ * Rend `{ ok: true, scope }` ou `{ ok: false, error }` — jamais d'exception.
+ */
+export function readScope(header, secret) {
+  if (typeof header !== 'string' || header === '') {
+    return { ok: false, error: `Missing ${SCOPE_HEADER} header` };
+  }
+  const separator = header.indexOf('.');
+  if (separator <= 0 || separator === header.length - 1) {
+    return { ok: false, error: `Malformed ${SCOPE_HEADER} header` };
+  }
+  const encoded = header.slice(0, separator);
+  if (!signatureMatches(encoded, header.slice(separator + 1), secret)) {
+    return { ok: false, error: `Invalid ${SCOPE_HEADER} signature` };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+  } catch {
+    return { ok: false, error: `Unreadable ${SCOPE_HEADER} payload` };
+  }
+  if (payload?.v !== SCOPE_VERSION) {
+    return { ok: false, error: `Unsupported ${SCOPE_HEADER} version: ${payload?.v}` };
+  }
+
+  const digest = crypto.createHash('sha256').update(encoded).digest('hex').slice(0, 8);
+  if (payload.all === true) return { ok: true, scope: { all: true, mcps: null, digest } };
+
+  const mcps = parseMcps(payload.mcps);
+  if (!mcps) return { ok: false, error: `Invalid ${SCOPE_HEADER} payload` };
+  return { ok: true, scope: { all: false, mcps, digest } };
+}
+
+/** Le MCP est-il visible dans ce périmètre ? */
+export function allowsMcp(scope, mcpName) {
+  return scope.all || scope.mcps.has(mcpName);
+}
+
+/** L'outil est-il appelable dans ce périmètre ? */
+export function allowsTool(scope, mcpName, toolName) {
+  if (scope.all) return true;
+  const tools = scope.mcps.get(mcpName);
+  if (tools === undefined) return false;
+  return tools === '*' || tools.has(toolName);
+}
+
+/** Les outils d'un MCP réduits à ceux du périmètre. */
+export function filterTools(scope, mcpName, tools) {
+  return (tools ?? []).filter((tool) => allowsTool(scope, mcpName, tool.name));
+}
+
+/**
+ * Révision servie à une requête : celle du registre, suffixée de l'empreinte du périmètre.
+ * Un changement de droits change donc la révision, ce qui suffit au relais stdio pour
+ * relire ses outils.
+ */
+export function scopedRevision(revision, scope) {
+  return scope.digest ? `${revision}~${scope.digest}` : revision;
+}

package/server.js

@@ -23,6 +23,9 @@ import { registerMcpEndpoint } from './mcp-endpoint.js';
 import { createMcpTokenVerifier } from './auth.js';
 import { relayPrefix, isRelayPath, createHttpRelay } from './http-relay.js';
 import { McpRegistry, REVISION_HEADER } from './mcp-registry.js';
+import {
+  FULL_SCOPE, SCOPE_HEADER, allowsMcp, allowsTool, filterTools, readScope, scopedRevision,
+} from './scope.js';
 import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
 import { rateLimit } from 'express-rate-limit';
 
@@ -41,13 +44,16 @@ function normalizeCfg(cfg) {
 
 /**
  * Routes `<route>/tools`, `<route>/tools/:toolName` et `<route>/http/*` de chaque MCP,
- * résolues sur le registre à chaque requête.
+ * résolues sur le registre à chaque requête et restreintes au périmètre de la requête :
+ * un MCP hors périmètre répond comme une route inconnue, un outil hors périmètre est
+ * absent de la liste et refusé en 403.
  */
 function mcpRoutes(registry) {
   return async (req, res, next) => {
     for (const entry of registry.entries) {
       const { route, name, client } = entry;
       if (req.path !== route && !req.path.startsWith(`${route}/`)) continue;
+      if (!allowsMcp(req.scope, name)) return next();
       const rest = req.path.slice(route.length);
 
       if (entry.relayPort && (rest === '/http' || rest.startsWith('/http/'))) {
@@ -58,7 +64,7 @@ function mcpRoutes(registry) {
       if (req.method === 'GET' && rest === '/tools') {
         try {
           const { tools } = await client.listTools();
-          return res.json(tools);
+          return res.json(filterTools(req.scope, name, tools));
         } catch (err) {
           console.error(`[${name}] listTools error:`, err.message);
           return res.status(500).json({ error: err.message });
@@ -68,6 +74,9 @@ function mcpRoutes(registry) {
       const toolMatch = /^\/tools\/([^/]+)$/.exec(rest);
       if (req.method === 'POST' && toolMatch) {
         const toolName = decodeURIComponent(toolMatch[1]);
+        if (!allowsTool(req.scope, name, toolName)) {
+          return res.status(403).json({ error: `Tool not allowed: ${toolName}` });
+        }
         try {
           const result = await client.callTool({ name: toolName, arguments: req.body ?? {} });
           return res.json(result);
@@ -162,6 +171,28 @@ async function main() {
     console.log('[gateway] Admin endpoint enabled: POST /admin/reload');
   }
 
+  // Périmètre de chaque requête (voir scope.js). Sans GATEWAY_SCOPE_SECRET, tout est visible.
+  const SCOPE_SECRET = process.env.GATEWAY_SCOPE_SECRET?.trim() || null;
+  if (SCOPE_SECRET) {
+    app.use((req, res, next) => {
+      if (req.path.startsWith('/.well-known/')) {
+        req.scope = FULL_SCOPE;
+        return next();
+      }
+      const result = readScope(req.get(SCOPE_HEADER), SCOPE_SECRET);
+      if (!result.ok) return res.status(403).json({ error: result.error });
+      req.scope = result.scope;
+      res.setHeader(REVISION_HEADER, scopedRevision(registry.revision, result.scope));
+      return next();
+    });
+    console.log(`[gateway] Access scopes enforced: every request must carry a signed ${SCOPE_HEADER} header`);
+  } else {
+    app.use((req, res, next) => {
+      req.scope = FULL_SCOPE;
+      next();
+    });
+  }
+
   // Les routes de relais HTTP transmettent leur corps en flux, sans le lire ni le borner.
   app.use((req, res, next) =>
     isRelayPath(registry.relayPrefixes, req.path) ? next() : jsonParser(req, res, next)
@@ -241,6 +272,7 @@ async function main() {
       const queryEmbedding = await getEmbedding(q);
       const results = getAllToolEmbeddings()
         .filter(row => registry.byName(row.mcp_name)?.tools.some(t => t.name === row.tool_name))
+        .filter(row => allowsTool(req.scope, row.mcp_name, row.tool_name))
         .map(row => ({ ...row, score: cosineSimilarity(queryEmbedding, row.embedding) }))
         .sort((a, b) => b.score - a.score)
         .slice(0, limit)
@@ -260,12 +292,14 @@ async function main() {
 
   app.get('/mcp-definitions', (req, res) => {
     res.json(
-      registry.entries.map(({ name, route, description, tools }) => ({
-        id: name,
-        route,
-        description,
-        tools,
-      }))
+      registry.entries
+        .filter(({ name }) => allowsMcp(req.scope, name))
+        .map(({ name, route, description, tools }) => ({
+          id: name,
+          route,
+          description,
+          tools: filterTools(req.scope, name, tools),
+        }))
     );
   });
 
@@ -274,7 +308,10 @@ async function main() {
   // mcp-mode.js) puisse les récupérer et les relayer à l'agent de façon transparente —
   // la config vit uniquement côté serveur, le bridge se contente de transmettre.
   app.get('/startup-exposition', (req, res) => {
-    res.json({ proxyTools: registry.proxyTools, revision: registry.revision });
+    res.json({
+      proxyTools: registry.proxyTools.filter(t => allowsTool(req.scope, t.mcpName, t.toolName)),
+      revision: scopedRevision(registry.revision, req.scope),
+    });
   });
 
   app.get('/mcps', (req, res) => {
@@ -286,7 +323,7 @@ async function main() {
       '',
       '## Serveurs',
       '',
-      ...registry.entries.map(({ name, route, description, relayPort }) =>
+      ...registry.entries.filter(({ name }) => allowsMcp(req.scope, name)).map(({ name, route, description, relayPort }) =>
         `### ${name}\n- **Route** : \`${route}\`\n- **Description** : ${description ?? 'Non renseignée'}` +
         (relayPort ? `\n- **Relais HTTP** : \`${relayPrefix(route)}/*\`` : '')
       ),

package/startup-exposition.js

@@ -56,8 +56,8 @@ function sanitizeSegment(value) {
   return String(value).replace(/[^a-zA-Z0-9_-]/g, '_');
 }
 
-// Construit les outils proxy à partir du registry. Chaque entrée porte `route` +
-// `toolName` pour le routage — à retirer avant publication via toolDefinition().
+// Construit les outils proxy à partir du registry. Chaque entrée porte `route`, `mcpName` et
+// `toolName` pour le routage et le périmètre — à retirer avant publication via toolDefinition().
 export function buildProxyTools(registry) {
   const proxyTools = [];
 
@@ -70,6 +70,7 @@ export function buildProxyTools(registry) {
         description: tool.description ?? '',
         inputSchema: tool.inputSchema ?? { type: 'object', properties: {} },
         route: entry.route,
+        mcpName: entry.name,
         toolName: tool.name,
       });
     }