From 6f57c8a80f50300de7cc17a3c6a3acef898c2811 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Tue, 20 Oct 2026 21:14:28 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20=D0=B2=D0=B0=D0=BB=D0=B8=D0=B4=D0=B0?= =?UTF-8?q?=D1=86=D0=B8=D1=8F=20=D0=BA=D0=BE=D0=BD=D1=82=D0=B5=D0=B9=D0=BD?= =?UTF-8?q?=D0=B5=D1=80=D0=B0=20.docx=20=D0=B8=20=D0=B7=D0=B0=D1=89=D0=B8?= =?UTF-8?q?=D1=82=D0=B0=20=D0=BE=D1=82=20zip-=D0=B1=D0=BE=D0=BC=D0=B1?= =?UTF-8?q?=D1=8B=20=D0=B2=20WordPdfValidator.validate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - checkDocxContainer: потоковый проход по zip — декларация wordprocessingml.document в [Content_Types].xml (голый zip / переименованный .xlsx → 400, а не 500 на docx4j) + лимиты MAX_DECOMPRESSED_MB (200) / MAX_ZIP_ENTRIES (8192) — бомба отсекается до readAllBytes в checkPageCount; пороги константные, не ConvertOptions - регрессии: validate_plainZipRejected/xlsxRenamedRejected/zipBombRejected/ tooManyEntriesRejected, inputNotDocx_rejectedBeforeRender, plainZipNotDocx_rejected; junkInsideValidZip_conversionError — на валидном контейнере с мусором (500) - прод-автест test_plain_zip_not_docx_rejected; AGENTS.md синхронизирован --- AGENTS.md | 12 +- prod-autotests/test_prod_api.py | 15 +++ .../wordpdf/app/ConvertControllerTest.java | 56 ++++++++- .../ru/pjandro/wordpdf/WordPdfSettings.java | 6 + .../ru/pjandro/wordpdf/WordPdfValidator.java | 114 ++++++++++++++++-- .../pjandro/wordpdf/WordPdfConverterTest.java | 19 +++ .../pjandro/wordpdf/WordPdfValidatorTest.java | 87 +++++++++++++ 7 files changed, 291 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9b943d8..cee0e31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ ### Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])` (порядок фиксирован, менять местами нельзя) -Наружу `WordPdfValidator.validate(docxBytes, options)` (размер → zip-подпись `PK\x03\x04` → страницы) вызывается **до** приватного `convertToStream`; внутри `convertToStream`: +Наружу `WordPdfValidator.validate(docxBytes, options)` (размер → zip-подпись `PK\x03\x04` → контейнер (.docx-манифест + zip-бомба) → страницы) вызывается **до** приватного `convertToStream`; внутри `convertToStream`: 1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя из name-таблицы TTF, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()` (иначе системный Calibri ломает em-dash-fallback). 2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим): `StrictOoxmlNormalizer` (strict-OOXML → transitional-байт: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`, элементы и атрибуты `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml), значения `start`/`end` у `w:jc`/`w:tab`; в `mc-preprocessor.xslt` docx4j ветка `%` закомментирована, start/end не маппятся; namespaces и `pt`-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) → `DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`) → `SymbolFontNormalizer` (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы ``; 5 карт по 256 слотов, таблица `SymbolMapper` сгенерирована из docx4j 17.x) → `FieldNormalizer` (`fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, вложенные/битые поля пропускает) → `GlyphCoverageNormalizer` (режет ран по покрытию глифов, пишет семейство в `w:rFonts`, иначе FOP рисует «#»; покрытие — `java.awt.Font.canDisplay` + BitSet-кэш, НЕ docx4j `GlyphCheck` — тот плодит INFO-лог; для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (DejaVu Serif/Tinos/Caladea), затем в sans) → `WordprocessingMLPackage.load`. @@ -21,7 +21,7 @@ - Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`-расширения — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). - Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. -- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). `ValidationException` — тип ядра `ru.pjandro.wordpdf.ValidationException extends ConversionException` (публичный), валидатор бросает его сам, app-дубликата нет; три app-исключения (`ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 500/503/504. `doConvert` перехватывает `ValidationException` раньше `ConversionException` — отказ страницы-лимита из конвейера ядра даёт 400, а не 500. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `WordPdfValidator.validate(docxBytes, options)` (внутри порядок значим: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCount`); тот же метод — вход ядра. +- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). `ValidationException` — тип ядра `ru.pjandro.wordpdf.ValidationException extends ConversionException` (публичный), валидатор бросает его сам, app-дубликата нет; три app-исключения (`ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 500/503/504. `doConvert` перехватывает `ValidationException` раньше `ConversionException` — отказ страницы-лимита из конвейера ядра даёт 400, а не 500. Граница: сломанный контейнер (не zip / голый zip без манифеста wordprocessingml / zip-бомба / размер / страницы) → 400 (проверка контейнера), валидный .docx-контейнер с мусором внутри → 500. Валидация до очереди: `WordPdfValidator.validate(docxBytes, options)` (внутри порядок значим: `checkInput` → zip-магик `PK\x03\x04` → `checkDocxContainer` — потоковый проход: декларация `wordprocessingml.document` в `[Content_Types].xml` + лимиты zip-бомбы `WordPdfSettings.MAX_DECOMPRESSED_MB`/`MAX_ZIP_ENTRIES`, не переопределяются `ConvertOptions` — → `checkPageCount`); тот же метод — вход ядра. - **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `/actuator/**` (HEALTHCHECK) и документация springdoc (`/swagger-ui*`, `/v3/api-docs*`) — матч по пути **без forwarded-contextPath** (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Springdoc в проде **включён**, документация открыта без ключа под `https://pjandro.ru/pdf-converter/swagger-ui.html` (server-URL/swagger-config собираются из `X-Forwarded-*`, `server.forward-headers-strategy=framework` — `native`-клапан Tomcat `X-Forwarded-Prefix` не понимает). Регрессии — `ApiKeyFilterTest#forwardedPrefix_healthStaysOpen`, `ApiKeyFilterTest#docsOpenWithoutKey`. - Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 МБ / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт. - SPA: вся сеть в `src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401 от `ApiKeyFilter`) подтвердил требование ключа — в dev без ключа форма открывается сразу; запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`). @@ -47,7 +47,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |Путь|Назначение| |---|---| -|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` — `byte[]`, с лимитом/без, и `validate(byte[], ConvertOptions)` — полная цепочка размер → zip-подпись → страницы; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxMb, maxPages)| +|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` — `byte[]`, с лимитом/без, и `validate(byte[], ConvertOptions)` — полная цепочка размер → zip-подпись → контейнер (.docx-манифест + zip-бомба) → страницы; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `WordPdfSettings` (константы-дефолты, в т.ч. защитные `MAX_DECOMPRESSED_MB`/`MAX_ZIP_ENTRIES`), `ConvertOptions` (record: renderCharts, renderSmartArt, maxMb, maxPages)| |`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`)| |`…/wordpdf/internal/`|5 байтовых нормализатора + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`declare`)| |`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| @@ -59,7 +59,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — на прод-сервере (координаты: `/home/pjandro/prod/java-word-pdf/DEPLOY.md`, вне репо)| |`.gitea/workflows/`|Gitea Actions: `pr.yml` (PR checks), `main.yml` (тесты → `images` (docker build + push в Nexus) → deploy (pull) → autotests → rollback)| |корневой `GITEA-vars.md`|инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений| -|корневой `prod-autotests/`|прод-автотесты API (pytest + requests, 19 проверок): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет; окружение — mise (`mise.toml`: python 3.15 + автосоздаваемый `.venv`, в venv от uv pip досеивается `ensurepip`); прод-раннер вне git — `/home/pjandro/prod/java-word-pdf/run-prod-tests.sh` (знает прод-настройки: base URL, лимит 100 стр. (= Gitea Variable `WORDPDF_MAX_PAGES`), ключ из соседнего `.env`)| +|корневой `prod-autotests/`|прод-автотесты API (pytest + requests, 20 проверок): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет; окружение — mise (`mise.toml`: python 3.15 + автосоздаваемый `.venv`, в venv от uv pip досеивается `ensurepip`); прод-раннер вне git — `/home/pjandro/prod/java-word-pdf/run-prod-tests.sh` (знает прод-настройки: base URL, лимит 100 стр. (= Gitea Variable `WORDPDF_MAX_PAGES`), ключ из соседнего `.env`)| |`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать| ## Development Commands @@ -150,11 +150,11 @@ SSH-пользователи/логины, ни хосты, ни директо ## Testing & QA - Гейт `maven-pmd-plugin` 3.28.0 (PMD 7.17) на `verify` для обоих модулей, ruleset `pmd-ruleset.xml` (codestyle без opinionated-правил + unused-правила + XPath `LiteralFirstInEquals` — строковый литерал слева в `equals`/`equalsIgnoreCase`; `junit5TestPattern` разрешает underscore-имена регрессий; `includeTests=true` — тесты сканируются). -- 14 тестовых классов / 132 `@Test` (core 11/107, app 3/25). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). +- 14 тестовых классов / 138 `@Test` (core 11/112, app 3/26). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). - **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (`PiePainterTest` аспект h/w=0.585, `assertRatio` отклонение <0.06; `Surface3dPainterTest` `assertRange` ±6 pt для центров силуэта + `assertRatio` допуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]). - Фикстуры — закоммиченные `samples/*.docx` (11; в тестах не генерировать): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject). - Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame` покрыт тестами только у zip-нормализаторов `DocxOnOff`/`SymbolFont`/`StrictOoxml`; у `Field`/`GlyphCoverage` — `rewrite`→`null`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `ChartSpec.readTitle`). - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`). -- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`↔`inputNotAZip_rejectedBeforeRender`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath). +- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`↔`inputNotAZip_rejectedBeforeRender`, `validate_plainZipRejected`/`validate_xlsxRenamedRejected`/`validate_zipBombRejected`/`validate_tooManyEntriesRejected`↔`plainZipNotDocx_rejected`/`inputNotDocx_rejectedBeforeRender` — контейнер и zip-бомба), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `plainZipNotDocx_rejected` (голый zip без манифеста → 400), `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath). - UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). diff --git a/prod-autotests/test_prod_api.py b/prod-autotests/test_prod_api.py index 0d48190..3e9e4ff 100644 --- a/prod-autotests/test_prod_api.py +++ b/prod-autotests/test_prod_api.py @@ -196,6 +196,21 @@ def test_not_a_zip_rejected(url, notzip_docx, key_header): assert "error" in r.json() +@needs_key +def test_plain_zip_not_docx_rejected(url, key_header): + """Граница «не .docx → 400»: валидный zip без манифеста wordprocessingml под .docx-суффиксом.""" + buf = io.BytesIO() + with zipfile.ZipFile(buf, "w") as z: + z.writestr("hello.txt", "не документ") + r = requests.post( + url(CONVERT), + headers=key_header, + files={"file": ("archive.docx", buf.getvalue())}, + timeout=TIMEOUT, + ) + assert r.status_code == 400 + assert "не является .docx" in r.json()["error"] + @needs_key def test_wrong_extension_rejected(url, samples, key_header): """Расширение проверяет контроллер (ядро байтов его не видит) — регрессия nonDocxFilename_rejected.""" diff --git a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java index a0b6d7d..7d9810f 100644 --- a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java +++ b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java @@ -94,8 +94,8 @@ class ConvertControllerTest { return count; } - /** Валидный zip с одной мусорной записью (не OPC-пакет). */ - private static byte[] zipWithGarbage() throws IOException { + /** Валидный zip, не .docx: без манифеста [Content_Types].xml (не OPC-пакет). */ + private static byte[] plainZipWithGarbage() throws IOException { ByteArrayOutputStream bos = new ByteArrayOutputStream(); try (ZipOutputStream zout = new ZipOutputStream(bos)) { zout.putNextEntry(new ZipEntry("garbage.txt")); @@ -105,6 +105,36 @@ class ConvertControllerTest { return bos.toByteArray(); } + /** + * .docx-контейнер (манифест декларирует документ wordprocessingml) с + * битым пакетом внутри: нет {@code _rels/.rels} — docx4j не находит + * основную часть документа, отказ на стадии конвертации. + */ + private static byte[] docxPackageWithGarbage() throws IOException { + ByteArrayOutputStream bos = new ByteArrayOutputStream(); + try (ZipOutputStream zout = new ZipOutputStream(bos)) { + putZipEntry(zout, "[Content_Types].xml", + "" + + "" + + "" + + "" + + ""); + putZipEntry(zout, "word/document.xml", + "" + + "" + + ""); + } + return bos.toByteArray(); + } + + private static void putZipEntry(ZipOutputStream zout, String name, String content) + throws IOException { + zout.putNextEntry(new ZipEntry(name)); + zout.write(content.getBytes(StandardCharsets.UTF_8)); + zout.closeEntry(); + } + @Test void convertSample_returnsPdf() throws Exception { MvcResult result = mockMvc.perform(multipart("/api/v1/convert") @@ -336,12 +366,28 @@ class ConvertControllerTest { org.hamcrest.Matchers.containsString("не zip-архив"))); } + /** + * Валидный zip, не .docx (в манифесте нет декларации wordprocessingml) — + * 400, а не 500: контейнер отсекает валидатор до очереди и docx4j. + * Регрессия — WordPdfValidatorTest#validate_plainZipRejected. + */ + @Test + void plainZipNotDocx_rejected() throws Exception { + mockMvc.perform(multipart("/api/v1/convert") + .file(docx("archive.docx", plainZipWithGarbage()))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.error", + org.hamcrest.Matchers.containsString("не является .docx"))); + } + @Test void junkInsideValidZip_conversionError() throws Exception { - // контейнер целый (валидный zip), мусор внутри — это ошибка - // преобразования (500), а не валидации (400) + // контейнер — .docx (манифест декларирует документ wordprocessingml), + // битый пакет внутри — ошибка преобразования (500), а не валидации + // (400); голый zip без манифеста теперь 400 — проверка контейнера + // (plainZipNotDocx_rejected) mockMvc.perform(multipart("/api/v1/convert") - .file(docx("bad.docx", zipWithGarbage()))) + .file(docx("bad.docx", docxPackageWithGarbage()))) .andExpect(status().isInternalServerError()) .andExpect(jsonPath("$.error", org.hamcrest.Matchers.containsString("Не удалось конвертировать"))); diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java index 34a874b..1f84cc6 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java @@ -15,6 +15,12 @@ public final class WordPdfSettings { /** Документ длиннее — ошибка (дефолт). */ public static final int MAX_PAGES = 100; + /** Потолок суммарного распакованного размера архива (МБ) — защита от zip-бомбы. */ + public static final long MAX_DECOMPRESSED_MB = 200; + + /** Потолок числа записей в архиве — защита от бомбы «много записей». */ + public static final int MAX_ZIP_ENTRIES = 8192; + /** * Генерация диаграмм (c:chart → PNG, chart-движок). {@code false} — диаграммы * не рендерятся и остаются в docx, откуда docx2fo выбрасывает их молча, diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java index eec14f2..a49ed2a 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java @@ -4,8 +4,10 @@ import javax.xml.stream.XMLInputFactory; import javax.xml.stream.XMLStreamException; import javax.xml.stream.XMLStreamReader; import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.InputStream; +import java.nio.charset.StandardCharsets; import java.util.ArrayDeque; import java.util.ArrayList; import java.util.Deque; @@ -15,7 +17,8 @@ import java.util.zip.ZipInputStream; /** * Валидатор ограничений на входной .docx: - * размер входа и число страниц. + * размер входа, корректность контейнера (.docx-манифест, защита от + * zip-бомбы) и число страниц. * *

