# Pengesahan sistem pilihan dan penguncian Vault

Mula-mula cipta atau buka kunci Vault dengan kata laluan induknya. Buka **Settings → Security (Tetapan → Keselamatan)**, semak status penyedia dan dayakan buka kunci biometrik. Pendaftaran meminta pengesahan sistem yang baharu. Selepas itu, tindanan log masuk menawarkan buka kunci Touch ID, Windows Hello atau cap jari di samping borang kata laluan induk. **Disable and remove enrollment (Lumpuhkan dan buang pendaftaran)** membuang kunci cache aplikasi ini, bukan cap jari yang didaftarkan dalam sistem pengendalian.

Simpan kata laluan induk: pembatalan, tamat masa, perkakasan/keyring yang tidak tersedia dan pendaftaran yang tidak sah lagi semuanya memerlukan sandaran kata laluan. Pendaftaran biometrik adalah setempat kepada pengguna, peranti dan Vault ini. Ia bukan mekanisme pemulihan atau sandaran. Menetapkan semula Vault membatalkan pendaftaran dan memadamkan profil yang disulitkan serta cap jari hos sedia ada hanya selepas pengesahan `SMAZAT` yang sedia ada.

| Platform | Pengesahan dan storan | Keperluan dan batasan |
| --- | --- | --- |
| macOS Apple Silicon | LocalAuthentication / Touch ID asli; item Keychain Security.framework dengan `biometryCurrentSet` dan `WhenUnlockedThisDeviceOnly` | Touch ID yang didaftarkan, penderia yang tersedia dan Keychain log masuk yang boleh digunakan. Perubahan cap jari menjadikan item tidak sah. Gunakan tandatangan Developer ID yang stabil untuk kemas kini pengeluaran; tandatangan alpha ad hoc boleh mengganggu kepercayaan Keychain dan penjejakan kebenaran rangkaian setempat. |
| Windows x64 | Interop desktop WinRT Windows Hello asli yang dilampirkan pada HWND utama; kunci yang disulitkan dengan DPAPI pengguna semasa dalam Windows Credential Manager | Cap jari, wajah **atau PIN** Hello yang dikonfigurasikan. Ini ialah buka kunci mudah: kelulusan Hello dikuatkuasakan oleh aplikasi, manakala DPAPI sendiri tidak dilindungi biometrik. Kod lain yang berjalan sebagai pengguna yang sama mungkin dapat menyahsulit bukti kelayakan. |
| Ubuntu x64 | Cap jari berdaftar pengguna semasa melalui fprintd D-Bus; storan bukti kelayakan libsecret / Secret Service yang eksplisit | Pembaca yang disokong, cap jari yang didaftarkan, Secret Service desktop yang sedang berjalan dan keyring lalai. Buka kunci mudah: bukti kelayakan keyring tidak terikat secara kriptografi kepada pengesahan cap jari. Tiada sandaran `basic_text` atau fail teks biasa. |

Pada Ubuntu, pakej masa jalan pilihan ialah `python3-gi`, `gir1.2-secret-1`, `gnome-keyring` (atau Secret Service lain yang serasi) dan `fprintd`. Pasang pakej yang tiada menggunakan pengurus pakej sistem pengendalian yang biasa, kemudian daftarkan cap jari dalam tetapan sistem pengendalian. Pengesahan menggunakan pengguna semasa dan tidak memerlukan root atau mengubah PAM. Sesi SSH tanpa kepala yang tiada keyring desktop melaporkan tidak tersedia; ia tidak menyimpan kunci di tempat lain secara senyap.

## Peraturan penguncian

Penguncian automatik dimatikan untuk pemasangan sedia ada. Apabila didayakan, **15 minit** dipilih secara lalai; nilai yang disokong ialah Never (Tidak pernah), 1, 5, 10, 15, 30 dan 60 minit. Input papan kekunci dan tetikus dalam tetingkap aplikasi dikira sebagai aktiviti; output SSH yang masuk tidak dikira. Penguncian fokus pilihan menganggap tetingkap pemalam aplikasi sebagai sebahagian daripada aplikasi dan membenarkan gesaan pengesahan sistem yang sedang berlangsung diselesaikan. Mengubah peraturan ini memerlukan kata laluan induk.

