nestjs-docfy 0.19 to wydanie bezpieczeństwa z breaking changes. Przeczytaj przewodnik migracji →

Bezpieczeństwo i migracja do 0.19

nestjs-docfy 0.19 domyślnie blokuje każdą powierzchnię ataku. Ta strona wymienia każde ustawienie domyślne, opcję, która je łagodzi, i co zmienić przy aktualizacji.

0.19 zawiera breaking changes
Istnieją po to, żeby biblioteka nie stała się furtką do Twojej aplikacji. Większość projektów potrzebuje tylko jednego lub dwóch kroków poniżej.

Domyślnie bezpieczne

Wszystko, co osłabia ustawienie domyślne, ma jawną nazwę opcji, więc widać to w code review:

  • Narzędzia buildu (ts-morph, commander, picocolors, openapi-typescript) nie są już instalowane na produkcji: to opcjonalne peery, instalowane jako zależności deweloperskie.
  • Przy NODE_ENV=production proxy "Try it out" jest wyłączone, chyba że ustawisz proxyAuthorize (lub allowProxyInProduction).
  • Proxy przyjmuje tylko Content-Type: application/json, nigdy nie przekazuje Host ani Set-Cookie i łączy się tylko z serwerami ze specyfikacji.
  • UI dokumentacji jest serwowane ze ścisłą Content-Security-Policy (script-src 'self'), nosniff i osadzaniem tylko z tego samego originu. Wyłączysz to przez securityHeaders: false.
  • Testy kontraktowe wysyłają tylko GET, HEAD i OPTIONS, chyba że podasz --allow-writes.
  • Reużywalny workflow sprawdzania PR wymaga docfy-version i docfy-ref, więc nigdy nie uruchamia kodu bez przypiętej wersji.

Guardy Nest i trasy dokumentacji

DocfyUiModule.setup() rejestruje swoje trasy bezpośrednio w adapterze HTTP, więc guardy Nest nigdy dla nich nie działają. Chroń dokumentację middlewarem zarejestrowanym przed setup(), a proxy przez 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,
});

Migracja do 0.19

Przejdź przez każdy punkt, który dotyczy Twojego projektu:

  1. Używaj Node.js 22.12 lub nowszego. Node 18 i 20 nie dostają już poprawek bezpieczeństwa.
  2. Jeśli używasz CLI lub pluginu kompilatora, uruchom npm install --save-dev ts-morph commander picocolors (oraz openapi-typescript dla generate-client).
  3. Jeśli używasz "Try it out" na produkcji, dodaj proxyAuthorize. Używaj allowProxyInProduction: true tylko wtedy, gdy coś innego już chroni ścieżkę montowania.
  4. Jeśli wywołujesz proxy z własnego klienta, wysyłaj Content-Type: application/json; wszystko inne dostaje 415.
  5. Jeśli "Try it out" wywołuje inne originy bezpośrednio albo dokumentacja ładuje zdalne zasoby, dodaj je przez cspConnectSrc lub zastąp politykę przez contentSecurityPolicy.
  6. Testy kontraktowe, które potrzebują endpointów zapisu, przyjmują --allow-writes; bazowy URL, który nie jest localhostem i leży poza serwerami ze specyfikacji, wymaga --no-restrict-to-servers.
  7. Użytkownicy reużywalnego workflowu PR muszą przekazać docfy-version i docfy-ref.
  8. Własne globy kontrolerów pasują teraz dokładnie: *.ctrl.ts nie pasuje już do users.ctrl.tsx.

Jak zostaniesz ostrzeżony

  • Przy starcie: ostrzeżenie w logach dla każdej ryzykownej konfiguracji i błąd, gdy proxy zostaje wyłączone na produkcji.
  • W UI dokumentacji: baner z listą problemów, pokazywany tylko poza produkcją.
  • W nestjs-docfy doctor: wyniki [security] ze statycznej analizy Twoich wywołań setup().
  • W odpowiedziach proxy: nagłówek X-Docfy-Proxy-Error mówi, dlaczego żądanie zostało odrzucone.

Zgłaszanie podatności

Znalazłeś problem z bezpieczeństwem? Użyj prywatnego formularza Report a vulnerability na GitHubie, nie publicznego issue. Ustawienie domyślne, które wpuszcza atakującego, liczy się jako podatność.