# Xác thực hệ thống tùy chọn và khóa Vault

Trước tiên, hãy tạo hoặc mở khóa Vault bằng mật khẩu chính của nó. Mở **Settings → Security (Cài đặt → Bảo mật)**, kiểm tra trạng thái của nhà cung cấp và bật mở khóa sinh trắc học. Việc đăng ký yêu cầu xác thực hệ thống mới. Sau đó, màn hình đăng nhập cung cấp tùy chọn mở khóa bằng Touch ID, Windows Hello hoặc vân tay bên cạnh biểu mẫu mật khẩu chính. **Disable and remove enrollment (Tắt và xóa đăng ký)** xóa khóa được lưu tạm của ứng dụng này, không bao giờ xóa các vân tay đã đăng ký trong hệ điều hành.

Hãy giữ mật khẩu chính: việc hủy, hết thời gian chờ, phần cứng/keyring không khả dụng và đăng ký bị vô hiệu đều yêu cầu dự phòng bằng mật khẩu. Đăng ký sinh trắc học chỉ có hiệu lực cục bộ cho người dùng, thiết bị và Vault này. Đây không phải là cơ chế khôi phục hay bản sao lưu. Đặt lại Vault sẽ thu hồi đăng ký và chỉ xóa các hồ sơ được mã hóa cùng dấu vân tay máy chủ hiện có sau bước xác nhận `SMAZAT` hiện có.

| Nền tảng | Xác thực và lưu trữ | Yêu cầu và giới hạn |
| --- | --- | --- |
| macOS Apple Silicon | LocalAuthentication / Touch ID gốc; mục Keychain của Security.framework với `biometryCurrentSet` và `WhenUnlockedThisDeviceOnly` | Touch ID đã đăng ký, cảm biến khả dụng và Keychain đăng nhập dùng được. Thay đổi vân tay làm mục này mất hiệu lực. Hãy dùng chữ ký Developer ID ổn định cho các bản cập nhật sản xuất; chữ ký alpha ad hoc có thể làm gián đoạn độ tin cậy của Keychain và việc theo dõi quyền mạng cục bộ. |
| Windows x64 | Interop máy tính WinRT Windows Hello gốc gắn với HWND chính; khóa được mã hóa bằng DPAPI của người dùng hiện tại trong Windows Credential Manager | Vân tay, khuôn mặt **hoặc PIN** Hello đã cấu hình. Đây là mở khóa tiện lợi: ứng dụng thực thi việc phê duyệt Hello, còn bản thân DPAPI không được bảo vệ bằng sinh trắc học. Mã khác chạy dưới cùng người dùng có thể giải mã thông tin xác thực. |
| Ubuntu x64 | Vân tay đã đăng ký của người dùng hiện tại qua fprintd D-Bus; lưu trữ thông tin xác thực rõ ràng bằng libsecret / Secret Service | Đầu đọc được hỗ trợ, vân tay đã đăng ký, Secret Service của máy tính đang chạy và keyring mặc định. Mở khóa tiện lợi: thông tin xác thực trong keyring không được ràng buộc về mặt mật mã với việc xác minh vân tay. Không có dự phòng `basic_text` hay tệp văn bản thuần. |

Trên Ubuntu, các gói runtime tùy chọn là `python3-gi`, `gir1.2-secret-1`, `gnome-keyring` (hoặc một Secret Service tương thích khác) và `fprintd`. Hãy cài các gói còn thiếu bằng trình quản lý gói thông thường của hệ điều hành, rồi đăng ký vân tay trong cài đặt hệ điều hành. Việc xác thực dùng người dùng hiện tại, không yêu cầu root và không thay đổi PAM. Phiên SSH không giao diện đồ họa và không có keyring máy tính sẽ báo không khả dụng; nó không âm thầm lưu khóa ở nơi khác.

## Quy tắc khóa

Khóa tự động bị tắt đối với các bản cài đặt hiện có. Khi bật, giá trị mặc định là **15 phút**; các giá trị được hỗ trợ là Never (Không bao giờ), 1, 5, 10, 15, 30 và 60 phút. Thao tác bàn phím và chuột trong cửa sổ ứng dụng được tính là hoạt động; đầu ra SSH nhận được thì không. Tùy chọn khóa khi mất tiêu điểm coi các cửa sổ plugin của ứng dụng là một phần của ứng dụng và cho phép lời nhắc xác thực hệ thống đang diễn ra được hoàn tất. Thay đổi các quy tắc này yêu cầu mật khẩu chính.

