Bcrypt Password Hasher (python, written by Claude Code)

Claude Code wrote this python project from the task below. It installed and ran on a clean Ubuntu 22.04 machine as written.

Task given to the agent:

TASK: Bcrypt Password Hasher

Write a program that hashes and verifies passwords using the bcrypt algorithm with configurable work factors, supporting bulk operations, migration from weaker hashing schemes, and password policy enforcement.

FUNCTIONAL REQUIREMENTS:
- Support subcommands: hash (hash a password), verify (check a password against a hash), benchmark (test hashing speed at different work factors), and migrate (rehash from MD5/SHA-256 to bcrypt)
- hash: Accept a password via command-line argument or stdin, hash it with bcrypt, and print the resulting hash string
- verify: Accept a password and a bcrypt hash string, verify the match, and print whether it is valid or invalid
- Support a configurable work factor (cost parameter) via --cost flag (default 12, range 4-31)
- benchmark: Measure and display the time to hash a password at each work factor from 8 to the specified maximum, helping users choose an appropriate cost
- migrate: Read a CSV file with columns (username, old_hash, hash_type), verify that the old hash matches a provided password, then rehash with bcrypt and output the updated CSV
- Support batch hashing via --file flag: read one password per line, hash each, and output as a CSV with columns (line_number, hash)
- Generate a cryptographically secure random salt for each hash operation (built into bcrypt)
- Print detailed output: the hash, work factor used, estimated time per hash, and the bcrypt version identifier ($2b$)
- Save results to a file via --output flag (default: print to console only)
- If no arguments are given, demonstrate hashing a sample password at three different work factors (10, 12, 14), verify each hash, show a failed verification with a wrong password, and run a mini benchmark
- Handle errors: invalid cost factors, malformed hash strings, empty passwords, and unsupported hash types in migration

Create a complete Python project for a clean Ubuntu 22.04 machine with only Python 3.10+ installed. Include:
- Source code
- requirements.txt with all dependencies (direct and transitive) pinned to exact versions
- README.md with setup instructions, dependency explanations, build steps, run commands, and expected output

[]

#!/usr/bin/env python3
"""
Bcrypt Password Hasher

Hashes and verifies passwords using bcrypt with configurable work factors,
benchmarking capabilities, and migration support for upgrading hash strength.
"""

import bcrypt
import time
import sys
import json
from dataclasses import dataclass, asdict
from typing import Optional


@dataclass
class HashResult:
    """Represents the result of a hashing operation."""
    hashed: str
    work_factor: int
    elapsed_ms: float


@dataclass
class BenchmarkResult:
    """Represents the result of a benchmark run."""
    work_factor: int
    avg_hash_ms: float
    avg_verify_ms: float
    iterations: int


