Core Module

Dokumentasi ringkas untuk modul inti TrueDignity. Bagian ini memuat gambaran umum fitur inti, alur kerja dasar, dan referensi teknis tingkat tinggi.

Arsitektur Perangkat Lunak

Sistem ini terdiri dari empat domain perangkat lunak yang berbeda, di mana masing-masing memiliki peran dan tanggung jawab yang spesifik:

• Matrix: Server pusat yang menangani logika bisnis inti, termasuk otentikasi, manajemen pengguna, dan orkestrasi data. Semua interaksi antar komponen lain dimediasi oleh Matrix.
• Terminal: Aplikasi yang diinstal pada perangkat Owner atau Officer. Perangkat lunak ini bertanggung jawab untuk otentikasi perangkat (Owner) dan otentikasi yang didelegasikan (Officer).
• Safe: Merupakan node penyimpanan yang aman dan terdesentralisasi yang dioperasikan oleh Owner. Safe menyimpan data sensitif, termasuk kredensial Officer, dan hanya dapat diakses melalui otorisasi dari Matrix.
• App: Aplikasi yang digunakan oleh pengguna umum untuk berinteraksi dengan layanan yang disediakan, mengakses data dari Safe setelah melalui proses otentikasi yang diatur oleh Matrix.

Penting untuk dipahami bahwa Terminal, Safe, Matrix, dan App bukanlah objek, melainkan domain perangkat lunak yang memiliki objek-objeknya sendiri.

Spesifikasi Perilaku & Alur Otentikasi

Berikut adalah skenario otentikasi yang menjadi dasar interaksi dalam sistem.

Skenario 1: Autentikasi Cross Subdomain (Owner)

Skenario ini menjelaskan alur otentikasi untuk Owner atau Notaris melalui Terminal. Proses ini melibatkan verifikasi identitas pengguna dan identifikasi perangkat keras yang digunakan. Tujuannya adalah untuk memastikan setiap Owner hanya mengoperasikan satu node Safe pada satu perangkat.

Penjelasan Diagram: Diagram di atas menggambarkan alur otentikasi Terminal untuk Owner. Terminal mengirimkan kredensial dan hash perangkat ke Matrix. Matrix memvalidasi kredensial dan hash perangkat untuk kemudian mengeluarkan token dan status instalasi Safe.

Aktor	Owner/Notaris & Sistem
Rincian	Given seorang Owner membuka aplikasi Terminal. When pengguna memasukkan username, password, dan Terminal mengirimkannya beserta hash perangkat (jika ada). Then Matrix memvalidasi kredensial. And jika password valid, Matrix mencari data node/homesafe. And Matrix mengirimkan token dalam set-cookie header dan payload berisi: hash, homesafe, dan safeinstall.

Skenario 2: Autentikasi Aplikasi Pengguna Umum

Skenario ini menjelaskan alur otentikasi untuk pengguna umum melalui App. Prosesnya lebih sederhana karena tidak memerlukan identifikasi perangkat.

Penjelasan Diagram: Diagram di atas menggambarkan alur otentikasi App untuk pengguna umum. App mengirimkan kredensial, Matrix memvalidasinya, dan jika berhasil, Matrix mengembalikan token sesi.

Aktor	Pengguna Umum & Sistem
Rincian	Given seorang pengguna umum membuka App. When pengguna memasukkan username dan password. Then Matrix memvalidasi kredensial. And jika valid, Matrix mengirimkan token otentikasi kembali ke App.

Skenario 3: Undangan dan Pendaftaran Officer

Skenario ini menjelaskan bagaimana seorang Owner mengundang Officer baru, yang kemudian mendaftar ke dalam sistem.

Penjelasan Diagram:

1. Owner membuat undangan melalui Terminal, yang dikirim ke Matrix.
2. Matrix menghasilkan link unik dan memberikannya kembali ke Owner.
3. Officer menerima dan membuka link, yang mengarahkannya ke formulir pendaftaran.
4. Setelah Officer melengkapi formulir, data dikirim ke Matrix, yang kemudian menyimpannya dan mengaitkannya dengan subdomain milik Owner.
5. Matrix mengembalikan token sesi kepada Officer.
6. Matrix kemudian mengirimkan data Officer (seperti kredensial) ke Safe yang relevan dalam bentuk JWT yang aman.

