Initial import of Brizzi HCE project

2026-05-03 10:23:41 +07:00
commit 9994823fb3
693 changed files with 51541 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,209 @@
+# BRIZZI HCE (Android NFC Host Card Emulation)
+
+Dokumen ini menjelaskan struktur project, alur eksekusi, dan cara membacanya supaya kamu bisa langsung maintance/debug proyek ini.
+
+## 1) Gambaran Umum
+
+Project ini adalah aplikasi Android HCE (Host Card Emulation) yang memproses APDU dari reader NFC (misalnya terminal).  
+Komponen utamanya:
+- [BrizziHostApduService](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziHostApduService.kt): service utama untuk menerima APDU.
+- [BrizziApduRouter](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziApduRouter.kt): pemroses perintah dan state machine transaksi.
+- [BrizziSession](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziSession.kt): menjaga kondisi sesi saat ini (AID, auth, transaksi pending).
+- [BrizziCard / BrizziCardSnapshot](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziCard.kt): model data kartu virtual.
+- [BrizziSecureStorage](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziSecureStorage.kt): persistensi kartu terenkripsi.
+- [BrizziSecurityMetrics](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziSecurityMetrics.kt): monitoring keamanan dan incident readiness.
+
+## 2) Bagaimana alur request APDU
+
+1. APDU masuk ke `processCommandApdu(...)` di `BrizziHostApduService`.
+2. Service melakukan:
+   - validasi basic (null/size/rate limit),
+   - log/track metrik event,
+   - dispatch ke `BrizziApduRouter.handle()`.
+3. Router:
+   - parse APDU via `ApduParser`,
+   - cek timeout sesi,
+   - cek replay untuk command sensitif,
+   - validasi state session (AID/auth/transaction),
+   - memetakan hasil ke SW response.
+4. Response SW/konten dikirim ke terminal.
+
+## 3) State machine yang penting
+
+`BrizziSession` menyimpan dua level state:
+- **SessionPhase**
+  - `NONE`
+  - `AID1_SELECTED`
+  - `AID3_SELECTED`
+  - `AID3_AUTHENTICATED`
+- **TransactionPhase**
+  - `NONE`
+  - `DEBIT_PENDING`
+  - `CREDIT_PENDING`
+  - `LOG_PENDING`
+  - `LAST_TXN_PENDING`
+
+`hasPendingTransactionState()` dipakai untuk mencegah abuse:
+- command debit/credit tidak boleh overlapping,
+- commit/abort (`C7`/`A7`) harus disinkron.
+
+## 4) Security hardening yang sudah diterapkan
+
+- Parsing APDU tidak lagi pakai regex string mentah sepenuhnya; gunakan `ApduParser` untuk parse CLA/INS/P1/P2/Lc/Data/Le.
+- Validasi panjang dan malformed handling lebih ketat (`wrongLength`, `unsupportedInstruction`, `rateLimitExceeded`, dll.).
+- Replay protection untuk command sensitif dalam window pendek.
+- Rate limit:
+  - max 80 command / 1000ms,
+  - minimum gap antar command 30ms.
+- Session timeout 120 detik.
+- `FLAG_SECURE` di UI supaya tidak mudah di-screenshot.
+- `usesCleartextTraffic=false` dan `networkSecurityConfig`.
+- Logging produksi diarahkan ke metadata minimal (tidak menyimpan raw APDU).
+
+## 5) Penyimpanan data (yang dipilih)
+
+Sebelum ini data ada di RAM. Sekarang:
+- `BrizziSecureStorage` menyimpan data kartu ke `EncryptedSharedPreferences`:
+  - `card_number`, `balance`, `logs`, `lastTransactionDate`, dsb.
+- Kunci enkripsi berasal dari Android Keystore (`MasterKey`).
+- Data dipersisten saat `commit` transaksi (`C7`) via callback `onCardUpdated`.
+- Bila loading gagal, sistem fallback ke nilai default (`BrizziCard()`).
+
+Catatan: ini aman untuk tingkat aplikasi, namun bukan secure element hardware.
+
+## 6) Monitoring & Incident readiness (point 5 yang kamu minta)
+
+`BrizziSecurityMetrics` menyimpan counter event:
+- command total/sukses/gagal,
+- timeout, rate limit, replay,
+- auth denied, parse fail, dan lain-lain.
+
+Mechanism:
+- service memanggil `track(event)` untuk setiap event penting,
+- bila ambang incident terlampaui (mis. `COMMAND_RATE_LIMIT`, `REPLAY_DETECTED`, `AUTH_DENIED`, dll), service log `security incidents` (throttled per menit),
+- snapshot juga diekspor ke file internal:
+  - `app/files/security_metrics_report.txt`.
+
+### Debug actions dari MainActivity
+
+- Dump metrics (debug only):
+  - `adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_DUMP_METRICS`
+- Reset metrics (debug only):
+  - `adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_RESET_METRICS`
+- Lihat file log:
+  - `/data/data/com.korancrew.brizzi/files/security_metrics_report.txt`
+
+## 7) Command support (high level)
+
+Di router, mapping didasarkan pada helper:
+- AID selector (1/3): `905A...0100...`, `905A...0300...`
+- AID 1 info/status
+- AID 3 auth & read balance/log/transaction
+- debit/credit
+- write log + update last transaction + commit/abort
+- fallback: `unsupportedInstruction` (6D00)
+
+Untuk daftar lengkap command literal, lihat:
+- [BrizziCommandCatalog](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziCommandCatalog.kt)
+- implementasi detail di `handleParsed(...)`:
+  - [BrizziApduRouter.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziApduRouter.kt)
+
+## 8) Cara memahami kode (urutan baca yang disarankan)
+
+1. [BrizziHostApduService.kt](app/src/main/java/com/korancrew/brizzi/hce/BrizziHostApduService.kt) – masuknya data APDU, rate limit, metrik.
+2. [BrizziApduRouter.kt](app/src/main/java/com/korancrew/brizzi/hce/BrizziApduRouter.kt) – policy/routing per command.
+3. [BrizziSession.kt](app/src/main/java/com/korancrew/brizzi/hce/BrizziSession.kt) – state session/transaction.
+4. [ApduParser.kt](app/src/main/java/com/korancrew/brizzi/hce/ApduParser.kt) – struktur parser.
+5. [BrizziCard.kt](app/src/main/java/com/korancrew/brizzi/hce/BrizziCard.kt) + [BrizziSecureStorage.kt](app/src/main/java/com/korancrew/brizzi/hce/BrizziSecureStorage.kt).
+6. [BrizziSecurityMetrics.kt](app/src/main/java/com/korancrew/brizzi/hce/BrizziSecurityMetrics.kt) – event/incident.
+7. [BrizziResponse.kt](app/src/main/java/com/korancrew/brizzi/hce/BrizziResponse.kt) + [Hex.kt](app/src/main/java/com/korancrew/brizzi/hce/Hex.kt).
+
+## 9) Build & release yang dipakai sekarang
+
+- `debug`: non-minify (mudah debug).
+- `release`: minify + shrink + ProGuard:
+  - [proguard-rules.pro](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/proguard-rules.pro)
+- Signing release hanya aktif jika property gradle diisi (via CI keystore properties):
+  - `RELEASE_STORE_FILE`, `RELEASE_STORE_PASSWORD`, `RELEASE_KEY_ALIAS`, `RELEASE_KEY_PASSWORD`.
+
+## 10) Known caveat (buat pembacaan objektif)
+
+- Banyak SW command belum sepenuhnya di-convert ke parser berbasis field; saat ini tetap berbasis string matching untuk backward compatibility.
+- Jika ini akan dipakai di production nyata (bukan simulasi/prototype), perlu hardening tambahan:
+  - enkripsi/rotasi kunci lebih ketat,
+  - secure policy distribusi dan integrity update,
+  - backend attestation/monitoring terpusat.
+
+---
+
+## 11) Ringkas: arsitektur dalam satu kalimat
+Ini adalah **stateful HCE emulator**: APDU masuk → rate-limit & parser → aturan fase sesi → update card/metrics → response status dengan persistensi terenkripsi + audit event.
+
+## 12) Cara membaca kode (bisa dijadikan panduan debugging)
+
+### 12.1 Alur end-to-end dalam 1 request
+
+1. Terminal mengirim APDU ke `BrizziHostApduService`.
+2. `processCommandApdu(...)` memvalidasi ukuran, null, dan rate-limit di service.
+3. `BrizziHostApduService` menyerahkan APDU ke `BrizziApduRouter.handle(...)`.
+4. Router memanggil `ApduParser.parse(...)` untuk decode field CLA/INS/P1/P2/Lc/Data/Le.
+5. Router memvalidasi:
+   - sesi timeout (`SESSION_TIMEOUT_MS`),
+   - replay untuk perintah sensitif (`REPLAY_WINDOW_MS`),
+   - state/phase yang valid (`BrizziSession`),
+   - format payload (contoh: debit/credit/write log/last transaction).
+6. Jika valid, router memproses rule per command dan memodifikasi `pending*` pada `session` serta `card` jika commit.
+7. Response dibentuk dari `BrizziResponse` (`6700`, `6985`, `6FFF`, `9100`, dll).
+8. Service mencatat event ke `BrizziSecurityMetrics`, menilai health, dan menulis snapshot ke `security_metrics_report.txt`.
+
+### 12.2 Urutan file untuk dibaca dari atas ke bawah
+
+1. [BrizziHostApduService.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziHostApduService.kt)
+   - Titik masuk APDU dari HCE.
+   - Juga memegang rate-limit, incident throttle log, dan ekpor metrik.
+2. [BrizziApduRouter.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziApduRouter.kt)
+   - Aturan stateful command routing.
+   - Core logic transaksi debit/credit/log/last transaction/commit-abort.
+3. [BrizziSession.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziSession.kt)
+   - Menjaga state sesi, fase autentikasi, fase transaksi, anti-replay, dan pending state.
+4. [ApduParser.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/ApduParser.kt)
+   - Parsing protokol APDU (case-1..case-4).
+5. [BrizziCard.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziCard.kt) + [BrizziSecureStorage.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziSecureStorage.kt)
+   - Struktur data card dan log transaksi; bagaimana data bertahan di penyimpanan terenkripsi.
+6. [BrizziSecurityMetrics.kt](/Users/wirabasalamah/Documents/Codex/brizzi-hce/app/src/main/java/com/korancrew/brizzi/hce/BrizziSecurityMetrics.kt)
+   - Event tracking, incident threshold, snapshot/report.
+
+### 12.3 Kontrak keamanan yang harus dipahami
+
+- **Syarat autentikasi:** akses area saldo/log/last transaction hanya setelah fase `AID3_AUTHENTICATED`.
+- **Syarat transaksi:** debit/credit harus dalam state siap transaksi, tidak boleh ada pending transaction lain.
+- **Commit/Abort:** `C7`/`A7` adalah pembatas akhir lifecycle transaksi. Tanpa pending state, kedua command itu ditolak.
+- **Logika rollback:** pending update hanya masuk ke state final saat `COMMIT`; `ABORT` membersihkan pending.
+- **Replay guard:** command sensitif (debit/credit/commit/abort/write log/last tx) tidak boleh diulang dalam window pendek.
+
+### 12.4 Checklist membaca log saat debugging
+
+- Jika terjadi `CONDITIONS_NOT_SATISFIED` berulang: cek urutan select-aid-auth-send command.
+- Jika `rateLimitExceeded` sering:
+  - periksa apakah device reader terlalu cepat kirim command (<30ms antar command).
+  - pastikan transaksi tidak melebihi 80 command/s.
+- Jika `COMMAND_PARSE_FAILED` naik: cek command malformed (Lc/Le mismatch, trailing bytes, payload aneh).
+- Ambil snapshot metrik:
+  - `adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_DUMP_METRICS`
+- Hapus metrik jika perlu test ulang:
+  - `adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_RESET_METRICS`
+
+## 13) Peta ancaman & mitigasi singkat (ringkas)
+
+- **Replay** → dibatasi window 800ms di router + deteksi command sensitif.
+- **Flood** → dibatasi 80 cmd/1000ms + minimum 30ms antar command di service.
+- **Session theft/continuity** → timeout 120 detik, reset state saat deactivated.
+- **Data disclosure** → `FLAG_SECURE`, cleartext dimatikan, keystore-backed storage untuk card state.
+- **Silent fail di prod** → metrik tidak menyimpan APDU mentah, hanya metadata event.
+
+## 14) Paket uji cepat (smoke test) untuk koneksi reader
+
+- Gunakan [HCE_BRIZZI_SMOKE_TEST.md](/Users/wirabasalamah/Documents/Codex/brizzi-hce/HCE_BRIZZI_SMOKE_TEST.md) untuk menjalankan alur verifikasi:
+  - build/install,
+  - cek service + logcat,
+  - validasi interaksi AID/auth/transaksi ke reader.