English | 日本語
M5Authenticator is a standalone TOTP authenticator for M5StickS3. It stores TOTP credentials in an encrypted Vault on the Device, keeps the Vault Master Key (VMK) only in RAM while unlocked, and uses a local-only Web app for provisioning, account management, firmware updates, and recovery.
Use the hosted Web app with the latest stable Desktop Chrome and Web Serial:
You can import standard TOTP QR images and Google Authenticator migration QR images locally in the browser, provision the Device, select an account on M5StickS3, and reveal a six-digit OTP without using a smartphone at authentication time.
- RFC 6238 TOTP using SHA-1, 6 digits, and a 30-second period
- up to 32 TOTP accounts
- account selection directly on M5StickS3
- short OTP reveal on the Device
- local import of standard TOTP QR images and Google Authenticator migration QR images
- encrypted Device Vault for credential persistence
- RAM-only VMK while the Device is unlocked
- Trusted Browser quick unlock without Passphrase re-entry, while still requiring fresh physical confirmation on the Device
- NTP and PC time synchronization with readiness gating before OTP display
- firmware first install and state-preserving update from the Web interface
- encrypted Recovery Package export/import for browser recovery
- no M5Authenticator-specific eFuse provisioning requirement
M5Authenticator separates persistent encrypted state from the key needed to use it:
- Device Flash stores the encrypted Vault, not plaintext TOTP secrets.
- The Vault Master Key (VMK) is held only in RAM while the Device is unlocked. Lock, reboot, or power loss discards it.
- A Trusted Browser can make normal unlocks more convenient, but it does not bypass fresh physical confirmation on M5StickS3 for an unlock attempt.
- Recovery Packages are encrypted, but they remain security-sensitive offline artifacts because possession enables offline Passphrase guessing.
- A Device Factory Reset does not erase or cryptographically revoke Recovery Packages that were previously exported elsewhere.
- Ordinary network time from NTP is operationally useful but is not cryptographically authenticated.
- The project does not claim a hardware root of trust or strong resistance to a compromised trusted browser/OS, malicious firmware, RAM probing while unlocked, or sophisticated physical attacks.
For the authoritative security contract, see SECURITY.md and docs/SECRET_VAULT.md.
- Open the hosted M5Authenticator Web app in the latest stable Desktop Chrome.
- Use First install / erase only for a new Device or when you intentionally want a clean Device. For an already provisioned Device, use the supported Update path to preserve supported user state.
- Connect the M5StickS3 through Web Serial.
- Import standard TOTP or Google Authenticator migration QR data locally in the browser.
- Provision the selected accounts and confirm the operation on the Device.
- When the Device is locked, unlock it through the Web app and approve the fresh physical confirmation on M5StickS3.
- Confirm that time status is ready before relying on displayed OTP values.
Detailed Provisioner behavior, account management, recovery, and firmware flows are documented in docs/WEB_PROVISIONER.md and docs/DISTRIBUTION.md.
Current production support is intentionally narrow:
- Device: M5StickS3
- Browser: latest stable Desktop Chrome
- Device communication: Web Serial
Other M5Stack targets should not be assumed to be supported unless they are explicitly documented as production targets.
- Hosted Help / Usage — user-facing usage guidance in the deployed Web app
- Web Provisioner — provisioning, account management, browser state, Trusted Browser flows, and recovery
- Device UI — account selection, Device confirmation, time status, and OTP display behavior
- Time — synchronization and OTP readiness rules
- Distribution — Web Flasher, first install, state-preserving update, and release packaging
- Security Policy — secret-handling requirements and threat-model boundary
- Secret Vault Architecture — encrypted Vault, VMK, Passphrase, Trusted Browser, Lock/Unlock, and Recovery Package semantics
- Storage — encrypted persistence and versioning boundaries
- Architecture — Device/Web/Vault responsibility boundaries and end-to-end flows
- Provisioning Protocol — Web Serial provisioning and unlock protocol
- V1 Requirements — durable cross-feature requirements reference
The firmware is built with ESP-IDF/CMake and the Web app uses TypeScript/Vite. Developer setup, pinned toolchains, and reproducible commands are in docs/DEVELOPMENT.md.
Repository contribution and work-tracking rules are documented in AGENTS.md and agent/WORK-TRACKING.md. These development-process documents are separate from the product usage and security contracts above.
Before submitting repository changes, keep all examples and test material synthetic and follow SECURITY.md.