**Setiap penguncian Vault, termasuk penguncian akibat tiada aktiviti dan kehilangan fokus, memutuskan sesi SSH aktif, menutup pemalam dan menghentikan diagnostik.** Simpan suntingan jauh sebelum mengunci. Ini mengekalkan tingkah laku penguncian manual yang sedia ada; tiada bukti kelayakan SSH kekal tersedia kepada pemalam latar belakang selepas penguncian.

Dasar operasi sensitif pilihan meminta pengesahan sistem yang baharu untuk pemadaman profil, pemasangan/pembuangan pemalam, pelancaran pemasang dan penetapan semula Vault yang tidak berkunci. Arahan terminal jauh dan suntingan fail oleh pemalam berada di luar dasar ini. Dasar ini tidak menggantikan kebenaran pelayan SSH. Jika penyedia berhenti berfungsi, buka kunci dengan kata laluan induk dan ubah dasar menggunakan kata laluan tersebut. Penetapan semula kekal tersedia daripada skrin pemulihan berkunci selepas pengesahan pemusnahnya.

## Reka bentuk Vault dan IPC

Vault v1 sedia ada kekal menggunakan AES-256-GCM dengan scrypt; pendaftaran tidak menulis semula failnya atau mengubah skemanya. Hanya salinan **kunci terbitan 32 bait** miliknya dihantar ke storan bukti kelayakan sistem pengendalian. Kata laluan induk dalam teks biasa tidak pernah disimpan. Metadata pendaftaran setempat mengandungi ID bukti kelayakan rawak, penyedia dan pengikatan SHA-256 kepada metadata Vault yang tidak boleh diubah. Kunci yang dipulihkan mesti lulus penyahsulitan yang disahkan sebelum sesi dibuka. Penimbal proses utama dikosongkan selepas digunakan; rentetan protokol asli ialah memori proses sementara, bukan dakwaan pemadaman memori sepenuhnya dalam masa jalan terurus.

Helper berkomunikasi melalui paip stdin/stdout persendirian yang terhad, tidak menerima arahan shell, mempunyai tamat masa pengesahan dan mengembalikan kod ralat yang dibersihkan. Helper dibungkus di luar ASAR dalam `resources/biometrics`; ia ialah boleh laku asli kendiri, jadi tiada modul asli ABI Electron diperlukan. Helper Linux menggunakan Python dan GI sistem. Objek asli dan kunci terbitan tidak pernah melintasi jambatan renderer/pemalam. IPC biometrik mengesahkan tetingkap utama yang aktif dan bingkai utamanya; pemalam tidak boleh memanggilnya. Penguncian eksplisit membatalkan kerja buka kunci biometrik dan kata laluan yang belum selesai supaya kelulusan lewat tidak dapat membuka semula Vault. Membuang pendaftaran membatalkan pengikatan setempatnya walaupun stor sistem pengendalian berada di luar talian; stor yang tidak boleh dicapai mungkin mengekalkan bukti kelayakan yatim yang tidak boleh digunakan.

## Binaan dan pengesahan

`npm run biometrics:build` menyediakan helper untuk platform hos; permulaan pembangunan dan penyediaan keluaran memanggilnya secara automatik. macOS memerlukan Swift/Apple SDK dengan Security dan LocalAuthentication; Windows memerlukan Visual Studio C++ Build Tools, Windows SDK dan C++/WinRT; Linux menyalin helper Python. Tiada kebergantungan npm baharu ditambah. Bina secara asli pada setiap sistem pengendalian sasaran. Helper macOS disertakan dalam tandatangan berkas rekursif; ia tidak memerlukan entitlement App Sandbox kerana aplikasi desktop ini tidak berjalan dalam kotak pasir. Pengedaran macOS pengeluaran masih memerlukan tandatangan Developer ID dan notarisasi, bebas daripada tandatangan keluaran OpenPGP.

