icq/PRD.md

PRD: Семейный мессенджер ICQ (XMPP) на chat.nixg.ru

Версия: 0.2 · Дата: 2026-08-28 · Статус: в разработке (Этап 1 завершён, Этап 2 начат)

Практический разбор всего сделанного: WALKTHROUGH.md — пошаговое описание с командами, почему выбрана такая архитектура, и все «засады».

Текущее состояние и план: STATUS.md — учётные данные, что работает, проблема пустой страницы + план исправления (точка входа для новой сессии).

1. Обзор (Executive Summary)

Разворачиваем собственный федеративный мессенджер для семьи на базе протокола XMPP. Сервер (Prosody) живёт на bigbox в каталоге /opt/icq, наружу выставляется через vps02 (Caddy + WireGuard). Домен: chat.nixg.ru.

Федерализация — обязательное требование: общение с любым XMPP-сервером в мире (email-подобная модель s2s).

Дополнительно: бот-книгоискатель, который по запросу находит и скачивает книги из сетевых библиотек (OPDS-каталоги) и присылает файл прямо в чат.

2. Цели (Goals)

• Личный, принадлежащий нам мессенджер для семьи (родители, дети).
• Федеративность: связь с пользователями любых XMPP-серверов.
• Клиенты под iOS и Android из официальных сторов (Snikket / Monal / Conversations).
• Сквозное шифрование (OMEMO) по умолчанию.
• Работает через наш туннель и не зависит от публичных мессенджеров.
• Бот, автоматизирующий скачивание книг из сетевых библиотек.

3. Не-цели (Non-Goals)

• Не пытаемся «слямзить» протокол Telegram/MTProto — это закрытый централизованный протокол, серверная часть не существует и не появится. Федеративность = XMPP.
• Не строим свой клиент — используем готовые (Element/Snikket/Monal/Conversations).
• Пока не делаем мост в Telegram/WhatsApp (mautrix) — только если понадобится позже.

4. Архитектура

4.1 Компоненты

[Клиенты: iOS/Android (Snikket/Monal/Conversations)]
        │  c2s (5222, TLS)
        ▼
[bigbox] Prosody (XMPP-сервер, Docker, /opt/icq)
        │  s2s (5269, TLS) — федерация с другими серверами
        │  http_upload (XEP-0363) — передача файлов (книги бота)
        ▼
[Бот-книгоискатель] slixmpp на bigbox, логинится как bot@chat.nixg.ru
        │  OPDS (HTTP)
        ▼
[Сетевые библиотеки: Флибуста и др.]

4.2 Сеть (доступность)

• bigbox — внутренний сервер (без публичного IP), Docker Compose.
• vps02 — публичный вход: Caddy (TLS, reverse-proxy WebSocket/HTTP) + WireGuard туннель до bigbox.
• Порты: 443 (клиенты, веб) + 5222 (прямые клиенты) + 5269 (федерация s2s).
• Форвард 5222/5269 с vps02 на bigbox через WireGuard (socat или iptables).

4.3 DNS (важно для федерации)

A      chat.nixg.ru            → публичный IP vps02
SRV    _xmpp-client._tcp.chat.nixg.ru  → chat.nixg.ru:5222
SRV    _xmpp-server._tcp.chat.nixg.ru  → chat.nixg.ru:5269

Без SRV-записей другие XMPP-серверы не смогут нас найти (федерация не заработает). Входящая федерация требует открытого 5269 на vps02.

4.4 TLS / сертификаты