**Mọi lần khóa Vault, kể cả khóa do không hoạt động và do mất tiêu điểm, đều ngắt các phiên SSH đang hoạt động, đóng plugin và dừng chẩn đoán.** Hãy lưu các chỉnh sửa từ xa trước khi khóa. Điều này giữ nguyên hành vi khóa thủ công hiện có; sau khi khóa, không còn thông tin xác thực SSH nào khả dụng cho plugin chạy nền.

Chính sách tùy chọn cho các thao tác nhạy cảm yêu cầu xác thực hệ thống mới khi xóa hồ sơ, cài đặt/gỡ plugin, khởi chạy trình cài đặt và đặt lại Vault đã mở khóa. Lệnh terminal từ xa và chỉnh sửa tệp của plugin nằm ngoài chính sách này. Chính sách này không thay thế việc phân quyền trên máy chủ SSH. Nếu nhà cung cấp ngừng hoạt động, hãy mở khóa bằng mật khẩu chính và thay đổi chính sách bằng mật khẩu đó. Chức năng đặt lại vẫn khả dụng từ màn hình khôi phục khi bị khóa, sau bước xác nhận mang tính phá hủy.

## Thiết kế Vault và IPC

Vault v1 hiện có vẫn dùng AES-256-GCM với scrypt; việc đăng ký không ghi lại các tệp hay thay đổi lược đồ của nó. Chỉ một bản sao của **khóa dẫn xuất 32 byte** được chuyển tới kho thông tin xác thực của hệ điều hành. Mật khẩu chính dạng văn bản thuần không bao giờ được lưu. Siêu dữ liệu đăng ký cục bộ chứa ID thông tin xác thực ngẫu nhiên, nhà cung cấp và một ràng buộc SHA-256 với siêu dữ liệu bất biến của Vault. Khóa được khôi phục phải vượt qua bước giải mã có xác thực trước khi mở phiên. Bộ đệm của tiến trình chính được xóa sau khi dùng; chuỗi giao thức gốc là bộ nhớ tiến trình tạm thời, không phải tuyên bố về việc xóa bộ nhớ hoàn toàn trong các runtime được quản lý.

Helper giao tiếp qua các đường ống stdin/stdout riêng tư có giới hạn, không chấp nhận lệnh shell, có thời gian chờ xác thực và trả về mã lỗi đã được làm sạch. Helper được đóng gói bên ngoài ASAR trong `resources/biometrics`; đây là các tệp thực thi gốc độc lập, nên không cần mô-đun gốc theo ABI của Electron. Helper Linux dùng Python và GI của hệ thống. Đối tượng gốc và khóa dẫn xuất không bao giờ đi qua cầu nối renderer/plugin. IPC sinh trắc học xác thực cửa sổ chính đang hoạt động và khung chính của nó; plugin không thể gọi đến. Việc khóa rõ ràng sẽ hủy các tác vụ mở khóa bằng sinh trắc học và mật khẩu đang chờ, để một phê duyệt đến muộn không thể mở lại Vault. Xóa đăng ký sẽ thu hồi ràng buộc cục bộ ngay cả khi kho của hệ điều hành đang ngoại tuyến; kho không truy cập được có thể còn giữ một thông tin xác thực mồ côi không dùng được.

## Dựng và xác minh

`npm run biometrics:build` chuẩn bị helper cho nền tảng máy chủ; quá trình khởi động khi phát triển và chuẩn bị phát hành tự động gọi lệnh này. macOS cần Swift/Apple SDK với Security và LocalAuthentication; Windows cần Visual Studio C++ Build Tools, Windows SDK và C++/WinRT; Linux sao chép helper Python. Không thêm phụ thuộc npm mới nào. Hãy dựng trực tiếp trên từng hệ điều hành đích. Helper macOS được đưa vào quá trình ký gói đệ quy; nó không cần entitlement App Sandbox vì ứng dụng máy tính này không chạy trong sandbox. Phân phối macOS cho sản xuất vẫn yêu cầu chữ ký Developer ID và công chứng, độc lập với chữ ký phát hành OpenPGP.

