Once bytes arrive, when can the system trust them?

Every uploaded file is hostile until proven acceptable for a specific use case.

This file satisfies the configured acceptance policy for this workflow,
at this point in time, using this scanner/version/signature/policy.

Allowed: pdf, jpg, png, csv, zip

Allowed for evidence-upload-v3:
- pdf: max 50MB, not encrypted, max pages 500, scan required
- jpg/png: max 20MB, max dimensions 10000x10000, strip metadata optional
- mp4: max 500MB, async scan, manual review if codec unknown

No file may be promoted to ACCEPTED unless the system has recorded
which validation policy was applied, which checks passed, which checks failed,
and which decision was made.

public record FileValidationDecision(
    String fileId,
    String policyName,
    String policyVersion,
    ValidationOutcome outcome,
    List<ValidationCheckResult> checks,
    Instant decidedAt
) {}

public enum ValidationOutcome {
    ACCEPT,
    REJECT,
    QUARANTINE,
    MANUAL_REVIEW
}

public record ValidationCheckResult(
    String checkName,
    String checkVersion,
    boolean passed,
    String reasonCode,
    Map<String, String> evidence
) {}

Path destination = uploadDir.resolve(file.getOriginalFilename());
file.transferTo(destination);

String originalName = sanitizeDisplayName(file.getOriginalFilename());
String generatedId = idGenerator.newFileId();
Path destination = uploadDir.resolve(generatedId + ".upload");

public record ClientFileName(String value) {
    public ClientFileName {
        if (value == null || value.isBlank()) {
            value = "unnamed";
        }
        if (value.length() > 255) {
            value = value.substring(0, 255);
        }
    }
}

public final class ExtensionAllowlist {
    private final Set<String> allowedExtensions;

    public ExtensionAllowlist(Set<String> allowedExtensions) {
        this.allowedExtensions = allowedExtensions.stream()
            .map(String::toLowerCase)
            .collect(java.util.stream.Collectors.toUnmodifiableSet());
    }

    public boolean isAllowed(String filename) {
        String ext = extensionOf(filename);
        return allowedExtensions.contains(ext);
    }

    private static String extensionOf(String filename) {
        int idx = filename.lastIndexOf('.');
        if (idx < 0 || idx == filename.length() - 1) return "";
        return filename.substring(idx + 1).toLowerCase(java.util.Locale.ROOT);
    }
}

invoice.pdf.exe
invoice.pdf%00.exe
invoice.PDF
invoice.pdF
invoice .pdf
invoice.pdf/../../evil
invoice.pdf::$DATA

Extension allowlist is necessary but never sufficient.

if (multipartFile.getContentType().equals("application/pdf")) {
    accept();
}

String declared = multipartFile.getContentType();
MediaType declaredType = parseOrUnknown(declared);

if (!policy.allowedDeclaredTypes().contains(declaredType)) {
    reject("DECLARED_CONTENT_TYPE_NOT_ALLOWED");
}

public enum DetectedType {
    PDF,
    PNG,
    JPEG,
    ZIP,
    UNKNOWN
}

public final class SimpleMagicDetector {
    public DetectedType detect(byte[] header) {
        if (startsWith(header, new byte[] {0x25, 0x50, 0x44, 0x46, 0x2D})) return DetectedType.PDF;
        if (startsWith(header, new byte[] {(byte) 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A})) return DetectedType.PNG;
        if (startsWith(header, new byte[] {(byte) 0xFF, (byte) 0xD8, (byte) 0xFF})) return DetectedType.JPEG;
        if (startsWith(header, new byte[] {0x50, 0x4B, 0x03, 0x04})) return DetectedType.ZIP;
        return DetectedType.UNKNOWN;
    }

    private boolean startsWith(byte[] value, byte[] prefix) {
        if (value.length < prefix.length) return false;
        for (int i = 0; i < prefix.length; i++) {
            if (value[i] != prefix[i]) return false;
        }
        return true;
    }
}

import org.apache.tika.Tika;

public final class TikaContentTypeDetector {
    private final Tika tika = new Tika();

    public String detect(Path file) throws IOException {
        return tika.detect(file);
    }
}

public record ContentTypeEvidence(
    String declaredContentType,
    String detectedContentType,
    String extension
) {}

public boolean isAcceptable(ContentTypeEvidence evidence) {
    return switch (evidence.detectedContentType()) {
        case "application/pdf" -> evidence.extension().equals("pdf");
        case "image/png" -> evidence.extension().equals("png");
        case "image/jpeg" -> evidence.extension().equals("jpg") || evidence.extension().equals("jpeg");
        default -> false;
    };
}

Can a constrained parser understand this file without violating limits?

public final class ZipPolicy {
    private final long maxTotalUncompressedBytes;
    private final int maxEntries;
    private final double maxCompressionRatio;

    public void validate(Path zipFile) throws IOException {
        long totalUncompressed = 0;
        int entries = 0;

        try (java.util.zip.ZipInputStream zin = new java.util.zip.ZipInputStream(Files.newInputStream(zipFile))) {
            java.util.zip.ZipEntry entry;
            while ((entry = zin.getNextEntry()) != null) {
                entries++;
                if (entries > maxEntries) throw new FileRejectedException("ZIP_TOO_MANY_ENTRIES");

                String name = entry.getName();
                if (name.startsWith("/") || name.contains("..")) {
                    throw new FileRejectedException("ZIP_ENTRY_PATH_TRAVERSAL");
                }

                long size = entry.getSize();
                if (size > 0) {
                    totalUncompressed += size;
                    if (totalUncompressed > maxTotalUncompressedBytes) {
                        throw new FileRejectedException("ZIP_UNCOMPRESSED_SIZE_LIMIT");
                    }
                }
            }
        }
    }
}

