@prmichaelsen/mcp-auth 0.1.0 → 0.1.2

package/README.md

@@ -6,42 +6,60 @@ Authentication and multi-tenancy framework for MCP (Model Context Protocol) serv
 
 `@prmichaelsen/mcp-auth` provides a pluggable authentication system for MCP servers, enabling:
 
+- **Zero modification**: Wrap existing MCP servers without code changes
 - **Multi-tenancy**: Multiple users with separate resource tokens
-- **Auth-agnostic**: Support for JWT, OAuth, API Keys, or custom auth schemes
+- **Auth-agnostic**: Support for JWT, environment variables, or custom auth schemes
 - **Transport-agnostic**: Works with stdio, HTTP, and SSE transports
 - **Type-safe**: Full TypeScript support
-- **Composable**: Middleware for rate limiting, logging, etc.
+- **Composable**: Middleware for rate limiting, logging, timeouts, retries
 
-## Installation
+## Two Patterns
 
-```bash
-npm install @prmichaelsen/mcp-auth @modelcontextprotocol/sdk
+### Pattern 1: Server Wrapping (Recommended for Production)
+
+Wrap existing MCP servers without modification:
+
+```typescript
+import { wrapServer, JWTAuthProvider, APITokenResolver } from '@prmichaelsen/mcp-auth';
+import { createServer } from '@myorg/my-mcp-server';
+
+const wrapped = wrapServer({
+  serverFactory: createServer,
+  
+  // Validates JWT from tenant manager
+  authProvider: new JWTAuthProvider({
+    jwtSecret: process.env.JWT_SECRET
+  }),
+  
+  // Resolves tokens via tenant manager API (recommended)
+  tokenResolver: new APITokenResolver({
+    tenantManagerUrl: process.env.TENANT_MANAGER_URL,
+    serviceToken: process.env.SERVICE_TOKEN
+  }),
+  
+  resourceType: 'myapi',
+  transport: { type: 'sse', port: 3000 }
+});
+
+await wrapped.start();
 ```
 
-## Quick Start
+### Pattern 2: Tool-Level Auth
 
-### Simple Function-Based Tool
+Build new servers with integrated authentication:
 
 ```typescript
-import { withAuth, AuthenticatedMCPServer } from '@prmichaelsen/mcp-auth';
-import { EnvAuthProvider, SimpleTokenResolver } from '@prmichaelsen/mcp-auth/providers/env';
-
-// Setup auth provider
-const authProvider = new EnvAuthProvider();
-const tokenResolver = new SimpleTokenResolver({ tokenEnvVar: 'API_TOKEN' });
+import { AuthenticatedMCPServer, withAuth, EnvAuthProvider, SimpleTokenResolver } from '@prmichaelsen/mcp-auth';
 
-// Create server
 const server = new AuthenticatedMCPServer({
-  name: 'my-mcp-server',
-  authProvider,
-  tokenResolver,
+  name: 'my-server',
+  authProvider: new EnvAuthProvider(),
+  tokenResolver: new SimpleTokenResolver({ tokenEnvVar: 'API_TOKEN' }),
   resourceType: 'myapi',
   transport: { type: 'stdio' }
 });
 
-// Register tool with automatic auth
 server.registerTool('get_data', withAuth(async (args, accessToken, userId) => {
-  // accessToken and userId are automatically injected
   const client = new MyAPIClient(accessToken);
   return client.getData(args);
 }));
