fa-mcp-sdk 0.2.121 → 0.2.125

package/cli-template/src/_examples/custom-basic-auth-example.ts

@@ -0,0 +1,252 @@
+// noinspection UnnecessaryLocalVariableJS
+
+/**
+ * Example: Custom Basic Authentication Implementation
+ *
+ * This example shows how to implement custom basic authentication
+ * validation with fa-mcp-sdk multi-authentication system.
+ */
+
+// @ts-ignore
+import { McpServerData, CustomBasicAuthValidator, initMcpServer } from 'fa-mcp-sdk';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+// ========================================================================
+// EXAMPLE 1: Database-backed Authentication
+// ========================================================================
+
+/**
+ * Custom validator using database lookup
+ */
+const databaseBasicAuthValidator: CustomBasicAuthValidator = async (username: string, password: string): Promise<boolean> => {
+  // Example: Check credentials against a database
+  try {
+    // This would be your actual database query
+    const user = await getUserFromDatabase(username);
+
+    if (!user) {
+      return false;
+    }
+
+    // Example: Compare hashed password
+    const isValidPassword = await comparePassword(password, user.hashedPassword);
+    return isValidPassword;
+
+  } catch (error) {
+    console.error('Database authentication error:', error);
+    return false;
+  }
+};
+
+// ========================================================================
+// EXAMPLE 2: LDAP/Active Directory Authentication
+// ========================================================================
+
+/**
+ * Custom validator using LDAP/AD
+ */
+const ldapBasicAuthValidator: CustomBasicAuthValidator = async (username: string, password: string): Promise<boolean> => {
+  try {
+    // Example LDAP authentication
+    const ldapResult = await authenticateWithLDAP(username, password);
+    return ldapResult.success;
+
+  } catch (error) {
+    console.error('LDAP authentication error:', error);
+    return false;
+  }
+};
+
+// ========================================================================
+// EXAMPLE 3: External API Authentication
+// ========================================================================
+
+/**
+ * Custom validator using external authentication service
+ */
+const externalApiAuthValidator: 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: any = await response.json();
+    return result.valid === true;
+
+  } catch (error) {
+    console.error('External API authentication error:', error);
+    return false;
+  }
+};
+
+// ========================================================================
+// EXAMPLE 4: Multi-factor Authentication
+// ========================================================================
+
+/**
+ * Custom validator with multi-factor authentication
+ */
+const mfaBasicAuthValidator: 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
+    const mfaValid = await validateMFAToken(username, mfaToken);
+    return mfaValid;
+
+  } catch (error) {
+    console.error('MFA authentication error:', error);
+    return false;
+  }
+};
+
+// ========================================================================
+// MCP SERVER INITIALIZATION WITH CUSTOM AUTH
+// ========================================================================
+
+const tools: Tool[] = [
+  {
+    name: 'example-tool',
+    description: 'An example tool',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message: { type: 'string' },
+      },
+    },
+  },
+];
+
+const toolHandler = async (params: { name: string; arguments?: any }) => {
+  return { content: [{ type: 'text', text: `Tool ${params.name} executed` }] };
+};
+
+const mcpServerData: McpServerData = {
+  tools,
+  toolHandler,
+  agentBrief: 'Example MCP Server with Custom Basic Auth',
+  agentPrompt: 'This server demonstrates custom basic authentication.',
+
+  // Custom basic auth validator
+// @ts-ignore
+  customBasicAuthValidator: databaseBasicAuthValidator, // or any of the other validators
+};
+
+// ========================================================================
+// MOCK FUNCTIONS (Replace with your actual implementations)
+// ========================================================================
+
+async function getUserFromDatabase (username: string): Promise<{ hashedPassword: string } | null> {
+  // Mock implementation - replace with your database query
+  const mockUsers = {
+    'admin': { hashedPassword: 'hashed_admin_password' },
+    'user': { hashedPassword: 'hashed_user_password' },
+  };
+  return mockUsers[username as keyof typeof mockUsers] || null;
+}
+
+async function comparePassword (plaintext: string, hashed: string): Promise<boolean> {
+  // Mock implementation - replace with proper password hashing library (e.g., bcrypt)
+  return `hashed_${plaintext}_password` === hashed;
+}
+
+async function authenticateWithLDAP (username: string, password: string): Promise<{ success: boolean }> {
+  // Mock implementation - replace with actual LDAP client
+  return { success: username === 'ldapuser' && password === 'ldappassword' };
+}
+
+async function validateMFAToken (username: string, token: string): Promise<boolean> {
+  // Mock implementation - replace with actual MFA validation
+  return token === '123456'; // Mock 6-digit MFA token
+}
+
+// ========================================================================
+// START THE SERVER
+// ========================================================================
+
+// Initialize and start the MCP server with custom basic authentication
+initMcpServer(mcpServerData).catch(console.error);
+
+// ========================================================================
+// CONFIGURATION EXAMPLE (config/default.yaml)
+// ========================================================================
+
+/*
+webServer:
+  auth:
+    enabled: true
+    basic:
+      type: 'basic'
+      # When using custom validator, username/password can be anything or even omitted
+      # The custom validator function will handle the actual authentication
+      username: 'placeholder'
+      password: 'placeholder'
+    # Other auth types can be configured alongside custom basic auth
+    jwtToken:
+      encryptKey: 'your-secret-key'
+      checkMCPName: true
+    permanentServerTokens:
+      - 'server-token-1'
+      - 'server-token-2'
+*/
+
+// ========================================================================
+// USAGE EXAMPLES
+// ========================================================================
+
+/*
+1. Using curl with custom basic auth:
+
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Basic $(echo -n 'admin:adminpassword' | base64)" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+
+2. With MFA (if using mfaBasicAuthValidator):
+
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Basic $(echo -n 'admin:adminpassword:123456' | base64)" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+
+3. JavaScript client example:
+
+const credentials = btoa('admin:adminpassword');
+const response = await fetch('http://localhost:3000/mcp', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Basic ${credentials}`
+  },
+  body: JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/list',
+    params: {}
+  })
+});
+*/
+
+export {
+  databaseBasicAuthValidator,
+  ldapBasicAuthValidator,
+  externalApiAuthValidator,
+  mfaBasicAuthValidator,
+};

