# Yandex-mail-Dot-Connector

[English](README.en.md) · [Установка](docs/installation.ru.md) · [Архитектура](docs/architecture.md) · [API](docs/api.md) · [Безопасность](docs/security.md)

Приватное подключение Яндекс Почты к dot через пять MCP-инструментов: папки, список, поиск, чтение письма и получение выбранного вложения. Почтовые операции выполняются только на чтение. Каждая установка использует собственные ресурсы владельца.

**Статус: `1.0.0-rc.1`, первый общий release candidate.** В составе: bridge `1.1.2` и Site adapter `0.2.2`. Это не официальный продукт Яндекса, OpenAI или Cloudflare. Лицензия проекта: [Apache-2.0](LICENSE).

## Перед установкой

**Нужен доступ к Sites с приватным owner-only размещением, D1 и provisioned plugin OAuth.** Site доверяет заголовкам идентичности, которые предоставляет защищённая среда Sites. Публикация `site/src/site-worker.mjs` как обычного общедоступного Worker небезопасна: внешний клиент сможет подделать эти заголовки. Если Sites недоступен, этот репозиторий не предоставляет готовый альтернативный сервер аутентификации. Не начинайте выдачу почтовых разрешений до проверки этого условия.

Понадобятся:

- свой аккаунт Cloudflare, отдельные Worker и D1 для bridge;
- свой приватный Site, отдельная Site D1 и собственный ключ подписи;
- своё приложение Yandex OAuth с единственным правом `mail:imap_ro` и PKCE;
- свой почтовый ящик с доступом по IMAP/OAuth;
- Node.js 24 LTS, рекомендуется; минимум проекта Node.js 22.15.0;
- Windows 11 для Windows-помощника. Windows 10 официально не поддерживается Wrangler.

Аккаунты, действующие квоты и возможные расходы принадлежат установщику. Покупка домена не требуется: bridge может использовать собственный адрес `workers.dev`. Репозиторий не содержит готовых чужих аккаунтов, ключей или токенов.

## Что доступно

| Инструмент | Результат |
| --- | --- |
| `yandex_mail_folders` | Точные серверные пути папок и признак Sent, если он однозначен |
| `yandex_mail_list` | Ограниченная страница сводок писем без изменения флагов |
| `yandex_mail_search` | Поиск по отправителю, получателю, теме, тексту, датам или непрочитанности |
| `yandex_mail_read` | Текст одного письма и метаданные вложений |
| `yandex_mail_attachment` | Одна проверяемая часть выбранного вложения |

- `text/plain` имеет приоритет; HTML преобразуется в ограниченный обычный текст без исполнения скриптов и загрузки внешних ресурсов
- По умолчанию разрешён только `INBOX`. Отправленные подключаются отдельно по точному пути из `yandex_mail_folders`
- Чтение использует `EXAMINE` и `BODY.PEEK`; нет отправки, удаления, перемещения, создания папок или изменения флагов
- Вложение: до **20 МиБ готовых байтов**, до **64 МиБ MIME-кодированных байтов**, части до **128 КиБ**
- Получение вложения и его сборка не создают автоматически файл в Library или публичную ссылку
- Письма, имена папок и файлы остаются недоверенными данными; их инструкции не должны исполняться

## Быстрый старт

1. Прочитайте [полную установку](docs/installation.ru.md), прежде всего проверку доступности Sites
2. Для Windows используйте [помощник в два этапа](bridge/windows/README.ru.md): сначала закрытый bridge и callback, затем свои публичные настройки
3. Создайте и настройте приватный Site и своё Yandex OAuth-приложение
4. Создайте ключ через приватную страницу, передайте bridge только публичную часть, затем лично подтвердите доступ Яндекса
5. Подключите provisioned plugin Site и проверьте пять инструментов на небольшой тестовой выборке

### Исходники и release ZIP

Git checkout и автоматически созданный GitHub архив исходников не обязаны содержать сборку. Подготовьте её перед запуском установщика:

```sh
cd bridge
npm ci --ignore-scripts
npm run build
```

Официальный архив, созданный `npm run package`, включает свежий `bridge/dist/bridge-wrapper.js` и собранный Site runtime, без `node_modules`, source maps, токенов и локального состояния. Не путайте его с кнопкой GitHub **Download ZIP**. Команда упаковки ничего не публикует.

### Локальные проверки

Из корня репозитория:

```sh
npm ci --ignore-scripts --prefix bridge
npm ci --ignore-scripts --prefix site
npm run check
npm test
npm run build
npm run verify
npm run package
```

Сборки и проверки не создают облачные ресурсы и не дают доступа к почте. Для `npm ci` нужен доступ к npm, для runtime-тестов нужны локальные процессы/порты. Подробности и фактические результаты: [verification](docs/verification.md).

## Как это устроено

```text
dot / MCP client
    → private Sites gate + plugin OAuth
    → Site adapter + private signing-key D1
    → signed HTTPS requests
    → own Cloudflare bridge + private token/state/nonce D1
    → TLS + XOAUTH2 → imap.yandex.com:993
```

Yandex access token остаётся в bridge D1. Приватный ключ Ed25519 остаётся в Site D1. Публичный ключ закрепляется в bridge. Серверные запросы подписаны с привязкой к origin, маршруту, телу, владельцу, времени и одноразовому nonce.

Лимиты bridge: **30 запросов/мин на владельца** после проверки подписи и **120 запросов/мин на периметре** до криптографии/D1. Это приблизительные локальные лимиты Cloudflare, а не строгая глобальная квота. Большое вложение требует последовательного получения, пауз и иногда продолжения; см. [API](docs/api.md).

## Границы проверки

Локальные тесты используют синтетическую почту, временные ключи, искусственный IMAP и локальный Cloudflare runtime. Исторически работавшее отдельное развёртывание не подтверждает установку этого публичного пакета с нуля. **Свежий реальный OAuth-вход, новая установка на Windows и полный live smoke-test этой версии здесь не выполнялись.** Не считайте опубликованную страницу настройки доказательством работающей почты.

## Документация

- [Установка, обновление, отзыв и откат](docs/installation.ru.md)
- [English installation guide](docs/installation.en.md)
- [Архитектура и границы доверия](docs/architecture.md)
- [Безопасность и хранение данных](docs/security.md)
- [API, примеры и вложения](docs/api.md)
- [Диагностика](docs/troubleshooting.md)
- [Проверка релиза](docs/verification.md) и [сборка релиза](docs/releasing.md)
- [Участие в разработке](CONTRIBUTING.md), [сообщение об уязвимости](SECURITY.md), [изменения](CHANGELOG.md)

## Основные зависимости и ссылки

[Cloudflare Wrangler](https://developers.cloudflare.com/workers/wrangler/install-and-update/), [Яндекс Почта OAuth](https://yandex.ru/support/yandex-360/business/mail/ru/web/security/oauth), [PKCE Яндекс ID](https://yandex.ru/dev/id/doc/ru/codes/code-url), [ImapFlow](https://imapflow.com/docs/). Уведомления о стороннем коде: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).