Verifier

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

provide.foundation.tools.verifier

Verifier Tool for Foundation.

Provides CLI commands for verifying checksums and digital signatures. Also provides ToolVerifier class for programmatic checksum verification.

Classes

ToolVerifier

Verify tool artifacts using checksums.

Provides checksum verification for downloaded tool artifacts, ensuring integrity before installation.

Functions

verify_checksum

verify_checksum(file_path: Path, expected: str) -> bool

Verify file checksum.

Parameters:

Name	Type	Description	Default
file_path	Path	Path to file to verify.	required
expected	str	Expected checksum in format "algorithm:hash" or just "hash" (defaults to sha256).	required

Returns:

Type	Description
bool	True if checksum matches, False otherwise.

Raises:

Type	Description
FileNotFoundError	If file doesn't exist.
ValueError	If checksum format is invalid.

Source code in provide/foundation/tools/verifier.py

def verify_checksum(self, file_path: Path, expected: str) -> bool:
    """Verify file checksum.

    Args:
        file_path: Path to file to verify.
        expected: Expected checksum in format "algorithm:hash" or just "hash" (defaults to sha256).

    Returns:
        True if checksum matches, False otherwise.

    Raises:
        FileNotFoundError: If file doesn't exist.
        ValueError: If checksum format is invalid.

    """
    if not file_path.exists():
        raise FileNotFoundError(f"File not found: {file_path}")

    log.debug(f"Verifying checksum for {file_path}")

    # Parse the checksum format
    if ":" in expected:
        algorithm, expected_hash = expected.split(":", 1)
    else:
        # Default to sha256 if no algorithm specified
        algorithm = "sha256"
        expected_hash = expected

    # Compute actual hash using Foundation's hash_file
    actual_hash = hash_file(file_path, algorithm=algorithm)

    matches = actual_hash == expected_hash

    if not matches:
        log.warning(
            f"Checksum mismatch for {file_path.name}",
            expected=expected_hash,
            actual=actual_hash,
            algorithm=algorithm,
        )

    return matches

VerificationError

VerificationError(
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any,
)

Bases: FoundationError

Raised when verification fails.

Source code in provide/foundation/errors/base.py

def __init__(
    self,
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any,
) -> None:
    self.message = message
    self.code = code or self._default_code()
    self.context = context or {}
    self.context.update(extra_context)
    self.cause = cause
    if cause:
        self.__cause__ = cause
    super().__init__(message)

Functions

verify_checksum_command

verify_checksum_command(
    hash: Annotated[
        str,
        "The expected checksum hash (e.g., 'sha256:...')",
    ],
    file: Annotated[
        Path | None,
        "Path to the file to verify (reads from stdin if not provided)",
    ] = None,
    algorithm: Annotated[
        str | None,
        "Explicitly specify the hash algorithm (e.g., 'sha256')",
    ] = None,
) -> None

Verify a file or stdin against a checksum.

Source code in provide/foundation/tools/verifier.py

@register_command("verify.checksum")
@requires_click
def verify_checksum_command(
    hash: Annotated[
        str,
        "The expected checksum hash (e.g., 'sha256:...')",
    ],
    file: Annotated[
        Path | None,
        "Path to the file to verify (reads from stdin if not provided)",
    ] = None,
    algorithm: Annotated[
        str | None,
        "Explicitly specify the hash algorithm (e.g., 'sha256')",
    ] = None,
) -> None:
    """Verify a file or stdin against a checksum."""
    data, error = _get_data_from_file_or_stdin(file)
    if error or data is None:
        perr(f"Error reading input: {error or 'No data'}", color="red")
        return

    try:
        if verify_checksum_with_hash(data, hash, algorithm):
            pout("✓ Checksum OK", color="green")
        else:
            perr("✗ Checksum MISMATCH", color="red")
    except VerificationError as e:
        perr(f"✗ Error: {e}", color="red")

verify_checksum_with_hash

