anch-hash 1.0.0

ANCH — Adaptive Neural Chaotic Hash Framework: experimental hashing combining feature extraction, neural parameter generation, and chaos theory.

ANCH — Adaptive Neural Chaotic Hash Framework

ANCH (Adaptive Neural Chaotic Hash) adalah framework hashing eksperimental sumber terbuka berbasis Python yang menggabungkan Ekstraksi Fitur (Feature Extraction), Generasi Parameter Pseudo-Neural, Chaos Theory (Teori Kekacauan), Permutasi Dinamis, dan Compression Engine untuk menghasilkan nilai digest 256-bit yang unik.

---

⚠️ Pernyataan Penting (Disclaimer)

ANCH adalah sebuah framework penelitian eksperimental. Protokol ini tidak dimaksudkan sebagai pengganti fungsi hash kriptografi standar industri seperti SHA-256 atau SHA-3 dalam sistem produksi nyata. Gunakan framework ini untuk keperluan riset akademis, benchmarking, edukasi kriptografi berbasis chaos, dan eksperimen fingerprinting data.

---

✨ Fitur Utama

Fitur	Deskripsi
🧠 Neural Parameter Generation	Parameter operasional hash dihasilkan secara adaptif dari representasi fitur input.
🌀 Chaos Theory Engine	Menggunakan rumus Logistic Map untuk menghasilkan aliran byte acak kacotik (chaotic stream).
🔀 Dynamic Permutation	Pengacakan bit dan rotasi kata berbasis chaos untuk memaksimalkan efek difusi longsor (avalanche effect).
🗜️ Compression Engine	Kompresi multi-round berbasis struktur mirip jaringan Feistel untuk pemampatan state internal.
🔬 Feature Extraction	Menganalisis karakteristik input data: panjang, bobot Hamming, Shannon entropy, distribusi frekuensi byte, dan bigram transition.
📊 Built-in Benchmark Suite	Pengujian bawaan untuk menghitung tingkat tabrakan (collisions), efek avalanche, nilai entropy digest, dan throughput.
🖥️ Antarmuka CLI	Akses cepat ke semua fungsi utama framework langsung dari terminal.
0️⃣ Tanpa Dependensi Eksternal	Ditulis dalam Python murni tanpa membutuhkan library tambahan seperti NumPy atau TensorFlow untuk versi dasar.

---

🚀 Instalasi

Instal langsung secara online melalui PyPI:

pip install anch-hash

Atau instal dari source code lokal:

git clone https://github.com/YudaHasibuan/enkripsi-ANCH.git
cd enkripsi-ANCH
pip install -e ".[dev]"

---

🔧 Panduan Penggunaan Cepat (Python API)

import anch

# 1. Hashing String Sederhana
digest = anch.hash("hello world")
print(f"Hasil Hash: {digest}")  # Menghasilkan 64 karakter hex (256-bit)

# 2. Verifikasi Hash
apakah_cocok = anch.verify("hello world", digest)
print(f"Verifikasi: {apakah_cocok}")  # True

# 3. Hashing File
digest_file = anch.hash_file("dokumen.pdf")
print(f"Hash File: {digest_file}")

# 4. Pengujian Efek Avalanche (Longsor)
# Mengukur berapa persen bit output yang berubah ketika input diubah 1 bit/karakter
persentase_perubahan = anch.avalanche("hello", "HELLO")
print(f"Efek Avalanche: {persentase_perubahan}% (Idealnya mendekati 50%)")

# 5. Pengukuran Entropy Digest
score = anch.entropy(digest)
print(f"Nilai Shannon Entropy: {score} bits/byte (Idealnya mendekati 8.0)")

# 6. Deteksi Tabrakan (Collision Test)
data_uji = ["data_1", "data_2", "data_3", "data_1"]
laporan = anch.collision_test(data_uji)
print(f"Total Tabrakan Terdeteksi: {laporan['collisions']}")

---

🖥️ Penggunaan via CLI (Command Line Interface)

Setelah paket diinstal, perintah anch dapat langsung dijalankan dari terminal:

# Melakukan hash teks
anch hash "hello world"

