Document DNS-rebind residual and prod-enablement egress hardening

The security docs claimed the in-browser SSRF filter (context.route/
routeWebSocket) re-applies "the same filtering" as the pre-fetch DNS
check. That's inaccurate for hostnames: the browser-level filter only
blocks literal private IPs and localhost/.local/.internal suffixes —
it never re-resolves hostnames, so a same-hostname DNS-rebind (public
IP on first resolve, private IP on a later request from inside
browserless) is not closed at that layer. Correct the wording in the
design spec and TECHNICAL.md, and add a prominent note to both the
spec's deploy section and the plan's deploy notes: before flipping
TOOLBOX_VISIBLE on prod, harden the browserless container's network
egress (block 169.254.0.0/16 and RFC1918 ranges via host firewall or
a dedicated internal docker network) to close the residual at the
network layer. Also note that per-user limits currently count only
successful generations — failed renders are uncapped, a bounded
self-DoS risk worth a follow-up.

.env.example

@@ -48,4 +48,6 @@ TOOLBOX_VISIBLE=""
 
 # Чистый PDF (browserless на staging/prod; локально — SSH-туннель на staging)
 BROWSER_WS_URL="ws://localhost:3333"
+# Секрет browserless (TOKEN в его env) — на прод/staging генерировать: openssl rand -hex 24
+BROWSERLESS_TOKEN=""
 PDF_MONTHLY_LIMIT="100"

TECHNICAL.md

@@ -171,6 +171,39 @@ CSS-классы: `.card-aubade`, `.btn-aubade`, `.btn-aubade-accent`, `.tag-aub
 |---|---|---|---|
 | `POST` | `/api/auth/[...all]` | Better Auth handler | Все |
 | `POST` | `/api/admin/upload` | Загрузка файла в S3, возвращает `{ url, key }` | admin |
+| `GET` | `/api/pdf` | Чистый PDF из URL (Bearer-ключ или сессия) — см. раздел ниже | платный студент, admin, curator |
+
+---
+
+## Чистый PDF (`/tools/clean-pdf`, `/api/pdf`)
+
+Инструмент Obsidian Toolbox: превращает произвольный URL в чистый PDF (без рекламы и меню, с типографикой, оглавлением, A4/Letter, light/dark). Полный дизайн-документ: [`docs/specs/20260706-clean-pdf-design.md`](docs/specs/20260706-clean-pdf-design.md).
+
+**Пайплайн генерации:**
+
+```
+URL студента
+  → browserless (Chromium по WebSocket, playwright-core) загружает страницу
+  → Next.js забирает итоговый HTML
+  → Defuddle (JSDOM) выделяет основной контент
+  → HTML-шаблон (типографика, A4/Letter, light/dark, оглавление)
+  → Playwright page.pdf() в том же browserless
+  → application/pdf в ответе
+```
+
+Доступ: любой платный студент (есть `CourseEnrollment` вне `FREE_COURSE_SLUG`), admin/curator — без ограничений. Видимость страницы гейтится флагом `TOOLBOX_VISIBLE`, но сам `/api/pdf` работает независимо от него (доступ проверяется отдельно). Ключ для внешнего API — модель `PdfApiKey` (`sbpdf_<random>`, ленивая генерация, регенерация инвалидирует старый).
+
+**Env-переменные:**
+
+| Переменная | Назначение |
+|---|---|
+| `BROWSER_WS_URL` | WebSocket-адрес browserless (`ws://browserless:3000` в compose, `ws://localhost:3333` при туннеле локально) |
+| `BROWSERLESS_TOKEN` | Секрет browserless (`TOKEN` в его env) — общий и для сервиса, и для клиента в LMS |
+| `PDF_MONTHLY_LIMIT` | Лимит генераций в месяц на студента (по умолчанию `100`), без пересборки |
+
+Контейнер `browserless` (`ghcr.io/browserless/chromium`) — внутренний, порт наружу не публикуется ни на staging, ни на проде.
+
+**SSRF-защита — честно про пределы:** до рендера URL проверяется резолвом DNS (блок приватных/зарезервированных диапазонов), плюс внутри browserless страница перехватывается фильтром буквальных приватных IP и `localhost`/`*.local`/`*.internal`. Этот browser-level фильтр **не** переразрешает хостнеймы — same-hostname DNS-rebind (публичный IP на первом резолве, приватный на повторном запросе изнутри browserless) он не закрывает. Полный разбор и требование захардить сетевой egress `browserless` перед включением `TOOLBOX_VISIBLE` на проде — см. «Безопасность» и «Деплой» в [`docs/specs/20260706-clean-pdf-design.md`](docs/specs/20260706-clean-pdf-design.md).
 
 ---
 

