@winstonsayno/mcp-gateway 0.3.0 → 1.0.0

package/dist/auth/middleware.d.ts

@@ -12,13 +12,32 @@
  *    /requests endpoint, and keys sharing a prefix shared a rate-limit bucket).
  */
 import type { Request, RequestHandler } from 'express';
-import type { AuthConfig } from '../utils/types.js';
+import type { ApiKeyConfig, AuthConfig } from '../utils/types.js';
+import { type AccessScope } from './scopes.js';
 export type AuthedRequest = Request & {
     clientId?: string;
     jwtPayload?: unknown;
+    /** Servers / tools / rate limit this client is restricted to (absent = unrestricted). */
+    scope?: AccessScope;
 };
-export declare function createAuthMiddleware(config?: AuthConfig): RequestHandler;
+/** An auth middleware that can also look up the current scope of a known client id (api keys). */
+export type AuthMiddleware = RequestHandler & {
+    /**
+     * Current scope for `clientId`: `{ known: false }` when no configured key
+     * produces that id any more. Undefined for strategies whose scopes travel
+     * with the credential (JWT).
+     */
+    resolveClient?: (clientId: string | undefined) => {
+        known: boolean;
+        scope?: AccessScope;
+    };
+};
+/** Normalise `auth.apiKeys` entries (plain strings or objects). */
+export declare function normalizeApiKeys(keys: AuthConfig['apiKeys']): ApiKeyConfig[];
+export declare function createAuthMiddleware(config?: AuthConfig): AuthMiddleware;
 export declare function fingerprint(key: string): string;
 /** Constant-time membership check against a pre-hashed key list. */
 export declare function matchesAnyKey(candidate: string, keyDigests: Buffer[]): boolean;
+/** Constant-time lookup: index of the matching key digest, or -1. */
+export declare function matchKeyIndex(candidate: string, keyDigests: Buffer[]): number;
 //# sourceMappingURL=middleware.d.ts.map

package/dist/auth/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAIlF,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,cAAc,CA2BxE;AAMD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAQ9E"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,KAAK;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,WAAW,CAAA;KAAE,CAAC;CAC3F,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,YAAY,EAAE,CAI5E;AAaD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,cAAc,CAmCxE;AAMD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAE9E;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ7E"}

package/dist/auth/middleware.js

@@ -14,17 +14,46 @@
 import { createHash, timingSafeEqual } from 'crypto';
 import { jwtVerify } from 'jose';
 import { logger } from '../utils/logger.js';
