package eu.righettod;


import org.apache.commons.csv.CSVFormat;
import org.apache.commons.csv.CSVRecord;
import org.apache.commons.imaging.ImageInfo;
import org.apache.commons.imaging.Imaging;
import org.apache.commons.imaging.common.ImageMetadata;
import org.apache.commons.validator.routines.EmailValidator;
import org.apache.commons.validator.routines.InetAddressValidator;
import org.apache.pdfbox.Loader;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDDocumentCatalog;
import org.apache.pdfbox.pdmodel.PDDocumentInformation;
import org.apache.pdfbox.pdmodel.PDDocumentNameDictionary;
import org.apache.pdfbox.pdmodel.common.PDMetadata;
import org.apache.pdfbox.pdmodel.interactive.action.*;
import org.apache.pdfbox.pdmodel.interactive.annotation.AnnotationFilter;
import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotation;
import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationLink;
import org.apache.poi.poifs.filesystem.DirectoryEntry;
import org.apache.poi.poifs.filesystem.POIFSFileSystem;
import org.apache.poi.poifs.macros.VBAMacroReader;
import org.apache.tika.detect.DefaultDetector;
import org.apache.tika.detect.Detector;
import org.apache.tika.io.TemporaryResources;
import org.apache.tika.io.TikaInputStream;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.mime.MediaType;
import org.apache.tika.mime.MimeTypes;
import org.w3c.dom.Document;
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.imageio.ImageIO;
import javax.json.Json;
import javax.json.JsonReader;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.io.*;
import java.net.*;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.List;
import java.util.*;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.regex.Pattern;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;

/**
 * Provides different utilities methods to apply processing from a security perspective.<br>
 * These code snippet:
 * <ul>
 *     <li>Can be used, as "foundation", to customize the validation to the app context.</li>
 *     <li>Were implemented in a way to facilitate adding or removal of validations depending on usage context.</li>
 *     <li>Were centralized on one class to be able to enhance them across time as well as <a href="https://github.com/righettod/code-snippets-security-utils/issues">missing case/bug identification</a>.</li>
 * </ul>
 */
public class SecurityUtils {

    /**
     * Default constructor: Not needed as the class only provides static methods.
     */
    private SecurityUtils() {
    }

    /**
     * Apply a collection of validation to verify if a provided PIN code is considered weak (easy to guess) or none.<br>
     * This method consider that format of the PIN code is [0-9]{6,}<br>
     * Rule to consider a PIN code as weak:<br>
     * - Length is inferior to 6 positions.<br>
     * - Contain only the same number or only a sequence of zero.<br>
     * - Contain sequence of following incremental or decremental numbers.<br>
     *
     * @param pinCode PIN code to verify.
     * @return True only if the PIN is considered as weak.
     */
    public static boolean isWeakPINCode(String pinCode) {
        boolean isWeak = true;
        //Length is inferior to 6 positions
        //Use "Long.parseLong(pinCode)" to cause a NumberFormatException if the PIN is not a numeric one
        //and to ensure that the PIN is not only a sequence of zero
        if (pinCode != null && Long.parseLong(pinCode) > 0 && pinCode.trim().length() > 5) {
            //Contain only the same number
            String regex = String.format("^[%s]{%s}$", pinCode.charAt(0), pinCode.length());
            if (!Pattern.matches(regex, pinCode)) {
                //Contain sequence of following incremental or decremental numbers
                char previousChar = 'X';
                boolean containSequence = false;
                for (char c : pinCode.toCharArray()) {
                    if (previousChar != 'X') {
                        int previousNbr = Integer.parseInt(String.valueOf(previousChar));
                        int currentNbr = Integer.parseInt(String.valueOf(c));
                        if (currentNbr == (previousNbr - 1) || currentNbr == (previousNbr + 1)) {
                            containSequence = true;
                            break;
                        }
                    }
                    previousChar = c;
                }
                if (!containSequence) {
                    isWeak = false;
                }
            }
        }
        return isWeak;
    }

    /**
     * Apply a collection of validations on a Word 97-2003 (binary format) document file provided:<br>
     * - Real Microsoft Word 97-2003 document file.<br>
     * - No VBA Macro.<br>
     * - No embedded objects.<br>
     *
     * @param wordFilePath Filename of the Word document file to check.
     * @return True only if the file pass all validations.
     * @see "https://poi.apache.org/components/"
     * @see "https://poi.apache.org/components/document/"
     * @see "https://poi.apache.org/components/poifs/how-to.html"
     * @see "https://poi.apache.org/components/poifs/embeded.html"
     * @see "https://poi.apache.org/"
     * @see "https://mvnrepository.com/artifact/org.apache.poi/poi"
     */
    public static boolean isWord972003DocumentSafe(String wordFilePath) {
        boolean isSafe = false;
        try {
            File wordFile = new File(wordFilePath);
            if (wordFile.exists() && wordFile.canRead() && wordFile.isFile()) {
                //Step 1: Try to load the file, if its fail then it imply that is not a valid Word 97-2003 format file
                try (POIFSFileSystem fs = new POIFSFileSystem(wordFile)) {
                    //Step 2: Check if the document contains VBA macros, in our case is not allowed
                    VBAMacroReader macroReader = new VBAMacroReader(fs);
                    Map<String, String> macros = macroReader.readMacros();
                    if (macros == null || macros.isEmpty()) {
                        //Step 3: Check if the document contains any embedded objects, in our case is not allowed
                        //From POI documentation:
                        //Word normally stores embedded files in subdirectories of the ObjectPool directory, itself a subdirectory of the filesystem root.
                        //Typically, these subdirectories and named starting with an underscore, followed by 10 numbers.
                        final List<String> embeddedObjectFound = new ArrayList<>();
                        DirectoryEntry root = fs.getRoot();
                        if (root.getEntryCount() > 0) {
                            root.iterator().forEachRemaining(entry -> {
                                if ("ObjectPool".equalsIgnoreCase(entry.getName()) && entry instanceof DirectoryEntry) {
                                    DirectoryEntry objPoolDirectory = (DirectoryEntry) entry;
                                    if (objPoolDirectory.getEntryCount() > 0) {
                                        objPoolDirectory.iterator().forEachRemaining(objPoolDirectoryEntry -> {
                                            if (objPoolDirectoryEntry instanceof DirectoryEntry) {
                                                DirectoryEntry objPoolDirectoryEntrySubDirectoryEntry = (DirectoryEntry) objPoolDirectoryEntry;
                                                if (objPoolDirectoryEntrySubDirectoryEntry.getEntryCount() > 0) {
                                                    objPoolDirectoryEntrySubDirectoryEntry.forEach(objPoolDirectoryEntrySubDirectoryEntryEntry -> {
                                                        if (objPoolDirectoryEntrySubDirectoryEntryEntry.isDocumentEntry()) {
                                                            embeddedObjectFound.add(objPoolDirectoryEntrySubDirectoryEntryEntry.getName());
                                                        }
                                                    });
                                                }
                                            }
                                        });
                                    }
                                }
                            });
                        }
                        isSafe = embeddedObjectFound.isEmpty();
                    }
                }
            }
        } catch (Exception e) {
            isSafe = false;
        }
        return isSafe;
    }