Вход валидатора — только {@code byte[]}: файловых проверок нет, * работа с файлами — забота вызывающего (приложения). @@ -27,10 +30,20 @@ import java.util.zip.ZipInputStream; *

Лимиты по умолчанию: *

- * Оба переопределяются на вызов: перегрузками с явным лимитом или + * Первые два переопределяются на вызов: перегрузками с явным лимитом или * {@link ConvertOptions} (конвертер {@link WordPdfConverter} применяет их сам). + * Последние два — защитные константные пороги ({@link #validate(byte[], ConvertOptions)}), + * {@link ConvertOptions} их не переопределяет. + * + *

Проверка контейнера: архив обязан декларировать документ + * wordprocessingml в {@code [Content_Types].xml} — иначе это не .docx + * (обычный zip, переименованный .xlsx/.pptx). * *

Число страниц берётся из самого .docx как максимум трёх нижних * оценок: кэша Word в {@code docProps/app.xml} ({@code }), @@ -102,8 +115,10 @@ public final class WordPdfValidator { * *

Не-zip байты не отвергаются: {@code ZipInputStream} доходит до EOF * без единой записи — молча, оценка «1 страница». Корректность контейнера - * по zip-подписи проверяет {@link #validate(byte[], ConvertOptions)} - * (регрессия — {@code WordPdfValidatorTest#validate_notAZip}). + * проверяет {@link #validate(byte[], ConvertOptions)}: zip-подпись, + * .docx-манифест и распакованный размер (регрессия — + * {@code WordPdfValidatorTest#validate_notAZip}); поэтому вызывать + * {@code checkPageCount} напрямую допустимо только над доверенным входом. * @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES} */ public static void checkPageCount(byte[] docxBytes) throws ValidationException { @@ -149,7 +164,8 @@ public final class WordPdfValidator { } /** - * Полная проверка входа: размер → zip-подпись → число страниц. Порядок + * Полная проверка входа: размер → zip-подпись → контейнер (.docx + + * zip-бомба) → число страниц. Порядок * значим: размер — дешёвая, разбор zip без подписи бессмысленен. Лимиты * берутся из {@link ConvertOptions} (переопределение на вызов, см. * {@link ConvertOptions#maxMb()}, {@link ConvertOptions#maxPages()}). @@ -161,8 +177,19 @@ public final class WordPdfValidator { * {@code WordPdfValidatorTest#validate_notAZip} (на HTTP-границе — * {@code ConvertControllerTest#corruptNotAZip_rejected}).

* + *

Проверка контейнера: в {@code [Content_Types].xml} обязана быть + * декларация документа wordprocessingml (архив без неё — не .docx); + * zip-бомба отсекается потоковым счётчиком распакованных байт + * ({@link WordPdfSettings#MAX_DECOMPRESSED_MB}) и числом записей + * ({@link WordPdfSettings#MAX_ZIP_ENTRIES}) — до загрузки содержимого + * в память в {@link #checkPageCount(byte[], int)}. Оба лимита — + * защитные пороги, {@link ConvertOptions} их не переопределяет. + * Регрессии — {@code WordPdfValidatorTest#validate_plainZipRejected}, + * {@code #validate_xlsxRenamedRejected}, {@code #validate_zipBombRejected}, + * {@code #validate_tooManyEntriesRejected}.

* @throws ValidationException при {@code null}, превышении {@code options.maxMb()}, - * отсутствии zip-подписи, ошибке разбора zip или превышении {@code options.maxPages()} + * отсутствии zip-подписи, не-.docx-контейнере, признаках zip-бомбы, + * ошибке разбора zip или превышении {@code options.maxPages()} */ public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException { checkInput(docxBytes, options.maxMb()); @@ -170,9 +197,82 @@ public final class WordPdfValidator { || (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) { throw new ValidationException("Содержимое не похоже на .docx (не zip-архив)"); } + checkDocxContainer(docxBytes); checkPageCount(docxBytes, options.maxPages()); } + /** + * Один потоковый проход по zip: суммарный распакованный размер и число + * записей (защита от zip-бомбы — отсечение ДО {@code readAllBytes} + * в {@link #checkPageCount(byte[], int)}) и наличие в + * {@code [Content_Types].xml} декларации документа wordprocessingml + * (архив без неё — не .docx: обычный zip, переименованный .xlsx/.pptx). + */ + private static void checkDocxContainer(byte[] docxBytes) throws ValidationException { + long maxTotal = WordPdfSettings.MAX_DECOMPRESSED_MB * 1024 * 1024; + long total = 0; + int entries = 0; + ByteArrayOutputStream ctBuf = new ByteArrayOutputStream(); + try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) { + ZipEntry entry; + while ((entry = zip.getNextEntry()) != null) { + if (!entry.isDirectory()) { + entries++; + if (entries > WordPdfSettings.MAX_ZIP_ENTRIES) { + throw new ValidationException("Слишком много записей в архиве: больше " + + WordPdfSettings.MAX_ZIP_ENTRIES); + } + } + boolean isCt = "[Content_Types].xml".equals(entry.getName()); + byte[] buf = new byte[8192]; + int n; + while ((n = zip.read(buf)) > 0) { + total += n; + if (total > maxTotal) { + throw new ValidationException("Распакованный размер архива больше " + + WordPdfSettings.MAX_DECOMPRESSED_MB + " МБ (признак zip-бомбы)"); + } + if (isCt) { + if (ctBuf.size() + n > 8 * 1024 * 1024) { + throw new ValidationException( + "Слишком большой [Content_Types].xml: больше 8 МБ"); + } + ctBuf.write(buf, 0, n); + } + } + } + } catch (ValidationException e) { + throw e; + } catch (IOException | RuntimeException e) { + throw new ValidationException("Не удалось разобрать байты .docx", e); + } + // Маркер — подстрока content-type части документа + // (application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml): + // URI пространства имён wml в [Content_Types].xml не появляется ни у + // одного генератора (Word/POI/docx4j пишут только content-type), а в + // манифестах .xlsx/.pptx стоит spreadsheetml/presentationml — не матчится. + String marker = "wordprocessingml.document"; + if (!containsAscii(ctBuf.toByteArray(), marker)) { + throw new ValidationException("Архив не является .docx: в [Content_Types].xml нет " + + "декларации документа wordprocessingml"); + } + } + + /** Поиск байтов ASCII-строки в массиве (манифест ограничен 8 МБ — наивного поиска достаточно). */ + private static boolean containsAscii(byte[] data, String needle) { + byte[] pat = needle.getBytes(StandardCharsets.UTF_8); + outer: + for (int i = 0; i + pat.length <= data.length; i++) { + for (int j = 0; j < pat.length; j++) { + if (data[i + j] != pat[j]) { + continue outer; + } + } + return true; + } + return false; + } + /** Поставщик потока по имени части zip; null — части нет. */ private interface PartStream { InputStream open(String name) throws IOException; diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java index 0691c28..19565c0 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java @@ -463,6 +463,25 @@ class WordPdfConverterTest { "сообщение должно упоминать zip-подпись: " + ex.getMessage()); } + /** + * Валидный zip без манифеста wordprocessingml — отказ как некорректный + * вход (ValidationException) до рендера, а не ошибка загрузки docx4j. + * Регрессия — WordPdfValidatorTest#validate_plainZipRejected. + */ + @Test + void inputNotDocx_rejectedBeforeRender() throws IOException { + ByteArrayOutputStream out = new ByteArrayOutputStream(); + try (ZipOutputStream zos = new ZipOutputStream(out)) { + zos.putNextEntry(new ZipEntry("hello.txt")); + zos.write("не документ".getBytes(StandardCharsets.UTF_8)); + zos.closeEntry(); + } + ValidationException ex = assertThrows(ValidationException.class, () -> + WordPdfConverter.convert(out.toByteArray(), "x")); + assertTrue(ex.getMessage().contains("не является .docx"), + "сообщение должно указывать на не-.docx-контейнер: " + ex.getMessage()); + } + /** * Лимит размера переопределяется {@link ConvertOptions} на вызов: * maxMb=1 отсекает вход больше 1 MiB до рендера, сообщение содержит diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java index 7d24a95..9acfac8 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java @@ -1,5 +1,6 @@ package ru.pjandro.wordpdf; +import org.apache.poi.xssf.usermodel.XSSFWorkbook; import org.apache.poi.xwpf.usermodel.BreakType; import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFParagraph; @@ -284,6 +285,92 @@ class WordPdfValidatorTest { "сообщение должно упоминать zip-подпись: " + ex.getMessage()); } + /** + * Валидный zip, не являющийся .docx (в {@code [Content_Types].xml} нет + * декларации wordprocessingml), отвергается валидацией — а не доходит + * до загрузки docx4j. Регрессия — WordPdfValidator#checkDocxContainer + * (на HTTP-границе — {@code ConvertControllerTest#plainZipNotDocx_rejected}). + */ + @Test + void validate_plainZipRejected() throws Exception { + ByteArrayOutputStream out = new ByteArrayOutputStream(); + try (ZipOutputStream zos = new ZipOutputStream(out)) { + zos.putNextEntry(new ZipEntry("hello.txt")); + zos.write("не документ".getBytes(StandardCharsets.UTF_8)); + zos.closeEntry(); + } + byte[] zip = out.toByteArray(); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(zip, ConvertOptions.defaults())); + assertTrue(ex.getMessage().contains("не является .docx"), + "zip без манифеста wordprocessingml — не .docx: " + ex.getMessage()); + } + + /** + * .xlsx под .docx-суффиксом: манифест xlsx декларирует spreadsheetml, + * не wordprocessingml — отказ как не-.docx, а не 500 на загрузке docx4j. + * Регрессия — WordPdfValidator#checkDocxContainer. + */ + @Test + void validate_xlsxRenamedRejected() throws Exception { + ByteArrayOutputStream out = new ByteArrayOutputStream(); + try (XSSFWorkbook wb = new XSSFWorkbook()) { + wb.createSheet("S1"); + wb.write(out); + } + byte[] xlsx = out.toByteArray(); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(xlsx, ConvertOptions.defaults())); + assertTrue(ex.getMessage().contains("не является .docx"), + "манифест xlsx — spreadsheetml: " + ex.getMessage()); + } + + /** + * Zip-бомба: распакованный суммарный размер больше + * {@link WordPdfSettings#MAX_DECOMPRESSED_MB} отсекается потоково — до + * {@code readAllBytes} в {@code checkPageCount} (без проверки валидатор + * прочитал бы 200+ МБ в память). Регрессия — WordPdfValidator#checkDocxContainer. + */ + @Test + void validate_zipBombRejected() throws Exception { + ByteArrayOutputStream out = new ByteArrayOutputStream(); + try (ZipOutputStream zos = new ZipOutputStream(out)) { + zos.putNextEntry(new ZipEntry("word/document.xml")); + zos.write(new byte[1024]); + zos.closeEntry(); + zos.putNextEntry(new ZipEntry("bomb.bin")); + zos.write(new byte[(int) (WordPdfSettings.MAX_DECOMPRESSED_MB * 1024 * 1024) + 1]); + zos.closeEntry(); + } + byte[] zip = out.toByteArray(); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(zip, ConvertOptions.defaults())); + assertTrue(ex.getMessage().contains("zip-бомбы"), ex.getMessage()); + assertTrue(ex.getMessage().contains(String.valueOf(WordPdfSettings.MAX_DECOMPRESSED_MB)), + "сообщение должно упоминать лимит: " + ex.getMessage()); + } + + /** + * Бомба «много записей»: больше {@link WordPdfSettings#MAX_ZIP_ENTRIES} + * записей отвергаются до разбора содержимого. + * Регрессия — WordPdfValidator#checkDocxContainer. + */ + @Test + void validate_tooManyEntriesRejected() throws Exception { + ByteArrayOutputStream out = new ByteArrayOutputStream(); + try (ZipOutputStream zos = new ZipOutputStream(out)) { + for (int i = 0; i <= WordPdfSettings.MAX_ZIP_ENTRIES; i++) { + zos.putNextEntry(new ZipEntry("e" + i + ".txt")); + zos.write(new byte[] {1}); + zos.closeEntry(); + } + } + byte[] zip = out.toByteArray(); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(zip, ConvertOptions.defaults())); + assertTrue(ex.getMessage().contains("записей"), ex.getMessage()); + } + @Test void validate_tooManyPages() throws Exception { byte[] bytes = docxWithPageBreaks(120);