• 443: Caddy выпускает сам (Let's Encrypt, http-01).
• 5222/5269: dns-01 (домен у нас, DNS контролируем) → e.g. через Caddy/acme.sh.
• Сертификат должен покрывать имена chat.nixg.ru (+ возможно conference.chat.nixg.ru для MUC).

5. Стек технологий

Слой	Технология	Почему
Протокол	XMPP (RFC 6120/6121)	Федеративный, открытый, XML — как email
Сервер	Prosody (Lua, Docker)	Лёгкий, гибкий, модули (http_upload, muc), удобен за реверс-прокси
Внешний доступ	Caddy на vps02 + WireGuard	TLS автоматически, reverse-proxy, WG-туннель до bigbox
Клиенты iOS	Monal / Snikket	Федерация + OMEMO + push (APNs)
Клиенты Android	Conversations / Snikket	Федерация + OMEMO + push (FCM)
Бот	Python + slixmpp	Зрелая живая библиотека XMPP
Поиск книг	OPDS (Atom/XML каталоги)	Стандарт сетевых библиотек (Флибуста и др.)
Передача файлов	XMPP HTTP Upload (XEP-0363)	Отправка книг в чат
Развёртывание	Docker Compose в /opt/icq	Изоляция, простота, переносимость

Примечание: Snikket как сервер не берём (спроектирован под прямой 443, капризен за реверс-прокси), но его клиенты хороши — используем их.

6. Функциональные требования

6.1 Обязательные (Must have)

• FR-1: Регистрация/вход по JID (user@chat.nixg.ru) с паролем.
• FR-2: Личные сообщения 1-на-1, статусы присутствия (presence).
• FR-3: Групповые чаты (MUC, конференции).
• FR-4: Сквозное шифрование OMEMO.
• FR-5: Передача файлов (HTTP Upload) — фото, документы.
• FR-6: Федерация s2s — общение с пользователями других серверов.
• FR-7: Админка/панель управления сервером (Prosody admin + командная строка).
• FR-8: Клиенты iOS и Android из официальных сторов.

6.2 Желательные (Should have)

• FR-9: Push-уведомления на iOS/Android (APNs/FCM) — через push-шлюз (Snikket/Conversations могут ходить на свой или публичный).
• FR-10: Бот-книгоискатель (slixmpp + OPDS).
• FR-11: Бэкапы базы/конфигов (в наш общий бэкап /opt/hermes).
• FR-12: Логирование и мониторинг (доступность).

6.3 Мосты в Telegram и WhatsApp (Bridges)

• FR-13: Мост в Telegram (mautrix-telegram) — общение с контактами Telegram из нашего клиента.
  • Двусторонняя переписка: наш пользователь ↔ контакт в Telegram.
  • Возможность отправлять/принимать файлы, реакции (по возможностям моста).
  • Авторизация через Telegram (логин/QR/MTProto), управление через панель бота моста.
• FR-14: Мост в WhatsApp (mautrix-whatsapp) — общение с контактами WhatsApp из нашего клиента.
  • Двусторонняя переписка: наш пользователь ↔ контакт в WhatsApp.
  • Авторизация через QR-код WhatsApp Web.
  • Передача файлов, голосовых (по возможностям моста).
• FR-15: Общий мост-хостинг (mautrix с Postgres/базой), регистрация в Prosody как компоненты.
• OQ-5: Какие мосты деплоим сразу (оба), какие позже? Сначала Telegram, потом WhatsApp (обычно надёжнее).

7. Бот-книгоискатель (детально)

7.1 Сценарий

1. Пользователь пишет боту book@chat.nixg.ru: «Пушкин Капитанская дочка».
2. Бот ищет по OPDS-каталогам (Флибуста и др.).
3. Находит, скачивает (epub/fb2), присылает файлом через HTTP Upload.
4. (Опц.) Ограничение размера, только легальные источники.

7.2 Требования

• FR-B1: Приём запросов через личные сообщения.
• FR-B2: Поиск по OPDS (Atom feed).
• FR-B3: Скачивание и отправка файла в чат (XEP-0363).
• FR-B4: Логирование запросов.
• FR-B5: Анти-флуд / ограничения.

8. Открытые вопросы (Open Questions)

• OQ-1: Какая библиотека OPDS основная? Флибуста (нужны ли регистрация/логин)?
• OQ-2: Snikket-клиенты работают только со Snikket-серверами? (нет — возьмём Monal + Conversations)
• OQ-3: Нужен ли мост Telegram (mautrix-telegram) сразу или позже?
• OQ-4: Нужен ли веб-клиент (Converse.js) на 443 через Caddy? ✅ СДЕЛАНО 2026-08-28 — https://chat.nixg.ru, Converse.js v14, локальные ассеты, WebSocket wss://chat.nixg.ru/xmpp-websocket.

9. Roadmap (этапы)

1. Этап 1 — Фундамент (✅ ЗАВЕРШЁН 2026-08-28): Docker Compose Prosody на bigbox (/opt/icq), базовые модули, DNS на chat.nixg.ru + SRV (A, _xmpp-client, _xmpp-server — внесены на Jino), Caddy на vps02 (443, reverse-proxy), форвард 5222/5269 через WG (iptables DNAT + FORWARD + MASQUERADE), группа безопасности Timeweb (TCP 5222/5269), веб-клиент Converse.js v14 на 443. Проверено: 5222/5269 открыты извне, webchat отдаётся, WebSocket 101 Switching Protocols. Подробности: WALKTHROUGH.md.
2. Этап 2 — Семья и федерация: MUC (есть), OMEMO, HTTP Upload (XEP-0363) — установить community-модуль mod_http_upload из prosody-modules (в docker-образе Prosody 0.11.9 его НЕТ), добавление внешнего контакта (проверка s2s), настоящие сертификаты dns-01 для 5222/5269. Приглашение семьи. Клиенты iOS/Android.
3. Этап 3 — Бот: slixmpp-бот с OPDS-поиском, HTTP Upload.
4. Этап 4 — Полировка: push, бэкапы, мониторинг, (опц.) мосты mautrix.

10. Принятые решения (Decisions)

• D-1: Протокол = XMPP (не Telegram/MTProto).
• D-2: Сервер = Prosody (не Snikket-сервер, не Ejabberd).
• D-3: Размещение = bigbox (/opt/icq), внешний вход = vps02 (Caddy + WG).
• D-4: Домен = chat.nixg.ru.
• D-5: Бот = Python slixmpp + OPDS + HTTP Upload.

11. Риски

• R-1: Флибуста меняет зеркала/требует VPN/логин — бот должен уметь переключать источники.
• R-2: Push на iOS (APNs) сложен для self-hosted — упираемся в публичный push-шлюз.
• R-3: Ограничение 5269 у провайдера vps02 — проверить заранее.
• R-4: Семейные пользователи малознакомы с XMPP-клиентами — подготовить инструкцию.