    /**
     * Ensure that an XML file does not contain any External Entity, DTD or XInclude instructions.
     *
     * @param xmlFilePath Filename of the XML file to check.
     * @return True only if the file pass all validations.
     * @see "https://portswigger.net/web-security/xxe"
     * @see "https://cheatsheetseries.owasp.org/cheatsheets/XML_External_Entity_Prevention_Cheat_Sheet.html#java"
     * @see "https://docs.oracle.com/en/java/javase/13/security/java-api-xml-processing-jaxp-security-guide.html#GUID-82F8C206-F2DF-4204-9544-F96155B1D258"
     * @see "https://www.w3.org/TR/xinclude-11/"
     * @see "https://en.wikipedia.org/wiki/XInclude"
     */
    public static boolean isXMLSafe(String xmlFilePath) {
        boolean isSafe = false;
        try {
            File xmlFile = new File(xmlFilePath);
            if (xmlFile.exists() && xmlFile.canRead() && xmlFile.isFile()) {
                //Step 1a: Verify that the XML file content does not contain any XInclude instructions
                boolean containXInclude = Files.readAllLines(xmlFile.toPath()).stream().anyMatch(line -> line.toLowerCase(Locale.ROOT).contains(":include "));
                if (!containXInclude) {
                    //Step 1b: Parse the XML file, if an exception occur than it's imply that the XML specified is not a valid ones
                    //Create an XML document builder throwing Exception if a DOCTYPE instruction is present
                    DocumentBuilderFactory dbfInstance = DocumentBuilderFactory.newInstance();
                    dbfInstance.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
                    //Xerces 2 only
                    //dbfInstance.setFeature("http://xerces.apache.org/xerces2-j/features.html#disallow-doctype-decl",true);
                    dbfInstance.setXIncludeAware(false);
                    DocumentBuilder builder = dbfInstance.newDocumentBuilder();
                    //Parse the document
                    Document doc = builder.parse(xmlFile);
                    isSafe = (doc != null && doc.getDocumentElement() != null);
                }
            }
        } catch (Exception e) {
            isSafe = false;
        }
        return isSafe;
    }


    /**
     * Extract all URL links from a PDF file provided.<br>
     * This can be used to apply validation on a PDF against contained links.
     *
     * @param pdfFilePath pdfFilePath Filename of the PDF file to process.
     * @return A List of URL objects that is empty if no links is found.
     * @throws Exception If any error occurs during the processing of the PDF file.
     * @see "https://www.gushiciku.cn/pl/21KQ"
     * @see "https://pdfbox.apache.org/"
     * @see "https://mvnrepository.com/artifact/org.apache.pdfbox/pdfbox"
     */
    public static List<URL> extractAllPDFLinks(String pdfFilePath) throws Exception {
        final List<URL> links = new ArrayList<>();
        File pdfFile = new File(pdfFilePath);
        try (PDDocument document = Loader.loadPDF(pdfFile)) {
            PDDocumentCatalog documentCatalog = document.getDocumentCatalog();
            AnnotationFilter actionURIAnnotationFilter = new AnnotationFilter() {
                @Override
                public boolean accept(PDAnnotation annotation) {
                    boolean keep = false;
                    if (annotation instanceof PDAnnotationLink) {
                        keep = (((PDAnnotationLink) annotation).getAction() instanceof PDActionURI);
                    }
                    return keep;
                }
            };
            documentCatalog.getPages().forEach(page -> {
                try {
                    page.getAnnotations(actionURIAnnotationFilter).forEach(annotation -> {
                        PDActionURI linkAnnotation = (PDActionURI) ((PDAnnotationLink) annotation).getAction();
                        try {
                            URL urlObj = new URL(linkAnnotation.getURI());
                            if (!links.contains(urlObj)) {
                                links.add(urlObj);
                            }
                        } catch (MalformedURLException e) {
                            throw new RuntimeException(e);
                        }
                    });
                } catch (Exception e) {
                    throw new RuntimeException(e);
                }
            });
        }
        return links;
    }

    /**
     * Apply a collection of validations on a PDF file provided:<br>
     * - Real PDF file<br>
     * - No attachments.<br>
     * - No Javascript code.<br>
     * - No links using action of type URI/Launch/RemoteGoTo/ImportData.<br>
     *
     * @param pdfFilePath Filename of the PDF file to check.
     * @return True only if the file pass all validations.
     * @see "https://stackoverflow.com/a/36161267"
     * @see "https://www.gushiciku.cn/pl/21KQ"
     * @see "https://github.com/jonaslejon/malicious-pdf"
     * @see "https://pdfbox.apache.org/"
     * @see "https://mvnrepository.com/artifact/org.apache.pdfbox/pdfbox"
     */
    public static boolean isPDFSafe(String pdfFilePath) {
        boolean isSafe = false;
        try {
            File pdfFile = new File(pdfFilePath);
            if (pdfFile.exists() && pdfFile.canRead() && pdfFile.isFile()) {
                //Step 1: Try to load the file, if its fail then it imply that is not a valid PDF file
                try (PDDocument document = Loader.loadPDF(pdfFile)) {
                    //Step 2: Check if the file contains attached files, in our case is not allowed
                    PDDocumentCatalog documentCatalog = document.getDocumentCatalog();
                    PDDocumentNameDictionary namesDictionary = new PDDocumentNameDictionary(documentCatalog);
                    if (namesDictionary.getEmbeddedFiles() == null) {
                        //Step 3: Check if the file contains Javascript code, in our case is not allowed
                        if (namesDictionary.getJavaScript() == null) {
                            //Step 4: Check if the file contains links using action of type URI/Launch/RemoteGoTo/ImportData, in our case is not allowed
                            final List<Integer> notAllowedAnnotationCounterList = new ArrayList<>();
                            AnnotationFilter notAllowedAnnotationFilter = new AnnotationFilter() {
                                @Override
                                public boolean accept(PDAnnotation annotation) {
                                    boolean keep = false;
                                    if (annotation instanceof PDAnnotationLink) {
                                        PDAnnotationLink link = (PDAnnotationLink) annotation;
                                        PDAction action = link.getAction();
                                        if ((action instanceof PDActionURI) || (action instanceof PDActionLaunch) || (action instanceof PDActionRemoteGoTo) || (action instanceof PDActionImportData)) {
                                            keep = true;
                                        }
                                    }
                                    return keep;
                                }
                            };
                            documentCatalog.getPages().forEach(page -> {
                                try {
                                    notAllowedAnnotationCounterList.add(page.getAnnotations(notAllowedAnnotationFilter).size());
                                } catch (IOException e) {
                                    throw new RuntimeException(e);
                                }
                            });
                            if (notAllowedAnnotationCounterList.stream().reduce(0, Integer::sum) == 0) {
                                isSafe = true;
                            }
                        }
                    }
                }
            }
        } catch (Exception e) {
            isSafe = false;
        }
        return isSafe;
    }

