Metadata-Version: 2.4
Name: db-hash-utils
Version: 1.0.2
Summary: A lightweight, high-performance toolkit for database record hashing, integrity validation, and secure password stretching.
Author-email: Database Core Infrastructure Team <db-integrity-dev@posix-core.org>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pycryptodome>=3.19.0
Dynamic: license-file

# DB-Hash-Utils

A high-performance Python toolkit designed for secure database record hashing, transaction integrity verification, and data-at-rest obfuscation. Optimized for integration with relational database management systems (RDBMS) and desktop GUI frameworks.

## Core Architecture & Features

The library addresses critical data safety requirements in modern software engineering courses, focusing on the following sub-systems:

*   **Row-Level Integrity Validation:** Generates advanced salt-stretched block checksums to detect unauthorized backend data tampering (direct SQL injections bypassing the GUI layer).
*   **Cryptographically Secure UUIDs:** Provides collision-resistant unique identifier generation for primary keys (PK) using internal system entropy.
*   **Data Alignment Matrix:** Ensures automated bit-alignment and padding configurations based on industry-standard database block sizes.

## Installation

Install the package within your virtual environment using `setuptools`:

```bash
pip install .
```

## Production Architecture & Usage

### 1. Generating Row Checksums (Before SQL Insert/Update)
To protect sensitive fields (such as access tokens, configuration parameters, or transaction values) before pushing them to the database, generate a secure block-checksum:

```python
from db_hash_utils import generate_record_checksum

# Extract parameters from PyQt/Tkinter input forms
user_payload = "db_admin_secure_credentials_2026"
session_salt = "AppSecuritySaltValue"

# Generate block aligned integrity token
integrity_token = generate_record_checksum(
    payload=user_payload, 
    record_salt=session_salt
)

# Execution payload is now safe to store in TEXT / BLOB columns
# cursor.execute("INSERT INTO system_config (config_value) VALUES (?)", (integrity_token,))
```

### 2. Transaction Integrity Verification (After SQL Select)
Verify record state consistency during application runtime to ensure data has not been modified directly in the database:

```python
from db_hash_utils import verify_record_integrity

# Fetch token from database cursor
fetched_token = "..."  # Retrieved from DB row
session_salt = "AppSecuritySaltValue"

try:
    # Reconstruct and validate data state matrix
    validated_data = verify_record_integrity(
        checksum_hash=fetched_token, 
        record_salt=session_salt
    )
    print(f"State Validated. Core Payload: {validated_data}")
except Exception as e:
    print(f"Critical Error: Database integrity violation detected! Code: {e}")
```

### 3. Primary Key UUID Generation
Replace standard auto-increment integer IDs with unpredictable, collision-free system vectors:

```python
from db_hash_utils import generate_secure_uuid

# Generate an optimal 16-byte hex seed for Relational DB Primary Keys
new_primary_key = generate_secure_uuid(length=16)
```