Aktor	Owner, Officer, & Sistem
Rincian	Given Owner ingin menambahkan Officer baru. When Owner mengirim undangan dari Terminal. And Officer menerima link, mengisi formulir pendaftaran. Then Matrix mendaftarkan Officer dan mengaitkannya dengan subdomain Owner. And Matrix mengirimkan kredensial Officer ke Safe yang sesuai dalam bentuk JWT. And Matrix memberikan token sesi kepada Officer.

Skenario 4: Autentikasi Officer (Delegated Authentication)

Skenario ini menjelaskan bagaimana Officer melakukan otentikasi. Karena kredensial Officer disimpan di Safe milik Owner, Matrix harus mendelegasikan proses validasi ke Safe yang sesuai. Untuk memastikan keamanan, Matrix tidak mengirimkan kredensial mentah, melainkan sebuah JWT yang ditandatanganinya.

Penjelasan Diagram:

1. Officer melakukan login melalui Terminal.
2. Matrix mengidentifikasi pengguna sebagai Officer dan mengambil subdomain terkait.
3. Matrix membuat JWT yang berisi detail permintaan otentikasi, lalu mengirimkannya ke Safe yang sesuai dengan subdomain tersebut melalui endpoint /delegate-auth.
4. Safe memverifikasi tanda tangan JWT dan memvalidasi kredensial Officer secara lokal.
5. Safe mengembalikan hasil validasi (berhasil/gagal) ke Matrix.
6. Jika berhasil, Matrix menghasilkan token sesi dan mengirimkannya ke Terminal Officer.

Aktor	Officer & Sistem
Rincian	Given Officer membuka Terminal. When Officer memasukkan username dan password. Then Matrix mengidentifikasi Officer dan subdomain terkait. And Matrix mendelegasikan permintaan otentikasi ke Safe yang benar dengan mengirimkan JWT yang aman. And Safe memverifikasi JWT tersebut dan memvalidasi kredensial. And Matrix menerima hasilnya dan memberikan token kepada Officer jika validasi berhasil.

Skenario 5: Otentikasi Berbasis JWT dan Rotasi Kunci

Karena jaringan ini dibentuk dengan arsitektur federated di atas protol HTTP, maka JWT dibutuhkan untuk autentikasi pengguna dalam sistem. Safe adalah sebutan untuk server terdistribusi, dan Matrix adalah server pusatnya. Skenario ini menjelaskan bagaimana JWT digunakan dan bagaimana rotasi kunci asimetris untuk tanda tangan (signature) dikelola.

Skenario 5.1: Validasi cookie request yang diterima oleh Safe melalui middleware

1. Safe memeriksa apakah ada cookie pada request yang masuk.
2. Safe melakukan hashing pada keseluruhan nilai JWT.
3. Safe memeriksa keberadaan hash tersebut di dalam cache. Jika ditemukan, token dianggap valid, dan proses dilanjutkan ke langkah 7.
4. Jika hash tidak ada di cache, Safe melakukan decode pada JWT untuk mendapatkan kid (Key ID) dari header.
5. Safe mencari public_key yang sesuai dengan kid tersebut di dalam cache memori. Jika tidak ditemukan, Safe akan membuat request ke Matrix untuk meminta public_key dengan versi yang dimaksud.
6. Setelah mendapatkan public_key, Safe memvalidasi tanda tangan JWT. Jika valid, Safe akan menyimpan hash dari JWT tersebut ke dalam cache untuk validasi di masa mendatang.
7. Jika token valid, permintaan akan diteruskan ke endpoint yang dituju pada server Safe.

Skenario 5.2: Validasi permintaan delegasi autentikasi (delegate-auth)

Proses validasi untuk permintaan delegate-auth mengikuti alur yang sama seperti pada Skenario 5.1, namun proses ini ditangani langsung oleh handler endpoint, bukan melalui middleware global.