    /**
     * Remove as much as possible metadata from the provided PDF document object.
     *
     * @param document PDFBox PDF document object on which metadata must be removed.
     * @see "https://gist.github.com/righettod/d7e07443c43d393a39de741a0d920069"
     * @see "https://pdfbox.apache.org/"
     * @see "https://mvnrepository.com/artifact/org.apache.pdfbox/pdfbox"
     */
    public static void clearPDFMetadata(PDDocument document) {
        if (document != null) {
            PDDocumentInformation infoEmpty = new PDDocumentInformation();
            document.setDocumentInformation(infoEmpty);
            PDMetadata newMetadataEmpty = new PDMetadata(document);
            document.getDocumentCatalog().setMetadata(newMetadataEmpty);
        }
    }


    /**
     * Validate that the URL provided is really a relative URL.
     *
     * @param targetUrl URL to validate.
     * @return True only if the file pass all validations.
     * @see "https://portswigger.net/web-security/ssrf"
     * @see "https://stackoverflow.com/q/6785442"
     */
    public static boolean isRelativeURL(String targetUrl) {
        boolean isValid = false;
        //Reject any URL encoded content and URL starting with a double slash
        //Reject any URL contains credentials or fragment to prevent potential bypasses
        String work = targetUrl;
        if (!work.contains("%") && !work.contains("@") && !work.contains("#") && !work.startsWith("//")) {
            //Creation of a URL object must fail
            try {
                new URL(work);
                isValid = false;
            } catch (MalformedURLException mf) {
                //Last check to be sure (for prod usage compile the pattern one time)
                isValid = Pattern.compile("^/[a-z0-9]+", Pattern.CASE_INSENSITIVE).matcher(work).find();
            }
        }
        return isValid;
    }

    /**
     * Apply a collection of validations on a ZIP file provided:<br>
     * - Real ZIP file<br>
     * - Contain less than a specified level of deepness.<br>
     * - Do not contain Zip-Slip entry path.<br>
     *
     * @param zipFilePath       Filename of the ZIP file to check.
     * @param maxLevelDeepness  Threshold of deepness above which a ZIP archive will be rejected.
     * @param rejectArchiveFile Flag to specify if presence of any archive entry will cause the rejection of the ZIP file.
     * @return True only if the file pass all validations.
     * @see "https://rules.sonarsource.com/java/type/Security%20Hotspot/RSPEC-5042"
     * @see "https://security.snyk.io/research/zip-slip-vulnerability"
     * @see "https://en.wikipedia.org/wiki/Zip_bomb"
     * @see "https://github.com/ptoomey3/evilarc"
     * @see "https://github.com/abdulfatir/ZipBomb"
     * @see "https://www.baeldung.com/cs/zip-bomb"
     * @see "https://thesecurityvault.com/attacks-with-zip-files-and-mitigations/"
     * @see "https://wiki.sei.cmu.edu/confluence/display/java/IDS04-J.+Safely+extract+files+from+ZipInputStream"
     */
    public static boolean isZIPSafe(String zipFilePath, int maxLevelDeepness, boolean rejectArchiveFile) {
        List<String> archiveExtensions = Arrays.asList("zip", "tar", "7z", "gz", "jar", "phar", "bz2", "tgz");
        boolean isSafe = false;
        try {
            File zipFile = new File(zipFilePath);
            if (zipFile.exists() && zipFile.canRead() && zipFile.isFile() && maxLevelDeepness > 0) {
                //Step 1: Try to load the file, if its fail then it imply that is not a valid ZIP file
                try (ZipFile zipArch = new ZipFile(zipFile)) {
                    //Step 2: Parse entries
                    long deepness = 0;
                    ZipEntry zipEntry;
                    String entryExtension;
                    String zipEntryName;
                    boolean validationsFailed = false;
                    Enumeration<? extends ZipEntry> entries = zipArch.entries();
                    while (entries.hasMoreElements()) {
                        zipEntry = entries.nextElement();
                        zipEntryName = zipEntry.getName();
                        entryExtension = zipEntryName.substring(zipEntryName.lastIndexOf(".") + 1).toLowerCase(Locale.ROOT).trim();
                        //Step 2a: Check if the current entry is an archive file
                        if (rejectArchiveFile && archiveExtensions.contains(entryExtension)) {
                            validationsFailed = true;
                            break;
                        }
                        //Step 2b: Check that level of deepness is inferior to the threshold specified
                        if (zipEntryName.contains("/")) {
                            //Determine deepness by inspecting the entry name.
                            //Indeed, folder will be represented like this: folder/folder/folder/
                            //So we can count the number of "/" to identify the deepness of the entry
                            deepness = zipEntryName.chars().filter(ch -> ch == '/').count();
                            if (deepness > maxLevelDeepness) {
                                validationsFailed = true;
                                break;
                            }
                        }
                        //Step 2c: Check if any entries match pattern of zip slip payload
                        if (zipEntryName.contains("..\\") || zipEntryName.contains("../")) {
                            validationsFailed = true;
                            break;
                        }
                    }
                    if (!validationsFailed) {
                        isSafe = true;
                    }
                }
            }
        } catch (Exception e) {
            isSafe = false;
        }
        return isSafe;
    }

    /**
     * Identify the mime type of the content specified (array of bytes).<br>
     * Note that it cannot be fully trusted (see the tweet '1595824709186519041' referenced), so, additional validations are required.
     *
     * @param content The content as an array of bytes.
     * @return The mime type in lower case or null if it cannot be identified.
     * @see "https://twitter.com/righettod/status/1595824709186519041"
     * @see "https://tika.apache.org/"
     * @see "https://mvnrepository.com/artifact/org.apache.tika/tika-core"
     * @see "https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types"
     * @see "https://www.iana.org/assignments/media-types/media-types.xhtml"
     */
    public static String identifyMimeType(byte[] content) {
        String mimeType = null;
        if (content != null && content.length > 0) {
            Detector detector = new DefaultDetector(MimeTypes.getDefaultMimeTypes());
            Metadata metadata = new Metadata();
            try {
                try (TemporaryResources temporaryResources = new TemporaryResources(); TikaInputStream tikaInputStream = TikaInputStream.get(new ByteArrayInputStream(content), temporaryResources, metadata)) {
                    MediaType mt = detector.detect(tikaInputStream, metadata);
                    if (mt != null) {
                        mimeType = mt.toString().toLowerCase(Locale.ROOT);
                    }
                }
            } catch (IOException ioe) {
                mimeType = null;
            }
        }
        return mimeType;
    }