package/cli-template/src/_examples/multi-auth-examples.ts

@@ -0,0 +1,333 @@
+/**
+ * Примеры использования системы мультиаутентификации fa-mcp-sdk
+ */
+
+import express from 'express';
+// @ts-ignore
+import { appConfig, enhancedAuthTokenMW, createConfigurableAuthMiddleware, getMultiAuthError, getAuthInfo, checkMultiAuth, detectAuthConfiguration, logAuthConfiguration } from 'fa-mcp-sdk';
+
+// ========================================================================
+// ПРИМЕР 1: ПРОСТАЯ ЗАМЕНА MIDDLEWARE
+// ========================================================================
+
+const app = express();
+
+// Вместо старого authTokenMW используем enhancedAuthTokenMW
+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,
+  });
+});
+
+// ========================================================================
+// ПРИМЕР 2: КОНФИГУРИРУЕМЫЙ MIDDLEWARE
+// ========================================================================
+
+// Middleware с логированием конфигурации при запуске
+const authWithLogging = createConfigurableAuthMiddleware({
+  logConfiguration: true,
+  forceMultiAuth: false, // Автоматически определяет нужна ли мультиаут
+});
+
+app.use('/api/v2', authWithLogging);
+
+// ========================================================================
+// ПРИМЕР 3: КАСТОМНАЯ ЛОГИКА АУТЕНТИФИКАЦИИ
+// ========================================================================
+
+app.use('/api/custom', async (req, res, next) => {
+  // Публичные эндпоинты
+  if (req.path.startsWith('/api/custom/public')) {
+    return next();
+  }
+
+  // Для админских эндпоинтов требуем только permanent tokens
+  if (req.path.startsWith('/api/custom/admin')) {
+    const token = (req.headers.authorization || '').replace(/^Bearer */, '');
+    const auth = appConfig.webServer.auth;
+
+    if (auth.permanentServerTokens.includes(token)) {
+      return next();
+    } else {
+      return res.status(403).json({ error: 'Admin access required' });
+    }
+  }
+
+  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');
+    return;
+  }
+});
+
+// ========================================================================
+// ПРИМЕР 4: РОУТЕР С РАЗНЫМИ УРОВНЯМИ ДОСТУПА
+// ========================================================================
+
+const apiRouter = express.Router();
+
+// Публичные роуты - без аутентификации
+apiRouter.get('/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+apiRouter.get('/info', (req, res) => {
+  const authInfo = getAuthInfo();
+  res.json({
+    authEnabled: authInfo.enabled,
+    configuredTypes: authInfo.configured,
+    validTypes: authInfo.valid,
+    usingMultiAuth: authInfo.usingMultiAuth,
+  });
+});
+
+// Защищенные роуты - с мультиаутентификацией
+apiRouter.use('/protected', enhancedAuthTokenMW);
+
+apiRouter.get('/protected/profile', (req, res) => {
+  const authInfo = (req as any).authInfo;
+  res.json({
+    profile: {
+      authType: authInfo.authType,
+      username: authInfo.username || 'anonymous',
+      permissions: getPermissionsForAuthType(authInfo.authType),
+    },
+  });
+});
+
+apiRouter.get('/protected/data', (req, res) => {
+  const authInfo = (req as any).authInfo;
+
+  // Разные данные в зависимости от типа аутентификации
+  let data;
+  switch (authInfo.authType) {
+    case 'permanentServerTokens':
+      data = { level: 'server', access: 'full' };
+      break;
+    case 'oauth2':
+      data = { level: 'user', access: 'scoped', scopes: authInfo.payload?.scope };
+      break;
+    case 'basic':
+      data = { level: 'basic', access: 'limited', username: authInfo.username };
+      break;
+    case 'pat':
+      data = { level: 'api', access: 'token-based' };
+      break;
+    case 'jwtToken':
+      data = { level: 'jwt', access: 'custom', payload: authInfo.payload };
+      break;
+    default:
+      data = { level: 'unknown', access: 'none' };
+  }
+
+  res.json({ data, authInfo: authInfo.authType });
+});
+
+app.use('/api/v3', apiRouter);
+
+// ========================================================================
+// ПРИМЕР 5: ПРОГРАММНОЕ ТЕСТИРОВАНИЕ ТОКЕНОВ
+// ========================================================================
+
+app.post('/api/test-token', async (req, res) => {
+  const { token } = req.body;
+
+  if (!token) {
+    return res.status(400).json({ error: 'Token required' });
+  }
+
+  try {
+    const authConfig = appConfig.webServer.auth;
+    const result = await checkMultiAuth(token, authConfig);
+
+    return res.json({
+      valid: result.success,
+      authType: result.authType,
+      tokenType: result.tokenType,
+      error: result.error,
+      username: result.username,
+      hasPayload: !!result.payload,
+    });
+  } catch (error) {
+    return res.status(500).json({ error: 'Authentication test failed' });
+  }
+});
+
+// ========================================================================
+// ПРИМЕР 6: MIDDLEWARE ДЛЯ РАЗНЫХ ТИПОВ API
+// ========================================================================
+
+// REST API - требует любую валидную аутентификацию
+app.use('/rest', enhancedAuthTokenMW);
+
+// GraphQL API - требует user-level аутентификацию (не server tokens)
+app.use('/graphql', async (req, res, next) => {
+  try {
+    const authError = await getMultiAuthError(req);
+    if (authError) {
+      return res.status(authError.code).send(authError.message);
+    }
+
+    const authInfo = (req as any).authInfo;
+    if (authInfo.authType === 'permanentServerTokens') {
+      return res.status(403).json({
+        error: 'GraphQL API requires user authentication, server tokens not allowed',
+      });
+    }
+
+    return next();
+  } catch (error) {
+    return res.status(500).send('Authentication error');
+  }
+});
+
+// WebSocket API - только JWT токены (для real-time connections)
+app.use('/ws', async (req, res, next) => {
+  try {
+    const authError = await getMultiAuthError(req);
+    if (authError) {
+      return res.status(authError.code).send(authError.message);
+    }
+
+    const authInfo = (req as any).authInfo;
+    if (authInfo.authType !== 'jwtToken' && authInfo.authType !== 'oauth2') {
+      return res.status(403).json({
+        error: 'WebSocket API requires JWT or OAuth2 tokens for session management',
+      });
+    }
+
+    return next();
+  } catch {
+    return res.status(500).send('Authentication error');
+  }
+});
+
+// ========================================================================
+// УТИЛИТНЫЕ ФУНКЦИИ
+// ========================================================================
+
+export function getPermissionsForAuthType (authType: string): string[] {
+  const permissions: Record<string, string[]> = {
+    'permanentServerTokens': ['read', 'write', 'admin', 'server'],
+    'oauth2': ['read', 'write', 'user'],
+    'jwtToken': ['read', 'write', 'session'],
+    'pat': ['read', 'write', 'api'],
+    'basic': ['read', 'basic'],
+  };
+
+  return permissions[authType] || ['read'];
+}
+
+// ========================================================================
+// ПРИМЕР 7: ИНИЦИАЛИЗАЦИЯ С ДИАГНОСТИКОЙ
+// ========================================================================
+
+export function initializeAuthSystem () {
+  const authConfig = appConfig.webServer.auth;
+
+  console.log('🔐 Initializing Multi-Authentication System...');
+
+  // Диагностика конфигурации
+  const detection = detectAuthConfiguration(authConfig);
+
+  console.log('📊 Auth Configuration:');
+  console.log(`   Enabled: ${authConfig.enabled}`);
+  console.log(`   Configured: ${detection.configured.join(', ')}`);
+  console.log(`   Valid: ${detection.valid.join(', ')}`);
+
+  if (Object.keys(detection.errors).length > 0) {
+    console.warn('⚠️  Configuration Issues:');
+    Object.entries(detection.errors).forEach(([type, errors]) => {
+      console.warn(`   ${type}: ${(errors as string[]).join(', ')}`);
+    });
+  }
+
+  // Логирование для отладки
+  logAuthConfiguration(authConfig);
+
+  console.log('✅ Multi-Authentication System initialized successfully');
+
+  return {
+    configured: detection.configured,
+    valid: detection.valid,
+    errors: detection.errors,
+    usingMultiAuth: !!(authConfig.pat || authConfig.basic || authConfig.oauth2),
+  };
+}
+
+// ========================================================================
+// ПРИМЕР 8: ТЕСТИРОВАНИЕ КОНФИГУРАЦИИ
+// ========================================================================
+
+export async function testAuthConfiguration () {
+  const authConfig = appConfig.webServer.auth;
+
+  console.log('🧪 Testing Authentication Configuration...');
+
+  const testCases = [
+    // Тест permanent token
+    {
+      name: 'Permanent Server Token',
+      token: authConfig.permanentServerTokens[0],
+      expectedType: 'permanentServerTokens',
+    },
+    // Тест PAT
+    {
+      name: 'Personal Access Token',
+      token: authConfig.pat,
+      expectedType: 'pat',
+    },
+    // Тест basic auth
+    {
+      name: 'Basic Authentication',
+      token: authConfig.basic
+        ? Buffer.from(`${authConfig.basic.username}:${authConfig.basic.password}`).toString('base64')
+        : undefined,
+      expectedType: 'basic',
+    },
+    // Тест OAuth2
+    {
+      name: 'OAuth2 Bearer Token',
+      token: authConfig.oauth2 ? `Bearer ${authConfig.oauth2.accessToken}` : undefined,
+      expectedType: 'oauth2',
+    },
+  ];
+
+  for (const testCase of testCases) {
+    if (!testCase.token) {
+      console.log(`⏭️  Skipping ${testCase.name}: not configured`);
+      continue;
+    }
+
+    try {
+      const result = await checkMultiAuth(testCase.token, authConfig);
+
+      if (result.success && result.authType === testCase.expectedType) {
+        console.log(`✅ ${testCase.name}: PASSED`);
+      } else {
+        console.log(`❌ ${testCase.name}: FAILED - ${result.error || 'Unexpected auth type'}`);
+      }
+    } catch (error) {
+      console.log(`❌ ${testCase.name}: FAILED - Authentication test error`);
+    }
+  }
+
+  console.log('🧪 Authentication testing completed');
+}
+
+// ========================================================================
+// ЭКСПОРТ ДЛЯ ИСПОЛЬЗОВАНИЯ
+// ========================================================================

package/cli-template/src/custom-resources.ts

@@ -1,3 +1,4 @@
+// @ts-ignore
 import { IResourceData } from 'fa-mcp-sdk';
 
 export const customResources: IResourceData[] = [