Package com.intsof.ai.build.integrity

Class ArtifactDigestsUtils

java.lang.Object

com.intsof.ai.build.integrity.ArtifactDigestsUtils

public final class ArtifactDigestsUtils
extends Object

Utility methods for artifact digest computation, artifact discovery, and path validation.

Unlike HashUtils which supports line-ending normalization for text files, this class provides streaming-only hash computation suitable for binary artifacts (JARs, WARs, ZIPs). Binary artifacts must never be loaded into heap memory in their entirety.

All methods are designed to be fast and allocation-light for use in large multi-module project builds.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ArtifactDigestsUtils.PathTraversalException	Exception thrown when a path traversal attack is detected.

Method Summary

Modifier and Type	Method	Description
static String	bytesToHex(byte[] bytes)	Converts a byte array to a lowercase hexadecimal string using a lookup table.
static String	computeHashStreaming(Path file, String algorithm)	Computes the hash of a file using the specified algorithm using streaming only.
static String	extensionForAlgorithm(String algorithm)	Returns the conventional file extension for a given hash algorithm (e.g. ".sha256", ".md5").
static boolean	isCompromisedAlgorithm(String algorithm)	Checks whether a given algorithm name is considered compromised.
static void	validateAlgorithm(String algorithm)	Validates that an algorithm is available in the current JVM's MessageDigest provider.
static Path	validateArtifactPath(Path artifactPath, Path buildDirectory)	Validates that an artifact path is within the project's build directory using canonical path enforcement.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isCompromisedAlgorithm

public static boolean isCompromisedAlgorithm(String algorithm)

Checks whether a given algorithm name is considered compromised.

Parameters:

algorithm - the algorithm name (e.g. "MD5", "SHA-1")

Returns:

true if the algorithm is compromised and requires explicit opt-in

validateAlgorithm

public static void validateAlgorithm(String algorithm)
                              throws NoSuchAlgorithmException

Validates that an algorithm is available in the current JVM's MessageDigest provider.

Parameters:

algorithm - the JCA algorithm name (e.g. "SHA-256", "MD5")

Throws:

NoSuchAlgorithmException - if the algorithm is not available

extensionForAlgorithm

public static String extensionForAlgorithm(String algorithm)

Returns the conventional file extension for a given hash algorithm (e.g. ".sha256", ".md5").

Parameters:

algorithm - the JCA algorithm name (e.g. "SHA-256", "MD5")

Returns:

the extension string including the leading dot (e.g. ".sha256")

computeHashStreaming

public static String computeHashStreaming(Path file,
                                          String algorithm)
                                   throws IOException,
                                          NoSuchAlgorithmException

Computes the hash of a file using the specified algorithm using streaming only. This method never loads the entire file into memory, making it safe for binary artifacts of any size.

Security note: This method does not perform line-ending normalization. For binary artifacts (JAR, WAR, ZIP), this is the correct behavior.

Parameters:

file - the file to hash

algorithm - the JCA algorithm name (e.g. "SHA-256", "MD5")

Returns:

the lowercase hex-encoded hash string

Throws:

IOException - if the file cannot be read

NoSuchAlgorithmException - if the algorithm is not available

validateArtifactPath

public static Path validateArtifactPath(Path artifactPath,
                                        Path buildDirectory)
                                 throws IOException

Validates that an artifact path is within the project's build directory using canonical path enforcement. This prevents path traversal attacks where an artifact symlink points outside the intended directory.

Implementation:

1. Resolve the artifact path using NOFOLLOW_LINKS to avoid following symlinks during resolution
2. If the path is a symlink, inspect the link target using Files.readSymbolicLink(java.nio.file.Path)
3. Verify the canonical path is a descendant of buildDirectory

Parameters:

artifactPath - the path to the artifact

buildDirectory - the project's build directory (e.g. target/)

Returns:

the validated canonical path

Throws:

ArtifactDigestsUtils.PathTraversalException - if the path escapes the build directory

IOException - if an I/O error occurs during path resolution

bytesToHex

public static String bytesToHex(byte[] bytes)

Converts a byte array to a lowercase hexadecimal string using a lookup table. This is significantly faster than String.format("%02x") per byte.

Parameters:

bytes - the bytes to encode

Returns:

the hex-encoded string