    /**
     * Apply a collection of validations on a string expected to be an public IP address:<br>
     * - Is a valid IP v4 or v6 address.<br>
     * - Is public from an Internet perspective.<br><br>
     * <b>Note:</b> I often see missing such validation in the value read from HTTP request headers like "X-Forwarded-For" or "Forwarded".
     * <br>
     * <b>Note for IPv6:</b> I used documentation found so it is really experimental!
     *
     * @param ip String expected to be a valid IP address.
     * @return True only if the string pass all validations.
     * @see "https://commons.apache.org/proper/commons-validator/"
     * @see "https://commons.apache.org/proper/commons-validator/apidocs/org/apache/commons/validator/routines/InetAddressValidator.html"
     * @see "https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html"
     * @see "https://cheatsheetseries.owasp.org/assets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet_Orange_Tsai_Talk.pdf"
     * @see "https://cheatsheetseries.owasp.org/assets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet_SSRF_Bible.pdf"
     * @see "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For"
     * @see "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded"
     * @see "https://ipcisco.com/lesson/ipv6-address/"
     * @see "https://www.juniper.net/documentation/us/en/software/junos/interfaces-security-devices/topics/topic-map/security-interface-ipv4-ipv6-protocol.html"
     * @see "https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/net/InetAddress.html#getByName(java.lang.String)"
     * @see "https://www.arin.net/reference/research/statistics/address_filters/"
     * @see "https://en.wikipedia.org/wiki/Multicast_address"
     * @see "https://stackoverflow.com/a/5619409"
     * @see "https://www.ripe.net/media/documents/ipv6-address-types.pdf"
     * @see "https://www.iana.org/assignments/ipv6-unicast-address-assignments/ipv6-unicast-address-assignments.xhtml"
     * @see "https://developer.android.com/reference/java/net/Inet6Address"
     * @see "https://en.wikipedia.org/wiki/Unique_local_address"
     */
    public static boolean isPublicIPAddress(String ip) {
        boolean isValid = false;
        try {
            //Quick validation on the string itself based on characters used to compose an IP v4/v6 address
            if (Pattern.matches("[0-9a-fA-F:.]+", ip)) {
                //If OK then use the dedicated InetAddressValidator from Apache Commons Validator
                if (InetAddressValidator.getInstance().isValid(ip)) {
                    //If OK then validate that is an public IP address
                    //From Javadoc for "InetAddress.getByName": If a literal IP address is supplied, only the validity of the address format is checked.
                    InetAddress addr = InetAddress.getByName(ip);
                    isValid = (!addr.isAnyLocalAddress() && !addr.isLinkLocalAddress() && !addr.isLoopbackAddress() && !addr.isMulticastAddress() && !addr.isSiteLocalAddress());
                    //If OK and the IP is an V6 one then make additional validation because the built-in Java API will let pass some V6 IP
                    //For the prefix map, the start of the key indicates if the value is a regex or a string
                    if (isValid && (addr instanceof Inet6Address)) {
                        Map<String, String> prefixes = new HashMap<>();
                        prefixes.put("REGEX_LOOPBACK", "^(0|:)+1$");
                        prefixes.put("REGEX_UNIQUE-LOCAL-ADDRESSES", "^f(c|d)[a-f0-9]{2}:.*$");
                        prefixes.put("STRING_LINK-LOCAL-ADDRESSES", "fe80:");
                        prefixes.put("REGEX_TEREDO", "^2001:[0]*:.*$");
                        prefixes.put("REGEX_BENCHMARKING", "^2001:[0]*2:.*$");
                        prefixes.put("REGEX_ORCHID", "^2001:[0]*10:.*$");
                        prefixes.put("STRING_DOCUMENTATION", "2001:db8:");
                        prefixes.put("STRING_GLOBAL-UNICAST", "2000:");
                        prefixes.put("REGEX_MULTICAST", "^ff[0-9]{2}:.*$");
                        final List<Boolean> results = new ArrayList<>();
                        final String ipLower = ip.trim().toLowerCase(Locale.ROOT);
                        prefixes.forEach((addressType, expr) -> {
                            String exprLower = expr.trim().toLowerCase();
                            if (addressType.startsWith("STRING_")) {
                                results.add(ipLower.startsWith(exprLower));
                            } else {
                                results.add(Pattern.matches(exprLower, ipLower));
                            }
                        });
                        isValid = ((results.size() == prefixes.size()) && !results.contains(Boolean.TRUE));
                    }
                }
            }
        } catch (Exception e) {
            isValid = false;
        }
        return isValid;
    }

    /**
     * Compute a SHA256 hash from an input composed of a collection of strings.<br><br>
     * This method take care to build the source string in a way to prevent this source string to be prone to abuse targeting the different parts composing it.<br><br>
     * Example of possible abuse without precautions applied during the hash calculation logic:<br>
     * Hash of <code>SHA256("Hello", "My", "World!!!")</code> will be equals to the hash of <code>SHA256("Hell", "oMyW", "orld!!!")</code>.<br><br>
     * This method ensure that both hash above will be different.<br><br>
     * <b>Note:</b> The character <code>|</code> is used, as separator, of every parts so a part is not allowed to contains this character.
     *
     * @param parts Ordered list of strings to use to build the input string for which the hash must be computed on. No null value is accepted on object composing the collection.
     * @return The hash, as an array of bytes, to allow caller to convert it to the final representation wanted (HEX, Base64, etc.). If the collection passed is null or empty then the method return null.
     * @throws Exception If any exception occurs
     * @see "https://github.com/righettod/code-snippets-security-utils/issues/16"
     * @see "https://pentesterlab.com/badges/codereview"
     * @see "https://blog.trailofbits.com/2024/08/21/yolo-is-not-a-valid-hash-construction/"
     * @see "https://www.nist.gov/publications/sha-3-derived-functions-cshake-kmac-tuplehash-and-parallelhash"
     */
    public static byte[] computeHashNoProneToAbuseOnParts(List<String> parts) throws Exception {
        byte[] hash = null;
        String separator = "|";
        if (parts != null && !parts.isEmpty()) {
            //Ensure that not part is null
            if (parts.stream().anyMatch(Objects::isNull)) {
                throw new IllegalArgumentException("No part must be null!");
            }
            //Ensure that the separator is absent from every part
            if (parts.stream().anyMatch(part -> part.contains(separator))) {
                throw new IllegalArgumentException(String.format("The character '%s', used as parts separator, must be absent from every parts!", separator));
            }
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            final StringBuilder buffer = new StringBuilder(separator);
            parts.forEach(p -> {
                buffer.append(p).append(separator);
            });
            hash = digest.digest(buffer.toString().getBytes(StandardCharsets.UTF_8));
        }
        return hash;
    }

