fa-mcp-sdk 0.2.121 → 0.2.125

package/bin/fa-mcp.js

@@ -723,6 +723,7 @@ certificate's public and private keys`,
 
   async handlePackageJson (content, config) {
     try {
+      content = content.replace('"project.name"', '"{{project.name}}"');
       // First replace all template parameters in the content string
       let updatedContent = content;
       for (const [param, value] of Object.entries(config)) {

package/cli-template/config/_local.yaml

@@ -1,6 +1,16 @@
 # Copy this file to local.yaml and update with your database credentials
 # local.yaml is gitignored and won't be committed
 ---
+#ad:
+#  domains:
+#    MYDOMAIN:
+#      default: true
+#      controllers:
+#        - 'ldap://c1.corp.com'
+#        - 'ldap://c2.corp.com'
+#      username: '***'
+#      password: '***'
+
 # --------------------------------------------------
 # CACHING Reduces API calls by caching responses
 # --------------------------------------------------
@@ -69,8 +79,18 @@ webServer:
     enabled: {{webServer.auth.enabled}} # Enables/disables token authorization
     # An array of fixed tokens that pass to the MCP (use only for MCPs with green data or for development)
     permanentServerTokens: []
-    token:
+    jwtToken:
       # Symmetric encryption key to generate a token for this MCP
       encryptKey: '{{webServer.auth.token.encryptKey}}'
       # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
       checkMCPName: {{webServer.auth.token.checkMCPName}}
+    #basic:
+    #  username: '***'
+    #  password: '***'
+    #oauth2:
+    #  type: 'oauth2';
+    #  clientId: '***'
+    #  clientSecret: '***'
+    #  redirectUri?: 'string'
+    #  tokenEndpoint?: string # For custom OAuth providers // VVR
+    #pat: string;

package/cli-template/config/custom-environment-variables.yaml

@@ -1,6 +1,7 @@
 cache:
   ttlSeconds: CACHE_TTL_SECONDS
   maxItems: CACHE_MAX_ITEMS
+  checkPeriod: CACHE_CHECK_PERIOD
 
 db:
   postgres:
@@ -33,6 +34,15 @@ webServer:
   auth:
     enabled: WS_AUTH_ENABLED
     permanentServerTokens: WS_SERVER_TOKENS # comma separated list
-    token:
+    jwtToken:
       encryptKey: WS_TOKEN_ENCRYPT_KEY
       checkMCPName: WS_CHECK_MC_NAME
+    basic:
+      username: WS_AUTH_BASIC_USERNAME
+      password: WS_AUTH_BASIC_PASSWORD
+    oauth2:
+      clientId: WS_AUTH_OAUTH2_CLIENT_ID
+      clientSecret: WS_AUTH_OAUTH2_CLIENT_SECRET
+      redirectUri: WS_AUTH_OAUTH2_REDIRECT_URI
+      tokenEndpoint: WS_AUTH_OAUTH2_TOKEN_ENDPOINT # For custom OAuth providers // VVR
+    pat: WS_AUTH_PAT

package/cli-template/config/default.yaml

@@ -114,8 +114,18 @@ webServer:
     enabled: false # Enables/disables token authorization
     # An array of fixed tokens that pass to the MCP (use only for MCPs with green data or for development)
     permanentServerTokens: []
-    token:
+    jwtToken:
       # Symmetric encryption key to generate a token for this MCP
       encryptKey: '***'
       # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
       checkMCPName: true
+    #basic:
+    #  username: '***'
+    #  password: '***'
+    #oauth2:
+    #  type: 'oauth2';
+    #  clientId: '***'
+    #  clientSecret: '***'
+    #  redirectUri?: 'string'
+    #  tokenEndpoint?: string # For custom OAuth providers // VVR
+    #pat: string;

package/cli-template/fa-mcp-sdk-spec.md

@@ -58,17 +58,27 @@ The primary function for starting your MCP server.
 **Example Usage in `src/start.ts`:**
 
 ```typescript
-import { initMcpServer, McpServerData } from 'fa-mcp-sdk';
+import { initMcpServer, McpServerData, CustomBasicAuthValidator } from 'fa-mcp-sdk';
 import { tools } from './tools/tools.js';
 import { handleToolCall } from './tools/handle-tool-call.js';
 import { AGENT_BRIEF } from './prompts/agent-brief.js';
 import { AGENT_PROMPT } from './prompts/agent-prompt.js';
 
+// Optional: Custom Basic Authentication validator
+const customAuthValidator: CustomBasicAuthValidator = async (username: string, password: string): Promise<boolean> => {
+  // Your custom authentication logic here (database, LDAP, API, etc.)
+  return await authenticateUser(username, password);
+};
+
 const serverData: McpServerData = {
   tools,
   toolHandler: handleToolCall,
   agentBrief: AGENT_BRIEF,
   agentPrompt: AGENT_PROMPT,
+
+  // Optional: Provide custom Basic Authentication
+  customBasicAuthValidator: customAuthValidator,
+
   // ... other configuration
 };
 
@@ -96,6 +106,9 @@ interface McpServerData {
   requiredHttpHeaders?: IRequiredHttpHeader[] | null; // HTTP headers for authentication
   customResources?: IResourceData[] | null;        // Custom resource definitions
 
+  // Authentication
+  customBasicAuthValidator?: CustomBasicAuthValidator; // Custom Basic Authentication validator function
+
   // HTTP Server Components (for HTTP transport)
   httpComponents?: {
     apiRouter?: Router | null;                     // Express router for additional endpoints
@@ -386,11 +399,21 @@ webServer:
       enabled: false # Enables/disables token authorization
       # An array of fixed tokens that pass to the MCP (use only for MCPs with green data or for development)
       permanentServerTokens: []
-      token:
+      jwtToken:
          # Symmetric encryption key to generate a token for this MCP
          encryptKey: '***'
          # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
          checkMCPName: true
+      #basic:
+      #  username: '***'
+      #  password: '***'
+      #oauth2:
+      #  type: 'oauth2';
+      #  clientId: '***'
+      #  clientSecret: '***'
+      #  redirectUri?: 'string'
+      #  tokenEndpoint?: string # For custom OAuth providers // VVR
+      #pat: string;
 ```
 
 **`config/local.yaml`** - local overrides. Usually contains secrets.
@@ -822,6 +845,366 @@ await generateTokenApp(); // Uses default configuration from appConfig
 //   domainController: 'dc.domain.com'
 ```
 
+#### Multi-Authentication System
+
+The FA-MCP-SDK supports a comprehensive multi-authentication system that allows multiple authentication methods to work together with CPU-optimized performance ordering.
+
+##### Types and Interfaces
+
+```typescript
+import {
+  AuthType,
+  AuthResult,
+  AuthDetectionResult,
+  CustomBasicAuthValidator,
+  checkMultiAuth,
+  detectAuthConfiguration,
+  logAuthConfiguration,
+  enhancedAuthTokenMW,
+  createConfigurableAuthMiddleware,
+  getAuthInfo,
+  getMultiAuthError
+} from 'fa-mcp-sdk';
+
+// Authentication types in CPU priority order (low to high cost)
+export type AuthType = 'permanentServerTokens' | 'pat' | 'basic' | 'jwtToken' | 'oauth2';
+
+// Custom Basic Authentication validator function
+export type CustomBasicAuthValidator = (username: string, password: string) => Promise<boolean> | boolean;
+
+// Authentication result interface
+export interface AuthResult {
+  success: boolean;
+  error?: string;
+  authType?: AuthType;
+  tokenType?: string;
+  username?: string;
+  accessToken?: string;
+  payload?: any;
+}
+
+// Authentication detection result
+export interface AuthDetectionResult {
+  configured: AuthType[];    // Authentication types found in configuration
+  valid: AuthType[];        // Authentication types properly configured and ready
+  errors: Record<string, string[]>;  // Configuration errors by auth type
+}
+```
+
+##### Core Multi-Authentication Functions
+
+```typescript
+// checkMultiAuth - validate token using all configured authentication methods
+// Function Signature:
+async function checkMultiAuth(
+  token: string,
+  authConfig: AppConfig['webServer']['auth']
+): Promise<AuthResult> {...}
+
+// Example:
+const authConfig = appConfig.webServer.auth;
+const result = await checkMultiAuth('user_token', authConfig);
+
+if (result.success) {
+  console.log(`Authenticated via ${result.authType} as ${result.username}`);
+} else {
+  console.log('Authentication failed:', result.error);
+}
+
+// detectAuthConfiguration - analyze auth configuration
+// Function Signature:
+function detectAuthConfiguration(authConfig: AppConfig['webServer']['auth']): AuthDetectionResult {...}
+
+// Example:
+const detection = detectAuthConfiguration(appConfig.webServer.auth);
+console.log('Configured auth types:', detection.configured);
+console.log('Valid auth types:', detection.valid);
+console.log('Configuration errors:', detection.errors);
+
+// logAuthConfiguration - log auth system status (debugging)
+// Function Signature:
+function logAuthConfiguration(authConfig: AppConfig['webServer']['auth']): void {...}
+
+// Example:
+logAuthConfiguration(appConfig.webServer.auth);
+// Output:
+// Auth system configuration:
+// - enabled: true
+// - configured types: permanentServerTokens, basic, pat
+// - valid types: permanentServerTokens, pat
+```
+
+##### Multi-Authentication Middleware
+
+```typescript
+import express from 'express';
+import {
+  enhancedAuthTokenMW,
+  createConfigurableAuthMiddleware,
+  getMultiAuthError,
+  getAuthInfo
+} from 'fa-mcp-sdk';
+
+// enhancedAuthTokenMW - automatic multi-auth middleware
+// Automatically detects if multi-auth is needed based on configuration
+const app = express();
+app.use('/api', enhancedAuthTokenMW);
+
+app.get('/api/protected', (req, res) => {
+  const authInfo = (req as any).authInfo;
+  res.json({
+    message: 'Access granted',
+    authType: authInfo?.authType,
+    username: authInfo?.username,
+    tokenType: authInfo?.tokenType
+  });
+});
+
+// createConfigurableAuthMiddleware - configurable middleware
+// Function Signature:
+function createConfigurableAuthMiddleware(options: {
+  forceMultiAuth?: boolean;
+  logConfiguration?: boolean;
+} = {}): (req: Request, res: Response, next: NextFunction) => void {...}
+
+// Example:
+const authMW = createConfigurableAuthMiddleware({
+  logConfiguration: true,    // Log auth config on first request
+  forceMultiAuth: false      // Auto-detect multi-auth need
+});
+
+app.use('/api/v2', authMW);
+
+// getMultiAuthError - programmatic auth checking
+// Function Signature:
+async function getMultiAuthError(req: Request): Promise<{ code: number, message: string } | undefined> {...}
+
+// Example - Custom middleware with different auth levels
+app.use('/api/custom', async (req, res, next) => {
+  if (req.path.startsWith('/api/custom/public')) {
+    return next(); // Public endpoints
+  }
+
+  if (req.path.startsWith('/api/custom/admin')) {
+    // Admin endpoints - require server tokens only
+    const token = (req.headers.authorization || '').replace(/^Bearer */, '');
+    if (appConfig.webServer.auth.permanentServerTokens.includes(token)) {
+      return next();
+    }
+    return res.status(403).json({ error: 'Admin access required' });
+  }
+
+  // Regular endpoints - use full multi-auth
+  try {
+    const authError = await getMultiAuthError(req);
+    if (authError) {
+      res.status(authError.code).send(authError.message);
+      return;
+    }
+    next();
+  } catch (error) {
+    res.status(500).send('Authentication error');
+  }
+});
+
+// getAuthInfo - get current authentication configuration info
+// Function Signature:
+function getAuthInfo(): {
+  enabled: boolean;
+  configured: AuthType[];
+  valid: AuthType[];
+  errors: Record<string, string[]>;
+  usingMultiAuth: boolean;
+} {...}
+
+// Example:
+app.get('/auth/info', (req, res) => {
+  const authInfo = getAuthInfo();
+  res.json(authInfo);
+});
+```
+
+##### Custom Basic Authentication
+
+You can provide custom Basic Authentication validation functions through the `McpServerData` interface:
+
+```typescript
+import { McpServerData, CustomBasicAuthValidator } from 'fa-mcp-sdk';
+
+// Database-backed authentication
+const databaseAuthValidator: CustomBasicAuthValidator = async (username: string, password: string): Promise<boolean> => {
+  try {
+    const user = await getUserFromDatabase(username);
+    if (!user) return false;
+
+    return await comparePassword(password, user.hashedPassword);
+  } catch (error) {
+    console.error('Database authentication error:', error);
+    return false;
+  }
+};
+
+// LDAP/Active Directory authentication
+const ldapAuthValidator: CustomBasicAuthValidator = async (username: string, password: string): Promise<boolean> => {
+  try {
+    const result = await authenticateWithLDAP(username, password);
+    return result.success;
+  } catch (error) {
+    console.error('LDAP authentication error:', error);
+    return false;
+  }
+};
+
+// External API authentication
+const apiAuthValidator: CustomBasicAuthValidator = async (username: string, password: string): Promise<boolean> => {
+  try {
+    const response = await fetch('https://auth.example.com/validate', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username, password })
+    });
+
+    if (!response.ok) return false;
+    const result = await response.json();
+    return result.valid === true;
+  } catch (error) {
+    console.error('API authentication error:', error);
+    return false;
+  }
+};
+
+// Multi-factor authentication
+const mfaAuthValidator: CustomBasicAuthValidator = async (username: string, password: string): Promise<boolean> => {
+  try {
+    // Password format: "actualPassword:mfaToken"
+    const [actualPassword, mfaToken] = password.split(':');
+    if (!actualPassword || !mfaToken) return false;
+
+    // Validate base credentials
+    const user = await getUserFromDatabase(username);
+    if (!user || !(await comparePassword(actualPassword, user.hashedPassword))) {
+      return false;
+    }
+
+    // Validate MFA token
+    return await validateMFAToken(username, mfaToken);
+  } catch (error) {
+    console.error('MFA authentication error:', error);
+    return false;
+  }
+};
+
+// Use custom validator in MCP server
+const serverData: McpServerData = {
+  tools,
+  toolHandler,
+  agentBrief: 'My MCP Server',
+  agentPrompt: 'Server with custom authentication',
+
+  // Provide custom basic auth validator
+  customBasicAuthValidator: databaseAuthValidator, // or ldapAuthValidator, apiAuthValidator, mfaAuthValidator
+
+  // ... other configuration
+};
+
+await initMcpServer(serverData);
+```
+
+##### Authentication Configuration
+
+Multi-authentication is configured in `config/default.yaml`:
+
+```yaml
+webServer:
+  auth:
+    enabled: true
+
+    # Permanent server tokens (CPU priority: 1 - fastest)
+    permanentServerTokens:
+      - 'server-token-1'
+      - 'server-token-2'
+
+    # Personal Access Tokens (CPU priority: 2)
+    pat: 'ATATT3xFfGF0...'
+
+    # Basic Authentication (CPU priority: 3)
+    basic:
+      type: 'basic'
+      username: 'admin'
+      password: 'password'
+      # Note: When using customBasicAuthValidator, username/password can be omitted
+
+    # JWT Tokens (CPU priority: 4)
+    jwtToken:
+      encryptKey: 'your-secret-key'
+      checkMCPName: true
+
+    # OAuth2 (CPU priority: 5 - most expensive)
+    oauth2:
+      type: 'oauth2'
+      clientId: 'your-client-id'
+      clientSecret: 'your-client-secret'
+      accessToken: 'your-access-token'
+      refreshToken: 'your-refresh-token'
+      redirectUri: 'https://example.com/callback'
+      tokenEndpoint: 'https://auth.provider.com/token'
+```
+
+##### Usage Examples
+
+```typescript
+// Test authentication programmatically
+app.post('/test-token', async (req, res) => {
+  const { token } = req.body;
+  if (!token) {
+    return res.status(400).json({ error: 'Token required' });
+  }
+
+  try {
+    const result = await checkMultiAuth(token, appConfig.webServer.auth);
+    res.json({
+      valid: result.success,
+      authType: result.authType,
+      tokenType: result.tokenType,
+      error: result.error,
+      username: result.username,
+      hasPayload: !!result.payload
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Authentication test failed' });
+  }
+});
+
+// Different authentication requirements for different endpoints
+app.use('/rest', enhancedAuthTokenMW);           // Any valid auth
+app.use('/graphql', userLevelAuthOnly);          // No server tokens
+app.use('/websocket', sessionTokensOnly);       // JWT/OAuth2 only
+```
+
+**Client Usage Examples:**
+
+```bash
+# Using permanent server token
+curl -H "Authorization: Bearer server-token-1" http://localhost:3000/mcp
+
+# Using JWT token
+curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhb..." http://localhost:3000/mcp
+
+# Using Basic Authentication
+curl -H "Authorization: Basic $(echo -n 'admin:password' | base64)" http://localhost:3000/mcp
+
+# Using PAT
+curl -H "Authorization: Bearer ATATT3xFfGF0..." http://localhost:3000/mcp
+
+# Using OAuth2
+curl -H "Authorization: Bearer ya29.A0AfH6..." http://localhost:3000/mcp
+
+# Using MFA Basic Auth (if custom validator supports it)
+curl -H "Authorization: Basic $(echo -n 'admin:password:123456' | base64)" http://localhost:3000/mcp
+```
+
+The multi-authentication system automatically tries authentication methods in CPU-optimized order (fastest first) and returns on the first successful match, providing both performance and flexibility.
+
 ### Utility Functions
 
 #### General Utilities

package/cli-template/package.json

@@ -1,73 +1,72 @@
-{
-  "name": "{{project.name}}",
-  "productName": "{{project.productName}}",
-  "version": "0.0.1",
-  "description": "{{project.description}}",
-  "type": "module",
-  "main": "dist/src/start.js",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "scripts": {
-    "start": "node dist/src/start.js",
-    "build": "tsc",
-    "clean": "rimraf dist",
-    "cb": "npm run clean && npm run build",
-    "ci": "node --no-deprecation ./scripts/npm/run.js",
-    "reinstall": "node --no-deprecation ./scripts/npm/run.js reinstall",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "lint:fix": "eslint --fix .",
-    "generate-token": "node node_modules/fa-mcp-sdk/dist/core/token/gen-token-app/gen-token-server.js",
-    "dead:exports": "ts-prune",
-    "dead:files": "knip",
-    "postinstall": "node scripts/npm/patch_node_modules.js",
-    "consul:unreg": "node node_modules/fa-mcp-sdk/dist/core/consul/deregister.js",
-    "test": "jest",
-    "test:mcp": "node scripts/test-mcp-tools.js",
-    "test:mcp-http": "node tests/mcp/test-http.js",
-    "test:mcp-sse": "node tests/mcp/test-sse.js",
-    "test:mcp-stdio": "node tests/mcp/test-stdio.js"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "typescript",
-    "template",
-    "ai",
-    "prompts",
-    "tools",
-    "resources"
-  ],
-  "author": {
-    "name": "{{author.name}}",
-    "email": "{{author.email}}"
-  },
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.22.0",
-    "dotenv": "^17.2.3",
-    "fa-mcp-sdk": "^0.2.108",
-    "swagger-jsdoc": "^6.2.8",
-    "swagger-ui-express": "^5.0.1"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.5",
-    "@types/jest": "^30.0.0",
-    "@types/node": "^24.10.1",
-    "@types/swagger-jsdoc": "^6.0.4",
-    "@types/swagger-ui-express": "^4.1.8",
-    "cross-env": "^10.1.0",
-    "eslint-config-at-25": "^25.9.6",
-    "jest": "^30.2.0",
-    "rimraf": "^6.1.0",
-    "ts-jest": "^29.4.5",
-    "tsx": "^4.20.6",
-    "typescript": "^5.9.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://{{git-base-url}}/{{project.name}}.git"
-  },
-  "private": true
-}
+{
+  "name": "project.name",
+  "productName": "{{project.productName}}",
+  "version": "0.0.3",
+  "description": "{{project.description}}",
+  "type": "module",
+  "main": "dist/src/start.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "start": "node dist/src/start.js",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "cb": "npm run clean && npm run build",
+    "ci": "node --no-deprecation ./scripts/npm/run.js",
+    "reinstall": "node --no-deprecation ./scripts/npm/run.js reinstall",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "generate-token": "node node_modules/fa-mcp-sdk/dist/core/auth/token-generator/server.js",
+    "dead:exports": "ts-prune",
+    "dead:files": "knip",
+    "postinstall": "node scripts/npm/patch_node_modules.js",
+    "consul:unreg": "node node_modules/fa-mcp-sdk/dist/core/consul/deregister.js",
+    "test": "jest",
+    "test:mcp": "node scripts/test-mcp-tools.js",
+    "test:mcp-http": "node tests/mcp/test-http.js",
+    "test:mcp-sse": "node tests/mcp/test-sse.js",
+    "test:mcp-stdio": "node tests/mcp/test-stdio.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "typescript",
+    "template",
+    "ai",
+    "prompts",
+    "tools",
+    "resources"
+  ],
+  "author": {
+    "name": "{{author.name}}",
+    "email": "{{author.email}}"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "dotenv": "^17.2.3",
+    "fa-mcp-sdk": "^0.2.125",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.10.1",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.8",
+    "cross-env": "^10.1.0",
+    "eslint-config-at-25": "^25.9.6",
+    "jest": "^30.2.0",
+    "rimraf": "^6.1.0",
+    "ts-jest": "^29.4.5",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://{{git-base-url}}/{{project.name}}.git"
+  }
+}