Chạy `npm test`, `npm run test:biometrics:ui` và `npm run test:diagnostics:ui`. Các kiểm thử Node sinh trắc học và kiểm thử nhanh UI tách biệt dùng một **bộ điều hợp hệ điều hành giả lập** để bao quát thành công, từ chối/hủy, khóa sai, thiếu phần cứng/đăng ký, đặt lại, hết thời gian chờ và kết quả đến muộn, keyring Linux không khả dụng, lỗi thông tin xác thực của hệ điều hành, phản hồi Windows được phê duyệt bằng PIN, thay đổi đăng ký trên macOS, khả năng tương thích với Vault hiện có, cô lập IPC và dọn dẹp SSH. Điều này không chứng minh việc xác thực thành công trên phần cứng.

Biên dịch gốc đã được xác minh trên macOS arm64 và Windows x64. macOS báo Touch ID khả dụng; máy ảo Windows báo Hello không khả dụng. Việc đăng ký vân tay/khuôn mặt/PIN, truy xuất thực tế khóa được bảo vệ, hủy hộp thoại của hệ điều hành và vô hiệu hóa do thay đổi đăng ký vẫn cần được thử nghiệm tương tác trên phần cứng của từng hệ thống được hỗ trợ. Helper Linux còn phải được thử nghiệm trên máy tính có đầu đọc fprintd được hỗ trợ; máy ảo không giao diện đồ họa không thể chứng minh việc xác minh đó.

Tài liệu tham khảo nền tảng: [Kiểm soát truy cập sinh trắc học của Apple](https://developer.apple.com/documentation/security/secaccesscontrolcreateflags/biometrycurrentset), [Interop Hello trên máy tính Windows](https://learn.microsoft.com/en-us/windows/win32/api/userconsentverifierinterop/nf-userconsentverifierinterop-iuserconsentverifierinterop-requestverificationforwindowasync), [Vòng đời thiết bị fprintd](https://fprint.freedesktop.org/fprintd-dev/Device.html), [Đặc tả Secret Service](https://specifications.freedesktop.org/secret-service/latest/).

## Quyền truy cập mạng cục bộ cho SSH trên macOS

Nếu mọi hồ sơ SSH cục bộ đều thất bại với `connect EHOSTUNREACH` nhưng cùng kết nối đó lại hoạt động trong Terminal, hãy kiểm tra **System Settings → Privacy & Security → Local Network → CH-J Server Manager (Cài đặt hệ thống → Quyền riêng tư & Bảo mật → Mạng cục bộ)**, cho phép truy cập, thoát hoàn toàn ứng dụng rồi mở lại. Nếu quyền đã được bật, hãy tắt rồi bật lại và khởi động lại. Đồng thời kiểm tra định tuyến, Wi-Fi/Ethernet và VPN: chỉ riêng lỗi này không chứng minh việc bị từ chối do cài đặt quyền riêng tư. Không đặt lại Vault hay loại bỏ các dấu vân tay SSH đáng tin cậy vì lỗi này.

Ứng dụng khai báo `NSLocalNetworkUsageDescription` và cung cấp hướng dẫn đã bản địa hóa cho các lỗi quyền/định tuyến mạng trên macOS. Ứng dụng không thể tự cấp quyền cho chính mình. Apple khuyến nghị dùng danh tính ký do Apple cấp để macOS có thể theo dõi quyền riêng tư mạng một cách đáng tin cậy qua các bản dựng; các bản dựng alpha ad hoc hiện tại vẫn còn hạn chế này. Xem [hướng dẫn của Apple về quyền riêng tư mạng cục bộ](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy).

## Biểu tượng ứng dụng trên Ubuntu

Các gói Debian cài đặt biểu tượng CH-J hiện có ở các kích thước hicolor tiêu chuẩn (16–512 px), cùng mục desktop và lớp cửa sổ Electron tương ứng. Cửa sổ chính cũng nhận biểu tượng khi được tạo lại. Sau khi cập nhật một trình khởi chạy cũ đã được ghim, hãy bỏ ghim rồi ghim lại ứng dụng vừa cài đặt; đăng xuất/đăng nhập lại máy tính có thể làm mới bộ nhớ đệm trình khởi chạy GNOME đã cũ.