blockmine 1.24.0 → 1.27.0

package/backend/docs/SECRETS_DOCUMENTATION.md

@@ -1,327 +0,0 @@
-# Документация по скрытым (секретным) значениям в настройках плагинов
-
-## Обзор
-
-Механика скрытых значений позволяет безопасно хранить чувствительные данные (API ключи, пароли, токены) в настройках плагинов. После сохранения такие значения маскируются при отправке на фронтенд, предотвращая утечку конфиденциальной информации.
-
-## Как использовать
-
-### 1. Объявление секретных настроек в package.json
-
-Чтобы пометить настройку как секретную, добавьте атрибут `"secret": true` в описание настройки:
-
-```json
-{
-  "botpanel": {
-    "settings": {
-      "apiKey": {
-        "type": "string",
-        "label": "API ключ",
-        "description": "Ваш секретный API ключ",
-        "default": "",
-        "secret": true
-      },
-      "apiKeys": {
-        "type": "string[]",
-        "label": "API ключи",
-        "description": "Список API ключей",
-        "default": [],
-        "secret": true
-      },
-      "password": {
-        "type": "string",
-        "label": "Пароль",
-        "description": "Пароль для доступа",
-        "default": "",
-        "secret": true
-      }
-    }
-  }
-}
-```
-
-### 2. Поддерживаемые типы настроек
-
-Атрибут `secret` работает со всеми типами настроек:
-- `string` - будет заменено на `********`
-- `string[]` - каждый элемент массива будет заменен на `********`
-- `object` - каждое значение в объекте будет заменено на `********`
-- `number` - будет заменено на `********`
-- `boolean` - будет заменено на `********`
-
-### 3. Работа с группированными настройками
-
-Механизм также поддерживает группированные настройки:
-
-```json
-{
-  "botpanel": {
-    "settings": {
-      "Аутентификация": {
-        "label": "Настройки аутентификации",
-        "token": {
-          "type": "string",
-          "label": "Токен",
-          "description": "Токен для API",
-          "default": "",
-          "secret": true
-        },
-        "apiKey": {
-          "type": "string",
-          "label": "API ключ",
-          "default": "",
-          "secret": true
-        }
-      }
-    }
-  }
-}
-```
-
-## Поведение системы
-
-### При чтении настроек (GET запросы)
-
-Когда фронтенд запрашивает настройки плагина, все секретные значения автоматически маскируются:
-
-```javascript
-// Реальные значения в БД:
-{
-  "apiKey": "sk-abc123xyz789",
-  "username": "john_doe"
-}
-
-// Что получает фронтенд:
-{
-  "apiKey": "********",  // секретное значение замаскировано
-  "username": "john_doe"  // обычное значение без изменений
-}
-```
-
-### При сохранении настроек (PUT запросы)
-
-Система автоматически определяет, были ли изменены секретные значения:
-
-#### Сценарий 1: Секретное значение не изменилось
-```javascript
-// Пользователь отправляет:
-{
-  "apiKey": "********",  // маска (не изменено)
-  "username": "new_username"
-}
-
-// Система сохраняет:
-{
-  "apiKey": "sk-abc123xyz789",  // оригинальное значение сохранено
-  "username": "new_username"
-}
-```
-
-#### Сценарий 2: Секретное значение изменилось
-```javascript
-// Пользователь отправляет:
-{
-  "apiKey": "sk-new-key-456",  // новое значение
-  "username": "new_username"
-}
-
-// Система сохраняет:
-{
-  "apiKey": "sk-new-key-456",  // новое значение сохранено
-  "username": "new_username"
-}
-```
-
-## Примеры использования
-
-### Пример 1: API ключи
-
-```json
-{
-  "botpanel": {
-    "settings": {
-      "apiKeys": {
-        "type": "string[]",
-        "label": "API ключи Google AI",
-        "description": "Список API ключей от Google AI Studio",
-        "default": [],
-        "secret": true
-      }
-    }
-  }
-}
-```
-
-### Пример 2: Пароль прокси-сервера
-
-```json
-{
-  "botpanel": {
-    "settings": {
-      "proxyPassword": {
-        "type": "string",
-        "label": "Пароль прокси",
-        "description": "Пароль для авторизации на прокси-сервере",
-        "default": "",
-        "secret": true
-      }
-    }
-  }
-}
-```
-
-### Пример 3: Токен доступа
-
-```json
-{
-  "botpanel": {
-    "settings": {
-      "accessToken": {
-        "type": "string",
-        "label": "Токен доступа",
-        "description": "Bearer токен для API",
-        "default": "",
-        "secret": true
-      }
-    }
-  }
-}
-```
-
-## Технические детали
-
-### Константы
-- `SECRET_MASK = '********'` - маска для замены секретных значений
-
-### Функции утилиты
-
-#### `isSecretSetting(settingConfig)`
-Проверяет, является ли настройка секретной.
-
-#### `maskSecretValue(value, settingConfig)`
-Маскирует значение, если настройка секретная.
-
-#### `filterSecretSettings(settings, manifestSettings, isGrouped)`
-Фильтрует настройки плагина, маскируя секретные значения перед отправкой на фронтенд.
-
-#### `prepareSettingsForSave(newSettings, existingSettings, manifestSettings, isGrouped)`
-Подготавливает настройки для сохранения, сохраняя оригинальные значения для замаскированных секретов.
-
-#### `isMaskedValue(value)`
-Проверяет, является ли значение замаскированным.
-
-## Безопасность
-
-### Что защищает эта механика:
-✅ Секретные значения не отправляются на фронтенд  
-✅ API ключи и пароли не отображаются в UI  
-✅ Случайное копирование настроек не раскрывает секреты  
-✅ Логи браузера не содержат чувствительных данных  
-
-### Что НЕ защищает эта механика:
-❌ Прямой доступ к базе данных  
-❌ Доступ к файловой системе сервера  
-❌ Server-side логи (секреты могут попасть в логи при загрузке плагинов)  
-❌ Network traffic sniffing (используйте HTTPS)  
-
-## Рекомендации
-
-1. **Всегда помечайте чувствительные данные как секретные:**
-   - API ключи
-   - Пароли
-   - Токены доступа
-   - OAuth секреты
-   - Приватные ключи
-
-2. **НЕ помечайте как секретные:**
-   - Публичные идентификаторы
-   - Имена пользователей (если не конфиденциальные)
-   - URL адреса
-   - Настройки UI
-
-3. **Дополнительная безопасность:**
-   - Используйте HTTPS для всех API запросов
-   - Ограничьте права доступа к настройкам плагинов
-   - Регулярно ротируйте API ключи
-   - Используйте переменные окружения для критически важных секретов
-
-## Миграция существующих плагинов
-
-Для добавления поддержки секретных значений в существующий плагин:
-
-1. Откройте `package.json` вашего плагина
-2. Найдите секретные настройки в секции `botpanel.settings`
-3. Добавьте `"secret": true` к каждой секретной настройке
-4. Сохраните файл
-5. Переустановите плагин или перезапустите бота
-
-```diff
-  "apiKey": {
-    "type": "string",
-    "label": "API ключ",
-    "description": "Ваш секретный API ключ",
--   "default": ""
-+   "default": "",
-+   "secret": true
-  }
-```
-
-## Отладка
-
-Если секретные значения не маскируются:
-
-1. Проверьте, что атрибут `"secret": true` добавлен корректно
-2. Убедитесь, что JSON валиден (нет лишних запятых)
-3. Проверьте логи сервера на наличие ошибок парсинга manifest
-4. Попробуйте переустановить плагин
-
-## API Endpoints
-
-Механика скрытых значений автоматически применяется к следующим endpoints:
-
-- `GET /api/bots/:botId/plugins/:pluginId/settings` - получение настроек плагина
-- `PUT /api/bots/:botId/plugins/:pluginId` - сохранение настроек плагина
-- `GET /api/bots/:id/settings/all` - получение всех настроек бота
-
-## Пример полного package.json
-
-```json
-{
-  "name": "my-secure-plugin",
-  "version": "1.0.0",
-  "description": "Плагин с секретными настройками",
-  "main": "index.js",
-  "botpanel": {
-    "icon": "Shield",
-    "categories": ["Утилиты"],
-    "settings": {
-      "apiKey": {
-        "type": "string",
-        "label": "API ключ",
-        "description": "Ваш секретный API ключ",
-        "default": "",
-        "secret": true
-      },
-      "serverUrl": {
-        "type": "string",
-        "label": "URL сервера",
-        "description": "Адрес API сервера",
-        "default": "https://api.example.com"
-      },
-      "tokens": {
-        "type": "string[]",
-        "label": "Токены",
-        "description": "Список токенов доступа",
-        "default": [],
-        "secret": true
-      },
-      "enableLogging": {
-        "type": "boolean",
-        "label": "Включить логирование",
-        "default": false
-      }
-    }
-  }
-}
-```
-