Безопасность и миграция на 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
Пройдите по каждому пункту, который относится к вашему проекту:
- Используйте Node.js 22.12 или новее. Node 18 и 20 больше не получают исправлений безопасности.
- Если вы используете CLI или плагин компилятора, выполните
npm install --save-dev ts-morph commander picocolors(иopenapi-typescriptдля generate-client). - Если вы используете "Try it out" в продакшене, добавьте
proxyAuthorize. ИспользуйтеallowProxyInProduction: true, только если путь монтирования уже защищён чем-то другим. - Если вы вызываете прокси из своего клиента, отправляйте
Content-Type: application/json; всё остальное получает415. - Если "Try it out" обращается к другим origin напрямую или документация загружает внешние ресурсы, добавьте их через
cspConnectSrcили замените политику черезcontentSecurityPolicy. - Контрактным тестам, которым нужны пишущие эндпоинты, передайте
--allow-writes; базовому URL, который не localhost и не входит в серверы спецификации, нужен--no-restrict-to-servers. - Пользователи переиспользуемого workflow PR должны передать
docfy-versionиdocfy-ref. - Собственные glob-шаблоны контроллеров теперь совпадают точно:
*.ctrl.tsбольше не совпадает сusers.ctrl.tsx.
Как вы узнаете о проблемах
- При запуске: предупреждение в логах для каждой рискованной настройки и ошибка, когда прокси отключается в продакшене.
- В UI документации: баннер со списком проблем, только вне продакшена.
- В
nestjs-docfy doctor: находки[security]из статического анализа ваших вызовов setup(). - В ответах прокси: заголовок
X-Docfy-Proxy-Errorобъясняет, почему запрос отклонён.
Сообщить об уязвимости
Нашли проблему безопасности? Используйте приватную форму GitHub Report a vulnerability, а не публичный issue. Настройка по умолчанию, которая пропускает атакующего, считается уязвимостью.