diff --git a/10-systems/applications/gnexus-bookmarks.md b/10-systems/applications/gnexus-bookmarks.md new file mode 100644 index 0000000..5a8f9b9 --- /dev/null +++ b/10-systems/applications/gnexus-bookmarks.md @@ -0,0 +1,129 @@ +--- +owner: gmikcon +status: draft +last_reviewed: 2026-10-11 +review_interval: 90d +confidence: medium +source_of_truth: planning +--- + +# Gnexus Bookmarks (проект, не задеплоен) + +Самодостаточный self-hosted сервис синхронизации закладок для экосистемы Gnexus — замена связки Floccus + Nextcloud Bookmarks. Проект оформлен 2026-10-11, к реализации приступаем позже (по явной команде владельца). + +## Purpose + +Зачем: Floccus привязан к Nextcloud Bookmarks (или сторонним облакам), E2E-шифрование доступно только на WebDAV/Google Drive, мобильная поддержка ограничена (Kiwi/Fennec-квирки), а Nextcloud VM на bserv — главный кандидат на OOM-килл гипервизора (standing risk, см. `10-systems/hosts/nextcloud.md`). Нужен лёгкий независимый сервис в стиле Gnexus: свой API, свой MCP, свой UI, своя авторизация. + +Что это даёт: +- Полный контроль над данными закладок без зависимости от Nextcloud. +- E2E-шифрование как первоклассная фича (не опция отдельного метода синка). +- MCP-интерфейс для Navi-агентов (поиск, добавление, аудит закладок). +- Единый UX в дизайне gnexus-ui-kit и единая авторизация gnexus-auth. + +## Ownership + +- Owner: gmikcon +- Criticality: low (комфорт-сервис, не критичная инфраструктура) +- Environment: планирование (не задеплоен) +- Status: draft / future work + +## Проблемы Floccus, которые решаем (факты, floccus.org/faq + GitHub, 2026-10) + +- E2E-шифрование: только методы WebDAV и Google Drive; Nextcloud Bookmarks и Git — без E2E. +- Safari не поддержан (issue #23); Android — open beta app, расширения на мобилках только в Kiwi; Firefox Android не имеет bookmarks API. +- Firefox: нативные теги не поддержаны (нет API от Mozilla). +- Ограничения URL-схем: Nextcloud Bookmarks — только http(s)/javascript; chrome:// только через WebDAV/GDrive. +- Боли синхронизации: lock-зависания («Scheduled» без действий, снятие через 2 часа), ошибки «Failed to map parentId», E034/E035 (битый файл после выключения питания), failsafe против массовых удалений с ручным разбором. +- Зависимость от внешнего бэкенда (Nextcloud/облако) и его API-квирков. + +## Требования + +### Функциональные (MVP) +- CRUD закладок: URL, title, описание, теги, папки (иерархия), favicon. +- Синхронизация между браузерами: merge-стратегия, инкрементальные изменения, разрешение конфликтов без ручного разбора (в отличие от Floccus failsafe). +- Поиск: полнотекстовый по URL/title/описанию/тегам. +- Импорт/экспорт: HTML bookmarks file (стандарт Netscape), JSON. +- Миграция с Floccus: импорт текущего набора из Nextcloud Bookmarks. + +### Клиенты +- Браузерные расширения: Chrome, Firefox, Edge (WebExtensions API; Chromium-сборка покрывает Opera/Brave/Vivaldi). +- PWA: полноценный веб-клиент (установка на домашний экран, офлайн-кэш чтения). +- Мобильная стратегия: PWA как основной мобильный клиент (обход ограничений Kiwi/Fennec). + +### Безопасность (расширенные фичи) +- E2E-шифрование контента закладок: ключ выводится из пароля на клиенте (WebCrypto PBKDF2/Argon2id → AES-GCM), сервер хранит только шифротекст; опция per-profile. +- Токены устройств: отдельные revocable токены для каждого браузера/устройства (паттерн Floccus app-токенов, но с UI управления и last_used_at). +- Аудит всех операций (кто/что/когда), особенно через MCP. +- Rate-limit на API и MCP. +- 2FA/passkeys — наследуется от gnexus-auth (см. проект Gnexus Auth: passkeys как PWA-часть). + +## Архитектура + +### Компоненты +- Backend API: REST + WebSocket/SSE для push-событий синхронизации. Стек — по решению на этапе спеки (кандидаты: Python/FastAPI или PHP/Laravel — консистентно с gnexus-auth-client-py/php). +- БД: SQLite или PostgreSQL (решить на спеке; объёмы персонального сервиса малы). +- MCP-сервер: встроен в сервис (паттерн gnexus-creds), streamable HTTP `/mcp-protocol/` (слэш значим), Bearer токены сервиса, scopes `mcp/read/write`, страница «Токены» в UI, аудит `channel=mcp`. +- Browser extension: WebExtensions, синк-движок с локальной очередью изменений и офлайн-устойчивостью (анти-паттерны Floccus: без серверных lock-файлов, без битых файлов — инкрементальный журнал изменений на сервере). +- PWA: gnexus-ui-kit (Vue), брутализм/тёмная тема/JetBrains Mono, SPA-гейт авторизации. + +### Sync-модель (ключевое отличие от Floccus) +- Событийная модель: каждый клиент пишет изменения (create/update/move/delete) в журнал на сервере; сервер раздаёт дельты по cursor'у. Нет «файла закладок целиком» — нет E034/E035. +- Конфликты: серверная детерминированная резолюция (last-write-wins по полям + tombstone для удалений), опциональный журнал для отката. +- Failsafe-аналог: мягкий лимит массовых удалений с подтверждением в UI, но без блокировки синка. + +### Авторизация (по конвенции handbook 10-platform/auth.md) +- SSO через gnexus-auth: OAuth 2.0 PKCE, redirect_uri `<сервис>/auth/callback`, клиентская либа gnexus-auth-client-py/php. +- SPA-гейт: splash → `GET /me` → denied/ready; cookie-сессия ~7 суток; webhookи `profile.update` и `global_logout` с HMAC-подписью. +- Матрица доступа: браузер — cookie-сессия; расширения и MCP — Bearer токены сервиса; allowlist email опционально. +- Секреты клиента OAuth — в `.env` сервиса и gnexus-creds, не в git. + +### UI (по конвенции handbook 10-platform/ui.md) +- gnexus-ui-kit как зависимость, Vue-адаптер; GnPageHeader, drawer-навигация, GnModal/GnConfirmDialog, useToast. +- i18n: язык по умолчанию из `profile.locale` gnexus-auth. + +### Интеграции экосистемы +- gnexus-auth: SSO + webhookи (обязательно). +- gnexus-creds: хранение секретов (OAuth client secret, ключи шифрования серверных снапшотов). +- Gnexus Synapse: уведомления о событиях (ошибки синка устройств, массовые удаления, новые устройства). +- hard-panel: health-чек после деплоя. +- GitBucket: репозиторий кода. + +## Deployment (черновик, решается на спеке) + +- Кандидаты: отдельная лёгкая VM на bserv (вне Nextcloud VM — изоляция от OOM-риска) или контейнер на существующем хосте. Бюджет-first: минимальные ресурсы. +- Публичный URL: `bookmarks.gnexus.space` (кандидат; TLS на internal-proxy-vps, паттерн прочих сервисов). +- Бэкапы: дамп БД + снапшоты по расписанию (политика 20-deployment handbook). + +## Фазы (бэклог в gntodo, проект «Gnexus Bookmarks») + +1. Спека: финализировать стек, схему БД, протокол синка, протокол E2E-шифрования. +2. MVP backend: CRUD + поиск + auth SSO + журнал изменений. +3. Browser extension (Chromium + Firefox): синк-движок, токены устройств. +4. PWA-клиент: ui-kit, поиск, управление, офлайн-чтение. +5. MCP-сервер: streamable HTTP, токены, scopes, аудит. +6. Расширенная безопасность: E2E-шифрование, rate-limit, аудит-дашборд. +7. Миграция: импорт из Nextcloud Bookmarks, отключение Floccus-профилей, вывод bookmarks-приложения из Nextcloud (по решению владельца). + +## Known Risks + +- Имя «Gnexus Bookmarks» визуально конфликтует с «Gnexus Book» (knowledge base) — финальное название решить на спеке. +- E2E-шифрование усложняет серверный поиск и MCP-чтение контента: искать компромисс (поиск по метаданным на сервере + локальный полнотекстовый индекс на клиенте) — ключевое решение спеки. +- Мобильные расширения ограничены платформами (Kiwi/Fennec) — PWA обязателен, не опционален. +- Синк-протокол — самая рискованная часть (история багов Floccus: parentId, lock, битые файлы) — прототипировать отдельно до UI. +- Проект не начат: все статусы в gntodo — «не начато», в активную работу не брать без явной команды владельца. + +## Related Records + +- Inventory: (создать при деплое: services.yml, endpoints.yml, projects.yml) +- Endpoints: (планируется bookmarks.gnexus.space) +- Integrations: gnexus-auth, gnexus-creds, gnexus-synapse, hard-panel, gitbucket +- Projects: gntodo проект «Gnexus Bookmarks» +- Runbooks: (создать при деплое) + +## Sources + +- floccus.org/faq (браузеры, E2E, lock, failsafe, parentId, URL-схемы) — 2026-10-11. +- github.com/floccusaddon/floccus README (7 методов синка, Safari issue #23, Android beta) — 2026-10-11. +- gnexus-handbook: 00-principles.md, 10-platform/auth.md, 10-platform/mcp.md, 10-platform/ui.md — 2026-10-11. +- gnexus-book: 10-systems/hosts/nextcloud.md (OOM standing risk, bookmarks app), 10-systems/services/gnexus-auth.md. diff --git a/90-maintenance/pending-changes/20261011192622-4c991971.json b/90-maintenance/pending-changes/20261011192622-4c991971.json new file mode 100644 index 0000000..d82f5c1 --- /dev/null +++ b/90-maintenance/pending-changes/20261011192622-4c991971.json @@ -0,0 +1,19 @@ +{ + "id": "20261011192622-4c991971", + "kind": "doc", + "target": "10-systems/applications/gnexus-bookmarks.md", + "summary": "Добавлен дизайн-док проекта Gnexus Bookmarks: замена Floccus/Nextcloud Bookmarks, self-hosted, SSO gnexus-auth, MCP, E2E-шифрование, расширения, PWA, фазы и риски", + "reason": "Новый проект владельца: самодостаточный сервис закладок взамен Floccus/Nextcloud Bookmarks, интегрированный в gnexus (SSO, MCP, ui-kit, PWA, расширения). Оформление до старта реализации.", + "payload": { + "content": "---\nowner: gmikcon\nstatus: draft\nlast_reviewed: 2026-10-11\nreview_interval: 90d\nconfidence: medium\nsource_of_truth: planning\n---\n\n# Gnexus Bookmarks (проект, не задеплоен)\n\nСамодостаточный self-hosted сервис синхронизации закладок для экосистемы Gnexus — замена связки Floccus + Nextcloud Bookmarks. Проект оформлен 2026-10-11, к реализации приступаем позже (по явной команде владельца).\n\n## Purpose\n\nЗачем: Floccus привязан к Nextcloud Bookmarks (или сторонним облакам), E2E-шифрование доступно только на WebDAV/Google Drive, мобильная поддержка ограничена (Kiwi/Fennec-квирки), а Nextcloud VM на bserv — главный кандидат на OOM-килл гипервизора (standing risk, см. `10-systems/hosts/nextcloud.md`). Нужен лёгкий независимый сервис в стиле Gnexus: свой API, свой MCP, свой UI, своя авторизация.\n\nЧто это даёт:\n- Полный контроль над данными закладок без зависимости от Nextcloud.\n- E2E-шифрование как первоклассная фича (не опция отдельного метода синка).\n- MCP-интерфейс для Navi-агентов (поиск, добавление, аудит закладок).\n- Единый UX в дизайне gnexus-ui-kit и единая авторизация gnexus-auth.\n\n## Ownership\n\n- Owner: gmikcon\n- Criticality: low (комфорт-сервис, не критичная инфраструктура)\n- Environment: планирование (не задеплоен)\n- Status: draft / future work\n\n## Проблемы Floccus, которые решаем (факты, floccus.org/faq + GitHub, 2026-10)\n\n- E2E-шифрование: только методы WebDAV и Google Drive; Nextcloud Bookmarks и Git — без E2E.\n- Safari не поддержан (issue #23); Android — open beta app, расширения на мобилках только в Kiwi; Firefox Android не имеет bookmarks API.\n- Firefox: нативные теги не поддержаны (нет API от Mozilla).\n- Ограничения URL-схем: Nextcloud Bookmarks — только http(s)/javascript; chrome:// только через WebDAV/GDrive.\n- Боли синхронизации: lock-зависания («Scheduled» без действий, снятие через 2 часа), ошибки «Failed to map parentId», E034/E035 (битый файл после выключения питания), failsafe против массовых удалений с ручным разбором.\n- Зависимость от внешнего бэкенда (Nextcloud/облако) и его API-квирков.\n\n## Требования\n\n### Функциональные (MVP)\n- CRUD закладок: URL, title, описание, теги, папки (иерархия), favicon.\n- Синхронизация между браузерами: merge-стратегия, инкрементальные изменения, разрешение конфликтов без ручного разбора (в отличие от Floccus failsafe).\n- Поиск: полнотекстовый по URL/title/описанию/тегам.\n- Импорт/экспорт: HTML bookmarks file (стандарт Netscape), JSON.\n- Миграция с Floccus: импорт текущего набора из Nextcloud Bookmarks.\n\n### Клиенты\n- Браузерные расширения: Chrome, Firefox, Edge (WebExtensions API; Chromium-сборка покрывает Opera/Brave/Vivaldi).\n- PWA: полноценный веб-клиент (установка на домашний экран, офлайн-кэш чтения).\n- Мобильная стратегия: PWA как основной мобильный клиент (обход ограничений Kiwi/Fennec).\n\n### Безопасность (расширенные фичи)\n- E2E-шифрование контента закладок: ключ выводится из пароля на клиенте (WebCrypto PBKDF2/Argon2id → AES-GCM), сервер хранит только шифротекст; опция per-profile.\n- Токены устройств: отдельные revocable токены для каждого браузера/устройства (паттерн Floccus app-токенов, но с UI управления и last_used_at).\n- Аудит всех операций (кто/что/когда), особенно через MCP.\n- Rate-limit на API и MCP.\n- 2FA/passkeys — наследуется от gnexus-auth (см. проект Gnexus Auth: passkeys как PWA-часть).\n\n## Архитектура\n\n### Компоненты\n- Backend API: REST + WebSocket/SSE для push-событий синхронизации. Стек — по решению на этапе спеки (кандидаты: Python/FastAPI или PHP/Laravel — консистентно с gnexus-auth-client-py/php).\n- БД: SQLite или PostgreSQL (решить на спеке; объёмы персонального сервиса малы).\n- MCP-сервер: встроен в сервис (паттерн gnexus-creds), streamable HTTP `/mcp-protocol/` (слэш значим), Bearer токены сервиса, scopes `mcp/read/write`, страница «Токены» в UI, аудит `channel=mcp`.\n- Browser extension: WebExtensions, синк-движок с локальной очередью изменений и офлайн-устойчивостью (анти-паттерны Floccus: без серверных lock-файлов, без битых файлов — инкрементальный журнал изменений на сервере).\n- PWA: gnexus-ui-kit (Vue), брутализм/тёмная тема/JetBrains Mono, SPA-гейт авторизации.\n\n### Sync-модель (ключевое отличие от Floccus)\n- Событийная модель: каждый клиент пишет изменения (create/update/move/delete) в журнал на сервере; сервер раздаёт дельты по cursor'у. Нет «файла закладок целиком» — нет E034/E035.\n- Конфликты: серверная детерминированная резолюция (last-write-wins по полям + tombstone для удалений), опциональный журнал для отката.\n- Failsafe-аналог: мягкий лимит массовых удалений с подтверждением в UI, но без блокировки синка.\n\n### Авторизация (по конвенции handbook 10-platform/auth.md)\n- SSO через gnexus-auth: OAuth 2.0 PKCE, redirect_uri `<сервис>/auth/callback`, клиентская либа gnexus-auth-client-py/php.\n- SPA-гейт: splash → `GET /me` → denied/ready; cookie-сессия ~7 суток; webhookи `profile.update` и `global_logout` с HMAC-подписью.\n- Матрица доступа: браузер — cookie-сессия; расширения и MCP — Bearer токены сервиса; allowlist email опционально.\n- Секреты клиента OAuth — в `.env` сервиса и gnexus-creds, не в git.\n\n### UI (по конвенции handbook 10-platform/ui.md)\n- gnexus-ui-kit как зависимость, Vue-адаптер; GnPageHeader, drawer-навигация, GnModal/GnConfirmDialog, useToast.\n- i18n: язык по умолчанию из `profile.locale` gnexus-auth.\n\n### Интеграции экосистемы\n- gnexus-auth: SSO + webhookи (обязательно).\n- gnexus-creds: хранение секретов (OAuth client secret, ключи шифрования серверных снапшотов).\n- Gnexus Synapse: уведомления о событиях (ошибки синка устройств, массовые удаления, новые устройства).\n- hard-panel: health-чек после деплоя.\n- GitBucket: репозиторий кода.\n\n## Deployment (черновик, решается на спеке)\n\n- Кандидаты: отдельная лёгкая VM на bserv (вне Nextcloud VM — изоляция от OOM-риска) или контейнер на существующем хосте. Бюджет-first: минимальные ресурсы.\n- Публичный URL: `bookmarks.gnexus.space` (кандидат; TLS на internal-proxy-vps, паттерн прочих сервисов).\n- Бэкапы: дамп БД + снапшоты по расписанию (политика 20-deployment handbook).\n\n## Фазы (бэклог в gntodo, проект «Gnexus Bookmarks»)\n\n1. Спека: финализировать стек, схему БД, протокол синка, протокол E2E-шифрования.\n2. MVP backend: CRUD + поиск + auth SSO + журнал изменений.\n3. Browser extension (Chromium + Firefox): синк-движок, токены устройств.\n4. PWA-клиент: ui-kit, поиск, управление, офлайн-чтение.\n5. MCP-сервер: streamable HTTP, токены, scopes, аудит.\n6. Расширенная безопасность: E2E-шифрование, rate-limit, аудит-дашборд.\n7. Миграция: импорт из Nextcloud Bookmarks, отключение Floccus-профилей, вывод bookmarks-приложения из Nextcloud (по решению владельца).\n\n## Known Risks\n\n- Имя «Gnexus Bookmarks» визуально конфликтует с «Gnexus Book» (knowledge base) — финальное название решить на спеке.\n- E2E-шифрование усложняет серверный поиск и MCP-чтение контента: искать компромисс (поиск по метаданным на сервере + локальный полнотекстовый индекс на клиенте) — ключевое решение спеки.\n- Мобильные расширения ограничены платформами (Kiwi/Fennec) — PWA обязателен, не опционален.\n- Синк-протокол — самая рискованная часть (история багов Floccus: parentId, lock, битые файлы) — прототипировать отдельно до UI.\n- Проект не начат: все статусы в gntodo — «не начато», в активную работу не брать без явной команды владельца.\n\n## Related Records\n\n- Inventory: (создать при деплое: services.yml, endpoints.yml, projects.yml)\n- Endpoints: (планируется bookmarks.gnexus.space)\n- Integrations: gnexus-auth, gnexus-creds, gnexus-synapse, hard-panel, gitbucket\n- Projects: gntodo проект «Gnexus Bookmarks»\n- Runbooks: (создать при деплое)\n\n## Sources\n\n- floccus.org/faq (браузеры, E2E, lock, failsafe, parentId, URL-схемы) — 2026-10-11.\n- github.com/floccusaddon/floccus README (7 методов синка, Safari issue #23, Android beta) — 2026-10-11.\n- gnexus-handbook: 00-principles.md, 10-platform/auth.md, 10-platform/mcp.md, 10-platform/ui.md — 2026-10-11.\n- gnexus-book: 10-systems/hosts/nextcloud.md (OOM standing risk, bookmarks app), 10-systems/services/gnexus-auth.md." + }, + "status": "applied", + "created_at": "2026-10-11T19:26:22Z", + "updated_at": "2026-10-11T19:26:23Z", + "applied_at": "2026-10-11T19:26:23Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}