# Melakukan hash berkas/file
anch hash-file laporan.pdf

# Memverifikasi teks terhadap hash
anch verify "hello world" <nilai_digest>

# Menganalisis efek avalanche antara dua teks
anch avalanche "hello" "HELLO"

# Menghitung nilai entropy dari suatu hash
anch entropy <nilai_digest>

# Menjalankan pengujian performa & analisis kriptografis bawaan
anch benchmark --samples 150

---

🏗️ Alur Arsitektur (Pipeline Hashing)

Proses transformasi data masukan menjadi digest keluaran mengikuti tahapan berikut:

Data Masukan (Teks/Byte/File)
    ↓
Feature Extractor        → Menghitung bit count, entropy, frekuensi byte, & bigram
    ↓
Neural Parameter Gen     → Menghasilkan seed, nilai-r chaos, rotasi schedule, & key kompresi
    ↓
Chaotic Engine           → Iterasi Logistic Map (x_n+1 = r * x_n * (1 - x_n)) → byte stream chaos
    ↓
Dynamic Permutation      → Pengacakan bit Fisher-Yates + rotasi byte state internal
    ↓
Compression Engine       → Putaran Feistel (4-16 putaran) & pencampuran XOR sisa state
    ↓
Finalisasi Digest        → Pelipatan state 64-byte menjadi 32-byte (256-bit Hex)

---

📊 Analisis Performa & Karakteristik

ANCH dirancang sebagai algoritma adaptif yang mementingkan kekacauan matematis (chaos) dibandingkan kecepatan mentah. Berikut adalah perbandingan performa ANCH vs SHA-256 pada Python 3.12 (Rata-rata 10 kali pengujian):

Ukuran Input	Waktu ANCH (ms)	Waktu SHA-256 (ms)	Rasio Kecepatan	Keterangan
64 Byte	~2.4 ms	~0.005 ms	~480x lebih lambat	Sangat cepat untuk string pendek
1 Kilobyte	~5.8 ms	~0.012 ms	~483x lebih lambat	Pengaruh kompresi deterministik
64 Kilobyte	~274 ms	~0.46 ms	~596x lebih lambat	Direkomendasikan untuk eksperimen

Catatan: Nilai rata-rata avalanche effect yang dicapai oleh ANCH berkisar antara 47% hingga 49% (sangat dekat dengan nilai teoritis ideal 50%), yang membuktikan tingkat difusi bit yang kuat.

---

📦 Struktur Repositori

ANCH/
├── src/anch/
│   ├── __init__.py        # Eksposur API Publik
│   ├── __main__.py        # Titik entri CLI
│   ├── core.py            # Orkestrator pipeline utama
│   ├── feature.py         # Analisis karakteristik input
│   ├── neural.py          # Generator parameter berbasis lapisan linier
│   ├── chaos.py           # Generator Logistic Map & Tent Map
│   ├── permutation.py     # Logika pengacakan bit & rotasi kata
│   ├── compression.py     # Algoritma pemampatan state Feistel
│   └── benchmark.py       # Suite benchmarking terintegrasi
├── tests/
│   ├── test_core.py       # Pengujian API publik
│   └── test_modules.py    # Pengujian fungsionalitas internal modul
├── website/               # Dashboard launching visual Next.js & Playground
├── docs/                  # File MkDocs tambahan
├── pyproject.toml         # Konfigurasi instalasi setuptools
└── README.md              # Dokumentasi utama proyek

---

🗺️ Rencana Pengembangan (Roadmap)

• v0.1.0 — Mesin Inti Hash, SDK Python, CLI, Unit Tests, Rilis PyPI.
• v0.2.0 — Dashboard Antarmuka Uji Kecepatan, REST API (FastAPI), Akselerasi Feature Extractor dengan NumPy.
• v0.3.0 — Penambahan Chaos Maps baru (Tent Map terintegrasi & Hénon Map), Integrasi opsional TensorFlow.
• v1.0.0 — Rilis stabil penuh, integrasi plugin komunitas, audit keamanan eksternal.

---

📄 Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT — bebas digunakan dan dimodifikasi untuk tujuan akademis maupun komersial.