Docs Access System

1. Summary

Goal: Полностью приватная документация. Доступ только через логин в админ-панели (с 2FA).

Как работает: Traefik ForwardAuth проверяет docs_session cookie перед каждым запросом к docs.goloot.online. Без cookie — пустая белая страница (403). С cookie — полный доступ ко всему контенту.

User Value: Никто кроме админа не имеет доступа к документации. Вся информация приватна.

---

2. Business Logic

Access Model

Состояние	Что видит пользователь
Не залогинен в админке	Пустая белая страница (HTTP 403)
Залогинен в админке (2FA)	Весь контент: Knowledge Base + API Reference

Единственный способ получить доступ — логин в админ-панели (admin.goloot.online), который уже защищён 2FA (TOTP). После логина устанавливается docs_session cookie на домен .goloot.online, который даёт доступ к docs.

Как включить/выключить доступ

Доступ контролируется через Traefik конфиг в Dokploy (не через код):

Действие	Что сделать
Закрыть доступ	Добавить middleware docs-forward-auth в websecure роутер
Открыть доступ	Убрать middleware → middlewares: []

Подробный Traefik конфиг — в Services Deployment → Docs Site.

Неактивная функциональность (сохранена в коде)

В коде сохранена, но не подключена, функциональность многоуровневого доступа:

Функция	Компоненты	Статус
Viewer invite-ссылки	DocsVisibilityService, роуты /docs/invite	Backend работает, ForwardAuth игнорирует docs_viewer cookie
Owner 2FA на docs	TwoFactorModal, ActivationModal, useVisibility hook	Компоненты не подключены в Root.tsx
Visibility по страницам	docusaurus-plugin-visibility, frontmatter visibility: owner	useCanSee() всегда возвращает true

Как вернуть:

1. Viewer invite: в ForwardAuth добавить проверку docs_viewer cookie (~3 строки)
2. Owner 2FA: в Root.tsx вернуть <TwoFactorModal /> и <ActivationModal />
3. Visibility по страницам: в useCanSee() вернуть проверку уровней

Весь код — в git history, коммит feat(docs): make docs-site fully private.

---

3. ADR (Architectural Decisions)

Почему Traefik ForwardAuth?

Проблема: Документация на отдельном домене (docs.goloot.online), нужна проверка доступа.

Решение: Traefik вызывает /admin-auth/verify-docs перед каждым запросом.

Альтернативы (отклонены):

• Client-side проверка — легко обойти
• Nginx auth_request — менее гибко чем Traefik

Последствия: Каждый запрос к docs проходит через backend проверку.

---

4. Architecture

Authentication Flow

Key Components

Компонент	Путь	Описание
AdminAuthRoutes	backend/src/domains/admin/routes/admin-auth.routes.ts	ForwardAuth endpoint verify-docs
VisibilityContext	docs-site/src/contexts/VisibilityContext.tsx	React контекст (упрощён — всегда true)

---

5. Cookies & Storage

Cookie Configuration

Cookie	Имя	Domain	Max-Age	HttpOnly	Secure
Admin Session	docs_session	.goloot.online	8 часов	Yes	Yes

Cookie устанавливается при логине в админ-панель (admin.goloot.online). Работает на всех поддоменах .goloot.online благодаря SameSite=Lax.

---

6. API Endpoints

Метод	Эндпоинт	Описание	Auth
GET	/admin-auth/verify-docs	ForwardAuth endpoint	Cookie

Вызывается Traefik'ом автоматически перед каждым запросом к docs.goloot.online. Возвращает 200 (OK, есть docs_session) или 403 (пустое тело, нет cookie).

Traefik ForwardAuth Setup (Dokploy)

ForwardAuth настраивается в Dokploy → Docs Service → Advanced → Traefik. Это инфраструктурный конфиг reverse proxy, не код приложения.

Два обязательных условия:

1. Middleware docs-forward-auth определён с forwardAuth.address → URL verify-docs эндпоинта
2. Middleware подключён к websecure роутеру (НЕ пустой [])

# Dokploy → Docs Service → Advanced → Traefik
http:
  routers:
    goloot-docssite-XXXXX-router-websecure-N:
      rule: Host(`docs.goloot.online`)
      service: goloot-docssite-XXXXX-service-N
      middlewares:
        - docs-forward-auth              # ← ОБЯЗАТЕЛЬНО! Без этого — доступ без проверки
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
  middlewares:
    docs-forward-auth:
      forwardAuth:
        address: https://api.goloot.online/admin-auth/verify-docs

Частые ошибки

• middlewares: [] — middleware определён, но не подключён → Traefik пропускает всех без проверки
• Middleware определён, но не указан в секции middlewares роутера → то же самое
• address указывает на неправильный backend → 403 для всех

---

7. Security Considerations

Уровни защиты

Уровень	Механизм	Что защищает
Traefik ForwardAuth	Проверка docs_session cookie	Блокирует все запросы без admin сессии
Admin 2FA (TOTP)	Требуется при логине в админку	Защищает от компрометации пароля
Cookie flags	HttpOnly, Secure, SameSite=Lax	XSS, MITM, CSRF

Экстренный kill switch

Смена JWT_SECRET в Dokploy → Backend → Environment → Redeploy мгновенно инвалидирует все docs_session cookies и JWT-токены админки. После смены — просто перелогиниться.

---

8. Related

• Docs Deployment — CI/CD для docs site, visibility plugin
• User Management — управление пользователями в админке