Hyper Authenticator là ứng dụng Flutter đa nền tảng để lưu tài khoản TOTP và tạo mã dùng một lần theo RFC 6238. Local vault hoạt động offline không cần đăng nhập; Supabase authentication chỉ phục vụ account-managed cloud sync tùy chọn; private Realtime Broadcast đánh thức sync foreground nhưng không truyền TOTP payload. Ứng dụng có app lock, nhập QR và giao diện sáng/tối.
Trạng thái dự án: production baseline kỹ thuật; GitHub Releases là kênh phân phối binary ưu tiên trong giai đoạn hiện tại. Web đang chạy production. Android có APK đã ký; Windows/Linux có package chưa ký. Các binary chỉ được phát hành dưới dạng pre-release với checksum và cảnh báo rõ ràng. App store, signing cho stable, device test, SMTP mailbox và public legal/support metadata được hoãn sang giai đoạn sau. Xem Trạng thái dự án.
- Web: authenticator.hyperz.xyz.
- GitHub Preview: trang GitHub Releases.
GitHub Preview có Android APK signed, Windows x64 installer và Linux amd64 Debian
package. Luôn kiểm tra SHA256SUMS.txt; Android có thể yêu cầu cho phép cài từ
browser/GitHub, còn Windows SmartScreen có thể cảnh báo vì installer chưa code-sign.
iOS và macOS chưa được phân phối binary ở giai đoạn này. Android signed APK đã
pass tag CI, public-download/signature gate và emulator clean-install/
vault-retaining upgrade; camera/biometric trên thiết bị thật vẫn là gate sau.
- Dùng TOTP local không cần tài khoản hoặc network.
- Đăng ký, đăng nhập và khôi phục mật khẩu Web qua Supabase Auth cho cloud sync.
- Thêm tài khoản bằng camera, ảnh QR hoặc nhập thủ công.
- Import QR chuyển dữ liệu do Google Authenticator xuất, gồm multi-part batch, schema v1/v2 đã quan sát, preview và duplicate detection trước một atomic local-vault commit.
- Export nhiều tài khoản sang Google Authenticator sau fresh OS authentication; QR multi-part có cảnh báo, tự hết hạn và đóng khi ứng dụng rời foreground. Google Authenticator 7.2 trên Android AVD đã nhận QR export v1 và tạo cùng TOTP; thiết bị thật vẫn là release gate riêng.
- Parse URI
otpauth://totpvà validate Base32, SHA1/SHA256/SHA512, 6–8 chữ số cùng chu kỳ tùy chỉnh. - Lưu TOTP bằng FlutterSecureStorage; tìm kiếm, sửa, xóa và sao chép.
- Khóa ứng dụng bằng sinh trắc học hoặc credential của OS trên platform được hỗ trợ.
- Ba visual style, mỗi style hỗ trợ sáng/tối/theo hệ thống.
- Không đăng nhập thì local-only; đăng nhập thì mã tự upload/download theo tài khoản. Xóa tạo cloud tombstone và truyền sang thiết bị khác; không recovery key.
Code được tổ chức theo feature và ba lớp chính:
UI pages
-> BLoCs
-> use cases và repository contracts
-> FlutterSecureStorage / SharedPreferences / Supabase
Tài liệu nên đọc trước:
Yêu cầu Flutter stable tương thích pubspec.yaml và toolchain của platform đích.
flutter pub get
dart run build_runner build
flutter run
Lệnh trên khởi động chế độ local-only. Chỉ tạo file .env khi cần đăng nhập và
cloud sync:
cp .env.example .env
flutter run --dart-define-from-file=.env
.env chứa public client configuration:
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
PASSWORD_RECOVERY_URL=https://auth.example.com/reset-password/
File này bị Git bỏ qua và không được đóng gói như Flutter asset. Không đặt service-role key, database password hoặc secret phía server vào đây. Thiếu toàn bộ cấu hình cloud là trạng thái local-only hợp lệ; cấu hình dở dang bị từ chối.
Kiểm tra public config mà không in giá trị:
dart run tool/agent/check_release_config.dart .env
Quality gate:
scripts/agent/doctor.sh
scripts/agent/check.sh quick
scripts/agent/check.sh app
scripts/agent/check.sh backend
scripts/agent/check.sh release
scripts/agent/check.sh infra
scripts/agent/check.sh full
Build theo host hoặc target:
scripts/agent/build.sh host
scripts/agent/build.sh host .env
scripts/agent/build.sh android
scripts/agent/build.sh web
Web production image và Linux compile cô lập:
web-deployment/test.sh
web-deployment/build-image.sh hyper-authenticator-web:1.1.0
scripts/agent/build_linux_container.sh
Sau khi tạo build/web bằng public release config hợp lệ, chạy thêm browser
artifact smoke để xác minh Flutter engine mount, semantics và local-vault shell:
scripts/agent/web_runtime_smoke.sh
Command có đối số .env validate public release contract trước khi build; không
có đối số chỉ là compile smoke. Xem Hướng dẫn phát triển
và Chiến lược kiểm thử.
| Platform | Build hiện tại | Giới hạn chức năng đáng chú ý |
|---|---|---|
| Android | Signed APK pre-release | Camera QR và device authentication; còn gate thiết bị thật |
| iOS | Đã xác minh simulator | Cần device và signing để release |
| macOS | Đã xác minh compile unsigned | Cần signing để test Keychain/runtime và release |
| Web | Production HTTPS | Không có device authentication; account sync dùng browser trust boundary |
| Windows | Hosted runtime + unsigned NSIS Preview | Nhập thủ công + account sync; không camera QR |
| Linux | Hosted runtime + unsigned .deb Preview |
Nhập thủ công + account sync; chưa KDE/physical desktop |
scripts/agent/build.sh tự từ chối target không thể build trên host hiện tại.
Client không ghi TOTP plaintext vào bảng public. Supabase Vault mã hóa payload khi lưu, nhưng authenticated backend RPC có quyền giải mã; đây không phải E2EE. Account ownership được bind local trước network để tránh cross-user upload; cloud failure không rollback local và deletion dùng tombstone. Trạng thái production rollout được ghi riêng trong Trạng thái dự án. Đọc Mô hình bảo mật trước khi dùng dữ liệu nhạy cảm.
Đọc Hướng dẫn đóng góp. Source do dự án sở hữu được phát hành
theo Apache License 2.0. Provider logo vendored từ Sentinel Icons có
source pin, MIT License và checksum trong third_party/sentinel-icons; trademark
thuộc chủ sở hữu tương ứng và chỉ dùng để nhận diện dịch vụ. Asset bên thứ ba
khác vẫn phải có provenance/license/NOTICE theo
ADR-0007.