morok-bot-sdk 1.0.1

package/README.ru.md

@@ -0,0 +1,602 @@
+# morok-bot-sdk
+
+Node.js / TypeScript SDK для разработки ботов на платформе сквозного шифрования [Морок](https://morok.me).
+
+SDK берет на себя установку сессии Signal Protocol, рассылку под channel-key в беседах и каналах, пополнение запаса одноразовых ключей, обновление JWT, переподключение WebSocket и шифрование вложений. Вы пишете обработчики событий.
+
+- English version: [README.md](./README.md).
+- Пошаговое руководство со скриншотами панели разработчика: [docs/getting-started.ru.md](./docs/getting-started.ru.md).
+- Полный справочник HTTP, WebSocket и формата обмена: [api.md](https://morok.me/api).
+- Развертывание (systemd, Docker, бэкапы, мониторинг): [docs/deployment.ru.md](./docs/deployment.ru.md).
+
+## Установка
+
+```bash
+npm install morok-bot-sdk
+```
+
+Требования:
+
+- Node **22 или новее** (SDK использует `globalThis.crypto`, нативный `Buffer.from(..., 'base64url')` и семантику `fs.rename`, которой нет гарантий в более старых версиях)
+- Файл токена `.morokbot`, сгенерированный при создании бота в приложении Морок
+
+Приватные ключи бота должны лежать на сервере, который вы контролируете.
+
+## Быстрый старт
+
+1. В приложении Морок откройте **Настройки -> О Мороке** и включите переключатель **Режим разработчика**. В настройках появится одноименный раздел.
+2. **Настройки -> Режим разработчика -> Создать бота**. Заполните три шага окна создания (описание, внешний вид, управление) и нажмите **Создать**. После этого под токеном появляется кнопка **Скачать .morokbot**. Она сохраняет JSON-файл с токеном и Signal-ключевым материалом бота.
+3. Положите файл рядом с кодом бота как `bot.morokbot` либо передайте абсолютный путь в `tokenFile`.
+4. Напишите обработчики:
+
+> **Не коммитьте `.morokbot` и `bot-state/` в git.** Файл `.morokbot` содержит signing-ключ бота: любой, у кого он есть, может выдавать себя за вашего бота. В `bot-state/` после первого запуска лежит Signal-идентичность и запас prekey. Готовый `.gitignore` с обоими паттернами лежит в репозитории SDK (`sdk/.gitignore`), скопируйте его в свой проект до первого коммита. После первого импорта: `chmod 0600 bot.morokbot && chmod 0700 bot-state/`.
+
+
+```ts
+import { MorokBot } from 'morok-bot-sdk'
+
+const bot = await MorokBot.fromFile({ tokenFile: './bot.morokbot' })
+
+bot.on('start',   (e) => console.log(`новый пользователь: @${e.peer.username}`))
+bot.on('stop',    (e) => console.log(`пользователь отписался: @${e.peer.username}`))
+
+bot.on('command', async (c) => {
+    if (c.command === 'help') await bot.reply(c, { text: 'Я эхо-бот.' })
+})
+
+bot.on('message', async (m) => {
+    if (m.text) await bot.reply(m, { text: `эхо: ${m.text}` })
+})
+
+bot.on('disconnect', (d) => console.log('сокет отвалился, willReconnect:', d.willReconnect))
+bot.on('error',      (e) => console.error('ошибка бота:', e.message))
+
+await bot.start()
+```
+
+SDK закрывает:
+
+- выпуск сессии через `/auth/bot-session` и обновление JWT по коду WS 4001 либо HTTP 401
+- подключение WebSocket с экспоненциальной задержкой повторов
+- X3DH-handshake при первом контакте и Double Ratchet через libsignal
+- пополнение одноразовых prekey (стартовый top-up, реактивный серверный сигнал prekeys_low и подстраховочный фоновый тик раз в 5 минут)
+- ротация подписанного prekey по серверному маркеру в 7 дней
+- доставка исходящего сообщения на все устройства собеседника
+- сопоставление собственных эхо-копий по `fanoutId`, чтобы `bot.send()` возвращал реальный `messageId`
+
+## Конфигурация
+
+`MorokBot.fromFile` принимает `BotConfig & { tokenFile }`:
+
+| Поле                   | По умолчанию             | Примечания                                                          |
+|------------------------|--------------------------|---------------------------------------------------------------------|
+| `tokenFile`            | (обязательно)            | Путь к файлу `.morokbot`                                            |
+| `stateDir`             | `./bot-state/`           | Свой каталог на каждого бота. Хранит приватные ключи. chmod 0700    |
+| `apiBaseUrl`           | `https://app.morok.me`   | Переопределите для self-hosted или dev-окружения                    |
+| `wsUrl`                | вычисляется              | http -> ws, https -> wss, добавляется `/ws`                         |
+| `replenishThreshold`   | `100`                    | Порог пополнения одноразовых ключей. Совпадает с серверной нижней отметкой, поэтому порог и реактивный сигнал `prekeys_low` согласованы |
+| `replenishTarget`      | `200`                    | Целевой размер запаса после пополнения (равен серверному потолку на один вызов) |
+| `backgroundIntervalMs` | `300_000` (5 минут)      | Подстраховочный тик за реактивным серверным сигналом `prekeys_low`, который пополняет по требованию. 0 отключает цикл (только для тестов) |
+| `autoBackfillOnJoin`   | `false`                  | Автоматически отдавать локальные эпохи новым участникам             |
+| `logger`               | молчит                   | В стиле pino: `info`, `warn`, `error`, `debug`                      |
+
+## Хранилище
+
+Данные бота лежат в двух местах:
+
+- `stateDir` на вашей машине: identity-ключ, prekeys, сессии Double Ratchet, локальные копии channel-key и group-secret. Десятки МБ максимум. Морок этот объем не квотирует, это ваш диск.
+- Сервер Морока хранит шифротекст сообщений в пути и все файлы бота, в том числе пока их не забрал офлайн-получатель. Разница только в том, на чью квоту они идут. **Обычный файл** сразу занимает квоту того, кому ушел: в ЛС квоту получателя (который запустил бота), в беседе или канале квоту владельца беседы (который добавил бота). Бот может занять все свободное место этой стороны, а когда оно кончится, отправка падает с `SendRejectedError`, код `recipient_storage_full`. **Голосовые и видеосообщения иначе: квоту они не занимают.** Сервер все равно держит их у себя, на локальном медиа-диске, и удаляет через 30 дней после отправки (и раньше, если диск переполняется, начиная со старых по всем пользователям). У получателей остается то, что они успели скачать или сохранить себе в Заметки.
+
+Дальше в этом разделе описана структура каталога `stateDir` (по умолчанию `./bot-state/`).
+
+```
+bot-state/
+  identity.json              пара ключей, accountSigningKey, registrationId
+  state.json                 счетчики (id следующего одноразового ключа, время последней ротации SPK)
+  state.lock                 pid-блокировка, один процесс на stateDir
+  sessions/<peer>.<dev>.json запись Double Ratchet на устройство собеседника
+  prekeys/signed-<id>.json   подписанные prekey (подпись сохраняется между раундами)
+  prekeys/onetime-<id>.json  одноразовые prekey
+  identity-cache/<addr>.json identity_key собеседника для TOFU
+  channel-keys/<conv>.json   история channel-key по разговору
+  group-secrets/<conv>.json  история group-secret по разговору
+  quarantine/                fsck перемещает сюда битые файлы при старте
+```
+
+После первого запуска в `stateDir` лежит приватный ключевой материал бота. Не выгружайте его в S3, не пересылайте по почте, не коммитьте в git. Храните резервную копию так же, как SSH-ключ.
+
+Два процесса на одном `stateDir` портят Signal-сессии. pid-lock это ловит, но на всякий случай давайте каждому боту свой каталог.
+
+## Публичный API
+
+### Конструктор
+
+```ts
+MorokBot.fromFile(config: BotConfig & { tokenFile: string }): Promise<MorokBot>
+```
+
+Читает и валидирует файл токена, собирает бота. Сетевых обращений до `start()` не делает.
+
+### Жизненный цикл
+
+| Вызов               | Эффект                                                                                  |
+|---------------------|-----------------------------------------------------------------------------------------|
+| `await bot.start()` | Импорт ключей, fsck, выпуск сессии, открытие WebSocket, первичное пополнение запаса. Повторный вызов безопасен. |
+| `await bot.stop()`  | Останавливает фоновые циклы, закрывает сокет, отвечает ошибкой на висящие отправки, снимает блокировку. Повторный вызов безопасен. |
+| `bot.isConnected`   | `true` после успешной аутентификации в WebSocket.                                       |
+| `bot.userId`        | Числовой userId. До завершения `start()` бросает исключение.                            |
+
+`start()` можно вызвать конкурентно: второй вызов сразу возвращается, бот окажется в одном состоянии. Если позвать `stop()` пока `start()` еще в полете, инициализация прерывается на ближайшей внутренней контрольной точке без утечек.
+
+### События
+
+```ts
+bot.on('message',             (m: IncomingMessage)         => …)
+bot.on('command',             (c: CommandInvocation)       => …)
+bot.on('start',               (e: BotStartEvent)           => …)  // пользователь нажал "Запустить"
+bot.on('stop',                (e: BotStopEvent)            => …)  // пользователь нажал "Стоп"
+bot.on('reaction',            (e: ReactionEvent)           => …)
+bot.on('conversation_added',  (e: ConversationAddedEvent)  => …)
+bot.on('conversation_kicked', (e: ConversationKickedEvent) => …)
+bot.on('disconnect',          (d: DisconnectInfo)          => …)
+bot.on('error',               (err: Error)                 => …)
+```
+
+`IncomingMessage`:
+
+```ts
+{
+    messageId:        number
+    conversationId:   number
+    conversationType: 'DIRECT' | 'GROUP' | 'CHANNEL'
+    sender:           Peer            // { userId, username, displayName }
+    senderDeviceId:   number
+    text:             string          // тело сообщения или подпись к вложению ('' если нет ни того, ни другого)
+    attachment?:      IncomingAttachment
+    gallery?:         IncomingGallery  // 2-10 элементов
+    clientMsgId:      string | null
+    replyToId:        number | null
+    threadRootId:     number | null
+    createdAt:        Date
+}
+```
+
+`CommandInvocation` дополняет его полями `{ command, args, argv }` для сообщений, начинающихся с `/cmd`.
+
+`DisconnectInfo.reason`:
+- `'transport'`: сетевой обрыв, SDK переподключается
+- `'auth'`: код WebSocket 4001, запись сессии в Redis удалена, SDK обновляет JWT и переподключается
+- `'shutdown'`: вы сами вызвали `stop()`, переподключения не будет
+
+### Отправка
+
+```ts
+// текстовое личное сообщение
+await bot.send({ peer: 12345,   text: 'привет' })
+await bot.send({ peer: 'alice', text: 'привет' })  // псевдоним резолвится через REST
+
+// файл (подпись необязательна)
+await bot.send({
+    peer,
+    text: 'фото кота',
+    attachment: {
+        kind: 'file',
+        data: fs.readFileSync('./cat.jpg'),
+        name: 'cat.jpg',
+        mime: 'image/jpeg',
+    },
+})
+
+// голосовое (подписи у голосовых нет)
+await bot.send({
+    peer,
+    attachment: {
+        kind: 'voice',
+        data: oggBytes,
+        duration: 4.2,
+        waveform: [10, 30, 80, 100, 70, 30, 10],
+    },
+})
+
+// видеосообщение
+await bot.send({
+    peer,
+    attachment: {
+        kind: 'video_note',
+        data: webmBytes,
+        duration: 6,
+        shape: 'circle',     // см. выноску "Формы видеосообщения" ниже
+    },
+})
+
+// галерея: от 2 до 10 файлов в одном пузыре
+await bot.send({
+    peer,
+    text: 'фото с прогулки',
+    attachments: [
+        { kind: 'file', data: a, name: '1.jpg', mime: 'image/jpeg' },
+        { kind: 'file', data: b, name: '2.jpg', mime: 'image/jpeg' },
+    ],
+})
+
+// сообщение в беседу или канал
+await bot.send({ conversation: 42, text: 'объявление' })
+
+// ответ на входящее сообщение (треды выставляются и для личных сообщений, и для бесед)
+await bot.reply(msg, { text: 'спасибо' })
+
+// поставить реакцию любым юникод-символом (не только эмодзи) либо снять реакцию
+await bot.react(msg, '𔙃')  // кабан
+await bot.unreact(msg)
+```
+
+`bot.send()` резолвится в `{ messageId, clientMsgId, conversationId }`. Ровно одно из `peer` или `conversation` обязательно.
+
+`bot.react(msg, unicode)` / `bot.unreact(msg)` принимают входящее сообщение или команду. Реакцией может быть любой юникод-символ, не только эмодзи. Она шифруется под разговор: в личных по устройствам собеседника, в беседах и каналах под channel-key. У бота может быть только одна реакция на сообщение, новая заменяет предыдущую. Свою реакцию бот обратно не получает, поэтому `react` завершается сразу после отправки. Чужие реакции приходят в `bot.on('reaction', ...)`.
+
+`peer` принимает числовой `userId` (предпочтительно при ответе на входящее, значение уже под рукой) либо строковый псевдоним (SDK резолвит его через `GET /users/:username` на каждый вызов, без кеша).
+
+`expiresInSeconds` в `send` или `reply` делает сообщение исчезающим, сервер удаляет его у всех через столько секунд после доставки
+
+Серверные лимиты:
+
+- Файлы до **5 ГБ** в открытом виде. До 50 МБ отправляются одним запросом, крупнее загружаются частями. SDK переключается между режимами сам.
+- Голосовые: длительность `[0.1, 600]` секунд, до 64 пиков waveform.
+- Видеосообщения: длительность `[0.5, 300]` секунд. `shape` это произвольная строка, актуальный список см. в выноске ниже.
+- Галереи: от 2 до 10 элементов, все типа `kind: 'file'`. Голосовые и видеосообщения внутри галереи не поддерживаются (фронтенд их там не рендерит).
+- **Обычные файлы** бота списываются с того, кто их получает (получатель в ЛС или владелец беседы/канала), в пределах его квоты, см. [Хранилище](#хранилище). **Голосовые и видеосообщения квоту не занимают**. Длинное видеосообщение все равно может превышать 50 МБ (5-минутный кружок около 58 МБ), SDK загружает его по chunked-пути прозрачно.
+
+> **Формы видеосообщения**: `shape` это строка, SDK передает ее как есть, приложение получателя рисует известные ему имена и подставляет `circle` для всего остального
+>
+> Имена, которые рисует получатель: `circle`, `square`, `slanted`, `pill`, `oval`, `arch`, `diamond`, `pentagon`, `gem`, `clamShell`, `sunny`, `cookie1`, `cookie2`, `cookie3`, `cookie4`, `clover1`, `clover2`, `burst`, `softBurst`, `puffyDiamond`, `pixelCircle`, `heart`
+
+### Команды и управление
+
+`bot.setMyCommands([{ command, description, sortOrder? }])` задает каталог слэш-команд, которые приложение подсказывает при вводе `/`. `bot.setMyControls([...])` задает дерево кнопок в меню бота, где контрол это `{ id, label, icon?, command?, children? }`. Кнопка с `children` открывает подменю на месте. Кнопка с `command` подставляет `/command ` в поле ввода. Кнопка без того и другого работает колбэком, боту приходит событие `control`, и он отвечает или перестраивает меню новым `setMyControls`. Слушайте через `bot.on('control', e => ...)`, где `e.controlId` это кнопка, а `e.sender` это кто нажал. Вызывайте после `start()`, каждый вызов заменяет дерево целиком. Бот объявляет до 32 команд и дерево кнопок до 64 узлов и до 4 уровней. `icon` берется из Material Symbols.
+
+`setMyControls` глобальный, одно меню для всех чатов. Чтобы у каждого пользователя были свои кнопки, вызывайте `bot.setControlsFor(userId, [...])` - она задает кнопки только для чата с одним пользователем, не затрагивая остальных. Так удобно показывать результаты поиска кнопками под конкретного человека или вести его по шагам. `userId` берется из события `control` (`e.sender.userId`) или из сообщения (`msg.sender.userId`). Переопределение живет недолго и переживает перезагрузку у этого пользователя. `bot.clearControlsFor(userId)` убирает его и возвращает пользователю глобальное меню. Границы те же, до 64 узлов и до 4 уровней. Корневое меню держите на `setMyControls`, а динамику ведите через `setControlsFor`.
+
+### Прием вложений
+
+`m.attachment` стоит на сообщениях с одним вложением, `m.gallery` на галереях. Байты не качаются, пока вы не вызовете `.download()`:
+
+```ts
+bot.on('message', async (m) => {
+    if (m.attachment) {
+        const a = m.attachment
+        console.log(`пришло ${a.kind} ${a.size}B (${a.mime})`)
+        if (a.kind === 'voice')      console.log(`длительность: ${a.duration}s`)
+        if (a.kind === 'video_note') console.log(`форма:        ${a.shape}`)
+        const bytes = await a.download()
+        fs.writeFileSync(`./inbox/${a.name ?? a.fileId}`, bytes)
+        return
+    }
+    if (m.gallery) {
+        for (const item of m.gallery.items) {
+            if (item.kind === 'file') {
+                const bytes = await item.attachment.download()
+                fs.writeFileSync(`./inbox/${item.attachment.name ?? item.attachment.fileId}`, bytes)
+            }
+            if (item.kind === 'contact')  console.log(`контакт: @${item.username ?? item.userId}`)
+            if (item.kind === 'location') console.log(`координаты: ${item.lat},${item.lng}`)
+        }
+        return
+    }
+    console.log('текст:', m.text)
+})
+```
+
+`download()` возвращает `Buffer` с расшифрованным содержимым. Reject на 404 либо 410 (файл удален или вытеснен по квоте), а также на ошибке расшифровки (порча формата обмена или неверный ключ). SDK не валидирует mime по белому списку: процесс это Node, а не браузер, поэтому считайте `mime` подсказкой от отправителя.
+
+`attachment.virusTotalVerdict` несет результат проверки VirusTotal (`'clean'`, `'suspicious'`, `'malware'`) на момент, когда SDK получил файл. Безопасные типы (картинки, медиа) не сканируются и сразу идут как `'clean'`. Потенциально опасные (исполняемые, архивы) уходят в VirusTotal, и пока он не ответил, вердикт `null`. SDK читает вердикт один раз и не следит за обновлениями, так что `null` значит, что проверка тогда еще не завершилась.
+
+### Беседы и каналы
+
+После добавления бота в беседу или канал (событие `conversation_added`) можно постить через `bot.send({ conversation, ... })` и отвечать через `bot.reply(msg, ...)`. SDK хранит channel-key по разговору в `stateDir/channel-keys/`, а group-secret в `stateDir/group-secrets/`.
+
+**Что боту можно и нельзя:**
+
+- Добавляет бота в беседу или канал и назначает ему роль только владелец (вкладка «Боты» в профиле, без подтверждения от бота).
+- Права бота те же, что у человека с такой же ролью.
+- В **канале** есть посты и комментарии, пост верхнего уровня пишет только бот-администратор или владелец, бот-модератор и бот-участник могут только комментировать.
+- В **беседе** есть обычные сообщения, писать может любой бот-участник, роль меняет только права модерации, такие как удаление чужих сообщений и заглушение участников, для них нужна роль модератора или выше.
+- Не может: менять роли участников, добавлять другого бота, становиться владельцем, создавать беседы и каналы, вызывать /start у другого бота.
+- Запрещенное действие сервер отклоняет с HTTP 403 или `SendRejectedError`.
+
+Администрирование беседы или канала:
+
+```ts
+// Сминтить свежий channel-key, разослать на устройства всех остальных участников
+await bot.rotateChannelKey(conversationId)
+
+// Перевыпустить group-secret (которым обернуты пакеты channel-key) и channel-key
+// одной серверной транзакцией. Делайте после исключения скомпрометированного участника,
+// старые участники не смогут расшифровать будущие пакеты
+await bot.rotateGroupSecret(conversationId)
+
+// Раздать локальную историю channel-key другим устройствам участника
+// Полезно, когда бот единственный онлайн-участник и новому подписчику нужно догнать историю
+await bot.backfillChannelKeys(conversationId, { userId: 7777 })
+```
+
+`autoBackfillOnJoin: true` в `BotConfig` дергает `backfillChannelKeys` для каждого нового участника без вашей обвязки. Сервер все равно режет по `joined_secret_version`, история до вступления не утечет.
+
+### Модель ошибок
+
+- **Ошибка расшифровки** -> событие `error`, сообщение отбрасывается, следующий type-3 кадр собеседника пересоберет сессию
+- **Сервер отклонил отправку** -> `send()` падает с экспортируемым `SendRejectedError`, причина в машиночитаемом `.code`: `bot_not_started` (пользователь не нажал "Запустить"), `recipient_storage_full`, `send_blocked`, `too_many_messages`
+- **Сервер отклонил загрузку** -> загрузка файла бросает экспортируемый `UploadRejectedError` с серверным `.code`, например `BOT_STAGING_FULL`, до того как уйдет кадр отправки
+- **Сетевой обрыв** -> событие `disconnect` с `willReconnect: true`, отправка, еще стоящая в очереди WebSocket-слоя, улетает после переподключения, а отправка, уже ушедшая в сеть и ждущая ответа сервера, падает с экспортируемым `SendUncertainError`, чтобы вы повторили или сверились, сообщение могло и дойти, и не дойти
+- **Отозванный JWT** (в панели разработчика обновили токен либо бот удален) -> WebSocket закрывается кодом 4001, SDK снова обращается к `/auth/bot-session` и переподключается, если бот еще жив, перевыпуск токена (кнопка "Перевыпустить токен") деструктивен, старый `.morokbot` теперь бесполезен, перезапустите SDK с новым файлом
+- **Отправка в беседу или канал, откуда вас исключили** -> `send()` падает с HTTP 403, локальное состояние channel-key уже сброшено на событии `conversation_kicked`
+
+## Вспомогательные классы
+
+Небольшие утилиты в составе `MorokBot`. Использовать не обязательно, они просто убирают типовую логику из обработчиков событий.
+
+### RateLimiter
+
+Счетчик по схеме token-bucket на каждый ключ. Сдерживает флуд от одного собеседника, не трогая нормальный трафик от других.
+
+```ts
+import { MorokBot, RateLimiter } from 'morok-bot-sdk'
+
+const limiter = new RateLimiter({
+    capacity:     5,    // допустимый всплеск
+    refillPerSec: 1,    // устойчивая скорость
+})
+
+bot.on('message', async (m) => {
+    if (!limiter.tryAcquire(m.sender.userId)) {
+        await bot.reply(m, { text: 'Слишком много сообщений, дайте мне минуту.' })
+        return
+    }
+    // ... ваш обработчик
+})
+```
+
+`tryAcquire(key, cost = 1)` возвращает `true`, если `cost` токенов было и они списаны, `false` иначе. `available(key)` подсматривает значение без расхода. `reset(key)` чистит один счетчик, `clear()` все.
+
+Доступ за O(1), счетчики сами удаляются после простоя в полном состоянии. Все хранится только в памяти. Если один бот работает в нескольких процессах, заведите общий счетчик в своем хранилище (например, Redis), в SDK он не входит.
+
+Чтобы держать темп постов верхнего уровня в канал под серверным (запас 5, дальше один в 30 секунд) задайте счетчик как `new RateLimiter({ capacity: 5, refillPerSec: 1 / 30 })` и вызывайте `tryAcquire` перед каждым постом. Сам SDK не повторяет отказ `too_many_messages` за вас, поймайте `SendRejectedError`, прочитайте `.code` и сбавьте темп, так же и с `SendUncertainError` после обрыва, где вы решаете, повторить или свериться
+
+### BotSessions
+
+Хранилище состояния на каждого пользователя для пошаговых сценариев ("спросить имя", "спросить email", "подтвердить"). Внутри обычная `Map` по `userId` с необязательным TTL и методом `update()` для частичных изменений.
+
+```ts
+import { MorokBot, BotSessions } from 'morok-bot-sdk'
+
+interface RegisterFlow {
+    step:   'name' | 'email'
+    name?:  string
+    email?: string
+}
+
+const flows = new BotSessions<RegisterFlow>({ ttlMs: 5 * 60_000 })  // 5 минут простоя = бросить
+
+bot.on('command', async (c) => {
+    if (c.command === 'register') {
+        flows.set(c.sender.userId, { step: 'name' })
+        await bot.reply(c, { text: 'Как вас зовут?' })
+    }
+})
+
+bot.on('message', async (m) => {
+    const state = flows.get(m.sender.userId)
+    if (!state) return                              // не в flow
+
+    if (state.step === 'name' && m.text) {
+        flows.update(m.sender.userId, { step: 'email', name: m.text })
+        await bot.reply(m, { text: 'А email?' })
+        return
+    }
+    if (state.step === 'email' && m.text) {
+        const final = flows.update(m.sender.userId, { email: m.text })
+        flows.delete(m.sender.userId)              // flow завершен
+        await bot.reply(m, { text: `Принято, ${final.name}. Напишем на ${final.email}.` })
+    }
+})
+```
+
+Только в памяти. Перезапуск процесса все стирает. Если нужно сохранение сценариев между перезапусками, сохраняйте состояние на диск или в Redis из обработчиков самостоятельно.
+
+## Восстановление токена
+
+Если потеряли файл `.morokbot`:
+
+1. Режим разработчика -> ваш бот -> **Редактировать** -> шаг **Управление** -> **Перевыпустить**.
+2. Сервер отзывает старый токен И закрывает все живые сессии.
+3. Окно создания один раз показывает новый токен. Замените поле `token` в файле `.morokbot` (все остальное остается прежним, identity, SPK, OTPK не меняются).
+4. Перезапустите SDK.
+
+Если потерян и ключевой материал, бота придется удалить и создать заново. Удаление убирает аккаунт бота целиком: у собеседников он превращается в удаленный аккаунт и пропадает из поиска. Новый бот будет отдельным аккаунтом, даже под тем же псевдонимом, согласие на него не переносится, поэтому каждому собеседнику придется заново найти бота и нажать "Запустить".
+
+## Безопасность
+
+- Сервер Морока никогда не расшифровывает содержимое сообщений. SDK использует ключи сессии Signal Protocol для личных сообщений и channel-key (AES-256-GCM) для каждой беседы или канала.
+- При полной утечке БД наружу уходят шифротекст, публичные Signal-ключи, HMAC от телефонных номеров, граф общения по псевдонимам (кто с кем и когда), размеры файлов. Содержимого сообщений и приватных ключей в БД нет. Сырые IP в логи не пишутся.
+- В `.morokbot` и в `stateDir` лежат приватные ключи бота. Если они попадут в чужие руки, бота можно только пересоздать заново.
+- При подключении бот перекрестно подписывает свое устройство, публикуя сертификат устройства, и проверяет сертификаты собеседников при первом контакте, поэтому переименованный собеседник или собеседник на новом устройстве по-прежнему дает согласованный номер безопасности. Сертификат устройства задается один раз. Сервер отклоняет тихую смену ключа (отправка другого сертификата на уже подписанное устройство возвращает HTTP 409), поэтому ни враждебный сервер, ни перехваченная сессия не подменят проверочный материал бота незаметно.
+
+> **Отчеты об уязвимостях**: пишите на `security@morok.me`. Пожалуйста, **не оформляйте публичные GitHub issues с описанием уязвимостей**: это раскроет проблему каждому встречному до того, как выйдет фикс. Машинно-читаемая политика раскрытия лежит в [`/.well-known/security.txt`](https://morok.me/.well-known/security.txt) (RFC 9116).
+
+## Что делать, если
+
+Типичные симптомы и решения. Подробности по кодам ошибок в [справочнике API](https://morok.me/api).
+
+### Подключение и аутентификация
+
+| Симптом                                                              | Что значит                                                                                                                                              | Решение                                                                                                                          |
+|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `disconnect` событие каждые несколько секунд, `reason: 'transport'`  | Нестабильная сеть, NAT, сервер ребутится или прокси режет идл-соединения.                                                                              | Проверьте `curl https://app.morok.me/health`. Если сервер ок, SDK переподключится сам. Включите `logger` для деталей.            |
+| WebSocket закрывается кодом 4001 (`reason: 'auth'`)                  | Запись сессии в Redis удалена, либо в панели разработчика обновили токен, либо `/auth/bot-session` отклонил ваш токен.                              | SDK обновит JWT автоматически. Если зациклилось, токен мертв: нажмите **Перевыпустить токен** в панели и подмените поле `token` в `.morokbot`. |
+| `MorokBot.start: ... 401 INVALID_CREDENTIALS`                         | В `.morokbot` устарел `token`.                                                                                                                          | Подмените поле `token` в `.morokbot` свежим из панели. Остальное (identity, prekeys) не трогайте.                                |
+| `MorokBot.start: refused state-dir lock, another process ...`        | Два SDK-процесса смотрят на один и тот же `stateDir`. Поймал pid-lock.                                                                                  | Убейте старый процесс или дайте каждому свой `stateDir`. Stale `state.lock` чистится автоматически, если pid уже мертв.          |
+
+### Отправка
+
+Отказы отправки бросают экспортируемый `SendRejectedError` с машиночитаемым `.code` (`bot_not_started`, `recipient_storage_full`, `send_blocked`, `too_many_messages`). Бот может отправить **5 сообщений подряд** в одном разговоре (ЛС, беседа, комментарии), счетчик сбрасывается, как только там пишет не-бот. Посты верхнего уровня в канал лимитируются иначе: 5 в запасе, дальше не чаще одного в 30 секунд. Галерея это одно сообщение (до 10 элементов), а реакции, правки и удаления не считаются. Отклоненная загрузка файла (больше 5 ГБ в открытом виде или у бота больше 10 ГБ неотправленного запаса) бросает экспортируемый `UploadRejectedError` с `.code` вроде `BOT_STAGING_FULL`, а обрыв во время ожидания ответа сервера бросает экспортируемый `SendUncertainError`, где сообщение могло и дойти, и не дойти, поэтому вы повторяете или сверяетесь
+
+| Симптом                                                              | Что значит                                                                                                                                             | Решение                                                                                                                                                                                                                    |
+|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `send()` reject с `bot_not_started`                                   | Собеседник не нажал "Запустить" в профиле бота. Серверная защита, боты не могут писать в ЛС первыми.                                                   | Ждите события `start` от пользователя, потом ему можно писать. Чтобы пользователи нажимали, попросите в описании профиля бота.                                                                                             |
+| `send()` reject с HTTP 403 в беседе или канале                        | Бота исключили или разговор удалили. Событие `conversation_kicked` уже пришло, SDK сбросил локальное состояние channel-key.                            | Не повторяйте запрос. Если ждете возврата, подпишитесь на `conversation_added`.                                                                                                                                            |
+| `send()` бросает `UploadRejectedError`                               | Файл больше 5 ГБ в открытом виде, либо у бота накопилось больше 10 ГБ загруженных, но еще не отправленных файлов (`.code` `BOT_STAGING_FULL`) | Уменьшите файл либо отправьте уже загруженное (после отправки файл перестает занимать этот лимит) |
+| `send()` падает с `SendUncertainError` после `disconnect`            | Соединение оборвалось, пока отправка ждала ответа сервера, сообщение могло и дойти, и не дойти | Поймайте `SendUncertainError`, затем повторите или сверьтесь с историей (он несет `clientMsgId` и `conversationId`), слепой повтор может задвоить, если первое дошло |
+| `send()` reject с `SendRejectedError` (`code: 'recipient_storage_full'`) | Обычный файл списан на сторону, которая его несет: получателя ЛС, запустившего бота, или владельца беседы/канала, добавившего бота. Его хранилище заполнено.                       | Эта сторона освобождает место или переходит на свое облако с большим объемом, либо посылайте меньше.                                                                             |
+| `send()` reject с `SendRejectedError` (`code: 'too_many_messages'`) | Бот превысил лимит частоты: 5 подряд в ЛС/беседе/комментариях (сброс сообщением не-бота) или, для постов верхнего уровня в канал, темп выше одного в 30 секунд после первых 5.                       | В ЛС/беседе/комментариях дождитесь сообщения не-бота (открывает новые 5). В канале сбавьте темп до одного поста в 30 секунд. Либо упакуйте больше в меньшее число сообщений: галерея это одно сообщение до 10 элементов. Реакции, правки и удаления не считаются.                                                                             |
+| `bot.send({ peer: 'alice' })` тормозит на резолве псевдонима           | Разрешение псевдонима в `userId` дергает `GET /users/:username` на каждый вызов (без кеша в SDK).                                                      | Если часто пишете одному собеседнику, закешируйте `userId` у себя. Числовое значение неизменно.                                                                                                                            |
+
+### Прием
+
+| Симптом                                                              | Что значит                                                                                                                                              | Решение                                                                                                                          |
+|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `error` событие с "decrypt failed" / "no matching session"            | Состояние Double Ratchet у собеседника разошлось с ботом. Часто после переустановки приложения.                                                         | SDK дропает сообщение и ждет следующий type-3 фрейм от собеседника, тот пересоберет сессию. Действий не требуется.              |
+| `warn` лог `[signal] PEER IDENTITY CHANGED` на type-3 фрейме          | Известный собеседник предъявил новый identity-ключ, и SDK перепиннил его, обычно из-за переустановки. SDK принимает это и продолжает, не блокирует.   | Для обычной переустановки действий не нужно. Если вы отслеживаете identity собеседников отдельно, считайте это поводом перепроверить собеседника.          |
+| `attachment.download()` reject с HTTP 404 / 410                       | Файл удален, истек либо вытеснен квотным cron.                                                                                                          | Считайте файл потерянным. Отправитель может перезалить.                                                                          |
+| Во фронтенде собеседника предупреждение «Изменился номер безопасности» | У того же аккаунта сменился identity-ключ (на аккаунт импортировали другой `.morokbot` с новым ключевым материалом). В обычном потоке это не случается: перевыпуск токена identity не трогает, очистка `stateDir` реимпортирует тот же ключ из `.morokbot`, а пересоздание бота дает отдельный аккаунт (это новый бот, собеседники заново находят его и жмут «Запустить»).                                                                  | Клиент собеседника сам перепиннит новый ключ (TOFU), предупреждение покажется один раз, без блокировки. Перепроверить номер безопасности вручную можно по желанию.    |
+
+### Каталог состояния
+
+| Симптом                                                              | Что значит                                                                                                                                              | Решение                                                                                                                          |
+|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| Boot-лог: `[bot] fsck quarantined N session files`                    | Один или несколько файлов в `stateDir/sessions/` не распарсились. SDK переместил битые в `stateDir/quarantine/`, остальное состояние работает.          | Затронутые сессии пересоберутся при следующем сообщении. Загляните в `quarantine/` хотя бы раз, чтобы понять, что их повредило (отказ диска, kill -9 во время записи). |
+| Размер `stateDir` медленно растет месяцами                            | Накапливаются записи сессий: один файл на пару собеседник-устройство.                                                                                  | Это нормально, даже на тысячах собеседников каталог занимает десятки МБ. Не чистите его вручную: удаление файлов сессий ломает Signal-сессии. |
+| Залипший `state.lock` после `kill -9`                                  | В pid-файле мертвый PID, SDK отказывается стартовать.                                                                                                   | SDK проверяет, что записанный PID жив, и снимает блокировку, если нет. Если все равно "refused", PID переиспользован системой. Удалите `state.lock` вручную. |
+
+### Создание и управление ботом
+
+| Симптом                                                              | Что значит                                                                                                                                              | Решение                                                                                                                          |
+|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `BOT_USERNAME_TAKEN` при создании                                     | Псевдоним с суффиксом `-bot` уже занят.                                                                                                                 | Выберите другой псевдоним.                                                                                                      |
+| `BOT_LIMIT_REACHED` (409)                                             | У вас уже 10 ботов.                                                                                                                                     | Удалите ненужного бота во вкладке Режим разработчика либо через `DELETE /developer/bots/:id`.                                                                            |
+| Новый `.morokbot` после "Перевыпустить токен" не импортируется         | Если оставили только новый `token` и подменили его в старом файле, все правильно. Если перевыкачали весь `.morokbot` и identity бота сменился, собеседники увидят «Изменился номер безопасности». | По умолчанию «Перевыпустить» в панели меняет только токен. Если сменилась и identity, у собеседников один раз покажется «Изменился номер безопасности», клиент перепиннит новый ключ сам (TOFU). Прежнюю идентичность не восстановить. |
+
+### Отладка
+
+Подайте логгер, и будете видеть, что SDK делает. Pino работает напрямую, `console`-shape тоже:
+
+```ts
+const bot = await MorokBot.fromFile({
+    tokenFile: './bot.morokbot',
+    logger: {
+        info:  (o, m) => console.log  (m, o),
+        warn:  (o, m) => console.warn (m, o),
+        error: (o, m) => console.error(m, o),
+        debug: (o, m) => console.debug(m, o),
+    },
+})
+```
+
+Уровень `debug` пишет каждый WS-фрейм и каждый цикл пополнения prekey, логи быстро разрастаются. `info` оставляет загрузочные сообщения и редкие события. На боевом сервере разумно держать `warn` и `error`, направленные в файл через systemd или journald.
+
+Если подозреваете проблему на стороне сервера, соберите:
+- `curl https://app.morok.me/health` и `/version`
+- Точный `error.message` из события `error`
+- Окружающие лог-строки на `debug` уровне
+
+и откройте [GitHub issue](https://github.com/geloid/morok-bot-sdk/issues) с этим.
+
+## Разработка
+
+```bash
+git clone https://github.com/geloid/morok-bot-sdk.git
+cd morok-bot-sdk
+npm install
+npm run build       # tsc -> dist/
+npm run typecheck
+npm test            # vitest unit-тесты
+```
+
+Unit-тесты покрывают парсер `.morokbot`, файловые хранилища Signal (с fsck и защитой от выхода за пределы каталога), форматы обмена channel и group-secret, файловый шифр (один запрос и chunked AAD), envelope галереи. Интеграционного набора нет: запускайте пример из `examples/echo-bot/` на своем тестовом окружении.
+
+`npm run lint` тоже нет, проект полагается на `tsc --strict` и тесты.
+
+### Генерация API reference
+
+```bash
+npm run docs:api      # typedoc -> docs-api/
+```
+
+`docs-api/` это статический HTML-сайт публичной поверхности SDK (все, что экспортируется из `src/index.ts`), генерируемый [TypeDoc](https://typedoc.org/) из TypeScript-типов и JSDoc. Опубликованная копия лежит на [morok.me/sdk-api/](https://morok.me/sdk-api/). Каталог в gitignore: это артефакт сборки, перегенерируется на каждый релиз.
+
+## Глоссарий
+
+Криптотермины, встречающиеся в SDK и [справочнике API](https://morok.me/api).
+
+| Термин                        | Значение                                                                                                                                                                          |
+|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Signal Protocol**           | Набор криптопримитивов, который Морок унаследовал от [Open Whisper Systems](https://signal.org/docs/). E2E-ратчет в личных сообщениях + симметричный channel-key для бесед и каналов + асинхронный handshake. |
+| **X3DH**                      | Extended Triple Diffie-Hellman: асинхронный handshake, позволяющий начать зашифрованную сессию с получателем, который сейчас офлайн. Смешивает identity-ключ + подписанный + одноразовый. |
+| **Double Ratchet**            | Алгоритм эволюции ключей внутри сессии после X3DH. Каждое сообщение продвигает ключ, поэтому компрометация одного ключа раскрывает максимум одно сообщение в каждом направлении.    |
+| **prekey**                    | Публичный Curve25519-ключ, который получатель публикует заранее. Инициатор X3DH забирает один и с ним собирает сессию. Бывают двух типов ниже.                                     |
+| **подписанный prekey (SPK)**  | Долгоживущий prekey, подписанный identity-ключом. Сервер требует ротации раз в 7 дней. Используется, когда одноразового prekey нет в запасе.                                        |
+| **одноразовый prekey (OTPK)** | Короткоживущий prekey, удаляется после первого использования. Запас поддерживается на уровне `replenishTarget`, SDK дополняет автоматически.                                          |
+| **identity-ключ**             | Долгоживущая пара Curve25519 у бота. Определяет криптоидентичность бота для собеседников. Лежит в `stateDir/identity.json`.                                                       |
+| **TOFU**                      | "Trust On First Use": собеседник принимает identity-ключ при первом контакте и проверяет, что он не меняется. Смена identity-ключа вызывает предупреждение в приложении собеседника.                |
+| **стирание sender_id**        | Ретроактивная минимизация метаданных. На личных сообщениях сервер держит sender_id лишь в горячем окне (по умолчанию 7 дней), чтобы вернуть квитанции о доставке и прочтении, после чего обнуляет его. В момент маршрутизации сервер отправителя видит, поэтому это не sealed sender (такая модель в сервисе не задействована). Содержимое бесед и каналов шифруется под channel-key. |
+| **channel-key**               | Симметричный AES-256 ключ на разговор. Шифрует сообщения в беседе или канале. Ротация через `rotateChannelKey()`.                                                            |
+| **group-secret**              | Симметричный ключ на разговор, которым оборачиваются пакеты channel-key при раздаче новым участникам. Ротация через `rotateGroupSecret()` (также ротирует channel-key).               |
+| **эпоха**                     | Монотонный счетчик у channel-key. Каждая ротация увеличивает его. SDK хранит историю, поэтому старые сообщения остаются читаемыми после ротации.                                  |
+| **формат обмена**               | Точный байтовый формат конверта шифротекста. Channel-шифр использует `"MOK1" \| epoch_BE32 \| iv12 \| ct+tag` (см. `src/crypto/channel-cipher.ts`).                                  |
+| **fanoutId**                  | Идентификатор, который сервер присваивает каждой копии исходящего (по копии на устройство получателя). SDK матчит свое эхо по нему, чтобы `bot.send()` резолвился в реальный `messageId`.          |
+| **clientMsgId**               | Стабильный идентификатор от отправителя, общий для всех веерных копий одной логической отправки. `bot.reply()` пробрасывает его, чтобы ответ попал на логическое сообщение, а не на копию конкретного устройства. |
+| **AAD**                       | Additional Authenticated Data: байты, передаваемые в AES-GCM, не шифруются, но должны совпасть при расшифровке. Морок использует строки вида `morok-channel-<convId>` для привязки шифротекста к контексту. |
+
+Дополнительное чтение: [Signal Protocol whitepaper](https://signal.org/docs/), [X3DH спецификация](https://signal.org/docs/specifications/x3dh/), [Double Ratchet спецификация](https://signal.org/docs/specifications/doubleratchet/).
+
+## Производительность и масштабирование
+
+Один процесс SDK обслуживает одного бота. Расход ресурсов на бота:
+
+| Метрика                         | Значение                                                                            |
+|---------------------------------|-------------------------------------------------------------------------------------|
+| RAM (резидентная)               | 80-150 МБ. Большая часть приходится на libsignal.                                 |
+| CPU                             | < 5% одного ядра в покое, всплески на X3DH handshake и AES-GCM при загрузках.       |
+| Пропускная способность          | Один процесс тянет сотни сообщений в секунду. Узкое место почти всегда в вашем обработчике или в сети. |
+| Рост `stateDir`                  | ~ 1 КБ на пару активных собеседник-устройство. Десятки МБ даже у бота с тысячами собеседников. |
+
+Один и тот же `stateDir` между процессами портит Signal-сессии, pid-lock не дает это сделать случайно. Чтобы запустить несколько ботов на одном хосте, выделите каждому свой процесс и свой `stateDir`. Память растет примерно линейно.
+
+Веерная рассылка исходящего сообщения по устройствам собеседника происходит на стороне сервера: один `bot.send()` производит один envelope у вас, сервер сам доставляет его на каждое устройство.
+
+Когда одному боту не хватает пропускной способности одного процесса, причина почти всегда в обработчике: запросы в БД, внешние API, обработка изображений. WebSocket и libsignal выдерживают значительно больше, чем типичный код обработчика.
+
+Вспомогательные классы `RateLimiter` и `BotSessions` из поставки живут в памяти и не пересекают границу процесса. Если один бот обслуживается несколькими процессами, напишите аналог поверх своего общего хранилища (например, Redis).
+
+## Переход с Telegram Bot API
+
+Если строили бота под Telegram, грубые эквиваленты:
+
+| Концепт                        | Telegram Bot API                            | Морок                                                                             |
+|--------------------------------|---------------------------------------------|------------------------------------------------------------------------------------|
+| Транспорт                      | HTTPS long-poll или webhook                 | Долгоживущий WebSocket (переподключение внутри SDK)                                  |
+| Формат токена                  | `<int>:<base64>`                             | `bot:<int>:<base64url>`                                                             |
+| Доставка серверу -> боту       | `getUpdates` long-poll или HTTP POST на URL | WS-фрейм -> `bot.on('message')`                                                    |
+| Идентичность                   | Один бот на токен, ключевого материала нет  | Signal identity-ключ + подписанный prekey + одноразовые prekey, генерация на клиенте |
+| Несколько устройств            | Не применимо: бот в одном экземпляре         | Из коробки: одно исходящее сообщение сервер сам доставляет на все устройства собеседника |
+| Беседы                         | Нативно (`message.chat.id`)                  | Та же форма (`bot.send({ conversation })`). Админ добавляет бота, SDK подтягивает channel-key |
+| Каналы                         | Нативно (broadcast)                          | Та же форма. Комментарии собираются в треды через `threadRootId`                   |
+| Шифрование                     | Plaintext на серверах Telegram               | E2E (Signal Protocol для личных сообщений, channel-key для бесед и каналов). Сервер хранит только шифротекст. |
+| Слэш-команды                   | Слэш-команды                                 | Через интерфейс редактирования бота либо `POST /developer/bots/:id/commands`             |
+| Кнопки (управление)            | Кнопки (управление)                          | Меню-дерево кнопок в боте (ПК и мобильный), задается `setMyControls`, нажатия в `bot.on('control')` |
+| Webhooks                       | Из коробки                                   | Не поддерживается                                                                  |
+| Inline-режим                   | Из коробки                                   | Не поддерживается                                                                  |
+| Платежи                        | Из коробки                                   | Не поддерживается                                                                  |
+| Создание sticker pack          | `createNewStickerSet` и т.п.                 | Не поддерживается                                                                  |
+| Лимит размера файла            | Зависит от тарифа (от 20 МБ до 2 ГБ)             | 5 ГБ на файл. Списывается с получателя (ЛС) или владельца беседы или канала |
+| Rate limits                    | ~ 30 сообщений/с глобально                   | Бот: 5 сообщений подряд в ЛС/беседе/комментариях (сброс сообщением не-бота). Посты в канал: 5, дальше не чаще одного в 30 секунд. Плюс общий лимит 300 сообщений в минуту на пользователя |
+| Модель согласия                | Пользователь начинает чат сообщением         | Пользователь нажимает **Запустить**, бот не может писать первым. Событие `bot.on('start')`. |
+| Смена идентичности             | Регенерация токена не меняет identity        | Смена identity-ключа вызывает TOFU-warning у собеседника                          |
+
+Если механически портируете бота из Telegram, основная часть кода обработки сообщений переезжает напрямую. Модель согласия та же, что в Telegram: пока пользователь не нажмет кнопку, бот не может ему писать. Переосмыслить нужно только шифрование вложений: SDK сам шифрует каждый файл отдельным AES-ключом, но клиентская проверка mime-типов на Node-бота не распространяется, поэтому `mime` от собеседника считайте подсказкой, а не гарантией.
+
+## Версионирование
+
+Пакет соблюдает [semver](https://semver.org/). Все, что экспортируется из `morok-bot-sdk` (класс `MorokBot`, `BotConfig`, `IncomingMessage`, нагрузки событий, типы вложений), это публичный API. Изменения формата обмена идут по правилам совместимости сервера Морока, описанным в [api.md](https://morok.me/api).
+
+## Лицензия
+
+Apache License 2.0. См. [LICENSE](./LICENSE).