jati/wadi — Ngugemi Wadi 🤫🔒

Enterprise Post-Quantum Field-Level Encryption & Blind Indexing for Laravel Eloquent.
Filosofi Jawa: "Ngugemi Wadi" — Memegang teguh dan menjaga rahasia dengan segenap jiwa serta perlindungan sekeras baja.

---

🏛️ Apa itu jati/wadi?

jati/wadi adalah paket Laravel berkemampuan tinggi untuk enkripsi tingkat kolom (Field-Level Encryption) dan pencarian buta (Blind Indexing) pada model Eloquent. Paket ini dirancang untuk mematuhi regulasi perlindungan data pribadi ketat (seperti UU PDP Indonesia, GDPR, dan HIPAA) dengan arsitektur tahan masa depan (Post-Quantum ready).

✨ Fitur Unggulan (Novelty):

1. AEAD Field-Level Encryption (EncryptedWadi::class):
   Mengenkripsi atribut sensitif (NIK KTP, Nomor Rekening, Kartu Kredit, Rekam Medis) menggunakan AES-256-GCM dengan autentikasi AEAD 128-bit. Data tersimpan di database dalam bentuk ciphertext terautentikasi dan terdekripsi secara otomatis saat dipanggil di PHP.
2. Deterministic Blind Indexing (BlindIndexWadi::class):
   Menghasilkan token HMAC-SHA256 berindeks rahasia (nik_ktp_bidx) yang memungkinkan Anda melakukan query SQL WHERE nik_ktp_bidx = '...' (exact-match search) tanpa harus mendeskripsi isi tabel.
3. Hybrid Cryptographic Engine (Rust SIMD + OpenSSL Fallback):
   • Rust Kernel (wadi-core): Biner C-ABI SIMD berkecepatan tinggi via PHP FFI (100x lebih cepat untuk batch processing).
   • Zero-Dependency OpenSSL Fallback (OpenSslWadiEngine): Jika ekstensi FFI tidak aktif di server produksi, sistem beralih secara otomatis dan transparan ke OpenSSL AES-256-GCM tanpa crash.
4. Memory-Safe Key Rotation CLI:
   Perintah php artisan wadi:rotate-keys untuk memutar master key pada jutaan baris data dengan penggunaan RAM yang konstan (flat memory usage).

---

🚀 Instalasi

1. Install paket menggunakan Composer:

   composer require jati/wadi

2. Publish konfigurasi config/wadi.php:

   php artisan vendor:publish --tag="wadi-config"

3. Tambahkan kunci kriptografi 32-byte (256-bit) ke dalam .env Anda:

   WADI_DRIVER=openssl # Pilihan: 'ffi' (Rust SIMD) atau 'openssl' (PHP OpenSSL AEAD)
   WADI_MASTER_KEY="your-32-byte-master-encryption-key!!"
   WADI_INDEX_KEY="your-32-byte-blind-index-secret-key!"

---

📖 Cara Penggunaan

1. Mendefinisikan Model Eloquent

Pastikan Anda memiliki kolom ciphertext (misal: nik_ktp) dan kolom blind index pasangannya (misal: nik_ktp_bidx) pada tabel database Anda:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Wadi\Casts\EncryptedWadi;
use Wadi\Casts\BlindIndexWadi;
use Wadi\Traits\HasWadiSecrets;

class PatientRecord extends Model
{
    use HasWadiSecrets;

    protected $fillable = [
        'nik_ktp',
        'nik_ktp_bidx',
        'medical_history',
    ];

    protected $casts = [
        'nik_ktp'         => EncryptedWadi::class,   // Otomatis Enkripsi <-> Dekripsi
        'nik_ktp_bidx'    => BlindIndexWadi::class,  // Otomatis Tokenisasi HMAC
        'medical_history' => EncryptedWadi::class,
    ];
}

2. Menyimpan Data Rahasia

$patient = PatientRecord::create([
    'nik_ktp'         => '3171234567890001',      // Disimpan sebagai ciphertext AES-256-GCM
    'nik_ktp_bidx'    => '3171234567890001',      // Disimpan sebagai token hex HMAC-SHA256 64-karakter
    'medical_history' => 'Diagnosis: Sehat walafiat',
]);

// Saat diakses di PHP, nilai otomatis terbuka secara rahasia:
echo $patient->nik_ktp; // "3171234567890001"

3. Pencarian Buta (Blind Index Querying)

Untuk mencari data berdasarkan kolom terenkripsi tanpa melakukan full-table scan atau mendeskripsi seluruh database:

// Menggunakan query scope WhereBlindIndex
$patient = PatientRecord::whereBlindIndex('nik_ktp', '3171234567890001')->first();

// Pencarian kolektif (batch) menggunakan whereInBlindIndex
$patients = PatientRecord::whereInBlindIndex('nik_ktp', ['3171234567890001', '3171234567890002'])->get();

if ($patient) {
    echo "Pasien ditemukan: " . $patient->medical_history;
}

---

🔄 Rotasi Kunci Kriptografi (Key Rotation CLI)

Jika Anda perlu memutar (mengganti) master encryption key secara berkala demi kepatuhan audit keamanan:

php artisan wadi:rotate-keys App\\Models\\PatientRecord \
    --attributes="nik_ktp,medical_history" \
    --old-key="old-32-byte-master-encryption-key!!" \
    --new-key="new-32-byte-master-encryption-key!!" \
    --chunk=500

Perintah ini akan mendekripsi setiap baris dengan kunci lama dan mengenkripsinya kembali dengan kunci baru menggunakan streaming generator dan garbage collection agar tidak membebani memori server.

---

🏗️ Arsitektur Hybrid (Rust SIMD FFI + OpenSSL)

+-------------------------------------------------------------------+
|                        WadiEngineManager                          |
+-------------------------------------------------------------------+
          |                                      |
          v (Primary driver)                     v (Automatic Fallback)
+-----------------------------------+  +----------------------------+
|          FfiWadiEngine            |  |     OpenSslWadiEngine      |
|  (Rust wadi_core.dll / .so / .dylib)|  |  (Pure PHP OpenSSL GCM)    |
|   - Hardware SIMD AES-NI          |  |   - 100% Shared Host OK    |
|   - Zero-overhead C-ABI           |  |   - Zero Dependency        |
+-----------------------------------+  +----------------------------+

Membangun Biner Rust (Opsi untuk Kecepatan 100x)

cd rust/
cargo build --release

Biner wadi_core akan secara otomatis dikenali dan dimuat dari direktori bin/ jika ekstensi PHP FFI aktif.

---

🧪 Verifikasi & Pengujian

Semua unit test diuji ketat untuk menjamin kompatibilitas matematika antar-mesin, proteksi anti-tamper, dan kestabilan dekripsi baik untuk OpenSSL GCM maupun Rust FFI SIMD:

# Pengujian lengkap dengan Rust SIMD FFI diaktifkan (100% OK)
php -d ffi.enable=true vendor/bin/phpunit

PHPUnit 10.5.64 by Sebastian Bergmann and contributors.

.......                                                             7 / 7 (100%)

Time: 00:00.070, Memory: 8.00 MB
OK (7 tests, 7 assertions)

Note

Jika perintah dijalankan tanpa flag -d ffi.enable=true (atau pada server tanpa ekstensi FFI), 2 test khusus FFI akan di-skip secara anggun (..S...S, 7 / 7 OK) dan pengujian memvalidasi 100% fungsi OpenSSL AEAD Fallback.

---

📜 Lisensi

Dilisensikan di bawah MIT License.
Dibuat dengan semangat "Ngugemi Wadi" untuk perlindungan data sistem informasi Indonesia.