class BcryptHasher:
    """
    A bcrypt-based password hasher with configurable work factors,
    benchmarking, and migration support.
    """

    DEFAULT_WORK_FACTOR = 12
    MIN_WORK_FACTOR = 4
    MAX_WORK_FACTOR = 31

    def __init__(self, work_factor: int = DEFAULT_WORK_FACTOR):
        """
        Initialize the hasher with a specific work factor (cost).

        Args:
            work_factor: The bcrypt cost parameter (log2 of iterations).
                         Must be between 4 and 31.
        """
        self._validate_work_factor(work_factor)
        self.work_factor = work_factor

    def _validate_work_factor(self, work_factor: int) -> None:
        """Validate that the work factor is within acceptable bounds."""
        if not isinstance(work_factor, int):
            raise TypeError(f"Work factor must be an integer, got {type(work_factor).__name__}")
        if work_factor < self.MIN_WORK_FACTOR or work_factor > self.MAX_WORK_FACTOR:
            raise ValueError(
                f"Work factor must be between {self.MIN_WORK_FACTOR} and "
                f"{self.MAX_WORK_FACTOR}, got {work_factor}"
            )

    def hash_password(self, password: str) -> HashResult:
        """
        Hash a password using bcrypt with the configured work factor.

        Args:
            password: The plaintext password to hash.

        Returns:
            A HashResult containing the hash, work factor, and timing info.
        """
        if not password:
            raise ValueError("Password cannot be empty")

        start = time.perf_counter()
        salt = bcrypt.gensalt(rounds=self.work_factor)
        hashed = bcrypt.hashpw(password.encode("utf-8"), salt)
        elapsed_ms = (time.perf_counter() - start) * 1000

        return HashResult(
            hashed=hashed.decode("utf-8"),
            work_factor=self.work_factor,
            elapsed_ms=round(elapsed_ms, 2),
        )

    def verify_password(self, password: str, hashed: str) -> bool:
        """
        Verify a password against a bcrypt hash.

        Args:
            password: The plaintext password to verify.
            hashed: The bcrypt hash to check against.

        Returns:
            True if the password matches, False otherwise.
        """
        if not password or not hashed:
            raise ValueError("Password and hash cannot be empty")

        try:
            return bcrypt.checkpw(
                password.encode("utf-8"),
                hashed.encode("utf-8") if isinstance(hashed, str) else hashed,
            )
        except (ValueError, TypeError):
            return False

    def extract_work_factor(self, hashed: str) -> int:
        """
        Extract the work factor (cost) from an existing bcrypt hash.

        Args:
            hashed: A bcrypt hash string.

        Returns:
            The work factor used to create the hash.
        """
        try:
            parts = hashed.split("$")
            if len(parts) >= 4:
                return int(parts[2])
        except (ValueError, IndexError):
            pass
        raise ValueError(f"Cannot extract work factor from hash: {hashed[:20]}...")

    def needs_migration(self, hashed: str) -> bool:
        """
        Check if a hash needs to be re-hashed with the current work factor.

        Args:
            hashed: An existing bcrypt hash.

        Returns:
            True if the hash uses a different (lower) work factor than configured.
        """
        try:
            existing_factor = self.extract_work_factor(hashed)
            return existing_factor < self.work_factor
        except ValueError:
            return True

    def migrate_hash(self, password: str, old_hash: str) -> Optional[HashResult]:
        """
        Migrate a password hash to the current work factor if needed.

        First verifies the password against the old hash, then re-hashes
        with the current work factor if the old hash uses a weaker factor.

        Args:
            password: The plaintext password.
            old_hash: The existing bcrypt hash.

        Returns:
            A new HashResult if migration was performed, None otherwise.
        """
        if not self.verify_password(password, old_hash):
            raise ValueError("Password does not match the provided hash")

        if self.needs_migration(old_hash):
            return self.hash_password(password)
        return None

    def benchmark(self, iterations: int = 5) -> list[BenchmarkResult]:
        """
        Benchmark hashing and verification across a range of work factors.

        Args:
            iterations: Number of iterations per work factor for averaging.

        Returns:
            A list of BenchmarkResult objects for each tested work factor.
        """
        if iterations < 1:
            raise ValueError("Iterations must be at least 1")

        test_password = "BenchmarkPassword!123"
        results = []

        # Benchmark work factors from 4 to min(current + 2, 16) for practicality
        max_factor = min(self.work_factor + 2, 16)
        for wf in range(self.MIN_WORK_FACTOR, max_factor + 1):
            hash_times = []
            verify_times = []

            for _ in range(iterations):
                # Time hashing
                start = time.perf_counter()
                salt = bcrypt.gensalt(rounds=wf)
                hashed = bcrypt.hashpw(test_password.encode("utf-8"), salt)
                hash_times.append((time.perf_counter() - start) * 1000)

                # Time verification
                start = time.perf_counter()
                bcrypt.checkpw(test_password.encode("utf-8"), hashed)
                verify_times.append((time.perf_counter() - start) * 1000)

            results.append(BenchmarkResult(
                work_factor=wf,
                avg_hash_ms=round(sum(hash_times) / len(hash_times), 2),
                avg_verify_ms=round(sum(verify_times) / len(verify_times), 2),
                iterations=iterations,
            ))

        return results