    /**
     * Ensure that an XML file only uses DTD/XSD references (called System Identifier) present in the allowed list provided.<br><br>
     * The code is based on the validation implemented into the OpenJDK 21, by the class <b><a href="https://github.com/openjdk/jdk/blob/jdk-21%2B35/src/java.prefs/share/classes/java/util/prefs/XmlSupport.java">java.util.prefs.XmlSupport</a></b>, in the method <b><a href="https://github.com/openjdk/jdk/blob/jdk-21%2B35/src/java.prefs/share/classes/java/util/prefs/XmlSupport.java#L240">loadPrefsDoc()</a></b>.<br><br>
     * The method also ensure that no Public Identifier is used to prevent potential bypasses of the validations.
     *
     * @param xmlFilePath              Filename of the XML file to check.
     * @param allowedSystemIdentifiers List of URL allowed for System Identifier specified for any XSD/DTD references.
     * @return True only if the file pass all validations.
     * @see "https://www.w3schools.com/xml/prop_documenttype_systemid.asp"
     * @see "https://www.ibm.com/docs/en/integration-bus/9.0.0?topic=doctypedecl-xml-systemid"
     * @see "https://www.liquid-technologies.com/Reference/Glossary/XML_DocType.html"
     * @see "https://www.xml.com/pub/98/08/xmlqna0.html"
     * @see "https://github.com/openjdk/jdk/blob/jdk-21%2B35/src/java.prefs/share/classes/java/util/prefs/XmlSupport.java#L397"
     * @see "https://en.wikipedia.org/wiki/Formal_Public_Identifier"
     */
    public static boolean isXMLOnlyUseAllowedXSDorDTD(String xmlFilePath, final List<String> allowedSystemIdentifiers) {
        boolean isSafe = false;
        final String errorTemplate = "Non allowed %s ID detected!";
        final String emptyFakeDTD = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><!ELEMENT dummy EMPTY>";
        final String emptyFakeXSD = "<xs:schema xmlns:xs=\"http://www.w3.org/2001/XMLSchema\"> <xs:element name=\"dummy\"/></xs:schema>";

        if (allowedSystemIdentifiers == null || allowedSystemIdentifiers.isEmpty()) {
            throw new IllegalArgumentException("At least one SID must be specified!");
        }
        File xmlFile = new File(xmlFilePath);
        if (xmlFile.exists() && xmlFile.canRead() && xmlFile.isFile()) {
            try {
                EntityResolver resolverValidator = (publicId, systemId) -> {
                    if (publicId != null) {
                        throw new SAXException(String.format(errorTemplate, "PUBLIC"));
                    }
                    if (!allowedSystemIdentifiers.contains(systemId)) {
                        throw new SAXException(String.format(errorTemplate, "SYSTEM"));
                    }
                    //If it is OK then return a empty DTD/XSD
                    return new InputSource(new StringReader(systemId.toLowerCase().endsWith(".dtd") ? emptyFakeDTD : emptyFakeXSD));
                };
                DocumentBuilderFactory dbfInstance = DocumentBuilderFactory.newInstance();
                dbfInstance.setIgnoringElementContentWhitespace(true);
                dbfInstance.setXIncludeAware(false);
                dbfInstance.setValidating(false);
                dbfInstance.setCoalescing(true);
                dbfInstance.setIgnoringComments(false);
                DocumentBuilder builder = dbfInstance.newDocumentBuilder();
                builder.setEntityResolver(resolverValidator);
                Document doc = builder.parse(xmlFile);
                isSafe = (doc != null);
            } catch (SAXException | IOException | ParserConfigurationException e) {
                isSafe = false;
            }
        }

        return isSafe;
    }

    /**
     * Apply a collection of validations on a EXCEL CSV file provided (file was expected to be opened in Microsoft EXCEL):<br>
     * - Real CSV file.<br>
     * - Do not contains any payload related to a CSV injections.<br><br>
     * Ensure that, if Apache Commons CSV does not find any record then, the file will be considered as NOT safe (prevent potential bypasses).<br><br>
     * <b>Note:</b> Record delimiter used is the <code>,</code> (comma) character. See the Apache Commons CSV reference provided for EXCEL.<br>
     *
     * @param csvFilePath Filename of the CSV file to check.
     * @return True only if the file pass all validations.
     * @see "https://commons.apache.org/proper/commons-csv/"
     * @see "https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html#EXCEL"
     * @see "https://www.we45.com/post/your-excel-sheets-are-not-safe-heres-how-to-beat-csv-injection"
     * @see "https://www.whiteoaksecurity.com/blog/2020-4-23-csv-injection-whats-the-risk/"
     * @see "https://book.hacktricks.xyz/pentesting-web/formula-csv-doc-latex-ghostscript-injection"
     * @see "https://owasp.org/www-community/attacks/CSV_Injection"
     * @see "https://payatu.com/blog/csv-injection-basic-to-exploit/"
     * @see "https://cwe.mitre.org/data/definitions/1236.html"
     */
    public static boolean isExcelCSVSafe(String csvFilePath) {
        boolean isSafe;
        final AtomicInteger recordCount = new AtomicInteger();
        final List<Character> payloadDetectionCharacters = List.of('=', '+', '@', '-', '\r', '\t');

        try {
            final List<String> payloadsIdentified = new ArrayList<>();
            try (Reader in = new FileReader(csvFilePath)) {
                Iterable<CSVRecord> records = CSVFormat.EXCEL.parse(in);
                records.forEach(record -> {
                    record.forEach(recordValue -> {
                        if (recordValue != null && !recordValue.trim().isEmpty() && payloadDetectionCharacters.contains(recordValue.trim().charAt(0))) {
                            payloadsIdentified.add(recordValue);
                        }
                        recordCount.getAndIncrement();
                    });
                });
            }
            isSafe = (payloadsIdentified.isEmpty() && recordCount.get() > 0);
        } catch (Exception e) {
            isSafe = false;
        }

        return isSafe;
    }