public record MalwareScanResult(
    String fileId,
    String scannerName,
    String scannerVersion,
    String signatureVersion,
    ScanVerdict verdict,
    String reasonCode,
    Instant scannedAt
) {}

public enum ScanVerdict {
    CLEAN,
    INFECTED,
    SUSPICIOUS,
    FAILED,
    UNSUPPORTED
}

Scanner unavailable must never be interpreted as file clean.

original file != sanitized derivative

public enum FileArtifactKind {
    ORIGINAL_UPLOAD,
    SANITIZED_COPY,
    PREVIEW_IMAGE,
    OCR_TEXT,
    THUMBNAIL,
    ARCHIVAL_RENDITION
}

public record FileDerivative(
    String derivativeFileId,
    String sourceFileId,
    FileArtifactKind kind,
    String transformationName,
    String transformationVersion,
    Instant createdAt
) {}

@PostMapping("/upload")
public ResponseEntity<?> upload(MultipartFile file) {
    if (!file.getOriginalFilename().endsWith(".pdf")) return badRequest();
    if (file.getSize() > 100_000_000) return badRequest();
    // ...
}

public record FileAcceptancePolicy(
    String name,
    String version,
    Set<String> allowedExtensions,
    Set<String> allowedDetectedContentTypes,
    long maxSizeBytes,
    boolean malwareScanRequired,
    boolean encryptedPdfAllowed,
    int maxArchiveEntries
) {}

public interface FileValidationCheck {
    ValidationCheckResult validate(FileValidationContext context) throws IOException;
}

public record FileValidationContext(
    String fileId,
    Path localPath,
    ClientFileName originalFilename,
    String declaredContentType,
    long sizeBytes,
    FileAcceptancePolicy policy
) {}

public final class FileValidationPipeline {
    private final List<FileValidationCheck> checks;

    public FileValidationDecision validate(FileValidationContext context) {
        List<ValidationCheckResult> results = new ArrayList<>();

        for (FileValidationCheck check : checks) {
            ValidationCheckResult result;
            try {
                result = check.validate(context);
            } catch (Exception ex) {
                result = new ValidationCheckResult(
                    check.getClass().getSimpleName(),
                    "1",
                    false,
                    "CHECK_FAILED",
                    Map.of("errorType", ex.getClass().getSimpleName())
                );
            }
            results.add(result);

            if (!result.passed()) {
                return new FileValidationDecision(
                    context.fileId(),
                    context.policy().name(),
                    context.policy().version(),
                    ValidationOutcome.REJECT,
                    results,
                    Instant.now()
                );
            }
        }

        return new FileValidationDecision(
            context.fileId(),
            context.policy().name(),
            context.policy().version(),
            ValidationOutcome.ACCEPT,
            results,
            Instant.now()
        );
    }
}

public record StoredBytes(long sizeBytes, String sha256) {}

public final class HashingFileWriter {
    public StoredBytes copyWithSha256(InputStream input, Path target) throws IOException, NoSuchAlgorithmException {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        long total = 0;

        try (DigestInputStream din = new DigestInputStream(input, digest);
             OutputStream out = Files.newOutputStream(target,
                 StandardOpenOption.CREATE_NEW,
                 StandardOpenOption.WRITE)) {

            byte[] buffer = new byte[8192];
            int read;
            while ((read = din.read(buffer)) != -1) {
                out.write(buffer, 0, read);
                total += read;
            }
        }

        return new StoredBytes(total, HexFormat.of().formatHex(digest.digest()));
    }
}

A validation decision must refer to the exact bytes identified by checksum.

Do not accept.
Move to QUARANTINED or FAILED_INSPECTION.
Retry if safe.
Alert if backlog grows.

Treat as failed validation.
Do not expose stack trace to user.
Record reason code.
Retain sample if security policy allows.

Do not validate partial bytes as final file.
Expire upload session.
Clean temp object.

Policy may require rescan for certain artifact classes.
Record scanner version at decision time.

file_validation_started_total
file_validation_rejected_total{reason="EXTENSION_NOT_ALLOWED"}
file_validation_quarantined_total{reason="SCAN_TIMEOUT"}
file_validation_duration_seconds
file_scan_queue_depth
file_scan_age_seconds
file_magic_mismatch_total
file_archive_bomb_rejected_total
file_policy_version_decision_total{policy="evidence-v3"}

{
  "event": "FILE_VALIDATION_DECIDED",
  "fileId": "FILE-01JZ...",
  "policy": "evidence-upload",
  "policyVersion": "3",
  "outcome": "QUARANTINE",
  "reason": "SCAN_TIMEOUT",
  "sha256": "9f86d081...",
  "correlationId": "REQ-123"
}

valid.pdf
valid.png
empty-file
pdf-with-exe-extension.exe
exe-with-pdf-extension.pdf
oversized.bin
zip-with-traversal-entry.zip
zip-bomb-small.zip
encrypted.pdf
malformed.pdf
unicode-filename.pdf
filename-with-path-..-attack.pdf