Jalankan `npm test`, `npm run test:biometrics:ui` dan `npm run test:diagnostics:ui`. Ujian Node biometrik dan ujian asap UI terpencil menggunakan **penyesuai sistem pengendalian olok-olok** untuk merangkumi kejayaan, penolakan/pembatalan, kunci yang salah, perkakasan/pendaftaran yang tiada, penetapan semula, tamat masa dan hasil lewat, keyring Linux yang tidak tersedia, kegagalan bukti kelayakan sistem pengendalian, respons Windows yang diluluskan dengan PIN, perubahan pendaftaran macOS, keserasian Vault sedia ada, pengasingan IPC dan pembersihan SSH. Ini tidak membuktikan pengesahan perkakasan yang berjaya.

Kompilasi asli telah disahkan pada macOS arm64 dan Windows x64. macOS melaporkan Touch ID tersedia; VM Windows melaporkan Hello tidak tersedia. Pendaftaran cap jari/wajah/PIN, pengambilan sebenar kunci yang dilindungi, pembatalan dialog sistem pengendalian dan penidaksahan akibat perubahan pendaftaran masih memerlukan ujian perkakasan interaktif pada setiap sistem yang disokong. Helper Linux juga mesti diuji pada desktop dengan pembaca fprintd yang disokong; VM tanpa kepala tidak dapat membuktikan pengesahan tersebut.

Rujukan platform: [Kawalan akses biometrik Apple](https://developer.apple.com/documentation/security/secaccesscontrolcreateflags/biometrycurrentset), [Interop Hello desktop Windows](https://learn.microsoft.com/en-us/windows/win32/api/userconsentverifierinterop/nf-userconsentverifierinterop-iuserconsentverifierinterop-requestverificationforwindowasync), [Kitaran hayat peranti fprintd](https://fprint.freedesktop.org/fprintd-dev/Device.html), [Spesifikasi Secret Service](https://specifications.freedesktop.org/secret-service/latest/).

## Akses rangkaian setempat SSH pada macOS

Jika setiap profil SSH setempat gagal dengan `connect EHOSTUNREACH` tetapi sambungan yang sama berfungsi dalam Terminal, semak **System Settings → Privacy & Security → Local Network → CH-J Server Manager (Tetapan Sistem → Privasi & Keselamatan → Rangkaian Setempat)**, benarkan akses, tutup aplikasi sepenuhnya dan bukanya semula. Jika sudah didayakan, togol kebenarannya dan mulakan semula. Semak juga penghalaan, Wi-Fi/Ethernet dan VPN: ralat ini sahaja bukan bukti penolakan privasi. Jangan tetapkan semula Vault atau buang cap jari SSH yang dipercayai kerana ralat ini.

Aplikasi mengisytiharkan `NSLocalNetworkUsageDescription` dan menyediakan panduan yang disetempatkan untuk ralat kebenaran/laluan rangkaian macOS. Ia tidak boleh memberikan kebenaran kepada dirinya sendiri. Apple mengesyorkan identiti tandatangan yang dikeluarkan oleh Apple supaya macOS dapat menjejaki privasi rangkaian dengan boleh dipercayai merentas binaan; binaan alpha ad hoc semasa masih mempunyai batasan itu. Lihat [panduan Apple tentang privasi rangkaian setempat](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy).

## Ikon aplikasi Ubuntu

Pakej Debian memasang ikon CH-J sedia ada pada saiz hicolor standard (16–512 px), dengan entri desktop dan kelas tetingkap Electron yang sepadan. Tetingkap utama juga menerima ikon apabila dicipta semula. Selepas mengemas kini pelancar lama yang telah disemat, nyahsemat dan semat aplikasi yang baru dipasang; log keluar/log masuk desktop boleh menyegarkan cache pelancar GNOME yang lapuk.