nestjs-docfy 0.19 — релиз безопасности с несовместимыми изменениями. Читать руководство по миграции →

Безопасность и миграция на 0.19

nestjs-docfy 0.19 по умолчанию закрывает всю поверхность атаки. На этой странице перечислены все настройки по умолчанию, опции, которые их ослабляют, и что изменить при обновлении.

В 0.19 есть несовместимые изменения
Они нужны, чтобы библиотека не стала входной точкой в ваше приложение. Большинству проектов хватит одного-двух шагов ниже.

Безопасно по умолчанию

Всё, что ослабляет настройку по умолчанию, называется явной опцией и поэтому видно на code review:

  • Инструменты сборки (ts-morph, commander, picocolors, openapi-typescript) больше не устанавливаются в продакшен: это опциональные peer-зависимости, которые ставятся как dev-зависимости.
  • При NODE_ENV=production прокси "Try it out" отключён, если вы не задали proxyAuthorize (или allowProxyInProduction).
  • Прокси принимает только Content-Type: application/json, никогда не передаёт Host и Set-Cookie и обращается только к серверам из спецификации.
  • UI документации отдаётся со строгой Content-Security-Policy (script-src 'self'), nosniff и встраиванием только с того же origin. Отключается через securityHeaders: false.
  • Контрактные тесты отправляют только GET, HEAD и OPTIONS, если не передать --allow-writes.
  • Переиспользуемый workflow проверки PR требует docfy-version и docfy-ref, поэтому никогда не запускает код без зафиксированной версии.

Guards Nest и маршруты документации

DocfyUiModule.setup() регистрирует маршруты напрямую в HTTP-адаптере, поэтому guards Nest для них никогда не выполняются. Защищайте документацию middleware, зарегистрированным до setup(), а прокси — через proxyAuthorize:

ts
// Registered before setup(): only allowed callers reach the docs UI
app.use('/docs', (req, res, next) => (isAllowedToSeeDocs(req) ? next() : res.status(404).end()));

DocfyUiModule.setup('/docs', app, {
  openApiDocument: document,
  // Runs for every "Try it out" proxy request; docfy-ui calls it same-origin, so cookies are sent
  proxyAuthorize: async (req) => (await currentUser(req))?.roles.includes('developer') ?? false,
});

Миграция на 0.19

Пройдите по каждому пункту, который относится к вашему проекту:

  1. Используйте Node.js 22.12 или новее. Node 18 и 20 больше не получают исправлений безопасности.
  2. Если вы используете CLI или плагин компилятора, выполните npm install --save-dev ts-morph commander picocolors (и openapi-typescript для generate-client).
  3. Если вы используете "Try it out" в продакшене, добавьте proxyAuthorize. Используйте allowProxyInProduction: true, только если путь монтирования уже защищён чем-то другим.
  4. Если вы вызываете прокси из своего клиента, отправляйте Content-Type: application/json; всё остальное получает 415.
  5. Если "Try it out" обращается к другим origin напрямую или документация загружает внешние ресурсы, добавьте их через cspConnectSrc или замените политику через contentSecurityPolicy.
  6. Контрактным тестам, которым нужны пишущие эндпоинты, передайте --allow-writes; базовому URL, который не localhost и не входит в серверы спецификации, нужен --no-restrict-to-servers.
  7. Пользователи переиспользуемого workflow PR должны передать docfy-version и docfy-ref.
  8. Собственные glob-шаблоны контроллеров теперь совпадают точно: *.ctrl.ts больше не совпадает с users.ctrl.tsx.

Как вы узнаете о проблемах

  • При запуске: предупреждение в логах для каждой рискованной настройки и ошибка, когда прокси отключается в продакшене.
  • В UI документации: баннер со списком проблем, только вне продакшена.
  • В nestjs-docfy doctor: находки [security] из статического анализа ваших вызовов setup().
  • В ответах прокси: заголовок X-Docfy-Proxy-Error объясняет, почему запрос отклонён.

Сообщить об уязвимости

Нашли проблему безопасности? Используйте приватную форму GitHub Report a vulnerability, а не публичный issue. Настройка по умолчанию, которая пропускает атакующего, считается уязвимостью.