docker-compose.prod.yml

@@ -13,9 +13,14 @@ services:
       NEXT_PUBLIC_APP_URL: "https://school.second-brain.ru"
       RESEND_API_KEY: "${RESEND_API_KEY}"
       EMAIL_FROM: "${EMAIL_FROM}"
+      BROWSER_WS_URL: "ws://browserless:3000"
+      BROWSERLESS_TOKEN: "${BROWSERLESS_TOKEN}"
+      PDF_MONTHLY_LIMIT: "${PDF_MONTHLY_LIMIT:-100}"
     depends_on:
       db:
         condition: service_healthy
+      browserless:
+        condition: service_started
 
   db:
     image: postgres:16-alpine
@@ -32,5 +37,15 @@ services:
       timeout: 5s
       retries: 10
 
+  browserless:
+    image: ghcr.io/browserless/chromium
+    restart: unless-stopped
+    environment:
+      TOKEN: "${BROWSERLESS_TOKEN}"
+      CONCURRENT: "2"
+      QUEUED: "10"
+      TIMEOUT: "120000"
+    mem_limit: 1g
+
 volumes:
   postgres_data:

docs/specs/20260706-clean-pdf-design.md

@@ -82,11 +82,12 @@ model PdfApiKey {
 
 - Только `http://` и `https://`.
 - Перед загрузкой — резолв DNS и блокировка приватных/зарезервированных диапазонов: localhost/127.x, 10.x, 172.16–31.x, 192.168.x, 169.254.x (метаданные облаков), ::1, fc00::/7, плюс docker-хостнеймы стенда (`db`, `app`, `browserless`).
-- Внутри browserless — перехват сетевых запросов страницы с той же фильтрацией (защита от редиректов и подгрузок на внутренние адреса).
+- Внутри browserless — перехват сетевых запросов страницы (`context.route`/`context.routeWebSocket`): блокирует буквальные приватные/зарезервированные IP и хосты `localhost`/`*.local`/`*.internal`. **Честно про предел этой защиты:** она не резолвит DNS заново — обычный хостнейм (не IP-литерал) проходит проверку без разрешения адреса. Значит, DNS-rebind на тот же хостнейм (первый резолв на этапе `assertPublicUrl` — публичный IP; повторный запрос со страницы внутри browserless — уже приватный IP того же имени) **не блокируется** этим browser-level фильтром. Остаточный риск закрывается на сетевом уровне — см. «Деплой».
 - Порт browserless наружу не публикуется, доступен только приложению по внутренней сети compose.
 - Куки/учётные данные пользователя на целевую страницу не передаются.
 - Санитайз имени файла в `Content-Disposition`.
 - Лимиты: 100/мес (env) + burst 5/мин на пользователя; сверху — очередь browserless (2 конкурентных рендера).
+- ⚠️ Follow-up (не блокирует релиз): оба счётчика лимита считают только **успешные** генерации (`ToolUsage` пишется после успешного рендера) — неудачные попытки (таймаут, 5xx с целевого сайта, зависший рендер) лимит не расходуют. Потенциальный ограниченный self-DoS повторными запросами к тяжёлым/неотвечающим URL. Рассмотреть подсчёт попыток, а не только успехов, отдельной задачей.
 
 ## Деплой
 
@@ -96,6 +97,8 @@ model PdfApiKey {
 - Стандартная схема деплоя LMS: сборка на Hetzner → `docker save | ssh | docker load` на Hoster.kz; browserless на Hoster.kz — обычный `docker pull`.
 - Hot-standby на Hetzner получает тот же compose (репликация БД уже покрывает `PdfApiKey` и `ToolUsage`).
 
+> ⚠️ **Перед включением `TOOLBOX_VISIBLE` на проде обязательно захардить сетевой egress контейнера `browserless`** — заблокировать `169.254.0.0/16` (cloud-metadata) и RFC1918-диапазоны (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) на уровне хост-файрвола или выделенной internal-only docker-сети. Именно это закрывает DNS-rebind остаточный риск, описанный выше в «Безопасность» — browser-level фильтр (`context.route`) его не закрывает, потому что не переразрешает хостнеймы.
+
 ## Тестирование
 
 - Юнит: SSRF-валидатор (таблица адресов → допуск/блок), пайплайн Defuddle → HTML-шаблон на фикстурах.

docs/superpowers/plans/20260706-clean-pdf.md

@@ -1654,9 +1654,13 @@ git commit -m "Add browserless service to prod compose and document clean-pdf"
 1. В `.env` на Hoster.kz добавить `BROWSERLESS_TOKEN=<random>` (например `openssl rand -hex 24`) и при желании `PDF_MONTHLY_LIMIT`.
 2. Миграция на проде: выполняется как обычно при деплое (`prisma migrate deploy` в entrypoint — проверить, что `add_pdf_api_key` применилась: `docker exec -i lms-sb-db-1 psql -U lms_user -d lms_db -c '\d "PdfApiKey"'`).
 3. `docker pull ghcr.io/browserless/chromium` на Hoster.kz (интернет с сервера есть) + обновлённый compose.
+
+> ⚠️ **Перед шагом 4 (включением `TOOLBOX_VISIBLE=true`) обязательно захардить сетевой egress контейнера `browserless` на проде** — заблокировать `169.254.0.0/16` (cloud-metadata) и RFC1918-диапазоны (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) на уровне хост-файрвола или выделенной internal-only docker-сети. Browser-level SSRF-фильтр (`context.route`/`context.routeWebSocket`) не резолвит DNS заново и не закрывает same-hostname DNS-rebind (публичный IP на первом резолве, приватный — на повторном запросе изнутри browserless); сетевой egress-блок — единственный слой, который закрывает этот остаточный риск. Подробности — «Безопасность»/«Деплой» в `docs/specs/20260706-clean-pdf-design.md`.
+
 4. Инструмент останется невидимым, пока на проде не выставлен `TOOLBOX_VISIBLE=true` — это отдельное продуктовое решение. `/api/pdf` при этом уже будет работать — это ок (доступ гейтится платным enrollment), но анонсировать до включения тулбокса не нужно.
 5. Hot-standby Hetzner: подтянуть тот же compose (`/root/digital-household/lms-sb/docker-compose.prod.yml` обновится через git pull).
 6. После релиза: обновить SBT-карточку `SBT/00-Стек/Сервисы/lms.md` (раздел про тулбокс + новые env) через capture-knowledge.
+7. Follow-up (не блокирует релиз): месячный/burst-лимит сейчас считает только **успешные** генерации — неудачные попытки (таймаут, 5xx, зависший рендер) лимит не расходуют, потенциальный ограниченный self-DoS повторными запросами. Рассмотреть подсчёт попыток, а не только успехов, отдельной задачей.
 
 ## Самопроверка при завершении
 

src/app/(student)/tools/clean-pdf/ZoteroSection.tsx

@@ -8,6 +8,7 @@ export function ZoteroSection({ apiKey, baseUrl }: { apiKey: string; baseUrl: st
   const [key, setKey] = useState(apiKey);
   const [revealed, setRevealed] = useState(false);
   const [pending, startTransition] = useTransition();
+  const [error, setError] = useState<string | null>(null);
 
   const shownKey = revealed ? key : key.slice(0, 8) + "…" + key.slice(-4);
   const curlExample = `curl -H "Authorization: Bearer ${key}" \\\n  "${baseUrl}/api/pdf?url=https://example.com/article&format=A4&theme=light" \\\n  -o article.pdf`;
@@ -15,9 +16,19 @@ export function ZoteroSection({ apiKey, baseUrl }: { apiKey: string; baseUrl: st
 
   function regenerate() {
     if (!confirm("Старый ключ перестанет работать (в том числе в Zotero). Продолжить?")) return;
+    setError(null);
     startTransition(async () => {
-      const res = await regeneratePdfApiKey();
+      try {
-      if (res.ok && res.key) { setKey(res.key); setRevealed(true); }
+        const res = await regeneratePdfApiKey();
+        if (res.ok && res.key) {
+          setKey(res.key);
+          setRevealed(true);
+        } else {
+          setError("Не удалось перевыпустить ключ, попробуйте ещё раз");
+        }
+      } catch {
+        setError("Не удалось перевыпустить ключ, попробуйте ещё раз");
+      }
     });
   }
 
@@ -40,6 +51,7 @@ export function ZoteroSection({ apiKey, baseUrl }: { apiKey: string; baseUrl: st
         <p className="text-xs" style={{ color: "var(--muted-foreground)" }}>
           Ключ персональный — не публикуйте его. Если ключ утёк, перевыпустите: старый сразу отключится.
         </p>
+        {error && <p className="text-sm" style={{ color: "var(--destructive)" }}>{error}</p>}
       </div>
 
       <div className="flex flex-col gap-2 text-sm" style={{ color: "var(--foreground)" }}>

src/lib/clean-pdf/__tests__/template.test.ts

@@ -42,6 +42,14 @@ describe("buildCleanHtml", () => {
     expect(new Set(ids).size).toBe(3);
   });
 
+  it("вырезает script и inline-обработчики из контента", () => {
+    const html = buildCleanHtml({ ...base, contentHtml: `<p onclick="alert(1)">t</p><script>alert(2)</script><a href="javascript:alert(3)">x</a>` });
+    expect(html).not.toContain("<script>alert(2)");
+    expect(html).not.toContain("onclick");
+    expect(html).not.toContain("javascript:alert(3)");
+    expect(html).toContain(">t<");
+  });
+
   it("переключает тёмную тему", () => {
     const light = buildCleanHtml({ ...base, contentHtml: "<p>x</p>" });
     const dark = buildCleanHtml({ ...base, theme: "dark", contentHtml: "<p>x</p>" });

src/lib/clean-pdf/__tests__/zotero-script.test.ts

@@ -9,4 +9,9 @@ describe("buildZoteroScript", () => {
     expect(s).toContain("/api/pdf?url=");
     expect(s).not.toContain("YOUR_KEY");
   });
+
+  it("генерирует синтаксически валидный JS", () => {
+    const s = buildZoteroScript({ apiKey: "sbpdf_test123", baseUrl: "https://school.second-brain.ru" });
+    expect(() => new Function(s)).not.toThrow();
+  });
 });

src/lib/clean-pdf/template.ts

@@ -42,6 +42,17 @@ function prepareContent(contentHtml: string): { html: string; toc: TocEntry[] }
     toc.push({ id, text, level: h.tagName === "H2" ? 2 : 3 });
   });
 
+  // Defuddle отдаёт очищенный, но не полностью доверенный HTML исходной
+  // страницы — вырезаем активное содержимое перед печатью в реальном браузере.
+  doc.querySelectorAll("script, style, iframe, object, embed").forEach((el) => el.remove());
+  doc.querySelectorAll("*").forEach((el) => {
+    for (const attr of [...el.attributes]) {
+      if (attr.name.startsWith("on") || (attr.name === "href" && attr.value.trim().toLowerCase().startsWith("javascript:"))) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  });
+
   return { html: doc.body.innerHTML, toc };
 }
 

src/lib/clean-pdf/zotero-script.ts

@@ -1,7 +1,7 @@
 // Адаптация скрипта Clean PDF (pdf.brainysnipe.ru/zotero-script.js) под школу.
 export function buildZoteroScript({ apiKey, baseUrl }: { apiKey: string; baseUrl: string }): string {
   return `// ── Настройки ──────────────────────────────────────────────────────────────
-const API_KEY     = '${apiKey}'; // персональный ключ из school.second-brain.ru/tools/clean-pdf
+const API_KEY     = '${apiKey}'; // персональный ключ из ${baseUrl}/tools/clean-pdf
 const SERVICE_URL = '${baseUrl}';
 const FORMAT      = 'A4';    // 'A4' или 'Letter'
 const THEME       = 'light'; // 'light' или 'dark'