toolception 0.2.5 → 0.4.0

package/dist/permissions/PermissionResolver.d.ts

@@ -0,0 +1,43 @@
+import { PermissionConfig } from '../types/index.js';
+/**
+ * Resolves and caches client permissions based on configured permission sources.
+ * Supports both header-based and config-based permission resolution with caching
+ * for performance optimization.
+ */
+export declare class PermissionResolver {
+    #private;
+    private config;
+    private cache;
+    private readonly normalizedHeaderName;
+    /**
+     * Creates a new PermissionResolver instance.
+     * @param config - The permission configuration defining how permissions are resolved
+     */
+    constructor(config: PermissionConfig);
+    /**
+     * Resolves permissions for a client based on the configured source.
+     * Results are cached to improve performance for subsequent requests from the same client.
+     * Handles all errors gracefully by returning empty permissions on failure.
+     *
+     * Note on caching: For header-based permissions, permissions are cached by clientId.
+     * This means subsequent requests from the same client will use cached permissions,
+     * even if headers change. Use invalidateCache(clientId) to force re-resolution.
+     *
+     * @param clientId - The unique identifier for the client
+     * @param headers - Optional request headers (required for header-based permissions)
+     * @returns Array of toolset names the client is allowed to access
+     */
+    resolvePermissions(clientId: string, headers?: Record<string, string>): string[];
+    /**
+     * Invalidates cached permissions for a specific client.
+     * Call this when you know a client's permissions have changed.
+     * @param clientId - The client ID to invalidate
+     */
+    invalidateCache(clientId: string): void;
+    /**
+     * Clears the permission cache.
+     * Useful for cleanup during server shutdown or when permissions need to be refreshed.
+     */
+    clearCache(): void;
+}
+//# sourceMappingURL=PermissionResolver.d.ts.map

package/dist/permissions/PermissionResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionResolver.d.ts","sourceRoot":"","sources":["../../src/permissions/PermissionResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,kBAAkB;;IAQjB,OAAO,CAAC,MAAM;IAP1B,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAE9C;;;OAGG;gBACiB,MAAM,EAAE,gBAAgB;IAO5C;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,MAAM,EAAE;IAyCX;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA6IvC;;;OAGG;IACH,UAAU,IAAI,IAAI;CAGnB"}

package/dist/permissions/createPermissionAwareBundle.d.ts