    /**
     * Provide a way to add an integrity marker (<a href="https://en.wikipedia.org/wiki/HMAC">HMAC</a>) to a serialized object serialized using the <a href="https://www.baeldung.com/java-serialization">java native system</a> (binary).<br>
     * The goal is to provide <b>a temporary workaround</b> to try to prevent deserialization attacks and give time to move to a text-based serialization approach.
     *
     * @param processingMode Define the mode of processing i.e. protect or validate. ({@link eu.righettod.ProcessingMode})
     * @param input          When the processing mode is "protect" than the expected input (string) is a java serialized object encoded in Base64 otherwise (processing mode is "validate") expected input is the output of this method when the "protect" mode was used.
     * @param secret         Secret to use to compute the SHA256 HMAC.
     * @return A map with the following keys: <ul><li><b>PROCESSING_MODE</b>: Processing mode used to compute the result.</li><li><b>STATUS</b>: A boolean indicating if the processing was successful or not.</li><li><b>RESULT</b>: Always contains a string representing the protected serialized object in the format <code>[SERIALIZED_OBJECT_BASE64_ENCODED]:[SERIALIZED_OBJECT_HMAC_BASE64_ENCODED]</code>.</li></ul>
     * @throws Exception If any exception occurs.
     * @see "https://cheatsheetseries.owasp.org/cheatsheets/Deserialization_Cheat_Sheet.html"
     * @see "https://owasp.org/www-project-top-ten/2017/A8_2017-Insecure_Deserialization"
     * @see "https://portswigger.net/web-security/deserialization"
     * @see "https://www.baeldung.com/java-serialization-approaches"
     * @see "https://www.baeldung.com/java-serialization"
     * @see "https://cryptobook.nakov.com/mac-and-key-derivation/hmac-and-key-derivation"
     * @see "https://en.wikipedia.org/wiki/HMAC"
     * @see "https://smattme.com/posts/how-to-generate-hmac-signature-in-java/"
     */
    public static Map<String, Object> ensureSerializedObjectIntegrity(ProcessingMode processingMode, String input, byte[] secret) throws Exception {
        Map<String, Object> results;
        String resultFormatTemplate = "%s:%s";
        //Verify input provided to be consistent
        if (processingMode == null) {
            throw new IllegalArgumentException("The processing mode is mandatory!");
        }
        if (input == null || input.trim().isEmpty()) {
            throw new IllegalArgumentException("Input data is mandatory!");
        }
        if (secret == null || secret.length == 0) {
            throw new IllegalArgumentException("The HMAC secret is mandatory!");
        }
        if (processingMode.equals(ProcessingMode.VALIDATE) && input.split(":").length != 2) {
            throw new IllegalArgumentException("Input data provided is invalid for the processing mode specified!");
        }
        //Processing
        Base64.Decoder b64Decoder = Base64.getDecoder();
        Base64.Encoder b64Encoder = Base64.getEncoder();
        String hmacAlgorithm = "HmacSHA256";
        Mac mac = Mac.getInstance(hmacAlgorithm);
        SecretKeySpec key = new SecretKeySpec(secret, hmacAlgorithm);
        mac.init(key);
        results = new HashMap<>();
        results.put("PROCESSING_MODE", processingMode.toString());
        switch (processingMode) {
            case PROTECT -> {
                byte[] objectBytes = b64Decoder.decode(input);
                byte[] hmac = mac.doFinal(objectBytes);
                String encodedHmac = b64Encoder.encodeToString(hmac);
                results.put("STATUS", Boolean.TRUE);
                results.put("RESULT", String.format(resultFormatTemplate, input, encodedHmac));
            }
            case VALIDATE -> {
                String[] parts = input.split(":");
                byte[] objectBytes = b64Decoder.decode(parts[0].trim());
                byte[] hmacProvided = b64Decoder.decode(parts[1].trim());
                byte[] hmacComputed = mac.doFinal(objectBytes);
                String encodedHmacComputed = b64Encoder.encodeToString(hmacComputed);
                Boolean hmacIsValid = Arrays.equals(hmacProvided, hmacComputed);
                results.put("STATUS", hmacIsValid);
                results.put("RESULT", String.format(resultFormatTemplate, parts[0].trim(), encodedHmacComputed));
            }
            default -> throw new IllegalArgumentException("Not supported processing mode!");
        }
        return results;
    }

    /**
     * Apply a collection of validations on a JSON string provided:<br>
     * - Real JSON structure.<br>
     * - Contain less than a specified number of deepness for nested objects or arrays.<br>
     * - Contain less than a specified number of items in any arrays.<br><br>
     *
     * <b>Note:</b> I decided to use a parsing approach using only string processing to prevent any StackOverFlow or OutOfMemory error that can be abused.<br><br>
     * I used the following assumption:
     * <ul>
     *      <li>The character <code>{</code> identify the beginning of an object.</li>
     *      <li>The character <code>}</code> identify the end of an object.</li>
     *      <li>The character <code>[</code> identify the beginning of an array.</li>
     *      <li>The character <code>]</code> identify the end of an array.</li>
     *      <li>The character <code>"</code> identify the delimiter of a string.</li>
     *      <li>The character sequence <code>\"</code> identify the escaping of an double quote.</li>
     * </ul>
     *
     * @param json                  String containing the JSON data to validate.
     * @param maxItemsByArraysCount Maximum number of items allowed in an array.
     * @param maxDeepnessAllowed    Maximum number nested objects or arrays allowed.
     * @return True only if the string pass all validations.
     * @see "https://javaee.github.io/jsonp/"
     * @see "https://community.f5.com/discussions/technicalforum/disable-buffer-overflow-in-json-parameters/124306"
     * @see "https://github.com/InductiveComputerScience/pbJson/issues/2"
     */
    public static boolean isJSONSafe(String json, int maxItemsByArraysCount, int maxDeepnessAllowed) {
        boolean isSafe = false;

        try {
            //Step 1: Analyse the JSON string
            int currentDeepness = 0;
            int currentArrayItemsCount = 0;
            int maxDeepnessReached = 0;
            int maxArrayItemsCountReached = 0;
            boolean currentlyInArray = false;
            boolean currentlyInString = false;
            int currentNestedArrayLevel = 0;
            String jsonEscapedDoubleQuote = "\\\"";//Escaped double quote must not be considered as a string delimiter
            String work = json.replace(jsonEscapedDoubleQuote, "'");
            for (char c : work.toCharArray()) {
                switch (c) {
                    case '{': {
                        if (!currentlyInString) {
                            currentDeepness++;
                        }
                        break;
                    }
                    case '}': {
                        if (!currentlyInString) {
                            currentDeepness--;
                        }
                        break;
                    }
                    case '[': {
                        if (!currentlyInString) {
                            currentDeepness++;
                            if (currentlyInArray) {
                                currentNestedArrayLevel++;
                            }
                            currentlyInArray = true;
                        }
                        break;
                    }
                    case ']': {
                        if (!currentlyInString) {
                            currentDeepness--;
                            currentArrayItemsCount = 0;
                            if (currentNestedArrayLevel > 0) {
                                currentNestedArrayLevel--;
                            }
                            if (currentNestedArrayLevel == 0) {
                                currentlyInArray = false;
                            }
                        }
                        break;
                    }
                    case '"': {
                        currentlyInString = !currentlyInString;
                        break;
                    }
                    case ',': {
                        if (!currentlyInString && currentlyInArray) {
                            currentArrayItemsCount++;
                        }
                        break;
                    }
                }
                if (currentDeepness > maxDeepnessReached) {
                    maxDeepnessReached = currentDeepness;
                }
                if (currentArrayItemsCount > maxArrayItemsCountReached) {
                    maxArrayItemsCountReached = currentArrayItemsCount;
                }
            }
            //Step 2: Apply validation against the value specified as limits
            isSafe = ((maxItemsByArraysCount > maxArrayItemsCountReached) && (maxDeepnessAllowed > maxDeepnessReached));

            //Step 3: If the content is safe then ensure that it is valid JSON structure using the "Java API for JSON Processing" (JSR 374) parser reference implementation.
            if (isSafe) {
                JsonReader reader = Json.createReader(new StringReader(json));
                isSafe = (reader.read() != null);
            }

        } catch (Exception e) {
            isSafe = false;
        }
        return isSafe;
    }

