Git Credentials Management

Обзор

tg-note поддерживает безопасное хранение и использование персональных Git credentials (GitHub и GitLab токенов) для каждого пользователя. Это позволяет:

• 🔐 Безопасное хранение: Токены шифруются с помощью Fernet (AES-128)
• 👥 Мультипользовательский режим: Каждый пользователь может иметь свои токены
• 🌐 Поддержка GitHub и GitLab: Работа с обеими платформами
• 🚀 Простое управление: Команды в Telegram для добавления/удаления токенов

Зачем это нужно?

При работе с Git через HTTPS необходима аутентификация. Проблема хранения токена в .env файле:

❌ Один токен на всех - все пользователи используют один и тот же токен ❌ Небезопасная передача - передача токена через другие каналы может быть небезопасной ❌ Сложное управление - нужно редактировать файлы на сервере

✅ Решение: Персональные зашифрованные токены для каждого пользователя

Безопасность

Как хранятся токены?

1. Шифрование: Все токены шифруются с помощью Fernet (симметричное шифрование, AES-128)
2. Ключ шифрования: Хранится в файле ./data/.credentials_key с правами доступа 600 (только владелец может читать)
3. Зашифрованные данные: Хранятся в ./data/user_credentials.enc с правами доступа 600
4. Блокировка файлов: Используется file locking для предотвращения race conditions

Рекомендации по безопасности

✅ DO: - Создавайте токены с минимально необходимыми правами (repo для GitHub, write_repository для GitLab) - Устанавливайте срок действия токенов - Удаляйте сообщения с токенами после отправки боту - Используйте разные токены для разных проектов

❌ DON'T: - Не передавайте токены через незащищенные каналы - Не используйте токены с полным доступом ко всему аккаунту - Не сохраняйте токены в общедоступных местах

Команды управления

/settoken - Добавить токен

Команда для безопасного добавления Git токена.

Процесс:

1. Выполните /settoken в чате с ботом
2. Выберите платформу (GitHub или GitLab)
3. Введите ваш username
4. Введите ваш Personal Access Token

Пример:

/settoken
→ Выбрать: GitHub
→ Ввести: john_doe
→ Ввести: ghp_xxxxxxxxxxxxxxxxxxxx
→ ✅ Токен сохранен и зашифрован

Автоматическое удаление: После отправки токена, сообщение автоматически удаляется для безопасности.

/listcredentials - Просмотр токенов

Показывает информацию о сохраненных токенах (без раскрытия самих токенов).

Пример вывода:

🔐 Сохраненные Git Credentials

🐙 GITHUB
  • Username: john_doe
  • Token: ✅ Установлен
  • Remote: https://github.com/user/repo

🦊 GITLAB
  • Username: jane_smith
  • Token: ✅ Установлен

/removetoken - Удалить токен

Удаляет сохраненные токены.

Варианты:

• Удалить токен для конкретной платформы (GitHub или GitLab)
• Удалить все токены сразу

Пример:

/removetoken
→ Выбрать: GitHub
→ ✅ GitHub токен удален

Получение токенов

GitHub Personal Access Token

1. Перейдите на GitHub Settings → Developer settings → Personal access tokens
2. Нажмите "Generate new token" → "Generate new token (classic)"
3. Укажите название токена (например, "tg-note bot")
4. Выберите scope: repo (Full control of private repositories)
5. Опционально: установите срок действия токена
6. Нажмите "Generate token"
7. Скопируйте токен (он будет показан только один раз!)

Необходимые права: - ✅ repo - для работы с приватными репозиториями

GitLab Personal Access Token

1. Перейдите на GitLab Settings → Access Tokens
2. Укажите название токена (например, "tg-note bot")
3. Выберите scopes: write_repository
4. Опционально: установите срок действия токена
5. Нажмите "Create personal access token"
6. Скопируйте токен (он будет показан только один раз!)

Необходимые права: - ✅ write_repository - для работы с репозиториями

Как это работает?

Приоритет credentials

При выполнении Git операций используется следующий порядок приоритета:

1. Персональный токен пользователя (из CredentialsManager) - высший приоритет
2. Глобальный токен (из .env файла) - fallback

Это позволяет: - Пользователям с персональными токенами использовать их автоматически - Пользователям без персональных токенов использовать глобальный токен (если настроен)

Автоматическое определение платформы

Система автоматически определяет платформу по URL репозитория:

• github.com → Использует GitHub credentials
• gitlab.com или другой GitLab → Использует GitLab credentials

Инжектирование credentials в URL

При выполнении Git операций (pull, push), credentials автоматически добавляются в HTTPS URL:

https://github.com/user/repo.git
    ↓
https://username:token@github.com/user/repo.git

