From f8c19d712a719444772801a87f833169808d5913 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 23 Jun 2026 20:23:01 +0300 Subject: [PATCH] Document BIM session sync canon boundaries --- docs/AUTH_MODEL.md | 24 ++++++++++++++++++++++++ docs/CURRENT_INFRA_HANDOFF.md | 15 ++++++++++++++- docs/SECURITY_CHECKLIST.md | 9 +++++++++ packages/auth-sdk/README.md | 3 +++ 4 files changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/AUTH_MODEL.md b/docs/AUTH_MODEL.md index 34ac6bc..58bfbff 100644 --- a/docs/AUTH_MODEL.md +++ b/docs/AUTH_MODEL.md @@ -50,6 +50,30 @@ Production login должен быть NODE.DC-branded: Текущее безопасное решение зафиксировано в `docs/AUTH_BRANDED_LOGIN_RFC.md`: сначала используем Authentik-native Brand/CSS/Flow customization. Reverse proxy HTML-rewrite, password form в Launcher и пересылка пароля через BFF запрещены. +## Inter-app session sync status 2026-06-23 + +Источник истины по пользовательской сессии остаётся в Launcher/Auth/Authentik chain. Приложения не должны выдавать себе права из локального browser-event или marker-а; любые live-события session sync являются только сигналом для revalidation через платформенный authority. + +Фактический общий live-контур до BIM был logout-only: + +- Launcher `/auth/session-sync` публиковал `nodedc:session:logout` в соседние приложения через iframe/BroadcastChannel/localStorage/frontchannel; +- Engine helper `src/platform/auth/sessionSync.ts` знает только `nodedc:session:logout`; +- Tasker/OPS имеет отдельный frontchannel/internal logout контур, но login/change parity не оформлен как общий protocol; +- login live promotion открытого приложения после входа в другом surface не был закрытым platform-wide контрактом. + +BIM Viewer 23.06.2026 добавил BIM-first login-sync slice для share-link сценария: + +- Launcher service registry получил `loginSyncUrl` для BIM; +- после успешного login Launcher публикует `nodedc:session:login` и делает frontchannel вызов зарегистрированных login-sync endpoints; +- BIM `/auth/login-sync` создаёт короткоживущий server-side marker; +- BIM `/api/auth/session` возвращает `loginSyncEventId`, но сам marker не является auth-token; +- BIM frontend по новому marker-у запускает обычный optional-launch/handoff через Launcher, где происходит нормальная проверка сессии и доступа; +- BIM logout приведён к существующему logout canon и должен live-понижать controls до guest/limited view без ручного refresh. + +Граница текущей реализации: это кандидат на общий login-sync contract, а не закрытый канон для всей платформы. Перед подключением следующего сервиса нужно оформить `ndcauth.session` protocol: `login`, `logout`, `change`, payload, origin checks, TTL/nonce/correlation, service registry fields, revalidation rules, audit/observability и browser e2e matrix по HUB/OPS/ENGINE/BIM. + +Правило для новых сервисов: не добавлять частный per-app login/logout bus. Сервис регистрирует sync endpoints в Launcher/control-plane registry, принимает event только как invalidate/promote trigger и всегда перепроверяет доступ через backend authority. + ## Required claims Минимальный normalized user object: diff --git a/docs/CURRENT_INFRA_HANDOFF.md b/docs/CURRENT_INFRA_HANDOFF.md index 728f31f..44fb0c7 100644 --- a/docs/CURRENT_INFRA_HANDOFF.md +++ b/docs/CURRENT_INFRA_HANDOFF.md @@ -1,6 +1,6 @@ # NODE.DC current infra handoff -Last updated: 2026-05-15. +Last updated: 2026-06-23. This document is the fast context entrypoint for a new engineering chat. Read it first before touching deploy, Synology, Authentik, Launcher, or Tasker. @@ -16,6 +16,7 @@ Source-of-truth repositories: | Launcher / Hub | NODE.DC control plane, user/admin UI, access requests, access matrix, Authentik sync | `/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher` | | Tasker / Operational Core | Plane fork, tasks/workspaces/projects, standalone-capable product module | `/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER` | | Ops Agents Gateway | Standalone MCP/API router for Tasker operational agents | `/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI` | +| BIM Viewer | Standalone BIM/CAD/point-cloud viewer, public share links, model runtime storage | `/Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_BIM_VIEWER` | Current Git branches: @@ -23,6 +24,7 @@ Current Git branches: - Launcher: `main` - Tasker: `master` - Ops Agents Gateway: `main` +- BIM Viewer: `beam` The modules communicate through HTTP/OIDC/internal APIs. They must remain independently buildable and deployable. @@ -59,6 +61,7 @@ https://id.nodedc.ru -> Authentik https://hub.nodedc.ru -> Launcher / Hub https://ops.nodedc.ru -> Tasker / Operational Core https://ops-agents.nodedc.ru -> Ops Agents Gateway / MCP endpoint +https://bim.nodedc.tech -> BIM Viewer ``` `id.nodedc.ru` is only the public OIDC/login host. Authentik Admin is deliberately kept off that public host; `/if/admin/*` returns `404` there. @@ -244,6 +247,16 @@ Git repo -> build image / sync deploy files -> Synology compose recreate selecte Do not edit NAS copies as the long-term fix. If an emergency live edit is made on NAS, port it back into the relevant repo before continuing product work. +## Auth/session sync status + +Read `docs/AUTH_MODEL.md` before changing cross-app auth/session behavior. + +As of 2026-06-23, the proven shared live-session path was logout-first: Launcher publishes `nodedc:session:logout` through `/auth/session-sync` and frontchannel app logout URLs, and Engine subscribes to that logout event. BIM Viewer has now been aligned with that logout path. + +BIM also introduced a BIM-first login-sync slice for share links: Launcher service registry can call BIM `loginSyncUrl`; BIM records only a short-lived marker and then revalidates through Launcher optional-launch/handoff. This marker is not auth and must not grant controls directly. + +This is not yet a platform-wide login/change canon. Before adding another service, define the shared `ndcauth.session` contract in Platform/Auth SDK terms and verify HUB/OPS/ENGINE/BIM with a browser matrix: login from any surface, logout from any surface, already-open apps update without refresh. + ## Platform / Launcher deploy From macOS with `/Volumes/docker` mounted: diff --git a/docs/SECURITY_CHECKLIST.md b/docs/SECURITY_CHECKLIST.md index 787818d..6f1f2c1 100644 --- a/docs/SECURITY_CHECKLIST.md +++ b/docs/SECURITY_CHECKLIST.md @@ -34,6 +34,15 @@ Service catalog UX rules: `docs/SERVICE_CATALOG_UX_RULES.md`. - [x] Local runtime не отдает `storage/launcher-data.json` напрямую через public static route. - [x] Local runtime требует user session для `/api/storage/data`. +## Cross-app session sync + +- [x] Общий live logout path зафиксирован как `nodedc:session:logout` через Launcher session-sync/frontchannel. +- [x] BIM Viewer подключён к logout path и по logout должен понижать UI до guest/limited controls. +- [x] BIM login-sync marker не является auth-token и требует revalidation через Launcher. +- [ ] Описан общий `ndcauth.session` contract для login/logout/change, а не только BIM-first slice. +- [ ] HUB/OPS/ENGINE/BIM проходят browser matrix: login/logout из любого surface обновляет уже открытые приложения без refresh. +- [ ] Session sync события имеют audit/observability без user secrets в логах. + ## Plane - [ ] Перед изменениями сделан backup DB/env/uploads/storage. diff --git a/packages/auth-sdk/README.md b/packages/auth-sdk/README.md index 54bc8e0..0c1fbc9 100644 --- a/packages/auth-sdk/README.md +++ b/packages/auth-sdk/README.md @@ -10,6 +10,7 @@ - нормализация claims; - helper `requireAppAccess(groupName)`; - helper `getCurrentUser()`; +- typed `ndcauth.session` helpers для cross-app login/logout/change revalidation events; - typed `AuthUser`. ## Type contract @@ -29,3 +30,5 @@ export type AuthUser = { Первый SDK рассчитан на Launcher backend и будущие Node.js/Next.js сервисы. Для Plane fork на Python/Django нужна отдельная реализация middleware по тем же правилам, а этот пакет остается спецификацией для TypeScript приложений. + +Session sync на 23.06.2026 не считается закрытым SDK-контрактом. Общий logout path уже существует в платформе, а BIM Viewer добавил BIM-first login-sync marker/revalidation slice. Перед подключением следующего сервиса нужно оформить общий `ndcauth.session` protocol здесь или в соседнем platform package, чтобы приложения не копировали BIM-specific логику.