📱 ShellGuard-TOTP Companion
ShellGuard-TOTP is the official native Android companion application for the ShellGuard secrets ecosystem. Built with Kotlin and Jetpack Compose, it serves as a sovereign, offline-first two-factor authentication (TOTP) authenticator that pairs seamlessly with your self-hosted ShellGuard vault.
🏗️ Architectural Topology: One-Way Mirror Sync
Unlike traditional cloud-based authenticators that require centralized servers and third-party account brokers, ShellGuard-TOTP implements a One-Way Mirror Sync architecture that prioritizes zero-knowledge isolation and offline sovereignty.
Core Sync Invariants:
- Remote Read-Only Mirror: When paired with your self-hosted ShellGuard instance, the Android app acts as a read-only mirror for vault logins containing TOTP seeds (
vault_pearls). These appear in a dedicated "☁️ Synced from ShellGuard" group. - Strictly Sovereign Local Codes: Any two-factor code created directly on the Android device is designated as a Local Code (
isLocalOnly = true). Local codes remain private to your phone and are never automatically transmitted upstream. - Selective Encrypted Backups: Only Local Codes are exported into
.sgtotp.bakbackup files to prevent secret duplication and eliminate collision risks with your main vault.
⚡ Core Capabilities
- 100% Offline-First Operation: Generates dynamic time-based 6-digit and 8-digit verification codes using the device hardware clock without needing active cellular data or Wi-Fi.
- Hardware-Backed KeyStore Protection: Master encryption keys are wrapped inside the Android Trusted Execution Environment (TEE) or StrongBox Keymaster.
- Biometric Authentication: Supports instant fingerprint and face unlock via
BiometricPromptwith zero biometric data exposure. - Instant QR Code Ingestion: Real-time in-memory QR decoding powered by CameraX and ML Kit, plus an in-memory "Scan from Gallery" photo picker fallback.
- Cross-Ecosystem Backup Compatibility: Encrypted
.sgtotp.bakarchives can be directly imported and decrypted client-side inside the ShellGuard Web Vault. - Window Screenshot Suppression: Protected by
FLAG_SECUREto prevent screen recorders, malware, and Android task-switcher previews from exposing OTP codes.
🧭 Companion Documentation Guide
Explore the technical architecture and operational specifications of ShellGuard-TOTP:
Security & Hardware Enclaves
Security Deep-dive into the Android KeyStore, BiometricPrompt isolation,
FLAG_SECURE, and RAM zeroization. Sync & Encrypted Backups
Interoperability Learn the
sgtotp.bak wire format, HKDF/AES-GCM encryption, and bidirectional vault restoration. RFC 6238 TOTP Engine
Cryptography Detailed specifications for HMAC-SHA1/256/512 algorithms, periods, digits, and CameraX QR scanning.
Privacy Policy & Google Play
Compliance Review our official Google Play Data Safety Fast-Card and regulatory permission disclosures.
📦 Releases & Source Code
- GitHub Repository: github.com/ClawStackStudios/ShellGuard-TOTP
- Official APK Releases: github.com/ClawStackStudios/ShellGuard-TOTP/releases