Настройка для администратора

Глобальные credentials (fallback)

Администратор может настроить глобальные credentials в .env файле:

# GitHub credentials (fallback for users without personal tokens)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_USERNAME=admin_username

# GitLab credentials (fallback for users without personal tokens)
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_USERNAME=admin_username

Местоположение файлов

• Ключ шифрования: ./data/.credentials_key
• Зашифрованные credentials: ./data/user_credentials.enc

Важно: - Не удаляйте ключ шифрования, иначе все сохраненные токены станут нечитаемыми - Делайте резервные копии ключа шифрования - Установите правильные права доступа к файлам (600)

Troubleshooting

Ошибка: "Authentication failed"

Причины: 1. Токен не установлен или устарел 2. У токена недостаточно прав 3. Токен был отозван на платформе

Решение: 1. Выполните /listcredentials - проверьте наличие токена 2. Удалите старый токен: /removetoken 3. Создайте новый токен на платформе 4. Добавьте новый токен: /settoken

Ошибка: "Could not decrypt credentials"

Причина: Ключ шифрования был изменен или удален.

Решение: 1. Удалите все токены: /removetoken → Удалить все 2. Добавьте токены заново: /settoken

Сообщение с токеном не удалилось

Решение: 1. Удалите сообщение вручную 2. Если токен был скомпрометирован - отзовите его на платформе 3. Создайте новый токен

Примеры использования

Пример 1: Первоначальная настройка

1. Создайте токен на GitHub
2. Отправьте /settoken боту
3. Выберите GitHub
4. Введите username: john_doe
5. Введите token: ghp_xxxxxxxxxxxxxxxxxxxx
6. ✅ Токен сохранен!

Теперь все Git операции будут использовать ваш токен автоматически.

Пример 2: Работа с несколькими платформами

1. Добавьте GitHub токен:
   /settoken → GitHub → username → token

2. Добавьте GitLab токен:
   /settoken → GitLab → username → token

3. Проверьте:
   /listcredentials

Бот автоматически выберет правильный токен в зависимости от платформы.

Пример 3: Обновление токена

1. Старый токен истек
2. Создайте новый токен на платформе
3. Отправьте /settoken
4. Выберите платформу (GitHub/GitLab)
5. Введите username и новый token

Новый токен заменит старый автоматически.

FAQ

Q: Можно ли использовать SSH вместо HTTPS?

A: Да, если ваш репозиторий использует SSH URL (git@github.com:...), токены не требуются. SSH ключи управляются стандартным образом через систему.

Q: Что произойдет если я потеряю ключ шифрования?

A: Все сохраненные токены станут нечитаемыми. Пользователям нужно будет добавить токены заново через /settoken.

Q: Безопасно ли передавать токен через Telegram?

A: Telegram использует шифрование для передачи сообщений. Дополнительно: - Сообщение с токеном автоматически удаляется после получения - Токен шифруется перед сохранением - Токен не логируется в системе

Q: Может ли администратор видеть мои токены?

A: Нет, токены хранятся в зашифрованном виде. Администратор может только удалить файл с зашифрованными токенами, но не прочитать их.

Q: Можно ли использовать один токен для нескольких репозиториев?

A: Да, один токен можно использовать для всех репозиториев на данной платформе (GitHub или GitLab).

Архитектура

Компоненты системы

┌─────────────────────────────────────────────────────────┐
│                    Telegram Bot                          │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────────────┐        ┌────────────────────┐    │
│  │ Credentials      │        │ Git Operations     │    │
│  │ Handlers         │◄──────►│                    │    │
│  │                  │        │ - pull/push        │    │
│  └────────┬─────────┘        │ - commit           │    │
│           │                   └──────────┬─────────┘    │
│           │                              │               │
│           ▼                              ▼               │
│  ┌─────────────────────────────────────────────────┐   │
│  │      CredentialsManager                          │   │
│  │                                                   │   │
│  │  ┌──────────────┐        ┌──────────────────┐  │   │
│  │  │  Encryption  │◄──────►│  File Storage    │  │   │
│  │  │  (Fernet)    │        │  (Encrypted)     │  │   │
│  │  └──────────────┘        └──────────────────┘  │   │
│  └─────────────────────────────────────────────────┘   │
│                                                           │
└─────────────────────────────────────────────────────────┘

Поток данных

1. Установка токена:

   User → Telegram → CredentialsHandlers → CredentialsManager
                                              ↓
                                          Encrypt → Save
   

2. Использование токена:

   Git Operation → GitOperations → CredentialsManager
                                      ↓
                                  Decrypt → Return
                                      ↓
                                  Inject to URL → Execute Git
   

См. также

• Configuration Guide
• Security Best Practices
• Troubleshooting