Brizzi-HCE/README.md

# 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.