solver-sdk 3.1.1 → 3.1.3

package/docs/AUTHENTICATION.md

@@ -1,316 +0,0 @@
-# Аутентификация v2.5.0
-
-Документация по аутентификации в AI Solver SDK v2.5.0.
-
-## API ключи
-
-AI Solver использует API ключи для аутентификации. Ключи имеют специальные префиксы:
-
-### Форматы ключей
-
-```
-dev_sk_test_12345678    # Development key (для разработки)
-sk_prod_1234567890abcd  # Production key (для продакшна)
-sk_temp_abcdef123456    # Temporary key (временный)
-```
-
-## Получение API ключа
-
-### Development ключ
-
-Для локальной разработки используйте тестовый ключ:
-
-```
-dev_sk_test_12345678
-```
-
-### Production ключ
-
-1. Зарегистрируйтесь на платформе AI Solver
-2. Перейдите в настройки аккаунта
-3. Создайте новый Production API ключ
-4. Сохраните ключ в безопасном месте
-
-## Использование API ключа
-
-### Рекомендуемый способ (v2.5.0)
-
-```javascript
-import { CodeSolverSDK } from '@ai-solver/sdk';
-
-const sdk = CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'dev_sk_test_12345678'
-});
-```
-
-### Через переменные окружения
-
-```bash
-# Development
-export AI_SOLVER_API_KEY=dev_sk_test_12345678
-
-# Production
-export AI_SOLVER_API_KEY=sk_prod_1234567890abcd
-```
-
-```javascript
-import { CodeSolverSDK } from '@ai-solver/sdk';
-
-const sdk = CodeSolverSDK.create({
-  baseURL: process.env.NODE_ENV === 'production' 
-    ? 'https://api.ai-solver.com'
-    : 'http://localhost:3000',
-  apiKey: process.env.AI_SOLVER_API_KEY
-});
-```
-
-### Динамическое обновление ключа
-
-```javascript
-// Обновление API ключа в runtime
-sdk.updateOptions({
-  apiKey: 'new_api_key_12345678'
-});
-```
-
-## Типы ключей
-
-| Тип | Префикс | Описание | Срок действия |
-|-----|---------|----------|---------------|
-| Development | `dev_sk_test_` | Для локальной разработки | Неограничен |
-| Production | `sk_prod_` | Для production использования | 1 год |
-| Temporary | `sk_temp_` | Временный доступ | 7-30 дней |
-
-## Области действия (Scopes)
-
-API ключи v2.5.0 поддерживают следующие области:
-
-### Базовые права
-
-- `projects:read` - Чтение проектов
-- `projects:write` - Создание и изменение проектов
-- `projects:index` - Запуск индексации
-
-### AI права
-
-- `chat:access` - Доступ к AI чату
-- `chat:stream` - Потоковый чат
-- `reasoning:access` - Доступ к reasoning API
-- `reasoning:manage` - Управление reasoning процессами
-
-### Поиск и данные
-
-- `search:access` - Семантический поиск
-- `context:access` - Доступ к контексту проекта
-- `websocket:connect` - WebSocket соединения
-
-### Development ключ
-
-Development ключ `dev_sk_test_12345678` имеет **все права** для удобства разработки.
-
-## Проверка аутентификации
-
-### Диагностика API
-
-```javascript
-// Полная диагностика включая аутентификацию
-const results = await sdk.diagnoseAPI();
-console.log('API diagnostics:', results);
-
-/* Пример ответа:
-{
-  '/api/v1/projects': { status: 200, authenticated: true },
-  '/api/v1/chat': { status: 200, authenticated: true },
-  '/api/v1/reasoning': { status: 401, authenticated: false, error: 'Invalid API key' }
-}
-*/
-```
-
-### Простая проверка
-
-```javascript
-try {
-  const projects = await sdk.projects.getAll();
-  console.log('✅ Authentication successful');
-} catch (error) {
-  if (error.status === 401) {
-    console.error('❌ Invalid API key');
-  } else if (error.status === 403) {
-    console.error('❌ Insufficient permissions');
-  }
-}
-```
-
-## Заголовки аутентификации
-
-SDK автоматически добавляет заголовки:
-
-```http
-Authorization: Bearer dev_sk_test_12345678
-Content-Type: application/json
-```
-
-### Дополнительные заголовки
-
-```javascript
-const sdk = CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'dev_sk_test_12345678',
-  headers: {
-    'X-Client-Version': '2.5.0',
-    'X-User-Agent': 'My-App/1.0'
-  }
-});
-```
-
-## WebSocket аутентификация
-
-WebSocket соединения автоматически используют API ключ:
-
-```javascript
-// API ключ автоматически передается в WebSocket
-await sdk.projects.connectWebSocket();
-await sdk.reasoning.connectWebSocket();
-await sdk.chat.connectWebSocket();
-```
-
-## Ошибки аутентификации
-
-### 401 Unauthorized
-
-```json
-{
-  "error": "Unauthorized",
-  "message": "Invalid or missing API key",
-  "code": "AUTH_INVALID_KEY"
-}
-```
-
-**Решение:** Проверьте правильность API ключа.
-
-### 403 Forbidden
-
-```json
-{
-  "error": "Forbidden",
-  "message": "Insufficient permissions for this operation",
-  "code": "AUTH_INSUFFICIENT_SCOPE",
-  "required_scope": "projects:write"
-}
-```
-
-**Решение:** Используйте ключ с нужными правами.
-
-### 429 Rate Limited
-
-```json
-{
-  "error": "Too Many Requests",
-  "message": "Rate limit exceeded",
-  "retry_after": 60
-}
-```
-
-**Решение:** Подождите указанное время или используйте Production ключ.
-
-## Безопасность
-
-### ✅ Рекомендации
-
-- Используйте переменные окружения для хранения ключей
-- Никогда не коммитьте ключи в git
-- Регулярно ротируйте Production ключи
-- Используйте минимальные необходимые права
-- Мониторьте использование ключей
-
-### ❌ Не делайте
-
-```javascript
-// ❌ НЕ ДЕЛАЙТЕ ТАК
-const sdk = CodeSolverSDK.create({
-  apiKey: 'sk_prod_1234567890abcd' // Хардкод в коде
-});
-
-// ❌ НЕ ДЕЛАЙТЕ ТАК
-fetch('/api/client-side', {
-  headers: {
-    'Authorization': 'Bearer sk_prod_1234567890abcd' // В браузере
-  }
-});
-```
-
-### ✅ Правильно
-
-```javascript
-// ✅ ПРАВИЛЬНО
-const sdk = CodeSolverSDK.create({
-  apiKey: process.env.AI_SOLVER_API_KEY
-});
-
-// ✅ ПРАВИЛЬНО - для браузера используйте proxy
-fetch('/api/proxy/ai-solver', {
-  headers: {
-    'Authorization': 'Bearer ' + clientToken // Только client token
-  }
-});
-```
-
-## Environment Configuration
-
-### Development
-
-```bash
-# .env.local
-AI_SOLVER_API_KEY=dev_sk_test_12345678
-AI_SOLVER_BASE_URL=http://localhost:3000
-```
-
-### Production
-
-```bash
-# .env.production
-AI_SOLVER_API_KEY=sk_prod_1234567890abcd
-AI_SOLVER_BASE_URL=https://api.ai-solver.com
-```
-
-### Configuration helper
-
-```javascript
-function createSDK() {
-  const isDev = process.env.NODE_ENV === 'development';
-  
-  return CodeSolverSDK.create({
-    baseURL: isDev 
-      ? 'http://localhost:3000'
-      : 'https://api.ai-solver.com',
-    apiKey: process.env.AI_SOLVER_API_KEY,
-    autoConnect: false
-  });
-}
-```
-
-## Отзыв ключей
-
-При компрометации ключа:
-
-1. **Немедленно** удалите ключ из системы
-2. Обновите переменные окружения
-3. Перезапустите все сервисы
-4. Создайте новый ключ
-5. Проверьте логи на подозрительную активность
-
-```javascript
-// Проверка активности ключа
-const diagnostics = await sdk.diagnoseAPI();
-if (diagnostics.unauthorized) {
-  console.error('🚨 API key might be compromised or revoked');
-  // Логика восстановления
-}
-```
-
----
-
-**Документация аутентификации для SDK v2.5.0**  
-**Совместимость:** AI Solver Backend v1.0.0  
-**Обновлено:** 28 июня 2025