solver-sdk 2.5.0 → 2.6.1

package/docs/AUTHENTICATION.md

@@ -1,61 +1,316 @@
-# Аутентификация в SDK
+# Аутентификация v2.5.0
 
-SDK автоматически обрабатывает процесс аутентификации при подключении к API и WebSocket-сервисам.
+Документация по аутентификации в AI Solver SDK v2.5.0.
 
-## Настройка аутентификации
+## API ключи
 
-Аутентификация выполняется через API ключ, который необходимо передать при инициализации SDK:
+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 'solver-sdk';
+import { CodeSolverSDK } from '@ai-solver/sdk';
 
-// Инициализация SDK с API ключом
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'ваш-api-ключ' // Этот ключ будет использован для автоматической аутентификации
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678'
 });
 ```
 
-## Автоматическая аутентификация при WebSocket подключении
+### Через переменные окружения
 
-При использовании методов для работы с WebSocket (например, `sdk.connect()` или `sdk.projects.connectWebSocket()`), SDK автоматически выполняет аутентификацию, используя указанный API ключ. Вам не нужно предпринимать дополнительных действий для аутентификации WebSocket соединений.
+```bash
+# Development
+export AI_SOLVER_API_KEY=dev_sk_test_12345678
 
-## Изменение API ключа во время выполнения
-
-Если необходимо изменить API ключ во время выполнения программы:
+# Production
+export AI_SOLVER_API_KEY=sk_prod_1234567890abcd
+```
 
 ```javascript
-// Установка нового API ключа
-sdk.setApiKey('новый-api-ключ');
+import { CodeSolverSDK } from '@ai-solver/sdk';
 
-// После этого все новые запросы и WebSocket соединения 
-// будут использовать новый ключ
+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'
+});
 ```
 
-При изменении API ключа:
-1. Обновляются заголовки для HTTP запросов
-2. Существующие WebSocket соединения закрываются
-3. Новые соединения будут установлены с новым API ключом
+## Типы ключей
+
+| Тип | Префикс | Описание | Срок действия |
+|-----|---------|----------|---------------|
+| 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 процессами
 
-Если API ключ недействителен или устарел, SDK сгенерирует соответствующие ошибки:
+### Поиск и данные
+
+- `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 {
-  // Попытка выполнить операцию, требующую аутентификации
-  await sdk.projects.getAllProjects();
+  const projects = await sdk.projects.getAll();
+  console.log('✅ Authentication successful');
 } catch (error) {
   if (error.status === 401) {
-    console.error('Ошибка аутентификации: недействительный API ключ');
-    
-    // Обновление API ключа
-    sdk.setApiKey('новый-api-ключ');
-    
-    // Повторная попытка
-    const projects = await sdk.projects.getAllProjects();
-  } else {
-    console.error('Другая ошибка:', error);
+    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