UploadValidator.kt

/*
  Copyright (C) 2026 Sber

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
*/

package org.archtool.fileloader2.service.upload

import org.apache.tika.mime.MediaType
import org.archtool.fileloader2.configuration.properties.UploadProperties
import org.archtool.fileloader2.exception.SecurityDataException
import org.archtool.fileloader2.exception.UserDataException
import org.archtool.fileloader2.repository.FileTableColumnLength
import org.springframework.stereotype.Component
import org.springframework.web.multipart.MultipartFile

/**
 * Проверка запроса на загрузку.
 * Запрос отклоняется целиком: если проверку не прошёл хотя бы один файл, не загружается ни один.
 *
 * Файлы проверяются по очереди, каждый полностью: имя, расширение, Content-Type, содержимое.
 */
@Component
class UploadValidator(
    private val uploadProperties: UploadProperties,
    private val fileTypeChecker: FileTypeChecker,
) {

    /**
     * Проверяет число файлов в запросе, затем каждый файл.
     *
     * @param files файлы запроса
     * @return проверенные файлы в порядке запроса
     * @throws UserDataException запрос не прошёл проверку, сообщение показывается клиенту
     * @throws SecurityDataException файл не прошёл проверку типа, причина пишется только в журнал
     */
    fun validate(files: List<MultipartFile>): List<ValidatedFile> {
        if (files.isEmpty()) {
            throw UserDataException("В запросе нет файлов")
        }
        val maxFiles = uploadProperties.maxFiles
        if (files.size > maxFiles) {
            throw UserDataException("В запросе ${files.size} файлов, допустимо не больше $maxFiles")
        }

        return files.mapIndexed { i, file ->
            validateFile(i, file)
        }
    }

    /**
     * Проверяет файл:
     * 1. имя после раскодирования (см. decodeFilename) не пустое, без CR и LF, наличие запрещенных символов/слов и не длиннее размера колонки;
     * 2. расширение из списка допустимых (без учёта регистра, файл без расширения отклоняется);
     * 3. Content-Type из запроса указан, не длиннее размера колонки и подходит расширению. application/octet-stream
     *    означает, что клиент тип не знает: вместо него берётся ожидаемый тип расширения;
     * 4. файл не пустой, и его содержимое соответствует расширению.
     *
     * Размер файла здесь не проверяется: его ограничивает spring.servlet.multipart.max-file-size при разборе
     * запроса, до вызова контроллера.
     *
     * @param index порядковый номер файла в запросе, с нуля - для сообщения клиенту
     * @param file файл
     * @return проверенный файл
     * @throws UserDataException файл не прошёл проверку имени, расширения, Content-Type не указан или слишком длинный,
     * файл пустой; причина показывается клиенту
     * @throws SecurityDataException файл не прошёл проверку типа, причина пишется только в журнал
     */
    private fun validateFile(index: Int, file: MultipartFile): ValidatedFile {
        val decodedName = file.originalFilename?.let {
            decodeFilename(it)
        }
        val validName = isValid(decodedName, index)
        val fileExtension = validName.substringAfterLast('.', missingDelimiterValue = "").lowercase()
        if (!fileTypeChecker.isExtensionAllowed(fileExtension)) {
            throw UserDataException("Тип файла '$validName' не из списка разрешённых: ${fileTypeChecker.getAllowedExtensionsAsString()}")
        }
        val contentType = resolveContentType(validName, fileExtension, file)
        if (contentType.toString().length > FileTableColumnLength.CONTENT_TYPE) {
            throw UserDataException("Content-Type файла '$validName' длиннее ${FileTableColumnLength.CONTENT_TYPE} символов")
        }
        if (!fileTypeChecker.isDeclaredTypeAllowed(fileExtension, contentType)) {
            throw SecurityDataException("Content-Type '${file.contentType}' файла '$validName' не соответствует расширению")
        }
        if (file.isEmpty) {
            throw UserDataException("Файл '$validName' пустой, проверить его содержимое невозможно")
        }
        if (!fileTypeChecker.isContentAllowed(fileExtension, file)) {
            throw SecurityDataException("Содержимое файла '$validName' не соответствует его расширению")
        }
        return ValidatedFile(name = validName, file = file, contentType = contentType.toString())
    }

    /**
     * Определяет сохраняемый тип файла по Content-Type части запроса. application/octet-stream означает, что клиент
     * тип не знает: вместо него берётся ожидаемый тип расширения, который заведомо подходит расширению.
     *
     * @param name имя файла, для сообщения клиенту
     * @param extension допустимое расширение файла в нижнем регистре
     * @param file файл
     * @return Content-Type части запроса с параметрами или, для application/octet-stream, ожидаемый тип расширения
     * @throws UserDataException Content-Type не указан
     * @throws SecurityDataException Content-Type не разбирается
     */
    private fun resolveContentType(name: String, extension: String, file: MultipartFile): MediaType {
        val contentType = file.contentType?.takeIf { it.isNotBlank() }
            ?: throw UserDataException("У файла '$name' не указан Content-Type")
        val declared = MediaType.parse(contentType)
            ?: throw SecurityDataException("Content-Type '$contentType' файла '$name' некорректен")
        if (declared.baseType == MediaType.OCTET_STREAM) {
            return fileTypeChecker.getDefaultContentType(extension)
        }
        return declared
    }

    /**
     * Раскодирует имя файла из части multipart. Браузер по алгоритму multipart/form-data (WHATWG) экранирует в filename
     * только три символа: '"' как %22, CR как %0D, LF как %0A. Остальные символы, включая '%', передаются как есть,
     * поэтому полное URL-декодирование испортило бы имя: 100%25.txt превратилось бы в 100%.txt.
     * Раскодируется только верхний регистр, в котором пишут браузеры: %0d, %0a и %22 в нижнем регистре
     * считаются частью имени.
     *
     * @param name имя из части multipart
     * @return имя с раскодированными '"', CR и LF
     */
    private fun decodeFilename(name: String): String {
        return name
            .replace(ENCODED_QUOTE, "\"")
            .replace(ENCODED_CR, CR.toString())
            .replace(ENCODED_LF, LF.toString())
    }

    /**
     * Проверяет, что имя файла допустимо и в Linux, и в Windows.
     */
    private fun isValid(name: String?, index: Int): String {
        if (name.isNullOrBlank()) {
            throw UserDataException("У файла №${index + 1} пустое имя")
        }
        if (name.contains(CR) || name.contains(LF)) {
            // имя в сообщение не подставляется: перевод строки попал бы в журнал как есть
            throw UserDataException("Имя файла №${index + 1} содержит перевод строки")
        }
        if (FORBIDDEN.containsMatchIn(name)) {
            throw UserDataException("Имя файла №${index + 1} содержит запрещенные символы")
        }
        if (RESERVED.matches(name)) {
            // имя устройства Windows (CON, NUL, COM1 и т.п.)
            throw UserDataException("Имя файла №${index + 1} содержит зарезервированные win слова")
        }
        if (name.length > FileTableColumnLength.ORIGINAL_NAME) {
            throw UserDataException("Имя файла №${index + 1} должно быть не длиннее ${FileTableColumnLength.ORIGINAL_NAME} символов")
        }
        return name
    }

    companion object {

        /** Как браузер экранирует '"', CR и LF в filename части multipart (WHATWG), см. decodeFilename */
        private const val ENCODED_QUOTE = "%22"
        private const val ENCODED_CR = "%0D"
        private const val ENCODED_LF = "%0A"

        /** Раскодированные ENCODED_CR и ENCODED_LF. В имени файла после раскодирования запрещены */
        private const val CR = '\r'
        private const val LF = '\n'

        /**
         * Символы, которые НЕ разрешены в имени файла.
         *
         * Квадратные скобки [...] описывают один символ из набора,
         * а ^ сразу после [ инвертирует набор: «любой символ, КРОМЕ перечисленных».
         *
         * Разрешено:
         *   \p{L}  — буквы любого алфавита (латиница, кириллица, иероглифы и т.д.)
         *   \p{N}  — цифры любой системы письма
         *   _      — подчёркивание
         *   .      — точка (внутри [] это обычный символ, а не «любой символ»)
         *   %      — процент
         *   +      — плюс
         *   ( )    — круглые скобки (внутри [] не группа, а обычные символы)
         *   \[ \]  — квадратные скобки; экранированы, иначе ] закроет класс раньше времени
         *   &      — амперсанд (одиночный; && внутри [] в Java означает пересечение наборов)
         *   ' '    — пробел (именно пробел, не \s: \s включает табуляцию и переводы строк)
         *   -      — дефис; стоит последним, иначе будет понят как диапазон (как в a-z)
         *
         * Двойная кавычка " намеренно не разрешена: она запрещена в именах файлов Windows.
         */
        val FORBIDDEN = Regex("""[^\p{L}\p{N}_.%+()\[\]& -]""")

        /**
         * Зарезервированные имена устройств Windows.
         * Такие файлы нельзя создать, даже с расширением (например, nul.txt).
         *
         *   (?i)        — без учёта регистра: con, Con, CON
         *   CON|PRN|AUX|NUL — консоль, принтер, вспомогательное устройство, «пустое» устройство
         *   COM\d       — последовательные порты COM0–COM9
         *   LPT\d       — параллельные порты LPT0–LPT9
         *   (\..*)?     — необязательное расширение: точка и любые символы после неё
         *
         * Используется с matches(), поэтому сравнивается всё имя целиком:
         * "con.txt" — совпадение, "console.txt" — нет.
         */
        val RESERVED = Regex("""(?i)(CON|PRN|AUX|NUL|COM\d|LPT\d)(\..*)?""")
    }
}