research: анализ auth-flow Nubes из HAR, реальные claim-имена

research/README.md

@@ -0,0 +1,5 @@
+# research/
+
+Материалы обратного инжиниринга платформы Nubes — анализ трафика, HAR, токены, схемы взаимодействия.
+
+В отличие от `docs/` (проектная документация), здесь — результаты исследования внешних систем, которые мы не контролируем.

research/auth-flow.md

@@ -0,0 +1,82 @@
+# Результаты анализа HAR — nubes_login.har
+
+> **Дата:** 2026-05-30  
+> **Источник:** `nubes_login.har` — запись входа в платформу Nubes  
+> **Пользователь:** tazet@narod.ru (Наиль Тазетдинов)
+
+---
+
+## Схема авторизации
+
+```
+Браузер → lk-api-gateway.ngcloud.ru/api/v1/iam/auth/login
+       → keycloak.nubes.ru/realms/cloud/login-actions/authenticate
+       → auth-api (выпускает JWT)
+```
+
+Платформа использует **собственный auth-api** как надстройку над Keycloak. Токен подписан `auth-api`, не Keycloak.
+
+---
+
+## Реальные claim-имена в JWT
+
+```json
+{
+  "iss": "auth-api",
+  "sub": "0199e325-1cdf-7cda-9319-e5302a85e291",
+  "ClientID": "WZ01325",
+  "company_id": "3e64aac6-dcfc-4082-88dc-da19c86555a5",
+  "company_name": "Тест",
+  "email": "tazet@narod.ru",
+  "login": "tazet@narod.ru",
+  "firstname": "Наиль",
+  "middlename": "Фарисович Тестовая учетка",
+  "lastname": "Тазетдинов",
+  "token_type": "access",
+  "realm_access": { "roles": null },
+  "resource_access": { "account": { "roles": null } },
+  "groups": null
+}
+```
+
+---
+
+## Выводы для IP WhiteList
+
+### ✅ Точно известно
+
+| Что | Значение |
+|---|---|
+| claim для clientId | `ClientID` (строка, например "WZ01325") |
+| claim для email | `email` |
+| claim для company_id | `company_id` (UUID-строка) |
+| claim для company_name | `company_name` |
+| Проверка подписи | JWKS от `auth-api`, НЕ `keycloak.nubes.ru` |
+| Multi-company | В этом токене — одна компания (строка, не массив) |
+
+### ❓ Ещё не известно
+
+| Вопрос | Почему важно |
+|---|---|
+| Admin-признак | `roles=null`, `groups=null` — нужен пример токена админа |
+| JWKS URL auth-api | Где брать публичный ключ для проверки подписи? |
+| Multi-company формат | Будет ли `ClientID` массивом для пользователей с несколькими компаниями? |
+| Как токен доставляется до сервиса | `Authorization: Bearer`? Или через ingress-заголовки? |
+
+### Как это использовать сейчас
+
+В `server.js` middleware уже близок к правильному:
+
+```js
+// Текущий код (почти правильный):
+req.user = {
+  email: payload.email,
+  clientId: payload.ClientID,        // ← подтверждено HAR
+  companyName: payload.company_name, // ← подтверждено HAR
+};
+```
+
+Нужно поправить:
+- `payload.company_id` → сохранять отдельно (UUID, пригодится)
+- Добавить `TODO` про admin-роль
+- Добавить `TODO` про JWKS проверку (сейчас base64 без подписи)