    /**
     * Apply a collection of validations on a image file provided:<br>
     * - Real image file.<br>
     * - Its mime type is into the list of allowed mime types.<br>
     * - Its metadata fields do not contains any characters related to a malicious payloads.<br>
     *
     * <br>
     * <b>Important note:</b> This implementation is prone to bypass using the "<b>raw insertion</b>" method documented in the <a href="https://www.synacktiv.com/en/publications/persistent-php-payloads-in-pngs-how-to-inject-php-code-in-an-image-and-keep-it-there">blog post</a> from the Synacktiv team.
     * To handle such case, it is recommended to resize the image to remove any non image-related content, see <a href="https://github.com/righettod/document-upload-protection/blob/master/src/main/java/eu/righettod/poc/sanitizer/ImageDocumentSanitizerImpl.java#L54">here</a> for an example.<br>
     *
     * @param imageFilePath         Filename of the image file to check.
     * @param imageAllowedMimeTypes List of image mime types allowed.
     * @return True only if the file pass all validations.
     * @see "https://commons.apache.org/proper/commons-imaging/"
     * @see "https://commons.apache.org/proper/commons-imaging/formatsupport.html"
     * @see "https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types"
     * @see "https://www.iana.org/assignments/media-types/media-types.xhtml#image"
     * @see "https://www.synacktiv.com/en/publications/persistent-php-payloads-in-pngs-how-to-inject-php-code-in-an-image-and-keep-it-there"
     * @see "https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html"
     * @see "https://github.com/righettod/document-upload-protection/blob/master/src/main/java/eu/righettod/poc/sanitizer/ImageDocumentSanitizerImpl.java"
     * @see "https://exiftool.org/examples.html"
     * @see "https://en.wikipedia.org/wiki/List_of_file_signatures"
     * @see "https://hexed.it/"
     * @see "https://github.com/sighook/pixload"
     */
    public static boolean isImageSafe(String imageFilePath, List<String> imageAllowedMimeTypes) {
        boolean isSafe = false;
        Pattern payloadDetectionRegex = Pattern.compile("[<>${}`]+", Pattern.CASE_INSENSITIVE);
        try {
            File imgFile = new File(imageFilePath);
            if (imgFile.exists() && imgFile.canRead() && imgFile.isFile() && !imageAllowedMimeTypes.isEmpty()) {
                final byte[] imgBytes = Files.readAllBytes(imgFile.toPath());
                //Step 1: Check the mime type of the file against the allowed ones
                ImageInfo imgInfo = Imaging.getImageInfo(imgBytes);
                if (imageAllowedMimeTypes.contains(imgInfo.getMimeType())) {
                    //Step 2: Load the image into an object using the Image API
                    BufferedImage imgObject = Imaging.getBufferedImage(imgBytes);
                    if (imgObject != null && imgObject.getWidth() > 0 && imgObject.getHeight() > 0) {
                        //Step 3: Check the metadata if the image format support it - Highly experimental
                        List<String> metadataWithPayloads = new ArrayList<>();
                        final ImageMetadata imgMetadata = Imaging.getMetadata(imgBytes);
                        if (imgMetadata != null) {
                            imgMetadata.getItems().forEach(item -> {
                                String metadata = item.toString();
                                if (payloadDetectionRegex.matcher(metadata).find()) {
                                    metadataWithPayloads.add(metadata);
                                }
                            });
                        }
                        isSafe = metadataWithPayloads.isEmpty();
                    }
                }
            }
        } catch (Exception e) {
            isSafe = false;
        }
        return isSafe;
    }

    /**
     * Rewrite the input file to remove any embedded files that is not embedded using a methods supported by the official format of the file.<br>
     * Example: a file can be embedded by adding it to the end of the source file, see the reference provided for details.
     *
     * @param inputFilePath Filename of the file to clean up.
     * @param inputFileType Type of the file provided.
     * @return A array of bytes with the cleaned file.
     * @throws IllegalArgumentException If an invalid parameter is passed
     * @throws Exception                If any technical error during the cleaning processing
     * @see "https://www.synacktiv.com/en/publications/persistent-php-payloads-in-pngs-how-to-inject-php-code-in-an-image-and-keep-it-there"
     * @see "https://github.com/righettod/toolbox-pentest-web/tree/master/misc"
     * @see "https://github.com/righettod/toolbox-pentest-web?tab=readme-ov-file#misc"
     * @see "https://stackoverflow.com/a/13605411"
     */
    public static byte[] sanitizeFile(String inputFilePath, InputFileType inputFileType) throws Exception {
        ByteArrayOutputStream sanitizedContent = new ByteArrayOutputStream();
        File inputFile = new File(inputFilePath);
        if (!inputFile.exists() || !inputFile.canRead() || !inputFile.isFile()) {
            throw new IllegalArgumentException("Cannot read the content of the input file!");
        }
        switch (inputFileType) {
            case PDF -> {
                try (PDDocument document = Loader.loadPDF(inputFile)) {
                    document.save(sanitizedContent);
                }
            }
            case IMAGE -> {
                // Load the original image
                BufferedImage originalImage = ImageIO.read(inputFile);
                String originalFormat = identifyMimeType(Files.readAllBytes(inputFile.toPath())).split("/")[1].trim();
                // Check that image has been successfully loaded
                if (originalImage == null) {
                    throw new IOException("Cannot load the original image !");
                }
                // Get current Width and Height of the image
                int originalWidth = originalImage.getWidth(null);
                int originalHeight = originalImage.getHeight(null);
                // Resize the image by removing 1px on Width and Height
                Image resizedImage = originalImage.getScaledInstance(originalWidth - 1, originalHeight - 1, Image.SCALE_SMOOTH);
                // Resize the resized image by adding 1px on Width and Height - In fact set image to is initial size
                Image initialSizedImage = resizedImage.getScaledInstance(originalWidth, originalHeight, Image.SCALE_SMOOTH);
                // Save image to a bytes buffer
                int bufferedImageType = BufferedImage.TYPE_INT_ARGB;//By default use a format supporting transparency
                if ("jpeg".equalsIgnoreCase(originalFormat) || "bmp".equalsIgnoreCase(originalFormat)) {
                    bufferedImageType = BufferedImage.TYPE_INT_RGB;
                }
                BufferedImage sanitizedImage = new BufferedImage(initialSizedImage.getWidth(null), initialSizedImage.getHeight(null), bufferedImageType);
                Graphics2D drawer = sanitizedImage.createGraphics();
                drawer.drawImage(initialSizedImage, 0, 0, null);
                drawer.dispose();
                ImageIO.write(sanitizedImage, originalFormat, sanitizedContent);
            }
            default -> throw new IllegalArgumentException("Type of file not supported !");
        }
        if (sanitizedContent.size() == 0) {
            throw new IOException("An error occur during the rewrite operation!");
        }
        return sanitizedContent.toByteArray();
    }