Skenario 5.3: Validasi permintaan untuk menyimpan staff (store-officer)

(Alur validasi sama seperti pada Skenario 5.2, lihat diagram di atas)

Sama seperti delegate-auth, validasi untuk permintaan store-officer juga ditangani langsung oleh handler endpoint terkait dan mengikuti alur validasi JWT yang sama.

Skenario 5.4: Generasi kunci asimetris dan rotasi

Sistem menggunakan kunci asimetris untuk menandatangani JWT, memastikan integritas dan otentisitasnya. Untuk menjaga keamanan, kunci-kunci ini dirotasi secara berkala.

Format Versi Kunci: Versi kunci dicantumkan dalam kid (Key ID) header pada JWT dan mengikuti format berikut:

1. SESSION_KEY_xxx: Versi kunci yang digunakan untuk menandatangani token sesi autentikasi pengguna.
2. MATRIX_PROTOCOL_xxx: Versi kunci yang digunakan untuk menandatangani perintah-perintah yang dibuat oleh Matrix untuk Safe (contoh: delegate-auth, store-officer). Hal ini memastikan hanya Matrix yang dapat mengakses endpoint tersebut.

Pembuatan Kunci (Lazy Generation): Untuk efisiensi, semua kunci asimetris dalam sistem dibuat secara lazy (saat dibutuhkan pertama kali).

• Pasangan kunci SESSION_KEY baru akan dibuat jika belum ada saat proses autentikasi pengguna pertama kali terjadi setelah rotasi.
• Pasangan kunci MATRIX_PROTOCOL baru akan dibuat jika belum ada saat Matrix perlu menandatangani perintah pertama kali ke Safe setelah rotasi.

Detail Teknis & Perancangan

Abstraksi & Objek Inti

Berikut adalah objek-objek data utama yang terlibat dalam alur otentikasi:

Objek	Anggota	Tipe Data/Keterangan
User	Properti:
	userId	string (ID unik pengguna)
	username	string
	passwordHash	string (Hash dari password, bisa null untuk Officer)
	userType	enum('owner', 'officer', 'general')
	subdomain	string (ID Notaris/Owner, untuk Officer)
Auth	Properti:
	username	string
	password	string (Password teks asli)
	hash	string (Hash identifikasi perangkat, opsional)
Token	Properti:
	jwt	string (JSON Web Token)
	payload	object (Data yang dikirim ke klien)
Node	Properti:
	nodeId	string (ID unik node/homesafe)
	ownerId	string (ID User pemilik)
	deviceHash	string (Hash perangkat yang terasosiasi)

Diagram Kelas (Class Diagram)

Diagram ini menunjukkan relasi antar objek-objek data inti dalam sistem.

Penjelasan Diagram: Diagram kelas di atas menunjukkan bahwa User dapat memiliki satu Node (khusus untuk Owner). Seorang User dengan tipe Owner dapat mengundang banyak User dengan tipe Officer.

ERD (Entity-Relationship Diagram)

Diagram ini merepresentasikan struktur database yang mendukung skenario otentikasi.

Penjelasan Diagram: ERD ini menunjukkan tabel USERS yang menyimpan data pengguna, termasuk user_type untuk membedakan peran. Kolom subdomain digunakan untuk mengaitkan Officer dengan Owner-nya. Tabel NODES menyimpan informasi tentang Safe yang dimiliki oleh Owner.

Rencana Pengujian (Test Cases)

Nama	Deskripsi	Hasil yang Diharapkan
Verifikasi Otentikasi Owner	Memastikan Terminal dapat melakukan otentikasi Owner dengan hash perangkat.	Respons berisi token dan payload dengan status safeinstall dan homesafe yang benar.
Verifikasi Undangan Officer	Memastikan Owner dapat membuat link undangan dan Officer bisa mendaftar.	Officer berhasil dibuat di database dengan subdomain yang benar dan menerima token sesi.
Verifikasi Delegated Auth	Memastikan Officer dapat login melalui Matrix yang mendelegasikan ke Safe.	Matrix berhasil meneruskan permintaan ke Safe, dan Officer menerima token setelah Safe memvalidasi kredensial.