@@ -49,77 +67,123 @@ server.registerTool('get_data', withAuth(async (args, accessToken, userId) => {
 await server.start();
 ```
 
-### Class-Based Tool
+## Installation
 
-```typescript
-import { Tool, AuthenticatedTool } from '@prmichaelsen/mcp-auth';
+```bash
+# Core package
+npm install @prmichaelsen/mcp-auth @modelcontextprotocol/sdk
 
-class GetDataTool implements Tool {
-  name = 'get_data';
-  description = 'Fetch data from API';
-  
-  async execute(args, accessToken, userId) {
-    const client = new MyAPIClient(accessToken);
-    return client.getData(args);
-  }
-}
+# For JWT support
+npm install jsonwebtoken
 
-server.registerTool(new AuthenticatedTool(new GetDataTool()));
+# For SSE/HTTP transports
+npm install express cors
 ```
 
 ## Authentication Providers
 
-### Environment Variable (Simple)
+### EnvAuthProvider (Single-User)
+
+For local development and single-user scenarios:
 
 ```typescript
-import { EnvAuthProvider, SimpleTokenResolver } from '@prmichaelsen/mcp-auth/providers/env';
+import { EnvAuthProvider, SimpleTokenResolver } from '@prmichaelsen/mcp-auth';
 
-const authProvider = new EnvAuthProvider();
-const tokenResolver = new SimpleTokenResolver({ tokenEnvVar: 'API_TOKEN' });
+const authProvider = new EnvAuthProvider({
+  userIdEnvVar: 'MCP_USER_ID',
+  defaultUserId: 'local-user'
+});
+
+const tokenResolver = new SimpleTokenResolver({
+  tokenEnvVar: 'API_TOKEN'
+});
 ```
 
-### JWT (Multi-tenant)
+### JWTAuthProvider + APITokenResolver (Multi-Tenant Production) ⭐ RECOMMENDED
+
+For production multi-tenant deployments:
 
 ```typescript
-import { JWTAuthProvider } from '@prmichaelsen/mcp-auth/providers/jwt';
+import { JWTAuthProvider, APITokenResolver } from '@prmichaelsen/mcp-auth';
 
+// Validates JWT tokens from tenant manager
 const authProvider = new JWTAuthProvider({
   jwtSecret: process.env.JWT_SECRET,
-  database: {
-    host: 'localhost',
-    database: 'users'
-  }
+  userIdClaim: 'sub'
+});
+
+// Resolves tokens via tenant manager API
+const tokenResolver = new APITokenResolver({
+  tenantManagerUrl: 'https://tenant-manager.example.com',
+  serviceToken: process.env.SERVICE_TOKEN,
+  cacheTokens: true, // Cache for performance
+  cacheTtl: 300000 // 5 minutes
 });
 ```
 
-### OAuth 2.0
+**Why API-Based is Better:**
+- ✅ Automatic token refresh (no new JWT needed)
+- ✅ Immediate token revocation
+- ✅ Tokens not exposed in JWT
+- ✅ Small JWT size (~200 bytes)
+- ✅ Centralized token management
+
+### JWTAuthProvider + JWTTokenResolver (MVP/Prototyping)
+
+For quick setup with JWT-embedded tokens:
 
 ```typescript
-import { OAuthProvider } from '@prmichaelsen/mcp-auth/providers/oauth';
+import { JWTAuthProvider, JWTTokenResolver } from '@prmichaelsen/mcp-auth';
 
-const authProvider = new OAuthProvider({
-  authorizationUrl: 'https://auth.example.com/authorize',
-  tokenUrl: 'https://auth.example.com/token',
-  clientId: process.env.OAUTH_CLIENT_ID,
-  clientSecret: process.env.OAUTH_CLIENT_SECRET
+const authProvider = new JWTAuthProvider({
+  jwtSecret: process.env.JWT_SECRET,
+  extractTokens: true // Extract tokens from JWT
+});
+
+const tokenResolver = new JWTTokenResolver({ authProvider });
+```
+
+**Trade-offs:**
+- ✅ Zero API calls (faster)
+- ✅ Simpler to implement
+- ❌ Token rotation requires new JWT
+- ❌ Larger JWT size
+- ❌ Tokens exposed in JWT payload
+
+### APITokenResolver (API-Based)
+
+For resolving tokens via tenant manager API:
+
+```typescript
+import { JWTAuthProvider, APITokenResolver } from '@prmichaelsen/mcp-auth';
+
+const authProvider = new JWTAuthProvider({
+  jwtSecret: process.env.JWT_SECRET
+});
+
+const tokenResolver = new APITokenResolver({
+  tenantManagerUrl: 'https://tenant-manager.example.com',
+  serviceToken: process.env.SERVICE_TOKEN,
+  endpointPath: '/api/credentials/:userId/:resourceType'
 });
 ```
 
 ### Custom Provider
 
+Implement your own authentication logic:
+
 ```typescript
 import { AuthProvider, AuthResult, RequestContext } from '@prmichaelsen/mcp-auth';
 
 class CustomAuthProvider implements AuthProvider {
   async authenticate(context: RequestContext): Promise<AuthResult> {
-    // Your custom auth logic
     const apiKey = context.headers?.['x-api-key'];
     
     if (!apiKey) {
       return { authenticated: false, error: 'No API key' };
     }
     
-    // Validate and return user ID
+    // Your validation logic
     return {
       authenticated: true,
       userId: 'user-123'
@@ -131,11 +195,12 @@ class CustomAuthProvider implements AuthProvider {
 ## Middleware Composition
 
 ```typescript
-import { compose, withAuth, withRateLimit, withLogging } from '@prmichaelsen/mcp-auth';
+import { compose, withAuth, withRateLimit, withLogging, withTimeout } from '@prmichaelsen/mcp-auth';
 
 const getTool = compose(
-  withLogging(),
+  withLogging({ logArgs: true }),
   withRateLimit({ maxRequests: 100, windowMs: 60000 }),
+  withTimeout(5000),
   withAuth(),
   async (args, accessToken, userId) => {
     // Your tool logic
@@ -150,41 +215,121 @@ server.registerTool('get_data', getTool);
 ### Stdio (Local)
 
 ```typescript
-const server = new AuthenticatedMCPServer({
-  // ...
-  transport: { type: 'stdio' }
-});
+transport: { type: 'stdio' }
 ```
 
-### HTTP/SSE (Remote)
+### SSE (Remote Multi-Tenant)
 
 ```typescript
-const server = new AuthenticatedMCPServer({
-  // ...
-  transport: {
-    type: 'sse',
-    port: 3000,
-    host: '0.0.0.0',
-    basePath: '/mcp'
-  }
-});
+transport: {
+  type: 'sse',
+  port: 3000,
+  host: '0.0.0.0',
+  basePath: '/mcp',
+  cors: true
+}
+```
+
+### HTTP (Remote)
+
+```typescript
+transport: {
+  type: 'http',
+  port: 3000,
+  host: '0.0.0.0'
+}
+```
+
+## MCP Server Contract
+
+To make your MCP server compatible with `wrapServer()`, export a factory function:
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+export function createServer(accessToken: string, userId?: string): Server {
+  const server = new Server({ name: 'my-server', version: '1.0.0' });
+  const client = new MyAPIClient(accessToken);
+  
+  // Register your tool handlers...
+  
+  return server;
+}
 ```
 
+That's it! No mcp-auth imports needed in your server.
+
+## Architecture
+
+### Three-Tier Deployment
+
+1. **Chat Platform** - Sends MCP requests with JWT
+2. **Tenant Manager** - Issues JWTs, manages user credentials
+3. **MCP Server Instance** - Uses mcp-auth to wrap MCP servers
+
+### Token Resolution Approaches
+
+**Approach 1: JWT with Embedded Tokens** (Recommended)
+- Tenant manager includes resource tokens in JWT
+- Zero external calls
+- Fastest performance
+
+**Approach 2: API-Based Resolution**
+- Tenant manager provides API for token lookup
+- Better separation of concerns
+- Easier token rotation
+
+See [`agent/token-resolution-approaches.md`](./agent/token-resolution-approaches.md) for details.
+
 ## Documentation
 
-See the [`agent/`](./agent/) directory for detailed architecture documentation:
+Comprehensive architecture documentation in [`agent/`](./agent/):
 
-- [`multi-tenant-architecture.md`](./agent/multi-tenant-architecture.md) - Overall architecture and auth schemes
-- [`lib-structure.md`](./agent/lib-structure.md) - Package structure and design
-- [`tool-patterns.md`](./agent/tool-patterns.md) - Tool registration patterns
+- [`server-wrapping-pattern.md`](./agent/server-wrapping-pattern.md) - Server wrapping architecture
+- [`server-contract.md`](./agent/server-contract.md) - MCP server compatibility guide
+- [`dual-pattern-architecture.md`](./agent/dual-pattern-architecture.md) - Both patterns explained
+- [`token-resolution-approaches.md`](./agent/token-resolution-approaches.md) - Token resolution strategies
+- [`why-two-steps.md`](./agent/why-two-steps.md) - AuthProvider vs TokenResolver
+- [`INTEGRATION.md`](./INTEGRATION.md) - Integration guide for MCP server authors
 
 ## Examples
 
-See the [`examples/`](./examples/) directory for complete examples:
+Working examples coming soon in [`examples/`](./examples/):
 
 - `simple-stdio/` - Single-user stdio server
-- `jwt-multi-tenant/` - Multi-tenant JWT server
-- `oauth-server/` - OAuth authentication flow
+- `wrapped-server/` - Server wrapping with JWT
+- `tool-level-auth/` - Tool-level authentication
+- `jwt-multi-tenant/` - Multi-tenant JWT deployment
+
+## API Reference
+
+### Core Functions
+
+- `wrapServer(config)` - Wrap MCP server with authentication
+- `withAuth(handler)` - Add auth to function-based tools
+- `compose(...middlewares)` - Compose middleware functions
+
+### Classes
+
+- `AuthenticatedMCPServer` - MCP server with integrated auth
+- `AuthenticatedTool` - Wrapper for class-based tools
+- `BaseAuthProvider` - Base class for auth providers
+
+### Providers
+
+- `EnvAuthProvider` - Environment variable authentication
+- `SimpleTokenResolver` - Environment variable token resolution
+- `JWTAuthProvider` - JWT validation with token extraction
+- `JWTTokenResolver` - JWT-embedded token resolution
+- `APITokenResolver` - API-based token resolution
+
+### Middleware
+
+- `withAuth()` - Authentication
+- `withLogging()` - Request/response logging
+- `withRateLimit()` - Rate limiting per user
+- `withTimeout()` - Request timeout
+- `withRetry()` - Automatic retry on failure
 
 ## License
 
@@ -192,4 +337,4 @@ MIT
 
 ## Contributing
 
-Contributions welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+Contributions welcome! Please open an issue or PR on [GitHub](https://github.com/prmichaelsen/mcp-auth).

package/dist/auth/base-provider.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Base authentication provider implementation
+ *
+ * Provides common functionality for authentication providers.
+ */
+import type { AuthProvider, AuthProviderConfig } from './types.js';
+import type { RequestContext, AuthResult } from '../types.js';
+import { type Logger } from '../utils/logger.js';
+/**
+ * Abstract base class for authentication providers
+ *
+ * Provides common functionality like caching, logging, and error handling.
+ * Extend this class to implement custom authentication logic.
+ *
+ * @example
+ * ```typescript
+ * class MyAuthProvider extends BaseAuthProvider {
+ *   protected async doAuthenticate(context: RequestContext): Promise<AuthResult> {
+ *     // Your authentication logic here
+ *     return { authenticated: true, userId: 'user-123' };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseAuthProvider implements AuthProvider {
+    protected config: AuthProviderConfig;
+    protected logger: Logger;
+    private authCache;
+    constructor(config?: AuthProviderConfig);
+    /**
+     * Authenticate a request
+     * Implements caching if enabled
+     */
+    authenticate(context: RequestContext): Promise<AuthResult>;
+    /**
+     * Abstract method to implement authentication logic
+     * Override this in your provider implementation
+     */
+    protected abstract doAuthenticate(context: RequestContext): Promise<AuthResult>;
+    /**
+     * Generate cache key from request context
+     * Override this to customize caching behavior
+     */
+    protected getCacheKey(context: RequestContext): string | null;
+    /**
+     * Extract authorization header from context
+     */
+    protected getAuthorizationHeader(context: RequestContext): string | null;
+    /**
+     * Extract bearer token from authorization header
+     */
+    protected extractBearerToken(context: RequestContext): string | null;
+    /**
+     * Create authentication failure result
+     */
+    protected createFailureResult(error: string): AuthResult;
+    /**
+     * Create authentication success result
+     */
+    protected createSuccessResult(userId: string, metadata?: Record<string, unknown>): AuthResult;
+    /**
+     * Optional: Initialize the provider
+     */
+    initialize(): Promise<void>;
+    /**
+     * Optional: Cleanup resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Optional: Validate provider configuration
+     */
+    validate(): Promise<boolean>;
+    /**
+     * Clear authentication cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        keys: string[];
+    };
+}
+//# sourceMappingURL=base-provider.d.ts.map

package/dist/auth/base-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-provider.d.ts","sourceRoot":"","sources":["../../src/auth/base-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,8BAAsB,gBAAiB,YAAW,YAAY;IAC5D,SAAS,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACrC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,SAAS,CAAyD;gBAE9D,MAAM,GAAE,kBAAuB;IAgB3C;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IA6DhE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAE/E;;;OAGG;IACH,SAAS,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAS7D;;OAEG;IACH,SAAS,CAAC,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAcxE;;OAEG;IACH,SAAS,CAAC,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAepE;;OAEG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAOxD;;OAEG;IACH,SAAS,CAAC,mBAAmB,CAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,UAAU;IAQb;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAMlC;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;CAMlD"}

package/dist/auth/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Authentication module exports
+ */
+export type { AuthProvider, ResourceTokenResolver, AuthenticatedContext, AuthProviderConfig, TokenResolverConfig } from './types.js';
+export { BaseAuthProvider } from './base-provider.js';
+export { EnvAuthProvider, type EnvAuthProviderConfig, SimpleTokenResolver, type SimpleTokenResolverConfig, JWTAuthProvider, type JWTAuthProviderConfig, type JWTPayload, JWTTokenResolver, type JWTTokenResolverConfig, APITokenResolver, type APITokenResolverConfig } from './providers/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,KAAK,yBAAyB,EAC9B,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC"}

package/dist/auth/index.js

@@ -1,11 +1,17 @@
 import { BaseAuthProvider } from "./base-provider.js";
 import {
   EnvAuthProvider,
-  SimpleTokenResolver
+  SimpleTokenResolver,
+  JWTAuthProvider,
+  JWTTokenResolver,
+  APITokenResolver
 } from "./providers/index.js";
 export {
+  APITokenResolver,
   BaseAuthProvider,
   EnvAuthProvider,
+  JWTAuthProvider,
+  JWTTokenResolver,
   SimpleTokenResolver
 };
 //# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/auth/index.ts"],
-  "sourcesContent": ["/**\n * Authentication module exports\n */\n\n// Types\nexport type {\n  AuthProvider,\n  ResourceTokenResolver,\n  AuthenticatedContext,\n  AuthProviderConfig,\n  TokenResolverConfig\n} from './types.js';\n\n// Base provider\nexport { BaseAuthProvider } from './base-provider.js';\n\n// Providers\nexport {\n  EnvAuthProvider,\n  type EnvAuthProviderConfig,\n  SimpleTokenResolver,\n  type SimpleTokenResolverConfig\n} from './providers/index.js';\n"],
-  "mappings": "AAcA,SAAS,wBAAwB;AAGjC;AAAA,EACE;AAAA,EAEA;AAAA,OAEK;",
+  "sourcesContent": ["/**\n * Authentication module exports\n */\n\n// Types\nexport type {\n  AuthProvider,\n  ResourceTokenResolver,\n  AuthenticatedContext,\n  AuthProviderConfig,\n  TokenResolverConfig\n} from './types.js';\n\n// Base provider\nexport { BaseAuthProvider } from './base-provider.js';\n\n// Providers\nexport {\n  EnvAuthProvider,\n  type EnvAuthProviderConfig,\n  SimpleTokenResolver,\n  type SimpleTokenResolverConfig,\n  JWTAuthProvider,\n  type JWTAuthProviderConfig,\n  type JWTPayload,\n  JWTTokenResolver,\n  type JWTTokenResolverConfig,\n  APITokenResolver,\n  type APITokenResolverConfig\n} from './providers/index.js';\n"],
+  "mappings": "AAcA,SAAS,wBAAwB;AAGjC;AAAA,EACE;AAAA,EAEA;AAAA,EAEA;AAAA,EAGA;AAAA,EAEA;AAAA,OAEK;",
   "names": []
 }

package/dist/auth/providers/api-token-resolver.d.ts

@@ -0,0 +1,110 @@
+/**
+ * API-based token resolver
+ *
+ * Resolves tokens by calling the tenant manager's API.
+ * Alternative to JWT-embedded tokens for better separation.
+ */
+import type { ResourceTokenResolver, TokenResolverConfig } from '../types.js';
+/**
+ * Configuration for APITokenResolver
+ */
+export interface APITokenResolverConfig extends TokenResolverConfig {
+    /**
+     * Tenant manager API base URL
+     * @example 'https://tenant-manager.example.com'
+     */
+    tenantManagerUrl: string;
+    /**
+     * Service token for authenticating MCP server → tenant manager requests
+     * This is a separate token from user JWTs
+     */
+    serviceToken: string;
+    /**
+     * API endpoint path template
+     * @default '/api/credentials/:userId/:resourceType'
+     *
+     * Variables:
+     * - :userId - Will be replaced with actual user ID
+     * - :resourceType - Will be replaced with resource type
+     */
+    endpointPath?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 5000
+     */
+    timeoutMs?: number;
+    /**
+     * Whether to throw error if token is not found
+     * @default true
+     */
+    throwOnMissing?: boolean;
+    /**
+     * Whether to validate token format
+     * @default true
+     */
+    validateToken?: boolean;
+    /**
+     * Custom headers to include in API requests
+     */
+    customHeaders?: Record<string, string>;
+}
+/**
+ * API token resolver
+ *
+ * Resolves tokens by calling the tenant manager's API endpoint.
+ * This approach provides better separation between MCP server and tenant manager.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new APITokenResolver({
+ *   tenantManagerUrl: 'https://tenant-manager.example.com',
+ *   serviceToken: process.env.SERVICE_TOKEN
+ * });
+ *
+ * // Calls: GET https://tenant-manager.example.com/api/credentials/user-123/instagram
+ * // Headers: { Authorization: Bearer <service-token> }
+ * // Returns: { accessToken: "IGQVJXabc..." }
+ * ```
+ */
+export declare class APITokenResolver implements ResourceTokenResolver {
+    private config;
+    private logger;
+    private tokenCache;
+    constructor(config: APITokenResolverConfig);
+    /**
+     * Resolve token by calling tenant manager API
+     */
+    resolveToken(userId: string, resourceType: string): Promise<string | null>;
+    /**
+     * Build API URL from template
+     */
+    private buildUrl;
+    /**
+     * Refresh token (calls API again)
+     */
+    refreshToken(userId: string, resourceType: string): Promise<string | null>;
+    /**
+     * Validate token (basic check)
+     */
+    validateToken(token: string, resourceType: string): Promise<boolean>;
+    /**
+     * Initialize resolver
+     */
+    initialize(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Clear token cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        keys: string[];
+    };
+}
+//# sourceMappingURL=api-token-resolver.d.ts.map

package/dist/auth/providers/api-token-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-token-resolver.d.ts","sourceRoot":"","sources":["../../../src/auth/providers/api-token-resolver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAK9E;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,YAAW,qBAAqB;IAC5D,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAoD;gBAE1D,MAAM,EAAE,sBAAsB;IAyB1C;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqJhF;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUhF;;OAEG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa1E;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBjC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;CAMlD"}