+import { scopeFromJwt } from './scopes.js';
+/** Normalise `auth.apiKeys` entries (plain strings or objects). */
+export function normalizeApiKeys(keys) {
+    return (keys ?? [])
+        .map((k) => (typeof k === 'string' ? { key: k } : k))
+        .filter((k) => !!k && typeof k.key === 'string' && k.key.length > 0);
+}
+function scopeOf(entry) {
+    const scope = {};
+    if (entry.name)
+        scope.name = entry.name;
+    if (entry.servers)
+        scope.servers = [...entry.servers];
+    if (entry.tools)
+        scope.tools = [...entry.tools];
+    if (entry.rateLimit)
+        scope.rateLimit = { ...entry.rateLimit, perKey: true };
+    return Object.keys(scope).length > 0 ? scope : undefined;
+}
 const JWT_ALGORITHMS = ['HS256', 'HS384', 'HS512'];
 export function createAuthMiddleware(config) {
     if (!config || config.strategy === 'none') {
-        return (_req, _res, next) => next();
+        const none = (_req, _res, next) => next();
+        none.resolveClient = () => ({ known: true });
+        return none;
     }
     switch (config.strategy) {
         case 'api-key': {
-            const keys = (config.apiKeys ?? []).filter((k) => k.length > 0);
+            const keys = normalizeApiKeys(config.apiKeys);
             if (keys.length === 0) {
                 throw new Error('auth.strategy is "api-key" but no auth.apiKeys are configured');
             }
+            const names = new Set();
+            for (const k of keys) {
+                if (!k.name)
+                    continue;
+                if (names.has(k.name))
+                    throw new Error(`auth.apiKeys: duplicate key name "${k.name}"`);
+                names.add(k.name);
+            }
             return apiKeyMiddleware(keys);
         }
         case 'jwt': {
@@ -50,14 +79,18 @@ export function fingerprint(key) {
 }
 /** Constant-time membership check against a pre-hashed key list. */
 export function matchesAnyKey(candidate, keyDigests) {
+    return matchKeyIndex(candidate, keyDigests) >= 0;
+}
+/** Constant-time lookup: index of the matching key digest, or -1. */
+export function matchKeyIndex(candidate, keyDigests) {
     const c = digest(candidate);
-    let match = false;
+    let index = -1;
     // Compare against every key (no early exit) to keep timing independent of position.
-    for (const k of keyDigests) {
-        if (timingSafeEqual(c, k))
-            match = true;
-    }
-    return match;
+    keyDigests.forEach((k, i) => {
+        if (timingSafeEqual(c, k) && index < 0)
+            index = i;
+    });
+    return index;
 }
 function extractKey(req) {
     const authHeader = req.headers.authorization;
@@ -69,18 +102,32 @@ function extractKey(req) {
         return apiKeyHeader;
     return undefined;
 }
-function apiKeyMiddleware(validKeys) {
-    const keyDigests = validKeys.map(digest);
-    return (req, res, next) => {
+function apiKeyMiddleware(entries) {
+    const keyDigests = entries.map((e) => digest(e.key));
+    const clients = entries.map((e) => ({
+        clientId: e.name ? `key:${e.name}` : `key:${fingerprint(e.key)}`,
+        scope: scopeOf(e),
+    }));
+    const byClientId = new Map(clients.map((c) => [c.clientId, c]));
+    const mw = (req, res, next) => {
         const key = extractKey(req);
-        if (!key || !matchesAnyKey(key, keyDigests)) {
+        const index = key ? matchKeyIndex(key, keyDigests) : -1;
+        if (index < 0) {
             logger.warn(`Unauthorized request from ${req.ip}: missing or invalid API key`);
             res.status(401).json({ error: 'Unauthorized', message: 'Valid API key required' });
             return;
         }
-        req.clientId = `key:${fingerprint(key)}`;
+        const client = clients[index];
+        req.clientId = client.clientId;
+        if (client.scope)
+            req.scope = client.scope;
         next();
     };
+    mw.resolveClient = (clientId) => {
+        const c = clientId ? byClientId.get(clientId) : undefined;
+        return c ? { known: true, scope: c.scope } : { known: false };
+    };
+    return mw;
 }
 function jwtMiddleware(secret) {
     const secretKey = new TextEncoder().encode(secret);
@@ -96,6 +143,9 @@ function jwtMiddleware(secret) {
         jwtVerify(token, secretKey, { algorithms: JWT_ALGORITHMS }).then(({ payload }) => {
             req.jwtPayload = payload;
             req.clientId = `jwt:${String(payload.sub ?? 'unknown')}`;
+            const scope = scopeFromJwt(payload);
+            if (scope)
+                req.scope = scope;
             next();
         }, (err) => {
             logger.warn(`JWT verification failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/auth/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAErD,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEjC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAI5C,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAEnD,MAAM,UAAU,oBAAoB,CAAC,MAAmB;IACtD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC1C,OAAO,CAAC,IAAa,EAAE,IAAc,EAAE,IAAkB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACvE,CAAC;IAED,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAChE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;YACnF,CAAC;YACD,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QACD,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;YACjF,CAAC;YACD,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;gBACjC,MAAM,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC;YAC1F,CAAC;YACD,OAAO,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;QACD;YACE,0EAA0E;YAC1E,yEAAyE;YACzE,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAC;IACvF,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,UAAoB;IACnE,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5B,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,oFAAoF;IACpF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;YAAE,KAAK,GAAG,IAAI,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,GAAY;IAC9B,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC;IAC7C,IAAI,UAAU,IAAI,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/C,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;IACjD,CAAC;IACD,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9C,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IACrF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,SAAmB;IAC3C,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAEzC,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACzD,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAE5B,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,6BAA6B,GAAG,CAAC,EAAE,8BAA8B,CAAC,CAAC;YAC/E,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC,CAAC;YACnF,OAAO;QACT,CAAC;QAEA,GAAqB,CAAC,QAAQ,GAAG,OAAO,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,MAAM,SAAS,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEnD,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACzD,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC;QAC7C,IAAI,CAAC,UAAU,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;YAClF,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAEzC,wEAAwE;QACxE,kCAAkC;QAClC,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC,IAAI,CAC9D,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;YACb,GAAqB,CAAC,UAAU,GAAG,OAAO,CAAC;YAC3C,GAAqB,CAAC,QAAQ,GAAG,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,SAAS,CAAC,EAAE,CAAC;YAC5E,IAAI,EAAE,CAAC;QACT,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;YACf,MAAM,CAAC,IAAI,CAAC,4BAA4B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC5F,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC,CAAC;YACvF,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"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"}

package/dist/auth/ratelimit.d.ts

@@ -9,11 +9,26 @@
  *
  * For multi-instance deployments, replace with a shared (e.g. Redis) store.
  */
-import type { RequestHandler } from 'express';
+import type { Request, Response, RequestHandler } from 'express';
 import type { RateLimitConfig } from '../utils/types.js';
+export interface RateLimitDecision {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    /** End of the current window (ms epoch). */
+    resetAt: number;
+    /** Seconds until a retry can succeed (only when not allowed). */
+    retryAfter?: number;
+}
 export interface RateLimiter extends RequestHandler {
     /** Stop the background cleanup timer and drop all state. */
     close(): void;
+    /**
+     * Count one request for `req` without responding (used by `/mcp`, where a
+     * limit hit becomes a JSON-RPC error). Returns undefined when unlimited.
+     */
+    take(req: Request): RateLimitDecision | undefined;
 }
 export declare function createRateLimiter(config?: RateLimitConfig, now?: () => number): RateLimiter;
+export declare function setRateLimitHeaders(res: Response, limit: number, remaining: number, resetAt: number): void;
 //# sourceMappingURL=ratelimit.d.ts.map

package/dist/auth/ratelimit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ratelimit.d.ts","sourceRoot":"","sources":["../../src/auth/ratelimit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAUzD,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,4DAA4D;IAC5D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,eAAe,EACxB,GAAG,GAAE,MAAM,MAAiB,GAC3B,WAAW,CAoEb"}
+{"version":3,"file":"ratelimit.d.ts","sourceRoot":"","sources":["../../src/auth/ratelimit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAgB,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAUzD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,4DAA4D;IAC5D,KAAK,IAAI,IAAI,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAAC;CACnD;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,eAAe,EACxB,GAAG,GAAE,MAAM,MAAiB,GAC3B,WAAW,CA6Eb;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,IAAI,CAMN"}

package/dist/auth/ratelimit.js

@@ -14,6 +14,7 @@ export function createRateLimiter(config, now = Date.now) {
     if (!config) {
         const passthrough = ((_req, _res, next) => next());
         passthrough.close = () => { };
+        passthrough.take = () => undefined;
         return passthrough;
     }
     const { limit, windowSeconds, perKey = true } = config;
@@ -29,7 +30,7 @@ export function createRateLimiter(config, now = Date.now) {
         }
     }, Math.max(windowMs, 1000));
     cleanup.unref();
-    const limiter = ((req, res, next) => {
+    const take = (req) => {
         const clientId = perKey
             ? (req.clientId ?? req.ip ?? 'anonymous')
             : 'global';
@@ -51,27 +52,33 @@ export function createRateLimiter(config, now = Date.now) {
         const estimated = entry.current + entry.previous * overlap;
         const resetAt = windowStart + windowMs;
         if (estimated >= limit) {
-            const retryAfter = Math.max(1, Math.ceil((resetAt - t) / 1000));
             logger.warn(`Rate limit exceeded for ${clientId}`);
-            setRateLimitHeaders(res, limit, 0, resetAt);
-            res.status(429).set('Retry-After', String(retryAfter)).json({
+            return { allowed: false, limit, remaining: 0, resetAt, retryAfter: Math.max(1, Math.ceil((resetAt - t) / 1000)) };
+        }
+        entry.current++;
+        return { allowed: true, limit, remaining: Math.max(0, Math.floor(limit - estimated - 1)), resetAt };
+    };
+    const limiter = ((req, res, next) => {
+        const d = take(req);
+        setRateLimitHeaders(res, d.limit, d.remaining, d.resetAt);
+        if (!d.allowed) {
+            res.status(429).set('Retry-After', String(d.retryAfter)).json({
                 error: 'Too Many Requests',
                 message: `Rate limit of ${limit} requests per ${windowSeconds}s exceeded`,
-                retryAfter,
+                retryAfter: d.retryAfter,
             });
             return;
         }
-        entry.current++;
-        setRateLimitHeaders(res, limit, Math.floor(limit - estimated - 1), resetAt);
         next();
     });
+    limiter.take = take;
     limiter.close = () => {
         clearInterval(cleanup);
         store.clear();
     };
     return limiter;
 }
-function setRateLimitHeaders(res, limit, remaining, resetAt) {
+export function setRateLimitHeaders(res, limit, remaining, resetAt) {
     res.set({
         'X-RateLimit-Limit': String(limit),
         'X-RateLimit-Remaining': String(Math.max(0, remaining)),

package/dist/auth/ratelimit.js.map

@@ -1 +1 @@
-{"version":3,"file":"ratelimit.js","sourceRoot":"","sources":["../../src/auth/ratelimit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ratelimit.js","sourceRoot":"","sources":["../../src/auth/ratelimit.ts"],"names":[],"mappings":"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"}

package/dist/auth/scopes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-client access scopes.
+ *
+ * A scope limits which upstream servers and tools a client (an API key or a
+ * JWT) may see and call:
+ *  - `servers`: glob patterns matched against server ids.
+ *  - `tools`: glob patterns matched against tool names. A pattern containing
+ *    `/` is matched against `<serverId>/<tool>` instead, so a tool can be
+ *    allowed on one server only (`github/create_issue`, `fs/read_*`).
+ *
+ * An absent list means "no restriction"; an empty list allows nothing. Both
+ * lists must allow a tool for it to be visible / callable. Scopes are applied
+ * on top of each server's own `tools` filter, never instead of it.
+ *
+ * JWTs carry scopes in the `mcp_servers` / `mcp_tools` claims (an array of
+ * patterns, or one string of space- or comma-separated patterns).
+ *
+ * @module auth/scopes
+ */
+import type { RateLimitConfig, ToolInfo } from '../utils/types.js';
+export interface AccessScope {
+    /** Optional label (API key `name`), used in client ids and logs. */
+    name?: string;
+    servers?: string[];
+    tools?: string[];
+    /** Own rate limit for this client (replaces the global `rateLimit`). */
+    rateLimit?: RateLimitConfig;
+}
+export declare const JWT_SERVERS_CLAIM = "mcp_servers";
+export declare const JWT_TOOLS_CLAIM = "mcp_tools";
+/** Whether the scope lets the client use `serverId` at all. */
+export declare function isServerInScope(scope: AccessScope | undefined, serverId: string): boolean;
+/** Whether the scope lets the client see / call `toolName` on `serverId`. */
+export declare function isToolInScope(scope: AccessScope | undefined, serverId: string, toolName: string): boolean;
+export declare function filterToolsByScope<T extends Pick<ToolInfo, 'serverId' | 'name'>>(scope: AccessScope | undefined, tools: readonly T[]): T[];
+/** Whether a scope restricts anything (unrestricted clients skip filtering). */
+export declare function isRestricted(scope: AccessScope | undefined): boolean;
+/** Scope from a verified JWT payload (undefined when it carries no scope claims). */
+export declare function scopeFromJwt(payload: unknown): AccessScope | undefined;
+//# sourceMappingURL=scopes.d.ts.map

package/dist/auth/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/auth/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGnE,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,eAAe,cAAc,CAAC;AAI3C,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGzF;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMzG;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,EAC9E,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,KAAK,EAAE,SAAS,CAAC,EAAE,GAClB,CAAC,EAAE,CAGL;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAEpE;AAUD,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAUtE"}

package/dist/auth/scopes.js

@@ -0,0 +1,76 @@
+/**
+ * Per-client access scopes.
+ *
+ * A scope limits which upstream servers and tools a client (an API key or a
+ * JWT) may see and call:
+ *  - `servers`: glob patterns matched against server ids.
+ *  - `tools`: glob patterns matched against tool names. A pattern containing
+ *    `/` is matched against `<serverId>/<tool>` instead, so a tool can be
+ *    allowed on one server only (`github/create_issue`, `fs/read_*`).
+ *
+ * An absent list means "no restriction"; an empty list allows nothing. Both
+ * lists must allow a tool for it to be visible / callable. Scopes are applied
+ * on top of each server's own `tools` filter, never instead of it.
+ *
+ * JWTs carry scopes in the `mcp_servers` / `mcp_tools` claims (an array of
+ * patterns, or one string of space- or comma-separated patterns).
+ *
+ * @module auth/scopes
+ */
+import { globToRegExp } from '../utils/tool-filter.js';
+export const JWT_SERVERS_CLAIM = 'mcp_servers';
+export const JWT_TOOLS_CLAIM = 'mcp_tools';
+const matches = (value, patterns) => patterns.some((p) => globToRegExp(p).test(value));
+/** Whether the scope lets the client use `serverId` at all. */
+export function isServerInScope(scope, serverId) {
+    if (!scope?.servers)
+        return true;
+    return matches(serverId, scope.servers);
+}
+/** Whether the scope lets the client see / call `toolName` on `serverId`. */
+export function isToolInScope(scope, serverId, toolName) {
+    if (!scope)
+        return true;
+    if (!isServerInScope(scope, serverId))
+        return false;
+    if (!scope.tools)
+        return true;
+    const qualified = `${serverId}/${toolName}`;
+    return scope.tools.some((p) => globToRegExp(p).test(p.includes('/') ? qualified : toolName));
+}
+export function filterToolsByScope(scope, tools) {
+    if (!scope || (!scope.servers && !scope.tools))
+        return [...tools];
+    return tools.filter((t) => isToolInScope(scope, t.serverId, t.name));
+}
+/** Whether a scope restricts anything (unrestricted clients skip filtering). */
+export function isRestricted(scope) {
+    return !!scope && (scope.servers !== undefined || scope.tools !== undefined);
+}
+function claimList(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string' && v.length > 0);
+    if (typeof value === 'string')
+        return value.split(/[\s,]+/).filter(Boolean);
+    // A malformed claim must not widen access: treat it as "nothing allowed".
+    return [];
+}
+/** Scope from a verified JWT payload (undefined when it carries no scope claims). */
+export function scopeFromJwt(payload) {
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    const p = payload;
+    const servers = claimList(p[JWT_SERVERS_CLAIM]);
+    const tools = claimList(p[JWT_TOOLS_CLAIM]);
+    if (servers === undefined && tools === undefined)
+        return undefined;
+    const scope = {};
+    if (servers !== undefined)
+        scope.servers = servers;
+    if (tools !== undefined)
+        scope.tools = tools;
+    return scope;
+}
+//# sourceMappingURL=scopes.js.map

package/dist/auth/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../src/auth/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAWvD,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAC/C,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,QAA2B,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AAElH,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAC,KAA8B,EAAE,QAAgB;IAC9E,IAAI,CAAC,KAAK,EAAE,OAAO;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,KAA8B,EAAE,QAAgB,EAAE,QAAgB;IAC9F,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,SAAS,GAAG,GAAG,QAAQ,IAAI,QAAQ,EAAE,CAAC;IAC5C,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAA8B,EAC9B,KAAmB;IAEnB,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;IAClE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,KAA8B;IACzD,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzG,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5E,0EAA0E;IAC1E,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,CAAC,GAAG,OAAkC,CAAC;IAC7C,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACnE,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,IAAI,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;IAC7C,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAgIvD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMzE;AAED,wBAAsB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsB5E;AAkCD,wBAAgB,qBAAqB,IAAI,MAAM,CA8E9C"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA2MvD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMzE;AAED,wBAAsB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsB5E;AAkCD,wBAAgB,qBAAqB,IAAI,MAAM,CAgG9C"}

package/dist/config/loader.js

@@ -7,6 +7,7 @@ import { existsSync } from 'fs';
 import { resolve } from 'path';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
+import { expandEnv } from '../transport/channel.js';
 // ─── Zod Schema ───────────────────────────────────────────────────────────────
 const ReconnectSchema = z.object({
     enabled: z.boolean().optional(),
@@ -29,6 +30,13 @@ function safeProtocol(url) {
         return '';
     }
 }
+const ToolPatternList = z.array(z.string().min(1, 'patterns must be non-empty'));
+const ToolFilterSchema = z
+    .object({
+    allow: ToolPatternList.optional(),
+    deny: ToolPatternList.optional(),
+})
+    .strict();
 const McpServerSchema = z.object({
     id: z.string().min(1),
     name: z.string().min(1),
@@ -45,6 +53,7 @@ const McpServerSchema = z.object({
     enabled: z.boolean().default(true),
     timeout: z.number().positive().default(30000),
     maxConcurrency: z.number().int().positive().default(10),
+    tools: ToolFilterSchema.optional(),
 }).superRefine((s, ctx) => {
     if (s.transport === 'stdio' && !s.command) {
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['command'], message: 'required for stdio transport' });
@@ -63,13 +72,41 @@ const McpServerSchema = z.object({
         }
     }
 });
+const PatternList = z.array(z.string().min(1, 'patterns must be non-empty'));
+const RateLimitSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    windowSeconds: z.number().positive().default(60),
+    perKey: z.boolean().default(true),
+});
+const ApiKeySchema = z.union([
+    z.string(),
+    z
+        .object({
+        // ${VAR} references are expanded from the gateway's environment.
+        key: z
+            .string()
+            .min(1)
+            .transform((k) => expandEnv(k)),
+        name: z
+            .string()
+            .regex(/^[A-Za-z0-9._-]{1,64}$/, 'letters, digits, ".", "_" or "-" (max 64)')
+            .optional(),
+        servers: PatternList.optional(),
+        tools: PatternList.optional(),
+        rateLimit: z
+            .object({ limit: z.number().int().positive(), windowSeconds: z.number().positive() })
+            .strict()
+            .optional(),
+    })
+        .strict(),
+]);
 const GatewayConfigSchema = z.object({
     port: z.number().int().min(1).max(65535).default(4000),
     host: z.string().default('0.0.0.0'),
     auth: z
         .object({
         strategy: z.enum(['none', 'api-key', 'jwt', 'oauth2']).default('none'),
-        apiKeys: z.array(z.string()).optional(),
+        apiKeys: z.array(ApiKeySchema).optional(),
         jwtSecret: z.string().optional(),
         protect: z
             .object({
@@ -79,7 +116,22 @@ const GatewayConfigSchema = z.object({
             .optional(),
     })
         .superRefine((a, ctx) => {
-        if (a.strategy === 'api-key' && !(a.apiKeys ?? []).some((k) => k.length > 0)) {
+        const keyOf = (k) => (typeof k === 'string' ? k : k.key);
+        const names = new Set();
+        (a.apiKeys ?? []).forEach((k, i) => {
+            if (typeof k === 'string' || !k.name)
+                return;
+            if (names.has(k.name)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['apiKeys', i, 'name'], message: `duplicate key name "${k.name}"` });
+            }
+            names.add(k.name);
+        });
+        (a.apiKeys ?? []).forEach((k, i) => {
+            if (typeof k !== 'string' && k.key.length === 0) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['apiKeys', i, 'key'], message: 'is empty (unset environment variable?)' });
+            }
+        });
+        if (a.strategy === 'api-key' && !(a.apiKeys ?? []).some((k) => keyOf(k).length > 0)) {
             ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['apiKeys'], message: 'at least one key is required for api-key strategy' });
         }
         if (a.strategy === 'jwt' && !a.jwtSecret) {
@@ -90,13 +142,7 @@ const GatewayConfigSchema = z.object({
         }
     })
         .optional(),
-    rateLimit: z
-        .object({
-        limit: z.number().int().positive().default(100),
-        windowSeconds: z.number().positive().default(60),
-        perKey: z.boolean().default(true),
-    })
-        .optional(),
+    rateLimit: RateLimitSchema.optional(),
     monitor: z
         .object({
         prometheus: z.boolean().default(false),
@@ -110,6 +156,31 @@ const GatewayConfigSchema = z.object({
     reconnect: ReconnectSchema.optional(),
     healthCheckIntervalMs: z.number().int().min(1000).default(30_000),
     dashboard: z.object({ enabled: z.boolean().default(true) }).optional(),
+    audit: z
+        .object({
+        enabled: z.boolean().default(false),
+        path: z.string().min(1).default('mcp-gateway-audit.db'),
+        retentionDays: z.number().int().min(0).default(30),
+    })
+        .strict()
+        .optional(),
+    mcp: z
+        .object({
+        enabled: z.boolean().default(true),
+        path: z
+            .string()
+            .regex(/^\/[A-Za-z0-9._~\-/]*$/, 'must be an absolute URL path such as /mcp')
+            .refine((p) => p !== '/' && !/^\/(api|dashboard)(\/|$)/.test(p), 'must not be "/" or under /api or /dashboard')
+            .default('/mcp'),
+        toolNaming: z.enum(['auto', 'prefix']).default('auto'),
+        pageSize: z.number().int().min(1).max(10_000).default(500),
+        sessionIdleTimeoutSeconds: z.number().int().positive().default(1800),
+        maxSessions: z.number().int().positive().default(1000),
+        allowedOrigins: z.array(z.string()).optional(),
+        instructions: z.string().optional(),
+    })
+        .strict()
+        .optional(),
 }).superRefine((c, ctx) => {
     const seen = new Set();
     c.servers.forEach((s, i) => {
@@ -198,7 +269,12 @@ logLevel: info
 # auth:
 #   strategy: api-key
 #   apiKeys:
-#     - your-secret-key-here
+#     - your-secret-key-here          # full access
+#     - key: \${AURA_GATEWAY_KEY}      # scoped key; \${VAR} is expanded (patterns are globs)
+#       name: aura
+#       servers: ["github", "fs-*"]
+#       tools: ["read_*", "github/create_issue"]
+#       rateLimit: { limit: 30, windowSeconds: 60 }
 #   protect:
 #     health: false    # true = /api/v1/health requires a key (/health/live stays public)
 #     metrics: false   # true = /api/v1/metrics requires a key (configure your scraper)
@@ -218,6 +294,19 @@ logLevel: info
 #   windowSeconds: 60
 #   perKey: true
 
+# Downstream MCP endpoint: point Claude Code / Cursor / any MCP client at
+# http://<host>:<port>/mcp (Streamable HTTP; uses the auth settings above)
+# mcp:
+#   enabled: true
+#   path: /mcp
+#   toolNaming: auto   # auto = prefix "<server>__" only on name collisions; prefix = always
+
+# Persistent audit log of requests (SQLite via node:sqlite, Node 22.5+; default off)
+# audit:
+#   enabled: true
+#   path: ./data/mcp-gateway-audit.db
+#   retentionDays: 30   # 0 = keep forever
+
 # Monitoring
 monitor:
   requestLog: true