verify_checksum_with_hash(
    data: bytes,
    expected_hash: str,
    algorithm: str | None = None,
) -> bool

Verify data against a given hash string.

Raises:

Type	Description
VerificationError	If algorithm is invalid or verification fails due to error conditions

Source code in provide/foundation/tools/verifier.py

def verify_checksum_with_hash(
    data: bytes,
    expected_hash: str,
    algorithm: str | None = None,
) -> bool:
    """Verify data against a given hash string.

    Raises:
        VerificationError: If algorithm is invalid or verification fails due to error conditions
    """
    supported_algorithms = ["sha256", "sha512", "blake2b", "blake2s", "md5", "adler32"]

    # Validate algorithm first if explicitly provided
    if algorithm:
        if algorithm not in supported_algorithms:
            raise VerificationError(
                f"Checksum verification failed: Unknown checksum algorithm: {algorithm}. "
                f"Supported: {', '.join(supported_algorithms)}"
            )
        checksum_str = f"{algorithm}:{expected_hash}"
    elif ":" not in expected_hash:
        # Default to sha256 if no algorithm prefix provided
        checksum_str = f"sha256:{expected_hash}"
    else:
        # Already has algorithm prefix - validate it
        if ":" in expected_hash:
            alg = expected_hash.split(":", 1)[0]
            if alg not in supported_algorithms:
                raise VerificationError(
                    f"Checksum verification failed: Unknown checksum algorithm: {alg}. "
                    f"Supported: {', '.join(supported_algorithms)}"
                )
        checksum_str = expected_hash

    try:
        return verify_checksum(data, checksum_str)
    except Exception as e:
        raise VerificationError(f"Checksum verification failed: {e}", cause=e) from e

verify_signature_command

verify_signature_command(
    signature: Annotated[
        str, "The base64-encoded signature to verify"
    ],
    key: Annotated[
        str,
        "The base64-encoded public key for verification",
    ],
    file: Annotated[
        Path | None,
        "Path to the file to verify (reads from stdin if not provided)",
    ] = None,
) -> None

Verify a digital signature for a file or stdin.

Source code in provide/foundation/tools/verifier.py

@register_command("verify.signature")
@requires_click
def verify_signature_command(
    signature: Annotated[
        str,
        "The base64-encoded signature to verify",
    ],
    key: Annotated[
        str,
        "The base64-encoded public key for verification",
    ],
    file: Annotated[
        Path | None,
        "Path to the file to verify (reads from stdin if not provided)",
    ] = None,
) -> None:
    """Verify a digital signature for a file or stdin."""
    data, error = _get_data_from_file_or_stdin(file)
    if error or data is None:
        perr(f"Error reading input: {error or 'No data'}", color="red")
        return

    try:
        if verify_signature_with_key(data, signature, key):
            pout("✓ Signature VERIFIED", color="green")
        else:
            # The function raises on failure, so this path is unlikely
            perr("✗ Signature INVALID", color="red")
    except VerificationError as e:
        perr(f"✗ Signature INVALID: {e}", color="red")

verify_signature_with_key

verify_signature_with_key(
    data: bytes, signature_b64: str, public_key_b64: str
) -> bool

Verify a signature using a public key.

Source code in provide/foundation/tools/verifier.py

def verify_signature_with_key(
    data: bytes,
    signature_b64: str,
    public_key_b64: str,
) -> bool:
    """Verify a signature using a public key."""
    try:
        signature = base64.b64decode(signature_b64)
        public_key = base64.b64decode(public_key_b64)
        verifier = Ed25519Verifier(public_key)
        is_valid = verifier.verify(data, signature)
        if not is_valid:
            raise VerificationError("Signature verification failed: Invalid signature")
        return True
    except VerificationError:
        # Re-raise VerificationError as-is
        raise
    except Exception as e:
        # This will catch decoding errors and other exceptions
        raise VerificationError(f"Signature verification failed: {e}", cause=e) from e