Home/lampac
0
0
Fork 0
Code Pull Requests Activity
Files
main
lampac/mods/TelegramAuth/README.md
T
prodik b6acef01ef TelegramAuth + TelegramAuthBot + WatchTogether; README/AGENT 
- mods/TelegramAuth, mods/TelegramAuthBot, mods/WatchTogether: копии из
  образа с enable: true (правило 1), секции в config/init.conf
- TelegramAuth в API-режиме (enable: false -> accsdb/гейт не поднимается),
  TelegramAuthBot: бот @GatusMonBot, long polling
- WatchTogether: customPlugins watchtogether.js, relay /wt/c/
- README: секция про SQLite/volume (первый запуск), таблица модулей,
  состояние Tg-notify и TelegramAuth, раздел WatchTogether
- AGENT: правило 10 дополнено секретами init.conf, §12 переписан,
  добавлен §13 WatchTogether, список mods/ в §1
- в git bot_token и mutations_api_secret оставлены пустыми (правило 10),
  реальные значения только в рабочем файле на сервере
2026-10-04 15:03:00 +00:00

138 lines
9.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TelegramAuth
HTTP API и файловое хранилище для привязки **UID устройства Lampa** к учётке Telegram. Проект: **`Modules/Community/TelegramAuth/`**. Работает с [TelegramAuthBot](../TelegramAuthBot/README.md) и с клиентским плагином (см. [обзор Community](../README.md) — `deny.js` / `telegram_auth_gate.js`).
---
## Включение
- Убедитесь, что **`TelegramAuth`** (и при использовании бота — **`TelegramAuthBot`**) **нет** в **`BaseModule.SkipModules`** в `init.conf` (в шаблоне [`config/base.conf`](../../../config/base.conf) оба отключены по умолчанию).
- [`manifest.json`](manifest.json): **`"enable": true`**.
- `init.conf`: секция **`TelegramAuth`**. Пример: [`init.merge.example.json`](init.merge.example.json).
---
## Назначение
- Пользователи Telegram: `telegramId`, роль, срок доступа, устройства (UID).
- Статус по UID для UI: привязан / ожидание / истёк срок.
- Лимит **активных** устройств для роли `user` (`max_active_devices_per_user`; у `admin` — без лимита).
- Опционально: импорт legacy, очистка устройств.
---
## Связь с accsdb
Если **`TelegramAuth.enable`** = **`true`**:
- В Core выставляется **`accsdb.enable`**.
- Активные привязанные UID синхронизируются в **корневой** **`users.json`** (рядом с `init.conf`) в формате **`AccsUser`**. Хост обычно подхватывает файл в течение ~1 с.
Если **`enable`** = **`false`**: только хранилище и HTTP API, без accsdb и без подмешивания WAF из этой секции.
**Когда UID попадает в корневой `users.json`:** пользователь **не** в `RegistrationPending`, **не** `Disabled`, устройство **активно**. Иначе для затронутых UID выполняется **`RemoveUid`**. При нехватке слотов под новое устройство самое старое активное переводится в неактивное и его UID снимается с accsdb.
Поле **`accs`** в записи пользователя в **`data_dir`/users.json** задаёт группу, бан, `params` (в т.ч. `telegram_id`) и т.д.; срок в accsdb берётся из **`ExpiresAt`** или **`accsdb.shared_daytime`** / 365 дней. Подробная логика: [`Services/AccsdbUidSync.cs`](Services/AccsdbUidSync.cs).
**Регистрация:** при выключенном `auto_provision_users` запись с таким `telegramId` уже должна быть в **`data_dir`/users.json`. При включённом — может создаваться автоматически (см. таблицу конфига). Ожидание модерации: **`RegistrationPending`** + при создании часто **`Disabled`**. Подтверждение: `POST /tg/auth/admin/user/pending` или бот.
**`owner_telegram_ids`:** при старте модуля создаются/обновляются как **admin** в **`data_dir`/users.json**.
Ограничение **чатов** для админ-команд бота задаётся в **`TelegramAuthBot.admin_chat_ids`**, не здесь.
---
## Конфигурация
| Поле | Описание |
|------|----------|
| `enable` | `true` — accsdb + синхронизация UID + применение **`limit_map`** к WAF. `false` (по умолчанию) — только API/хранилище. |
| `data_dir` | Каталог данных (по умолчанию `database/tgauth`). |
| `legacy_import_path` | База для `POST /tg/auth/import`. |
| `enable_import` / `enable_cleanup` | Разрешить импорт / `POST /tg/auth/devices/cleanup`. |
| `max_active_devices_per_user` | Лимит активных устройств для `user`; `0` → **5**. Для `admin` не применяется. |
| `mutations_api_secret` | Заголовок **`X-TelegramAuth-Mutations-Secret`** (совпадает с ботом). Пусто → `bind/complete` без заголовка; мутации админа из бота без cookie — невозможны. |
| `owner_telegram_ids` | Владельцы → admin при старте. |
| `auto_provision_users` | Создавать пользователя при bind неизвестного `telegramId`. |
| `auto_provision_role` | Роль новой записи (`admin` через auto-provision недоступен → `user`). |
| `auto_provision_lang` | Язык по умолчанию. |
| `auto_provision_expires_days` | Срок в днях; `0` — без срока. |
| `auto_provision_activate_immediately` | `false` — pending до решения админа; `true` — сразу активен. |
| `limit_map` | Правила WAF (тот же формат, что **`WAF.limit_map`** в Core). |
| `accsdb_sync_group_admin` / `accsdb_sync_group_user` | Значение **`group`** в accsdb, если не задано в **`accs.group`** (по умолчанию 100 / 0). |
### WAF и `limit_map`
При **`TelegramAuth.enable`** записи из **`TelegramAuth.limit_map`** переносятся в **`CoreInit.conf.WAF.limit_map`**. Перед добавлением из глобального списка удаляются правила с тем же **`pattern`** (точное строковое совпадение, `Ordinal`). Core выбирает **первое** подходящее по пути правило; иначе — глобальный **`WAF.limit_req`**.
Запрос может **не попадать** под лимит, если для него выставлены **`IsLocalRequest`** / **`IsAnonymousRequest`** — см. порядок middleware в хосте.
Шаблон по умолчанию в примере: `^/tg/auth` с лимитом запросов с IP. Переопределение: [`init.merge.example.json`](init.merge.example.json).
---
## Хранилище (`data_dir`)
| Файл | Содержимое |
|------|------------|
| `users.json` | Пользователи Telegram, устройства, опционально **`accs`**. |
| `admins.json` | Служебно (legacy-импорт). |
| `user_langs.json` | `telegramId → язык`. |
---
## HTTP API (префикс `/tg/auth`)
Маршруты анонимны в смысле cookie-сессии Lampac; админские мутации требуют cookie **`accspasswd`** (root) **или** заголовок **`X-TelegramAuth-Mutations-Secret`** при **непустом** `mutations_api_secret`. Если секрет пуст — заголовок не принимается, для мутаций остаётся только cookie.
**`POST /tg/auth/bind/complete`:** секрет обязателен только если `mutations_api_secret` не пустой.
### Чтение / статус
- `GET /tg/auth/status?uid=` — авторизован ли UID, срок, роль, число устройств.
- `GET /tg/auth/me?uid=` — полная запись владельца UID (404 если нет).
### Пользователь по Telegram
- `GET /tg/auth/user/by-telegram?telegramId=` — сводка для бота.
- `GET /tg/auth/devices?telegramId=` — список устройств.
### Привязка и устройства
- `POST /tg/auth/bind/start` — `{ "uid" }`.
- `POST /tg/auth/bind/complete` — `{ "uid", "telegramId", "username?", "deviceName?" }`.
- `POST /tg/auth/device/name` — `{ "uid", "name?" }` (плагин Lampa после успешного статуса).
- `POST /tg/auth/device/unbind` — `{ "telegramId", "uid" }` (без секрета мутаций).
- `POST /tg/auth/device/reactivate` — `{ "telegramId", "uid" }` (403 если pending/disabled).
### Административные
- `GET /tg/auth/admin/users`
- `GET /tg/auth/admin/user?telegramId=`
- `POST /tg/auth/admin/user/patch` — патч профиля и **`accs`**, см. код/бот `/setuser`.
- `POST /tg/auth/admin/user/disabled` — `{ "telegramId", "disabled" }` (admin нельзя отключить).
- `POST /tg/auth/admin/user/pending` — `{ "telegramId", "approve" }` (отклонение удаляет пользователя из `data_dir` и снимает UID с accsdb).
- `POST /tg/auth/import`
- `POST /tg/auth/devices/cleanup`
---
## Безопасность
- Не коммитьте **`mutations_api_secret`**. В проде лучше ненулевой секрет.
- Расширяйте **`limit_map`** при необходимости.
- GET с `uid` / `telegramId` раскрывают факт привязки — при жёсткой модели угроз ограничивайте сеть/прокси.
---
## Связь с ботом и клиентом
- Бот ходит на **`TelegramAuthBot.lampac_base_url`** + пути `tg/auth/...`. Секрет должен совпадать с **`TelegramAuth.mutations_api_secret`**.
- Клиент Lampa: [Community README — плагины](../README.md).
---
## Legacy-импорт
Каталог **`legacy_import_path`**: минимум **`tokens.json`**; опционально `admin_ids.json`, `user_langs.json`. Форматы — `TelegramAuthStore.ImportFromLegacy`. Запись с `approved_by` = **`registration-pending`** → pending/disabled как при auto-provision без немедленной активации.
View Git Blame Copy Permalink