@@ -0,0 +1,58 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ServerOrchestrator } from '../core/ServerOrchestrator.js';
+import { PermissionResolver } from './PermissionResolver.js';
+/**
+ * Context information extracted from a client request.
+ * Used to identify the client and resolve their permissions.
+ */
+export interface ClientRequestContext {
+    /**
+     * Unique identifier for the client making the request.
+     * May be provided via mcp-client-id header or generated as anonymous ID.
+     */
+    clientId: string;
+    /**
+     * Request headers that may contain permission data.
+     * Used for header-based permission resolution.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Result of permission-aware bundle creation, including the resolved permissions.
+ */
+export interface PermissionAwareBundle {
+    /**
+     * The MCP server instance for this client.
+     */
+    server: McpServer;
+    /**
+     * The orchestrator managing toolsets for this client.
+     */
+    orchestrator: ServerOrchestrator;
+    /**
+     * The resolved permissions (allowed toolsets) for this client.
+     * Contains only the toolsets that were successfully enabled.
+     */
+    allowedToolsets: string[];
+    /**
+     * Toolsets that failed to enable (e.g., invalid names).
+     * Empty if all requested toolsets were enabled successfully.
+     */
+    failedToolsets: string[];
+}
+/**
+ * Creates a permission-aware bundle creation function that wraps the original
+ * createBundle function with permission resolution and enforcement.
+ *
+ * This function resolves client permissions and passes them to the bundle creator,
+ * which creates a server with STATIC mode configured to only those toolsets.
+ *
+ * @param originalCreateBundle - Bundle creation function that accepts allowed toolsets
+ * @param permissionResolver - Resolver instance for determining client permissions
+ * @returns Enhanced bundle creation function that accepts client context
+ */
+export declare function createPermissionAwareBundle(originalCreateBundle: (allowedToolsets: string[]) => {
+    server: McpServer;
+    orchestrator: ServerOrchestrator;
+}, permissionResolver: PermissionResolver): (context: ClientRequestContext) => Promise<PermissionAwareBundle>;
+//# sourceMappingURL=createPermissionAwareBundle.d.ts.map

package/dist/permissions/createPermissionAwareBundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPermissionAwareBundle.d.ts","sourceRoot":"","sources":["../../src/permissions/createPermissionAwareBundle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,SAAS,CAAC;IAElB;;OAEG;IACH,YAAY,EAAE,kBAAkB,CAAC;IAEjC;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,oBAAoB,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK;IACnD,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,kBAAkB,CAAC;CAClC,EACD,kBAAkB,EAAE,kBAAkB,IAcpC,SAAS,oBAAoB,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAkDlC"}

package/dist/permissions/validatePermissionConfig.d.ts

@@ -0,0 +1,9 @@
+import { PermissionConfig } from '../types/index.js';
+/**
+ * Validates a permission configuration object to ensure it meets all requirements.
+ * Throws descriptive errors for any validation failures.
+ * @param config - The permission configuration to validate
+ * @throws {Error} If the configuration is invalid or missing required fields
+ */
+export declare function validatePermissionConfig(config: PermissionConfig): void;
+//# sourceMappingURL=validatePermissionConfig.d.ts.map

package/dist/permissions/validatePermissionConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatePermissionConfig.d.ts","sourceRoot":"","sources":["../../src/permissions/validatePermissionConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAKvE"}

package/dist/server/createMcpServer.d.ts

@@ -1,9 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ExposurePolicy, Mode, ToolSetCatalog } from '../types/index.js';
+import { ExposurePolicy, Mode, ModuleLoader, ToolSetCatalog } from '../types/index.js';
 import { FastifyTransportOptions } from '../http/FastifyTransport.js';
 export interface CreateMcpServerOptions {
     catalog: ToolSetCatalog;
-    moduleLoaders?: Record<string, any>;
+    moduleLoaders?: Record<string, ModuleLoader>;
     exposurePolicy?: ExposurePolicy;
     context?: unknown;
     startup?: {
@@ -12,7 +12,8 @@ export interface CreateMcpServerOptions {
     };
     registerMetaTools?: boolean;
     http?: FastifyTransportOptions;
-    /** Factory to create an MCP server instance. Required.
+    /**
+     * Factory to create an MCP server instance. Required.
      * In DYNAMIC mode, a new instance is created per client bundle.
      * In STATIC mode, a single instance is created and reused across bundles.
      */

package/dist/server/createMcpServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createMcpServer.d.ts","sourceRoot":"","sources":["../../src/server/createMcpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE9E,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;KAAE,CAAC;IACvE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B;;;OAGG;IACH,YAAY,EAAE,MAAM,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB;;;;GAkFpE"}
+{"version":3,"file":"createMcpServer.d.ts","sourceRoot":"","sources":["../../src/server/createMcpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC7C,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;KAAE,CAAC;IACvE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B;;;;OAIG;IACH,YAAY,EAAE,MAAM,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB;;;;GA0FpE"}

package/dist/server/createPermissionBasedMcpServer.d.ts

@@ -0,0 +1,65 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CreatePermissionBasedMcpServerOptions } from '../types/index.js';
+/**
+ * Creates an MCP server with permission-based toolset access control.
+ *
+ * This function provides a separate API for creating servers where each client receives
+ * only the toolsets they're authorized to access. Each client gets a fresh server instance
+ * with STATIC mode configured to their allowed toolsets, ensuring per-client isolation
+ * without meta-tools or dynamic loading.
+ *
+ * The server supports two permission sources:
+ * - **Header-based**: Permissions are read from request headers (e.g., `mcp-toolset-permissions`)
+ * - **Config-based**: Permissions are resolved server-side using static maps or resolver functions
+ *
+ * @param options - Configuration options including permission settings, catalog, and HTTP transport options
+ * @returns Server instance with `server`, `start()`, and `close()` methods matching the createMcpServer interface
+ * @throws {Error} If permission configuration is invalid, missing, or if startup.mode is provided
+ *
+ * @example
+ * // Header-based permissions
+ * const server = await createPermissionBasedMcpServer({
+ *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
+ *   catalog: { toolsetA: { name: "Toolset A", tools: [...] } },
+ *   permissions: {
+ *     source: 'headers',
+ *     headerName: 'mcp-toolset-permissions' // optional, this is the default
+ *   }
+ * });
+ *
+ * @example
+ * // Config-based permissions with static map
+ * const server = await createPermissionBasedMcpServer({
+ *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
+ *   catalog: { toolsetA: { name: "Toolset A", tools: [...] } },
+ *   permissions: {
+ *     source: 'config',
+ *     staticMap: {
+ *       'client-1': ['toolsetA', 'toolsetB'],
+ *       'client-2': ['toolsetC']
+ *     },
+ *     defaultPermissions: [] // optional, defaults to empty array
+ *   }
+ * });
+ *
+ * @example
+ * // Config-based permissions with resolver function
+ * const server = await createPermissionBasedMcpServer({
+ *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
+ *   catalog: { toolsetA: { name: "Toolset A", tools: [...] } },
+ *   permissions: {
+ *     source: 'config',
+ *     resolver: (clientId) => {
+ *       // Your custom logic to determine permissions
+ *       return clientId.startsWith('admin-') ? ['toolsetA', 'toolsetB'] : ['toolsetA'];
+ *     },
+ *     defaultPermissions: ['toolsetA'] // fallback if resolver fails
+ *   }
+ * });
+ */
+export declare function createPermissionBasedMcpServer(options: CreatePermissionBasedMcpServerOptions): Promise<{
+    server: McpServer;
+    start: () => Promise<void>;
+    close: () => Promise<void>;
+}>;
+//# sourceMappingURL=createPermissionBasedMcpServer.d.ts.map

package/dist/server/createPermissionBasedMcpServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPermissionBasedMcpServer.d.ts","sourceRoot":"","sources":["../../src/server/createPermissionBasedMcpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,qCAAqC,EAEtC,MAAM,mBAAmB,CAAC;AAoD3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,qCAAqC;;;;GAkG/C"}

package/dist/session/ClientResourceCache.d.ts

@@ -1,22 +1,53 @@
-export interface ClientResourceCacheOptions {
+export interface ClientResourceCacheOptions<T> {
     maxSize?: number;
     ttlMs?: number;
     pruneIntervalMs?: number;
+    /**
+     * Optional cleanup callback called when a resource is removed from the cache.
+     * Use this to close connections, clean up sessions, etc.
+     * @param key - The cache key being removed
+     * @param resource - The resource being removed
+     */
+    onEvict?: (key: string, resource: T) => void | Promise<void>;
 }
 export declare class ClientResourceCache<T> {
+    #private;
     private storage;
     private maxSize;
     private ttlMs;
+    private onEvict?;
     private pruneInterval?;
-    constructor(options?: ClientResourceCacheOptions);
+    constructor(options?: ClientResourceCacheOptions<T>);
     getEntryCount(): number;
     getMaxSize(): number;
     getTtl(): number;
     get(key: string): T | null;
     set(key: string, resource: T): void;
+    /**
+     * Removes an entry from the cache.
+     * Calls the onEvict callback if configured.
+     * @param key - The key to remove
+     */
     delete(key: string): void;
-    stop(): void;
+    /**
+     * Stops the background pruning interval and optionally clears all entries.
+     * @param clearEntries - If true, also removes all entries and calls onEvict for each
+     */
+    stop(clearEntries?: boolean): void;
+    /**
+     * Clears all entries from the cache.
+     * Calls onEvict for each entry being removed.
+     */
+    clear(): void;
+    /**
+     * Evicts the least recently used entry from the cache.
+     * @private
+     */
     private evictLeastRecentlyUsed;
+    /**
+     * Removes all expired entries from the cache.
+     * @private
+     */
     private pruneExpired;
 }
 //# sourceMappingURL=ClientResourceCache.d.ts.map

package/dist/session/ClientResourceCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientResourceCache.d.ts","sourceRoot":"","sources":["../../src/session/ClientResourceCache.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAOD,qBAAa,mBAAmB,CAAC,CAAC;IAChC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAS;IAEtB,OAAO,CAAC,aAAa,CAAC,CAAiC;gBAE3C,OAAO,GAAE,0BAA+B;IAO7C,aAAa,IAAI,MAAM;IAIvB,UAAU,IAAI,MAAM;IAIpB,MAAM,IAAI,MAAM;IAIhB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAa1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI;IAQnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,IAAI,IAAI,IAAI;IAOnB,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,YAAY;CAQrB"}
+{"version":3,"file":"ClientResourceCache.d.ts","sourceRoot":"","sources":["../../src/session/ClientResourceCache.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAOD,qBAAa,mBAAmB,CAAC,CAAC;;IAChC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAC,CAAqD;IAErE,OAAO,CAAC,aAAa,CAAC,CAAiC;gBAE3C,OAAO,GAAE,0BAA0B,CAAC,CAAC,CAAM;IAQhD,aAAa,IAAI,MAAM;IAIvB,UAAU,IAAI,MAAM;IAIpB,MAAM,IAAI,MAAM;IAIhB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAa1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI;IAQ1C;;;;OAIG;IACI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQhC;;;OAGG;IACI,IAAI,CAAC,YAAY,UAAQ,GAAG,IAAI;IAUvC;;;OAGG;IACI,KAAK,IAAI,IAAI;IASpB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;;OAGG;IACH,OAAO,CAAC,YAAY;CAkCrB"}

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+import { CreateMcpServerOptions } from '../server/createMcpServer.js';
 export type McpToolDefinition = {
     name: string;
     description: string;
@@ -22,4 +23,232 @@ export type ExposurePolicy = {
 };
 export type ToolingErrorCode = "E_VALIDATION" | "E_POLICY_MAX_ACTIVE" | "E_TOOL_NAME_CONFLICT" | "E_NOTIFY_FAILED" | "E_INTERNAL";
 export type ModuleLoader = (context?: unknown) => Promise<McpToolDefinition[]> | McpToolDefinition[];
+/**
+ * Configuration for permission-based toolset access control.
+ *
+ * Defines how client permissions are resolved and applied when using
+ * `createPermissionBasedMcpServer`. Supports two permission sources:
+ *
+ * **Header-based permissions**: Permissions are extracted from request headers.
+ * This approach is simpler but requires proper authentication/authorization in your
+ * application layer to prevent header tampering.
+ *
+ * **Config-based permissions**: Permissions are resolved server-side using either
+ * a static map or a resolver function. This provides stronger security by not
+ * trusting client-provided permission data.
+ *
+ * @example Header-based configuration
+ * ```typescript
+ * const config: PermissionConfig = {
+ *   source: 'headers',
+ *   headerName: 'mcp-toolset-permissions' // optional, this is the default
+ * };
+ * // Client sends: mcp-toolset-permissions: toolset-a,toolset-b
+ * ```
+ *
+ * @example Config-based with static map
+ * ```typescript
+ * const config: PermissionConfig = {
+ *   source: 'config',
+ *   staticMap: {
+ *     'client-1': ['toolset-a', 'toolset-b'],
+ *     'client-2': ['toolset-c']
+ *   },
+ *   defaultPermissions: [] // optional, for unknown clients
+ * };
+ * ```
+ *
+ * @example Config-based with resolver function
+ * ```typescript
+ * const config: PermissionConfig = {
+ *   source: 'config',
+ *   resolver: (clientId: string) => {
+ *     // Custom logic to determine permissions
+ *     if (clientId.startsWith('admin-')) {
+ *       return ['toolset-a', 'toolset-b', 'toolset-c'];
+ *     }
+ *     return ['toolset-a'];
+ *   },
+ *   defaultPermissions: ['toolset-a'] // fallback if resolver fails
+ * };
+ * ```
+ */
+export type PermissionConfig = {
+    /**
+     * The source of permission data.
+     *
+     * - `'headers'`: Read permissions from request headers. Requires proper authentication
+     *   in your application layer to prevent tampering.
+     * - `'config'`: Use server-side permission configuration via staticMap or resolver.
+     *   Provides stronger security by not trusting client-provided data.
+     */
+    source: "headers" | "config";
+    /**
+     * Name of the header containing permission data (for header-based permissions).
+     *
+     * The header value should be a comma-separated list of toolset names.
+     * Only used when `source` is `'headers'`.
+     *
+     * @default 'mcp-toolset-permissions'
+     * @example
+     * ```typescript
+     * // With default header name
+     * { source: 'headers' }
+     * // Client sends: mcp-toolset-permissions: toolset-a,toolset-b
+     *
+     * // With custom header name
+     * { source: 'headers', headerName: 'x-allowed-toolsets' }
+     * // Client sends: x-allowed-toolsets: toolset-a,toolset-b
+     * ```
+     */
+    headerName?: string;
+    /**
+     * Static mapping of client IDs to their allowed toolsets (for config-based permissions).
+     *
+     * Each key is a client ID, and the value is an array of toolset names the client can access.
+     * Only used when `source` is `'config'`. At least one of `staticMap` or `resolver` must
+     * be provided for config-based permissions.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   source: 'config',
+     *   staticMap: {
+     *     'client-1': ['toolset-a', 'toolset-b'],
+     *     'client-2': ['toolset-c'],
+     *     'admin-user': ['toolset-a', 'toolset-b', 'toolset-c']
+     *   }
+     * }
+     * ```
+     */
+    staticMap?: Record<string, string[]>;
+    /**
+     * Synchronous function to resolve permissions for a client (for config-based permissions).
+     *
+     * Called with the client ID and should return an array of allowed toolset names.
+     * Only used when `source` is `'config'`. If both `staticMap` and `resolver` are provided,
+     * the resolver takes precedence with staticMap as fallback.
+     *
+     * The function should be synchronous and deterministic. If it throws an error or returns
+     * a non-array value, the system falls back to `staticMap` or `defaultPermissions`.
+     *
+     * @param clientId - The unique identifier for the client requesting access
+     * @returns Array of toolset names the client is allowed to access
+     *
+     * @example
+     * ```typescript
+     * {
+     *   source: 'config',
+     *   resolver: (clientId: string) => {
+     *     // Integrate with your auth system
+     *     const user = getUserFromCache(clientId);
+     *     if (user.role === 'admin') {
+     *       return ['toolset-a', 'toolset-b', 'toolset-c'];
+     *     } else if (user.role === 'user') {
+     *       return ['toolset-a'];
+     *     }
+     *     return [];
+     *   }
+     * }
+     * ```
+     */
+    resolver?: (clientId: string) => string[];
+    /**
+     * Default permissions to apply when a client is not found in staticMap or resolver fails.
+     *
+     * Used as a fallback when:
+     * - Client ID is not found in `staticMap`
+     * - `resolver` function throws an error or returns invalid data
+     * - No other permission source provides valid permissions
+     *
+     * If not specified, defaults to an empty array (no toolsets allowed).
+     *
+     * @default []
+     * @example
+     * ```typescript
+     * {
+     *   source: 'config',
+     *   staticMap: { 'known-client': ['toolset-a'] },
+     *   defaultPermissions: ['public-toolset'] // Unknown clients get this
+     * }
+     * ```
+     */
+    defaultPermissions?: string[];
+};
+/**
+ * Options for creating a permission-based MCP server.
+ *
+ * Extends `CreateMcpServerOptions` but removes the `startup` field and requires
+ * a `permissions` configuration. Permission-based servers automatically use DYNAMIC
+ * mode internally to ensure per-client isolation, with each client receiving only
+ * their authorized toolsets.
+ *
+ * All standard options from `CreateMcpServerOptions` are supported, including:
+ * - `createServer`: Factory function to create MCP server instances
+ * - `catalog`: Toolset catalog defining available toolsets
+ * - `moduleLoaders`: Optional lazy-loading modules for toolsets
+ * - `exposurePolicy`: Optional policy for toolset exposure control
+ * - `http`: HTTP transport configuration (host, port, CORS, etc.)
+ * - `context`: Optional context passed to module loaders
+ *
+ * @example Basic header-based server
+ * ```typescript
+ * const options: CreatePermissionBasedMcpServerOptions = {
+ *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
+ *   catalog: {
+ *     'toolset-a': { name: 'Toolset A', tools: [...] },
+ *     'toolset-b': { name: 'Toolset B', tools: [...] }
+ *   },
+ *   permissions: {
+ *     source: 'headers'
+ *   },
+ *   http: {
+ *     port: 3000,
+ *     cors: true
+ *   }
+ * };
+ * ```
+ *
+ * @example Config-based server with static map
+ * ```typescript
+ * const options: CreatePermissionBasedMcpServerOptions = {
+ *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
+ *   catalog: {
+ *     'toolset-a': { name: 'Toolset A', tools: [...] },
+ *     'toolset-b': { name: 'Toolset B', tools: [...] }
+ *   },
+ *   permissions: {
+ *     source: 'config',
+ *     staticMap: {
+ *       'client-1': ['toolset-a'],
+ *       'client-2': ['toolset-a', 'toolset-b']
+ *     },
+ *     defaultPermissions: []
+ *   }
+ * };
+ * ```
+ */
+export type CreatePermissionBasedMcpServerOptions = Omit<CreateMcpServerOptions, "startup"> & {
+    /**
+     * Permission configuration defining how client access control is enforced.
+     *
+     * This field is required for permission-based servers. It determines whether
+     * permissions are read from request headers or resolved server-side using
+     * static maps or resolver functions.
+     *
+     * @see {@link PermissionConfig} for detailed configuration options and examples
+     */
+    permissions: PermissionConfig;
+    /**
+     * Startup configuration is not allowed for permission-based servers.
+     *
+     * Permission-based servers automatically determine which toolsets to load for
+     * each client based on the `permissions` configuration. The server internally
+     * uses STATIC mode per client to ensure isolation and prevent dynamic toolset
+     * changes during a session.
+     *
+     * @deprecated Do not use - permission-based servers determine toolsets from client permissions
+     */
+    startup?: never;
+};
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAE5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE/D,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,qBAAqB,GACrB,sBAAsB,GACtB,iBAAiB,GACjB,YAAY,CAAC;AAKjB,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,CAAC,iBAAiB,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAI3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAE5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE/D,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,qBAAqB,GACrB,sBAAsB,GACtB,iBAAiB,GACjB,YAAY,CAAC;AAKjB,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,CAAC,iBAAiB,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAE7B;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,MAAM,qCAAqC,GAAG,IAAI,CACtD,sBAAsB,EACtB,SAAS,CACV,GAAG;IACF;;;;;;;;OAQG;IACH,WAAW,EAAE,gBAAgB,CAAC;IAE9B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolception",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -34,7 +34,7 @@
     "@vitest/coverage-v8": "^3.2.4",
     "tsx": "^4.19.0",
     "typescript": "^5.9.2",
-    "vite": "^5.3.1",
+    "vite": "^7.2.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.2.4"
   },
@@ -58,6 +58,11 @@
     "dynamic-tools",
     "toolset",
     "tool-management",
+    "permissions",
+    "authentication",
+    "access-control",
+    "security",
+    "authorization",
     "json-rpc",
     "fastify",
     "zod",