    /**
     * Apply a collection of validations on a string expected to be an email address:<br>
     * - Is a valid email address, from a parser perspective, following RFCs on email addresses.<br>
     * - Is not using "Encoded-word" format.<br>
     * - Is not using comment format.<br>
     * - Is not using "Punycode" format.<br>
     * - Is not using UUCP style addresses.<br>
     * - Is not using address literals.<br>
     * - Is not using source routes.<br>
     * - Is not using the "percent hack".<br><br>
     * This is based on the research work from <a href="https://portswigger.net/research/gareth-heyes">Gareth Heyes</a> added in references (Portswigger).<br><br>
     *
     * <b>Note:</b> The notion of valid, here, is to take from a secure usage of the data perspective.
     *
     * @param addr String expected to be a valid email address.
     * @return True only if the string pass all validations.
     * @see "https://commons.apache.org/proper/commons-validator/"
     * @see "https://commons.apache.org/proper/commons-validator/apidocs/org/apache/commons/validator/routines/EmailValidator.html"
     * @see "https://datatracker.ietf.org/doc/html/rfc2047#section-2"
     * @see "https://portswigger.net/research/splitting-the-email-atom"
     * @see "https://www.jochentopf.com/email/address.html"
     * @see "https://en.wikipedia.org/wiki/Email_address"
     */
    public static boolean isEmailAddress(String addr) {
        boolean isValid = false;
        String work = addr.toLowerCase(Locale.ROOT);
        Pattern encodedWordRegex = Pattern.compile("[=?]+", Pattern.CASE_INSENSITIVE);
        Pattern forbiddenCharacterRegex = Pattern.compile("[():!%\\[\\],;]+", Pattern.CASE_INSENSITIVE);
        try {
            //Start with the use of the dedicated EmailValidator from Apache Commons Validator
            if (EmailValidator.getInstance(true, true).isValid(work)) {
                //If OK then validate it does not contains "Encoded-word" patterns using an aggressive approach
                if (!encodedWordRegex.matcher(work).find()) {
                    //If OK then validate it does not contains punycode
                    if (!work.contains("xn--")) {
                        //If OK then validate it does not use:
                        // UUCP style addresses,
                        // Comment format,
                        // Address literals,
                        // Source routes,
                        // The percent hack.
                        if (!forbiddenCharacterRegex.matcher(work).find()) {
                            isValid = true;
                        }
                    }
                }
            }
        } catch (Exception e) {
            isValid = false;
        }
        return isValid;
    }

    /**
     * The <a href="https://www.stet.eu/en/psd2/">PSD2 STET</a> specification require to use <a href="https://datatracker.ietf.org/doc/draft-cavage-http-signatures/">HTTP Signature</a>.
     * <br>
     * Section <b>3.5.1.2</b> of the document <a href="https://www.stet.eu/assets/files/PSD2/1-6-3/api-dsp2-stet-v1.6.3.1-part-1-framework.pdf">Documentation Framework</a> version <b>1.6.3</b>.
     * <br>
     * The problem is that, by design, the HTTP Signature specification is prone to blind SSRF.
     * <br>
     * URL example taken from the STET specification: <code>https://path.to/myQsealCertificate_714f8154ec259ac40b8a9786c9908488b2582b68b17e865fede4636d726b709f</code>.
     * <br>
     * The objective of this code is to try to decrease the "exploitability/interest" of this SSRF for an attacker.
     *
     * @param certificateUrl Url pointing to a Qualified Certificate (QSealC) encoded in PEM format and respecting the ETSI/TS119495 technical Specification .
     * @return TRUE only if the url point to a Qualified Certificate in PEM format.
     * @see "https://www.stet.eu/en/psd2/"
     * @see "https://www.stet.eu/assets/files/PSD2/1-6-3/api-dsp2-stet-v1.6.3.1-part-1-framework.pdf"
     * @see "https://datatracker.ietf.org/doc/draft-cavage-http-signatures/"
     * @see "https://datatracker.ietf.org/doc/rfc9421/"
     * @see "https://openjdk.org/groups/net/httpclient/intro.html"
     * @see "https://docs.oracle.com/en/java/javase/21/docs/api/java.net.http/java/net/http/package-summary.html"
     * @see "https://portswigger.net/web-security/ssrf"
     * @see "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control"
     */
    public static boolean isPSD2StetSafeCertificateURL(String certificateUrl) {
        boolean isValid = false;
        long connectionTimeoutInSeconds = 10;
        String userAgent = "PSD2-STET-HTTPSignature-CertificateRequest";
        try {
            //1. Ensure that the URL end with the SHA-256 fingerprint encoded in HEX of the certificate like requested by STET
            if (certificateUrl != null && certificateUrl.lastIndexOf("_") != -1) {
                String digestPart = certificateUrl.substring(certificateUrl.lastIndexOf("_") + 1);
                if (Pattern.matches("^[0-9a-f]{64}$", digestPart)) {
                    //2. Ensure that the URL is a valid url by creating a instance of the class URI
                    URI uri = URI.create(certificateUrl);
                    //3. Require usage of HTTPS and reject any url containing query parameters
                    if ("https".equalsIgnoreCase(uri.getScheme()) && uri.getQuery() == null) {
                        //4. Perform a HTTP HEAD request in order to get the content type of the remote resource
                        //and limit the interest to use the SSRF because to pass the check the url need to:
                        //- Do not having any query parameters.
                        //- Use HTTPS protocol.
                        //- End with a string having the format "_[0-9a-f]{64}".
                        //- Trigger the malicious action that the attacker want but with a HTTP HEAD without any redirect and parameters.
                        HttpResponse<String> response;
                        try (HttpClient client = HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NEVER).build()) {
                            HttpRequest request = HttpRequest.newBuilder()
                                    .uri(uri)
                                    .timeout(Duration.ofSeconds(connectionTimeoutInSeconds))
                                    .method("HEAD", HttpRequest.BodyPublishers.noBody())
                                    .header("User-Agent", userAgent)//To provide an hint to the target about the initiator of the request
                                    .header("Cache-Control", "no-store, max-age=0")//To prevent caching issues or abuses
                                    .build();
                            response = client.send(request, HttpResponse.BodyHandlers.ofString());
                            if (response.statusCode() == 200) {
                                //5. Ensure that the response content type is "text/plain"
                                Optional<String> contentType = response.headers().firstValue("Content-Type");
                                isValid = (contentType.isPresent() && contentType.get().trim().toLowerCase(Locale.ENGLISH).startsWith("text/plain"));
                            }
                        }
                    }
                }
            }
        } catch (Exception e) {
            isValid = false;
        }
        return isValid;
    }


}