Add core functionality for password hashing and cracking utilities

- Implemented Argon2id, bcrypt, and scrypt hashing algorithms with verification.
- Created a unified CLI for hashing and attack demos.
- Developed rainbow table functionality for MD5 hashes.
- Added dictionary attack logic for password verification.
- Introduced modules for managing hash records and wordlists.
- Included tests for hashing, rainbow table operations, and record management.
- Added example usage and documentation in README.md.
- Established project structure with pyproject.toml and requirements files.

Author: SagarBiswas-MultiHAT

.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.md]
+indent_size = 2
+trim_trailing_whitespace = false

.github/workflows/python-ci.yml

@@ -0,0 +1,32 @@
+name: python-ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest

.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+dist/
+build/
+hash_password_cracker/tempCodeRunnerFile.py
+tempCodeRunnerFile.py
+hash_records.json
+hash_records*.json

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing Guide
+
+Thanks for your interest in improving this project. This repository is intentionally simple and educational, so clarity matters more than cleverness.
+
+## Quick start
+
+1. Create a virtual environment and install dev dependencies:
+
+```bash
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -r requirements-dev.txt
+```
+
+2. Run tests and lint:
+
+```bash
+pytest
+ruff check .
+```
+
+## Coding principles
+
+- Prefer clear, readable code over clever optimizations.
+- Keep the educational intent intact: explain why, not just how.
+- Avoid changing defaults unless you also update docs and tests.
+
+## Adding new features
+
+If you add a new feature:
+
+- Add tests in `tests/`
+- Update `README.md` and any relevant script docs
+- Keep CLI behavior backward compatible where possible
+
+## Reporting issues
+
+If you find a bug or unclear behavior, open an issue with:
+
+- The script or function name
+- The exact input used
+- The observed output
+- The expected output

DeepDriveForLearners/DictionaryToBuildaRainbowTable.py

@@ -0,0 +1,47 @@
+"""Educational demo: build a tiny rainbow table from a small dictionary.
+
+This demonstrates why unsalted, fast hashes (like MD5) are dangerous.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Iterable
+
+
+def build_rainbow_table(words: Iterable[str]) -> dict[str, str]:
+    """Return a mapping of md5_hash -> plaintext."""
+    table: dict[str, str] = {}
+    for word in words:
+        md5_hash = hashlib.md5(word.encode("utf-8")).hexdigest()
+        table[md5_hash] = word
+    return table
+
+
+def main() -> None:
+    dictionary = ["123456", "password", "qwerty", "letmein", "admin"]
+
+    print("Building rainbow table from a tiny dictionary...")
+    table = build_rainbow_table(dictionary)
+
+    print("\nRainbow table entries (md5 -> plaintext):")
+    for md5_hash, word in table.items():
+        print(f"{md5_hash} : {word}")
+
+    stolen_password = "qwerty"
+    stolen_hash = hashlib.md5(stolen_password.encode("utf-8")).hexdigest()
+
+    print("\nSimulated stolen hash:")
+    print(stolen_hash)
+
+    recovered = table.get(stolen_hash)
+    if recovered:
+        print(f"\nPassword cracked! Plaintext is: {recovered}")
+    else:
+        print("\nPassword not found in the rainbow table.")
+
+    print("\nKey lesson: MD5 is fast and unsalted, so rainbow tables can crack it quickly.")
+
+
+if __name__ == "__main__":
+    main()

DeepDriveForLearners/SaltedVsUnsaltedDemo.py

@@ -0,0 +1,43 @@
+"""Educational demo: salted vs unsalted hashes.
+
+This is not a password storage recommendation. It only shows why salts matter.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def main() -> None:
+    password = "password123"
+
+    unsalted_1 = sha256_hex(password.encode("utf-8"))
+    unsalted_2 = sha256_hex(password.encode("utf-8"))
+
+    salt_a = os.urandom(16)
+    salt_b = os.urandom(16)
+
+    salted_1 = sha256_hex(salt_a + password.encode("utf-8"))
+    salted_2 = sha256_hex(salt_b + password.encode("utf-8"))
+
+    print("Password:", password)
+    print("\nUnsalted hash 1:")
+    print(unsalted_1)
+    print("Unsalted hash 2:")
+    print(unsalted_2)
+
+    print("\nSalted hash 1 (salt A):")
+    print(salted_1)
+    print("Salted hash 2 (salt B):")
+    print(salted_2)
+
+    print("\nKey lesson: salting makes identical passwords hash differently.")
+
+
+if __name__ == "__main__":
+    main()

DeepDriveForLearners/WhyRainbowTablesFailwithArgon2id.py

@@ -0,0 +1,29 @@
+"""Educational demo: why rainbow tables fail against Argon2id.
+
+Argon2id uses a random salt, so the same password produces different hashes.
+"""
+
+from __future__ import annotations
+
+from argon2 import PasswordHasher
+
+
+def main() -> None:
+    ph = PasswordHasher(time_cost=3, memory_cost=65536, parallelism=4)
+
+    password = "password123"
+    hash1 = ph.hash(password)
+    hash2 = ph.hash(password)
+
+    print("Password:", password)
+    print("\nHash 1:")
+    print(hash1)
+    print("\nHash 2:")
+    print(hash2)
+
+    print("\nEven though the password is the same, the hashes are different.")
+    print("That's the salt doing its job, which breaks rainbow tables.")
+
+
+if __name__ == "__main__":
+    main()

DeepDriveForLearners/readme.md

@@ -0,0 +1,23 @@
+# DeepDriveForLearners
+
+This folder contains small, focused learning scripts. Each file is short on purpose so you can read it in a few minutes and understand the concept.
+
+## Scripts
+
+- `DictionaryToBuildaRainbowTable.py`: Builds a tiny rainbow table from a small dictionary and cracks a simulated MD5 hash.
+- `WhyRainbowTablesFailwithArgon2id.py`: Shows that the same password produces different Argon2id hashes because of random salt.
+- `SaltedVsUnsaltedDemo.py`: Demonstrates how salting changes hashes even when the password is the same.
+
+## How to run
+
+From the project root:
+
+```bash
+python DeepDriveForLearners\DictionaryToBuildaRainbowTable.py
+python DeepDriveForLearners\WhyRainbowTablesFailwithArgon2id.py
+python DeepDriveForLearners\SaltedVsUnsaltedDemo.py
+```
+
+## Learning goal
+
+These are conceptual demos, not production patterns. They exist to help you internalize why modern password hashing uses salt and cost factors.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hash Password Cracker Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.