Merge pull request #7 from xmatic-squad/codex/docs/readme-hero

Оформить README и добавить hero Bare
2026-08-24 13:19:48 +03:00
parent d80078b2df a5955030bb
commit 3a30cc63d3
2 changed files with 64 additions and 17 deletions
@@ -1,28 +1,75 @@
-# Bare
+<p align="center">
+  <img src="docs/identity/hero.png" alt="" width="100%">
+</p>

-Максимально простой веб-чат. Web-native PWA на ванильных технологиях: HTML, CSS, vanilla JS — и Go-сервер одним бинарём. Ноль npm-зависимостей, никакой сборки.
+<h1 align="center">bare</h1>

-Bare — маленький независимый инструмент, а не конкурент Discord, Slack или Telegram. Название буквальное: голый, без лишнего, ничего не спрятано за слоями абстракций.
+<p align="center">
+  сообщения шифруются в браузере · история остаётся на устройстве · сервер доставляет шифротекст
+</p>

-Сервер — реле, а не архив: он передаёт зашифрованные сообщения и забывает их. История живёт только на устройстве. E2EE по умолчанию — оператор видит только шифротекст. Забыл пароль — значит забыл: восстановления нет, потому что пароль — материал ключа.
+<p align="center">
+  <a href="https://bare.xmatic.team">открыть bare</a> ·
+  <a href="docs/philosophy.md">философия</a> ·
+  <a href="docs/threat-model.md">модель угроз</a>
+</p>

-## Документация
+## что это

- [Философия](docs/philosophy.md) — манифест
- [Архитектура](docs/architecture.md) — обзор системы
- [Модель угроз](docs/threat-model.md) — от чего защищаемся и от чего нет
- [Решения](docs/decisions/) — ADR по ключевым решениям
- [Криптография](docs/crypto.md), [протокол](docs/protocol.md), [хранение](docs/storage.md) — спецификации для кода
- [Интерфейс](docs/ui.md) и [айдентика](docs/identity/brief.md)
- [Деплой](docs/deploy.md) и [план реализации](docs/plan.md)
- [Открытые вопросы](docs/open-questions.md)
+Bare — маленький независимый E2EE-чат, а не платформа. Он умеет личные чаты и комнаты, работает как PWA, присылает уведомления и переносит локальную историю через зашифрованный файл `.bare`.

-## Статус
+Клиент — HTML, CSS и vanilla JS без npm и сборки. Сервер — Go + SQLite, статика встроена в один бинарь.

-Все шесть этапов `docs/plan.md` сделаны и работают на [bare.xmatic.team](https://bare.xmatic.team): аккаунты, чат 1:1, комнаты с ключом на комнату, TOFU и отпечатки, PWA и пуши, экспорт и импорт истории, лимиты и закалка.
+- **без аккаунтной обвязки** — только ник и пароль, без email, телефона и OAuth;
+- **локальная история** — сообщения после доставки живут в IndexedDB текущего устройства, а не в облачном архиве;
+- **сервер-реле** — сервер хранит метаданные и временную очередь недоставленных шифротекстов, удаляя сообщения после подтверждения устройства;
+- **криптография в браузере** — пароль не покидает клиент, личные чаты и комнаты шифруются через WebCrypto;
+- **простая поверхность аудита** — клиент состоит из читаемых ES-модулей без бандлера и скрытого шага сборки.

-Осталось ручное: прогон сценариев на iOS Safari (установленное на «Домой» приложение), Android Chrome, десктопных Firefox и Safari. Автоматика гоняла только Chrome. Чеклист — в `docs/plan.md`, этап 4.
+## внутри

-## Лицензия
+| слой | решение |
+|---|---|
+| клиент | HTML, CSS, vanilla JS, PWA, IndexedDB |
+| сервер | Go, SQLite, HTTPS, SSE |
+| ключи | ECDH P-256, PBKDF2, HKDF, AES-GCM |
+| доверие | TOFU и сверка отпечатков при смене ключа |
+| история | только на устройстве; ручной экспорт и импорт `.bare` |
+
+## запустить локально
+
+Нужен Go 1.27.
+
+```sh
+git clone https://github.com/xmatic-squad/bare.git
+cd bare
+go run ./cmd/bare serve
+```
+
+Откройте [http://127.0.0.1:8411](http://127.0.0.1:8411). Без переменных окружения Bare создаст `bare.db` в текущей папке, разрешит регистрацию и запустится без пушей.
+
+```sh
+go test ./...
+```
+
+Production-настройка, VAPID, nginx и systemd описаны в [руководстве по развёртыванию](docs/deploy.md).
+
+## честные ограничения
+
+- Забыл пароль — значит забыл: восстановления нет, потому что пароль участвует в выводе ключей.
+- История в IndexedDB не зашифрована at rest и доступна коду, работающему на устройстве.
+- E2EE не скрывает метаданные, не защищает скомпрометированное устройство и не спасает от оператора, который подменил веб-клиент.
+- Forward secrecy в v1 нет. На iOS пуши работают только у PWA, установленного на экран «Домой».
+
+Полная граница обещаний и допущений — в [модели угроз](docs/threat-model.md).
+
+## документация
+
+- [Философия](docs/philosophy.md), [архитектура](docs/architecture.md), [модель угроз](docs/threat-model.md)
+- [Криптография](docs/crypto.md), [HTTP-протокол](docs/protocol.md), [хранение](docs/storage.md)
+- [Интерфейс](docs/ui.md), [айдентика](docs/identity/brief.md), [архитектурные решения](docs/decisions/)
+- [Деплой](docs/deploy.md), [план v1](docs/plan.md), [открытые вопросы](docs/open-questions.md)
+
+## лицензия

 [MIT](LICENSE)