def main():
    """Command-line interface for the bcrypt password hasher."""
    import argparse

    parser = argparse.ArgumentParser(
        description="Bcrypt Password Hasher - hash, verify, benchmark, and migrate passwords"
    )
    subparsers = parser.add_subparsers(dest="command", help="Available commands")

    # Hash command
    hash_parser = subparsers.add_parser("hash", help="Hash a password")
    hash_parser.add_argument("password", help="Password to hash")
    hash_parser.add_argument(
        "-w", "--work-factor", type=int, default=12,
        help="Bcrypt work factor / cost (default: 12)"
    )

    # Verify command
    verify_parser = subparsers.add_parser("verify", help="Verify a password against a hash")
    verify_parser.add_argument("password", help="Password to verify")
    verify_parser.add_argument("hash", help="Bcrypt hash to verify against")

    # Benchmark command
    bench_parser = subparsers.add_parser("benchmark", help="Benchmark bcrypt work factors")
    bench_parser.add_argument(
        "-w", "--work-factor", type=int, default=12,
        help="Maximum work factor to benchmark up to (default: 12)"
    )
    bench_parser.add_argument(
        "-i", "--iterations", type=int, default=3,
        help="Number of iterations per work factor (default: 3)"
    )

    # Migrate command
    migrate_parser = subparsers.add_parser("migrate", help="Check/perform hash migration")
    migrate_parser.add_argument("password", help="Password to migrate")
    migrate_parser.add_argument("hash", help="Existing bcrypt hash")
    migrate_parser.add_argument(
        "-w", "--work-factor", type=int, default=12,
        help="Target work factor for migration (default: 12)"
    )

    args = parser.parse_args()

    if args.command == "hash":
        hasher = BcryptHasher(work_factor=args.work_factor)
        result = hasher.hash_password(args.password)
        print(json.dumps(asdict(result), indent=2))

    elif args.command == "verify":
        hasher = BcryptHasher()
        is_valid = hasher.verify_password(args.password, args.hash)
        print(json.dumps({"valid": is_valid}, indent=2))
        sys.exit(0 if is_valid else 1)

    elif args.command == "benchmark":
        hasher = BcryptHasher(work_factor=args.work_factor)
        results = hasher.benchmark(iterations=args.iterations)
        print(json.dumps([asdict(r) for r in results], indent=2))

    elif args.command == "migrate":
        hasher = BcryptHasher(work_factor=args.work_factor)
        if hasher.needs_migration(args.hash):
            result = hasher.migrate_hash(args.password, args.hash)
            if result:
                print(json.dumps({"migrated": True, **asdict(result)}, indent=2))
            else:
                print(json.dumps({"migrated": False}, indent=2))
        else:
            print(json.dumps({"migrated": False, "reason": "Hash already at target strength"}, indent=2))

    else:
        parser.print_help()
        sys.exit(1)


if __name__ == "__main__":
    main()

# Bcrypt Password Hasher (Python - Trial 1)

A password hashing utility using bcrypt with configurable work factors, benchmarking, and hash migration support.

## Dependencies

- **bcrypt** (4.1.2): Core bcrypt hashing library

## Installation

```bash
pip install -r requirements.txt
```

## Usage

### Hash a password
```bash
python hasher.py hash "mypassword" -w 12
```

### Verify a password
```bash
python hasher.py verify "mypassword" "$2b$12$..."
```

### Benchmark work factors
```bash
python hasher.py benchmark -w 14 -i 5
```

### Migrate a hash to a stronger work factor
```bash
python hasher.py migrate "mypassword" "$2b$10$..." -w 12
```

## Features

- Configurable bcrypt work factor (cost parameter 4-31)
- Password hashing and verification
- Benchmark mode to compare work factor performance
- Hash migration to upgrade weaker hashes to stronger work factors
- JSON output for easy integration

bcrypt==4.1.2